Move endian-specific integer types to public qtendian header

The classes have recently been cleaned up to be ready for being made
public, and this change adds the final documentation. The classes are
already used in qjson, qtdeclarative and some image format decoders.

Change-Id: Ib6df89f1119162c5bad7a08e9b6f843a2db4040f
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>

3 files changed, 490 insertions, 81 deletions

diff --git a/src/corelib/global/qendian.h b/src/corelib/global/qendian.h
index cacb822947..3337829de0 100644
--- a/src/corelib/global/qendian.h
+++ b/src/corelib/global/qendian.h
@@ -219,6 +219,127 @@ template <> inline quint8 qFromBigEndian<quint8>(const void *src)
 template <> inline qint8 qFromBigEndian<qint8>(const void *src)
 { return static_cast<const qint8 *>(src)[0]; }
 
+template<class S>
+class QSpecialInteger
+{
+    typedef typename S::StorageType T;
+    T val;
+public:
+    QSpecialInteger() = default;
+    explicit Q_DECL_CONSTEXPR QSpecialInteger(T i) : val(S::toSpecial(i)) {}
+
+    QSpecialInteger &operator =(T i) { val = S::toSpecial(i); return *this; }
+    operator T() const { return S::fromSpecial(val); }
+
+    bool operator ==(QSpecialInteger<S> i) const { return val == i.val; }
+    bool operator !=(QSpecialInteger<S> i) const { return val != i.val; }
+
+    QSpecialInteger &operator +=(T i)
+    {   return (*this = S::fromSpecial(val) + i); }
+    QSpecialInteger &operator -=(T i)
+    {   return (*this = S::fromSpecial(val) - i); }
+    QSpecialInteger &operator *=(T i)
+    {   return (*this = S::fromSpecial(val) * i); }
+    QSpecialInteger &operator >>=(T i)
+    {   return (*this = S::fromSpecial(val) >> i); }
+    QSpecialInteger &operator <<=(T i)
+    {   return (*this = S::fromSpecial(val) << i); }
+    QSpecialInteger &operator /=(T i)
+    {   return (*this = S::fromSpecial(val) / i); }
+    QSpecialInteger &operator %=(T i)
+    {   return (*this = S::fromSpecial(val) % i); }
+    QSpecialInteger &operator |=(T i)
+    {   return (*this = S::fromSpecial(val) | i); }
+    QSpecialInteger &operator &=(T i)
+    {   return (*this = S::fromSpecial(val) & i); }
+    QSpecialInteger &operator ^=(T i)
+    {   return (*this = S::fromSpecial(val) ^ i); }
+};
+
+template<typename T>
+class QLittleEndianStorageType {
+public:
+    typedef T StorageType;
+    static Q_DECL_CONSTEXPR T toSpecial(T source) { return qToLittleEndian(source); }
+    static Q_DECL_CONSTEXPR T fromSpecial(T source) { return qFromLittleEndian(source); }
+};
+
+template<typename T>
+class QBigEndianStorageType {
+public:
+    typedef T StorageType;
+    static Q_DECL_CONSTEXPR T toSpecial(T source) { return qToBigEndian(source); }
+    static Q_DECL_CONSTEXPR T fromSpecial(T source) { return qFromBigEndian(source); }
+};
+
+#ifdef Q_QDOC
+class QLEInteger {
+public:
+    explicit Q_DECL_CONSTEXPR QLEInteger(T i);
+    QLEInteger &operator =(T i);
+    operator T() const;
+    bool operator ==(QLEInteger i) const;
+    bool operator !=(QLEInteger i) const;
+    QLEInteger &operator +=(T i);
+    QLEInteger &operator -=(T i);
+    QLEInteger &operator *=(T i);
+    QLEInteger &operator >>=(T i);
+    QLEInteger &operator <<=(T i);
+    QLEInteger &operator /=(T i);
+    QLEInteger &operator %=(T i);
+    QLEInteger &operator |=(T i);
+    QLEInteger &operator &=(T i);
+    QLEInteger &operator ^=(T i);
+};
+
+class QBEInteger {
+public:
+    explicit Q_DECL_CONSTEXPR QBEInteger(T i);
+    QBEInteger &operator =(T i);
+    operator T() const;
+    bool operator ==(QBEInteger i) const;
+    bool operator !=(QBEInteger i) const;
+    QBEInteger &operator +=(T i);
+    QBEInteger &operator -=(T i);
+    QBEInteger &operator *=(T i);
+    QBEInteger &operator >>=(T i);
+    QBEInteger &operator <<=(T i);
+    QBEInteger &operator /=(T i);
+    QBEInteger &operator %=(T i);
+    QBEInteger &operator |=(T i);
+    QBEInteger &operator &=(T i);
+    QBEInteger &operator ^=(T i);
+};
+#else
+
+template<typename T>
+using QLEInteger = QSpecialInteger<QLittleEndianStorageType<T>>;
+
+template<typename T>
+using QBEInteger = QSpecialInteger<QBigEndianStorageType<T>>;
+#endif
+template <typename T>
+class QTypeInfo<QLEInteger<T> >
+    : public QTypeInfoMerger<QLEInteger<T>, T> {};
+
+template <typename T>
+class QTypeInfo<QBEInteger<T> >
+    : public QTypeInfoMerger<QBEInteger<T>, T> {};
+
+typedef QLEInteger<qint16> qint16_le;
+typedef QLEInteger<qint32> qint32_le;
+typedef QLEInteger<qint64> qint64_le;
+typedef QLEInteger<quint16> quint16_le;
+typedef QLEInteger<quint32> quint32_le;
+typedef QLEInteger<quint64> quint64_le;
+
+typedef QBEInteger<qint16> qint16_be;
+typedef QBEInteger<qint32> qint32_be;
+typedef QBEInteger<qint64> qint64_be;
+typedef QBEInteger<quint16> quint16_be;
+typedef QBEInteger<quint32> quint32_be;
+typedef QBEInteger<quint64> quint64_be;
+
 QT_END_NAMESPACE
 
 #endif // QENDIAN_H
diff --git a/src/corelib/global/qendian.qdoc b/src/corelib/global/qendian.qdoc
index 9ce9dbdb0e..2ccdea5979 100644
--- a/src/corelib/global/qendian.qdoc
+++ b/src/corelib/global/qendian.qdoc
@@ -183,3 +183,372 @@
     unmodified.
 */
 
+/*!
+    \class QLEInteger
+    \inmodule QtCore
+    \brief The QLEInteger class provides platform-independent little-endian integers.
+    \since 5.10
+
+    The template parameter \c T must be a C++ integer type:
+    \list
+       \li 8-bit: char, signed char, unsigned char, qint8, quint8
+       \li 16-bit: short, unsigned short, qint16, quint16, char16_t
+       \li 32-bit: int, unsigned int, qint32, quint32, char32_t
+       \li 64-bit: long long, unsigned long long, qint64, quint64
+       \li platform-specific size: long, unsigned long
+       \li pointer size: qintptr, quintptr, qptrdiff
+    \endlist
+
+    \note Using this class may be slower than using native integers, so only use it when
+    an exact endian is needed.
+*/
+
+/*! \fn QLEInteger::QLEInteger(T value)
+
+    Constructs a QLEInteger with the given \a value.
+*/
+
+/*! \fn QLEInteger &QLEInteger::operator=(T value)
+
+    Assigns \a value to this QLEInteger and returns a reference to
+    this QLEInteger.
+*/
+
+/*!
+    \fn QLEInteger::operator T() const
+
+    Returns the value of this QLEInteger as a native integer.
+*/
+
+/*!
+    \fn bool QLEInteger::operator==(QLEInteger other) const
+
+    Returns \c true if the value of this QLEInteger is equal to the value of \a other.
+*/
+
+/*!
+    \fn bool QLEInteger::operator!=(QLEInteger other) const
+
+    Returns \c true if the value of this QLEInteger is not equal to the value of \a other.
+*/
+
+/*!
+    \fn QLEInteger &QLEInteger::operator+=(T i)
+
+    Adds \a i to this QLEInteger and returns a reference to
+    this object.
+*/
+
+/*!
+    \fn QLEInteger &QLEInteger::operator-=(T i)
+
+    Subtracts \a i from this QLEInteger and returns a reference to
+    this object.
+*/
+
+/*!
+    \fn QLEInteger &QLEInteger::operator*=(T i)
+
+    Multiplies \a i with this QLEInteger and returns a reference to
+    this object.
+*/
+
+/*!
+    \fn QLEInteger &QLEInteger::operator/=(T i)
+
+    Divides this QLEInteger with \a i and returns a reference to
+    this object.
+*/
+
+/*!
+    \fn QLEInteger &QLEInteger::operator%=(T i)
+
+    Sets this QLEInteger to the remainder of a division by \a i and
+    returns a reference to this object.
+*/
+
+/*!
+    \fn QLEInteger &QLEInteger::operator>>=(T i)
+
+    Performs a left-shift by \a i on this QLEInteger and returns a
+    reference to this object.
+*/
+
+/*!
+    \fn QLEInteger &QLEInteger::operator<<=(T i)
+
+    Performs a right-shift by \a i on this QLEInteger and returns a
+    reference to this object.
+*/
+
+/*!
+    \fn QLEInteger &QLEInteger::operator|=(T i)
+
+    Performs a bitwise OR with \a i onto this QLEInteger and returns a reference to
+    this object.
+*/
+
+/*!
+    \fn QLEInteger &QLEInteger::operator&=(T i)
+
+    Performs a bitwise AND with \a i onto this QLEInteger and returns a reference to
+    this object.
+*/
+
+/*!
+    \fn QLEInteger &QLEInteger::operator^=(T i)
+
+    Performs a bitwise XOR with \a i onto this QLEInteger and returns a reference to
+    this object.
+*/
+
+/*!
+    \class QBEInteger
+    \inmodule QtCore
+    \brief The QBEInteger class provides platform-independent big-endian integers.
+    \since 5.10
+
+    The template parameter \c T must be a C++ integer type:
+    \list
+       \li 8-bit: char, signed char, unsigned char, qint8, quint8
+       \li 16-bit: short, unsigned short, qint16, quint16, char16_t (C++11)
+       \li 32-bit: int, unsigned int, qint32, quint32, char32_t (C++11)
+       \li 64-bit: long long, unsigned long long, qint64, quint64
+       \li platform-specific size: long, unsigned long
+       \li pointer size: qintptr, quintptr, qptrdiff
+    \endlist
+
+    \note Using this class may be slower than using native integers, so only use it when
+    an exact endian is needed.
+*/
+
+/*! \fn QBEInteger::QBEInteger(T value)
+
+    Constructs a QBEInteger with the given \a value.
+*/
+
+/*! \fn QBEInteger &QBEInteger::operator=(T value)
+
+    Assigns \a value to this QBEInteger and returns a reference to
+    this QBEInteger.
+*/
+
+/*!
+    \fn QBEInteger::operator T() const
+
+    Returns the value of this QBEInteger as a native integer.
+*/
+
+/*!
+    \fn bool QBEInteger::operator==(QBEInteger other) const
+
+    Returns \c true if the value of this QBEInteger is equal to the value of \a other.
+*/
+
+/*!
+    \fn bool QBEInteger::operator!=(QBEInteger other) const
+
+    Returns \c true if the value of this QBEInteger is not equal to the value of \a other.
+*/
+
+/*!
+    \fn QBEInteger &QBEInteger::operator+=(T i)
+
+    Adds \a i to this QBEInteger and returns a reference to
+    this object.
+*/
+
+/*!
+    \fn QBEInteger &QBEInteger::operator-=(T i)
+
+    Subtracts \a i from this QBEInteger and returns a reference to
+    this object.
+*/
+
+/*!
+    \fn QBEInteger &QBEInteger::operator*=(T i)
+
+    Multiplies \a i with this QBEInteger and returns a reference to
+    this object.
+*/
+
+/*!
+    \fn QBEInteger &QBEInteger::operator/=(T i)
+
+    Divides this QBEInteger with \a i and returns a reference to
+    this object.
+*/
+
+/*!
+    \fn QBEInteger &QBEInteger::operator%=(T i)
+
+    Sets this QBEInteger to the remainder of a division by \a i and
+    returns a reference to this object.
+*/
+
+/*!
+    \fn QBEInteger &QBEInteger::operator>>=(T i)
+
+    Performs a left-shift by \a i on this QBEInteger and returns a
+    reference to this object.
+*/
+
+/*!
+    \fn QBEInteger &QBEInteger::operator<<=(T i)
+
+    Performs a right-shift by \a i on this QBEInteger and returns a
+    reference to this object.
+*/
+
+/*!
+    \fn QBEInteger &QBEInteger::operator|=(T i)
+
+    Performs a bitwise OR with \a i onto this QBEInteger and returns a reference to
+    this object.
+*/
+
+/*!
+    \fn QBEInteger &QBEInteger::operator&=(T i)
+
+    Performs a bitwise AND with \a i onto this QBEInteger and returns a reference to
+    this object.
+*/
+
+/*!
+    \fn QBEInteger &QBEInteger::operator^=(T i)
+
+    Performs a bitwise XOR with \a i onto this QBEInteger and returns a reference to
+    this object.
+*/
+
+/*!
+    \typedef quint16_le
+    \relates <QtEndian>
+    \since 5.10
+
+    Typedef for QLEInteger<quint16>. This type is guaranteed to be stored in memory as
+    a 16-bit little-endian unsigned integer on all platforms supported by Qt.
+
+    \sa quint16
+*/
+
+/*!
+    \typedef quint32_le
+    \relates <QtEndian>
+    \since 5.10
+
+    Typedef for QLEInteger<quint32>. This type is guaranteed to be stored in memory as
+    a 32-bit little-endian unsigned integer on all platforms supported by Qt.
+
+    \sa quint32
+*/
+
+/*!
+    \typedef quint64_le
+    \relates <QtEndian>
+    \since 5.10
+
+    Typedef for QLEInteger<quint64>. This type is guaranteed to be stored in memory as
+    a 64-bit little-endian unsigned integer on all platforms supported by Qt.
+
+    \sa quint64
+*/
+
+/*!
+    \typedef quint16_be
+    \relates <QtEndian>
+    \since 5.10
+
+    Typedef for QBEInteger<quint16>. This type is guaranteed to be stored in memory as
+    a 16-bit big-endian unsigned integer on all platforms supported by Qt.
+
+    \sa quint16
+*/
+
+/*!
+    \typedef quint32_be
+    \relates <QtEndian>
+    \since 5.10
+
+    Typedef for QBEInteger<quint32>. This type is guaranteed to be stored in memory as
+    a 32-bit big-endian unsigned integer on all platforms supported by Qt.
+
+    \sa quint32
+*/
+
+/*!
+    \typedef quint64_be
+    \relates <QtEndian>
+    \since 5.10
+
+    Typedef for QBEInteger<quint64>. This type is guaranteed to be stored in memory as
+    a 64-bit big-endian unsigned integer on all platforms supported by Qt.
+
+    \sa quint64
+*/
+
+/*!
+    \typedef qint16_le
+    \relates <QtEndian>
+    \since 5.10
+
+    Typedef for QLEInteger<qint16>. This type is guaranteed to be stored in memory as
+    a 16-bit little-endian signed integer on all platforms supported by Qt.
+
+    \sa qint16
+*/
+
+/*!
+    \typedef qint32_le
+    \relates <QtEndian>
+    \since 5.10
+
+    Typedef for QLEInteger<qint32>. This type is guaranteed to be stored in memory as
+    a 32-bit little-endian signed integer on all platforms supported by Qt.
+
+    \sa qint32
+*/
+
+/*!
+    \typedef qint64_le
+    \relates <QtEndian>
+    \since 5.10
+
+    Typedef for QLEInteger<qint64>. This type is guaranteed to be stored in memory as
+    a 64-bit little-endian signed integer on all platforms supported by Qt.
+
+    \sa qint64
+*/
+
+/*!
+    \typedef qint16_be
+    \relates <QtEndian>
+    \since 5.10
+
+    Typedef for QBEInteger<qint16>. This type is guaranteed to be stored in memory as
+    a 16-bit big-endian signed integer on all platforms supported by Qt.
+
+    \sa qint16
+*/
+
+/*!
+    \typedef qint32_be
+    \relates <QtEndian>
+    \since 5.10
+
+    Typedef for QBEInteger<qint32>. This type is guaranteed to be stored in memory as
+    a 32-bit big-endian signed integer on all platforms supported by Qt.
+
+    \sa qint32
+*/
+
+/*!
+    \typedef qint64_be
+    \relates <QtEndian>
+    \since 5.10
+
+    Typedef for QBEInteger<qint64>. This type is guaranteed to be stored in memory as
+    a 64-bit big-endian signed integer on all platforms supported by Qt.
+
+    \sa qint64
+*/
diff --git a/src/corelib/global/qendian_p.h b/src/corelib/global/qendian_p.h
index 42d91cf735..c830e65b54 100644
--- a/src/corelib/global/qendian_p.h
+++ b/src/corelib/global/qendian_p.h
@@ -55,87 +55,6 @@
 
 QT_BEGIN_NAMESPACE
 
-template<class S>
-class QSpecialInteger
-{
-    typedef typename S::StorageType T;
-    T val;
-public:
-    QSpecialInteger() = default;
-    explicit Q_DECL_CONSTEXPR QSpecialInteger(T i) : val(S::toSpecial(i)) {}
-
-    QSpecialInteger &operator =(T i) { val = S::toSpecial(i); return *this; }
-    operator T() const { return S::fromSpecial(val); }
-
-    bool operator ==(QSpecialInteger<S> i) const { return val == i.val; }
-    bool operator !=(QSpecialInteger<S> i) const { return val != i.val; }
-
-    QSpecialInteger &operator +=(T i)
-    {   return (*this = S::fromSpecial(val) + i); }
-    QSpecialInteger &operator -=(T i)
-    {   return (*this = S::fromSpecial(val) - i); }
-    QSpecialInteger &operator *=(T i)
-    {   return (*this = S::fromSpecial(val) * i); }
-    QSpecialInteger &operator >>=(T i)
-    {   return (*this = S::fromSpecial(val) >> i); }
-    QSpecialInteger &operator <<=(T i)
-    {   return (*this = S::fromSpecial(val) << i); }
-    QSpecialInteger &operator /=(T i)
-    {   return (*this = S::fromSpecial(val) / i); }
-    QSpecialInteger &operator %=(T i)
-    {   return (*this = S::fromSpecial(val) % i); }
-    QSpecialInteger &operator |=(T i)
-    {   return (*this = S::fromSpecial(val) | i); }
-    QSpecialInteger &operator &=(T i)
-    {   return (*this = S::fromSpecial(val) & i); }
-    QSpecialInteger &operator ^=(T i)
-    {   return (*this = S::fromSpecial(val) ^ i); }
-};
-
-template<typename T>
-class QLittleEndianStorageType {
-public:
-    typedef T StorageType;
-    static Q_DECL_CONSTEXPR T toSpecial(T source) { return qToLittleEndian(source); }
-    static Q_DECL_CONSTEXPR T fromSpecial(T source) { return qFromLittleEndian(source); }
-};
-
-template<typename T>
-class QBigEndianStorageType {
-public:
-    typedef T StorageType;
-    static Q_DECL_CONSTEXPR T toSpecial(T source) { return qToBigEndian(source); }
-    static Q_DECL_CONSTEXPR T fromSpecial(T source) { return qFromBigEndian(source); }
-};
-
-template<typename T>
-using QLEInteger = QSpecialInteger<QLittleEndianStorageType<T>>;
-
-template<typename T>
-using QBEInteger = QSpecialInteger<QBigEndianStorageType<T>>;
-
-template <typename T>
-class QTypeInfo<QLEInteger<T> >
-    : public QTypeInfoMerger<QLEInteger<T>, T> {};
-
-template <typename T>
-class QTypeInfo<QBEInteger<T> >
-    : public QTypeInfoMerger<QBEInteger<T>, T> {};
-
-typedef QLEInteger<qint16> qint16_le;
-typedef QLEInteger<qint32> qint32_le;
-typedef QLEInteger<qint64> qint64_le;
-typedef QLEInteger<quint16> quint16_le;
-typedef QLEInteger<quint32> quint32_le;
-typedef QLEInteger<quint64> quint64_le;
-
-typedef QBEInteger<qint16> qint16_be;
-typedef QBEInteger<qint32> qint32_be;
-typedef QBEInteger<qint64> qint64_be;
-typedef QBEInteger<quint16> quint16_be;
-typedef QBEInteger<quint32> quint32_be;
-typedef QBEInteger<quint64> quint64_be;
-
 // Note if using multiple of these bitfields in a union; the underlying storage type must
 // match. Since we always use an unsigned storage type, unsigned and signed versions may
 // be used together, but different bit-widths may not.