include/QtCore/qversionnumber.h

0001 // Copyright (C) 2020 The Qt Company Ltd.
0002 // Copyright (C) 2022 Intel Corporation.
0003 // Copyright (C) 2015 Keith Gardner <kreios4004@gmail.com>
0004 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
0005
0006 #ifndef QVERSIONNUMBER_H
0007 #define QVERSIONNUMBER_H
0008
0009 #include <QtCore/qcompare.h>
0010 #include <QtCore/qcontainertools_impl.h>
0011 #include <QtCore/qlist.h>
0012 #include <QtCore/qmetatype.h>
0013 #include <QtCore/qnamespace.h>
0014 #include <QtCore/qspan.h>
0015 #include <QtCore/qstring.h>
0016 #include <QtCore/qtypeinfo.h>
0017 #if !defined(QT_LEAN_HEADERS) || QT_LEAN_HEADERS < 2
0018 #include <QtCore/qtyperevision.h>
0019 #endif // lean headers level 2
0020
0021 QT_BEGIN_NAMESPACE
0022
0023 class QVersionNumber;
0024 Q_CORE_EXPORT size_t qHash(const QVersionNumber &key, size_t seed = 0);
0025
0026 #ifndef QT_NO_DATASTREAM
0027 Q_CORE_EXPORT QDataStream &operator<<(QDataStream &out, const QVersionNumber &version);
0028 Q_CORE_EXPORT QDataStream &operator>>(QDataStream &in, QVersionNumber &version);
0029 #endif
0030
0031 class QVersionNumber
0032 {
0033     /*
0034      * QVersionNumber stores small values inline, without memory allocation.
0035      * We do that by setting the LSB in the pointer that would otherwise hold
0036      * the longer form of the segments.
0037      * The constants below help us deal with the permutations for 32- and 64-bit,
0038      * little- and big-endian architectures.
0039      */
0040     enum {
0041         // in little-endian, inline_segments[0] is shared with the pointer's LSB, while
0042         // in big-endian, it's inline_segments[7]
0043         InlineSegmentMarker = Q_BYTE_ORDER == Q_LITTLE_ENDIAN ? 0 : sizeof(void *) - 1,
0044         InlineSegmentStartIdx = !InlineSegmentMarker, // 0 for BE, 1 for LE
0045         InlineSegmentCount = sizeof(void *) - 1
0046     };
0047     static_assert(InlineSegmentCount >= 3);   // at least major, minor, micro
0048
0049     struct SegmentStorage
0050     {
0051         // Note: we alias the use of dummy and inline_segments in the use of the
0052         // union below. This is undefined behavior in C++98, but most compilers implement
0053         // the C++11 behavior. The one known exception is older versions of Sun Studio.
0054         union {
0055             quintptr dummy;
0056             qint8 inline_segments[sizeof(void *)];
0057             QList<int> *pointer_segments;
0058         };
0059
0060         // set the InlineSegmentMarker and set length to zero
0061         SegmentStorage() noexcept : dummy(1) {}
0062
0063         SegmentStorage(const QList<int> &seg)
0064         {
0065             if (dataFitsInline(seg.data(), seg.size()))
0066                 setInlineData(seg.data(), seg.size());
0067             else
0068                 setListData(seg);
0069         }
0070
0071         Q_CORE_EXPORT void setListData(const QList<int> &seg);
0072
0073         SegmentStorage(const SegmentStorage &other)
0074         {
0075             if (other.isUsingPointer())
0076                 setListData(*other.pointer_segments);
0077             else
0078                 dummy = other.dummy;
0079         }
0080
0081         SegmentStorage &operator=(const SegmentStorage &other)
0082         {
0083             if (isUsingPointer() && other.isUsingPointer()) {
0084                 *pointer_segments = *other.pointer_segments;
0085             } else if (other.isUsingPointer()) {
0086                 setListData(*other.pointer_segments);
0087             } else {
0088                 if (isUsingPointer())
0089                     delete pointer_segments;
0090                 dummy = other.dummy;
0091             }
0092             return *this;
0093         }
0094
0095         SegmentStorage(SegmentStorage &&other) noexcept
0096             : dummy(other.dummy)
0097         {
0098             other.dummy = 1;
0099         }
0100
0101         QT_MOVE_ASSIGNMENT_OPERATOR_IMPL_VIA_PURE_SWAP(SegmentStorage)
0102
0103         void swap(SegmentStorage &other) noexcept
0104         {
0105             std::swap(dummy, other.dummy);
0106         }
0107
0108         explicit SegmentStorage(QList<int> &&seg)
0109         {
0110             if (dataFitsInline(std::as_const(seg).data(), seg.size()))
0111                 setInlineData(std::as_const(seg).data(), seg.size());
0112             else
0113                 setListData(std::move(seg));
0114         }
0115
0116         Q_CORE_EXPORT void setListData(QList<int> &&seg);
0117
0118         explicit SegmentStorage(QSpan<const int> args)
0119             : SegmentStorage(args.begin(), args.end()) {}
0120
0121         explicit SegmentStorage(const int *first, const int *last)
0122         {
0123             if (dataFitsInline(first, last - first)) {
0124                 setInlineData(first, last - first);
0125             } else {
0126                 setListData(first, last);
0127             }
0128         }
0129
0130         Q_CORE_EXPORT void setListData(const int *first, const int *last);
0131
0132         ~SegmentStorage() { if (isUsingPointer()) delete pointer_segments; }
0133
0134         bool isUsingPointer() const noexcept
0135         { return (inline_segments[InlineSegmentMarker] & 1) == 0; }
0136
0137         qsizetype size() const noexcept
0138         { return isUsingPointer() ? pointer_segments->size() : (inline_segments[InlineSegmentMarker] >> 1); }
0139
0140         void setInlineSize(qsizetype len)
0141         {
0142             Q_ASSERT(len <= InlineSegmentCount);
0143             inline_segments[InlineSegmentMarker] = qint8(1 + 2 * len);
0144         }
0145
0146         Q_CORE_EXPORT void resize(qsizetype len);
0147
0148         int at(qsizetype index) const
0149         {
0150             return isUsingPointer() ?
0151                         pointer_segments->at(index) :
0152                         inline_segments[InlineSegmentStartIdx + index];
0153         }
0154
0155         void setSegments(int len, int maj, int min = 0, int mic = 0)
0156         {
0157             if (maj == qint8(maj) && min == qint8(min) && mic == qint8(mic)) {
0158                 int data[] = { maj, min, mic };
0159                 setInlineData(data, len);
0160             } else {
0161                 setVector(len, maj, min, mic);
0162             }
0163         }
0164
0165     private:
0166         static bool dataFitsInline(const int *data, qsizetype len)
0167         {
0168             if (len > InlineSegmentCount)
0169                 return false;
0170             for (qsizetype i = 0; i < len; ++i)
0171                 if (data[i] != qint8(data[i]))
0172                     return false;
0173             return true;
0174         }
0175         void setInlineData(const int *data, qsizetype len)
0176         {
0177             Q_ASSERT(len <= InlineSegmentCount);
0178             dummy = 1 + len * 2;
0179 #if Q_BYTE_ORDER == Q_LITTLE_ENDIAN
0180             for (qsizetype i = 0; i < len; ++i)
0181                 dummy |= quintptr(data[i] & 0xFF) << (8 * (i + 1));
0182 #elif Q_BYTE_ORDER == Q_BIG_ENDIAN
0183             for (qsizetype i = 0; i < len; ++i)
0184                 dummy |= quintptr(data[i] & 0xFF) << (8 * (sizeof(void *) - i - 1));
0185 #else
0186             // the code above is equivalent to:
0187             setInlineSize(len);
0188             for (qsizetype i = 0; i < len; ++i)
0189                 inline_segments[InlineSegmentStartIdx + i] = data[i] & 0xFF;
0190 #endif
0191         }
0192
0193         Q_CORE_EXPORT void setVector(int len, int maj, int min, int mic);
0194     } m_segments;
0195
0196     class It
0197     {
0198         const QVersionNumber *v;
0199         qsizetype i;
0200
0201         friend class QVersionNumber;
0202         explicit constexpr It(const QVersionNumber *vn, qsizetype idx) noexcept : v(vn), i(idx) {}
0203
0204         friend constexpr bool comparesEqual(const It &lhs, const It &rhs)
0205         { Q_ASSERT(lhs.v == rhs.v); return lhs.i == rhs.i; }
0206         friend constexpr Qt::strong_ordering compareThreeWay(const It &lhs, const It &rhs)
0207         { Q_ASSERT(lhs.v == rhs.v); return Qt::compareThreeWay(lhs.i, rhs.i); }
0208         // macro variant does not exist: Q_DECLARE_STRONGLY_ORDERED_LITERAL_TYPE_NON_NOEXCEPT(It)
0209         friend constexpr bool operator==(It lhs, It rhs) {
0210             return comparesEqual(lhs, rhs);
0211         }
0212 #ifdef __cpp_lib_three_way_comparison
0213         friend constexpr std::strong_ordering operator<=>(It lhs, It rhs) {
0214             return compareThreeWay(lhs, rhs);
0215         }
0216 #else
0217         friend constexpr bool operator!=(It lhs, It rhs) {
0218             return !operator==(lhs, rhs);
0219         }
0220         friend constexpr bool operator<(It lhs, It rhs) {
0221             return is_lt(compareThreeWay(lhs, rhs));
0222         }
0223         friend constexpr bool operator<=(It lhs, It rhs) {
0224             return is_lteq(compareThreeWay(lhs, rhs));
0225         }
0226         friend constexpr bool operator>(It lhs, It rhs) {
0227             return is_gt(compareThreeWay(lhs, rhs));
0228         }
0229         friend constexpr bool operator>=(It lhs, It rhs) {
0230             return is_gteq(compareThreeWay(lhs, rhs));
0231         }
0232 #endif
0233
0234     public:
0235         // Rule Of Zero applies
0236         It() = default;
0237
0238         using iterator_category = std::random_access_iterator_tag;
0239         using value_type = int;
0240 #ifdef QT_COMPILER_HAS_LWG3346
0241         using element_type = const int;
0242 #endif
0243         using difference_type = qptrdiff; // difference to container requirements
0244         using size_type = qsizetype;      // difference to container requirements
0245         using reference = value_type;     // difference to container requirements
0246         using pointer = QtPrivate::ArrowProxy<reference>;
0247
0248         reference operator*() const { return v->segmentAt(i); }
0249         pointer operator->() const { return {**this}; }
0250
0251         It &operator++() { ++i; return *this; }
0252         It operator++(int) { auto copy = *this; ++*this; return copy; }
0253
0254         It &operator--() { --i; return *this; }
0255         It operator--(int) { auto copy = *this; --*this; return copy; }
0256
0257         It &operator+=(difference_type n) { i += n; return *this; }
0258         friend It operator+(It it, difference_type n) { it += n; return it; }
0259         friend It operator+(difference_type n, It it) { return it + n; }
0260
0261         It &operator-=(difference_type n) { i -= n; return *this; }
0262         friend It operator-(It it, difference_type n) { it -= n; return it; }
0263
0264         friend difference_type operator-(It lhs, It rhs)
0265         { Q_ASSERT(lhs.v == rhs.v); return lhs.i - rhs.i; }
0266
0267         reference operator[](difference_type n) const { return *(*this + n); }
0268     };
0269
0270 public:
0271     using const_iterator = It;
0272     using const_reverse_iterator = std::reverse_iterator<const_iterator>;
0273
0274     using value_type = It::value_type;
0275     using difference_type = It::difference_type;
0276     using size_type = It::size_type;
0277     using reference = It::reference;
0278     using const_reference = reference;
0279     using pointer = It::pointer;
0280     using const_pointer = pointer;
0281
0282     inline QVersionNumber() noexcept
0283         : m_segments()
0284     {}
0285     Q_WEAK_OVERLOAD
0286     inline explicit QVersionNumber(const QList<int> &seg) : m_segments(seg) { }
0287
0288     // compiler-generated copy/move ctor/assignment operators and the destructor are ok
0289
0290     Q_WEAK_OVERLOAD
0291     explicit QVersionNumber(QList<int> &&seg) : m_segments(std::move(seg)) { }
0292
0293     inline QVersionNumber(std::initializer_list<int> args)
0294         : m_segments(QSpan{args})
0295     {}
0296
0297     explicit QVersionNumber(QSpan<const int> args)
0298         : m_segments(args)
0299     {}
0300
0301     inline explicit QVersionNumber(int maj)
0302     { m_segments.setSegments(1, maj); }
0303
0304     inline explicit QVersionNumber(int maj, int min)
0305     { m_segments.setSegments(2, maj, min); }
0306
0307     inline explicit QVersionNumber(int maj, int min, int mic)
0308     { m_segments.setSegments(3, maj, min, mic); }
0309
0310     [[nodiscard]] inline bool isNull() const noexcept
0311     { return segmentCount() == 0; }
0312
0313     [[nodiscard]] inline bool isNormalized() const noexcept
0314     { return isNull() || segmentAt(segmentCount() - 1) != 0; }
0315
0316     [[nodiscard]] inline int majorVersion() const noexcept
0317     { return segmentAt(0); }
0318
0319     [[nodiscard]] inline int minorVersion() const noexcept
0320     { return segmentAt(1); }
0321
0322     [[nodiscard]] inline int microVersion() const noexcept
0323     { return segmentAt(2); }
0324
0325     [[nodiscard]] Q_CORE_EXPORT QVersionNumber normalized() const;
0326
0327     [[nodiscard]] Q_CORE_EXPORT QList<int> segments() const;
0328
0329     [[nodiscard]] inline int segmentAt(qsizetype index) const noexcept
0330     { return (m_segments.size() > index) ? m_segments.at(index) : 0; }
0331
0332     [[nodiscard]] inline qsizetype segmentCount() const noexcept
0333     { return m_segments.size(); }
0334
0335     [[nodiscard]] const_iterator begin()  const noexcept { return const_iterator{this, 0}; }
0336     [[nodiscard]] const_iterator end()    const noexcept { return begin() + segmentCount(); }
0337     [[nodiscard]] const_iterator cbegin() const noexcept { return begin(); }
0338     [[nodiscard]] const_iterator cend()   const noexcept { return end(); }
0339
0340     [[nodiscard]] const_reverse_iterator rbegin()  const noexcept { return const_reverse_iterator{end()}; }
0341     [[nodiscard]] const_reverse_iterator rend()    const noexcept { return const_reverse_iterator{begin()}; }
0342     [[nodiscard]] const_reverse_iterator crbegin() const noexcept { return rbegin(); }
0343     [[nodiscard]] const_reverse_iterator crend()   const noexcept { return rend(); }
0344
0345     [[nodiscard]] const_iterator constBegin() const noexcept { return begin(); }
0346     [[nodiscard]] const_iterator constEnd() const noexcept { return end(); }
0347
0348     [[nodiscard]] Q_CORE_EXPORT bool isPrefixOf(const QVersionNumber &other) const noexcept;
0349
0350     [[nodiscard]] Q_CORE_EXPORT static int compare(const QVersionNumber &v1, const QVersionNumber &v2) noexcept;
0351
0352     [[nodiscard]] Q_CORE_EXPORT static QVersionNumber commonPrefix(const QVersionNumber &v1, const QVersionNumber &v2);
0353
0354     [[nodiscard]] Q_CORE_EXPORT QString toString() const;
0355     [[nodiscard]] Q_CORE_EXPORT static QVersionNumber fromString(QAnyStringView string, qsizetype *suffixIndex = nullptr);
0356
0357 #if QT_DEPRECATED_SINCE(6, 4) && QT_POINTER_SIZE != 4
0358     Q_WEAK_OVERLOAD
0359     QT_DEPRECATED_VERSION_X_6_4("Use the 'qsizetype *suffixIndex' overload.")
0360     [[nodiscard]] static QVersionNumber fromString(QAnyStringView string, int *suffixIndex)
0361     {
0362         QT_WARNING_PUSH
0363         // fromString() writes to *n unconditionally, but GCC can't know that
0364         QT_WARNING_DISABLE_GCC("-Wmaybe-uninitialized")
0365         qsizetype n;
0366         auto r = fromString(string, &n);
0367         if (suffixIndex) {
0368             Q_ASSERT(int(n) == n);
0369             *suffixIndex = int(n);
0370         }
0371         return r;
0372         QT_WARNING_POP
0373     }
0374 #endif
0375
0376
0377 #if QT_CORE_REMOVED_SINCE(6, 4)
0378     [[nodiscard]] Q_CORE_EXPORT static QVersionNumber fromString(const QString &string, int *suffixIndex);
0379     [[nodiscard]] Q_CORE_EXPORT static QVersionNumber fromString(QLatin1StringView string, int *suffixIndex);
0380     [[nodiscard]] Q_CORE_EXPORT static QVersionNumber fromString(QStringView string, int *suffixIndex);
0381 #endif
0382
0383 private:
0384     [[nodiscard]] friend bool comparesEqual(const QVersionNumber &lhs,
0385                                             const QVersionNumber &rhs) noexcept
0386     {
0387         return lhs.segmentCount() == rhs.segmentCount() && compare(lhs, rhs) == 0;
0388     }
0389     [[nodiscard]] friend Qt::strong_ordering compareThreeWay(const QVersionNumber &lhs,
0390                                                              const QVersionNumber &rhs) noexcept
0391     {
0392         int c = compare(lhs, rhs);
0393         return Qt::compareThreeWay(c, 0);
0394     }
0395     Q_DECLARE_STRONGLY_ORDERED(QVersionNumber)
0396
0397 #ifndef QT_NO_DATASTREAM
0398     friend Q_CORE_EXPORT QDataStream& operator>>(QDataStream &in, QVersionNumber &version);
0399 #endif
0400     friend Q_CORE_EXPORT size_t qHash(const QVersionNumber &key, size_t seed);
0401 };
0402
0403 Q_DECLARE_TYPEINFO(QVersionNumber, Q_RELOCATABLE_TYPE);
0404
0405 #ifndef QT_NO_DEBUG_STREAM
0406 Q_CORE_EXPORT QDebug operator<<(QDebug, const QVersionNumber &version);
0407 #endif
0408
0409 QT_END_NAMESPACE
0410
0411 QT_DECL_METATYPE_EXTERN(QVersionNumber, Q_CORE_EXPORT)
0412
0413 #endif // QVERSIONNUMBER_H