diff options
author | Giuseppe D'Angelo <giuseppe.dangelo@kdab.com> | 2020-02-15 00:11:22 +0100 |
---|---|---|
committer | Giuseppe D'Angelo <giuseppe.dangelo@kdab.com> | 2020-06-10 16:49:08 +0200 |
commit | 8e98a161e993c6636d217276a0f2373d642ff050 (patch) | |
tree | 23adce823bfab9795cf7b775d35f14be7baedc10 /src/corelib/tools/qpair.qdoc | |
parent | ce5931aaf2c9698925366e787d08747a1c60c378 (diff) |
Long live std::pair!
Make QPair an alias for std::pair, and qMakePair just a forwarder
towards std::make_pair.
Why? Fundamentally to ditch a bunch of NIH code; gain for free
structured bindings, std::tuple and std::reference_wrapper
compatibility, and so on.
Breakages:
* Some that code manually forward declares QPair.
We don't care about it (<QContainerFwd> is the proper way).
* Some code that overloads on std::pair and QPair. Luckily
it's mostly centralized: debug, metatypes, testing macros.
Just remove the QPair overload.
* Usages of qMakePair forcing the template type parameters.
There are a handful of these in qtbase, but only one was actually
broken.
* std::pair is NOT (and will never likely be) trivially copiable.
This is agreed to be a mistake done by practically all implementations
in C++11, can can't be fixed without breaking ABI.
Some code using QPair assuming it's trivially copiable may break;
exactly one occurrence was in qtbase.
* QMetaType logic extracts the type names in two different ways,
one by looking at the source code string (e.g. extracted by moc)
and one via some ad-hoc reflection in C++. We need to make
"QPair" (as spelled in the source code) be the same as "std::pair"
(gathered via reflection, which will see through the alias)
when compared. The way it's already done e.g. for QList is
by actually replacing the moc-extracted name with the name
of the actual type used in C++; do the same here.
On libc++, std::pair is actually in an inline namespace --
i.e. std::__1::pair; the reflection will extract and store
"std::__1::pair" so we need an ad-hoc fix to QMetaType.
[ChangeLog][QtCore][QPair] QPair is now an alias to std::pair,
and does not exist as a class in Qt any more. This may break
code such as functions overloaded for both QPair and std::pair.
Usually, the overload taking a QPair can be safely discarded,
leaving only the one taking a std::pair. QPair API has not changed,
and qMakePair is still available for compatibility (although
new code is encouraged to use std::pair and std::make_pair
directly instead).
Change-Id: I7725c751bf23946cde577b1406e86a336c0a3dcf
Reviewed-by: Lars Knoll <lars.knoll@qt.io>
Diffstat (limited to 'src/corelib/tools/qpair.qdoc')
-rw-r--r-- | src/corelib/tools/qpair.qdoc | 251 |
1 files changed, 10 insertions, 241 deletions
diff --git a/src/corelib/tools/qpair.qdoc b/src/corelib/tools/qpair.qdoc index 65576ef2e6..0e17b6c3b9 100644 --- a/src/corelib/tools/qpair.qdoc +++ b/src/corelib/tools/qpair.qdoc @@ -28,255 +28,24 @@ /*! \class QPair \inmodule QtCore - \reentrant - \brief The QPair class is a template class that stores a pair of items. + \obsolete + \brief QPair is an alias for std::pair. \ingroup tools - QPair\<T1, T2\> can be used in your application if the STL \c - pair type is not available. It stores one value of type T1 and - one value of type T2. It can be used as a return value for a - function that needs to return two values, or as the value type of - a \l{Container classes}{generic container}. - - Here's an example of a QPair that stores one QString and one \c - double value: - - \snippet code/doc_src_qpair.cpp 0 - - The components are accessible as public data members called \l - first and \l second. For example: - - \snippet code/doc_src_qpair.cpp 1 - - Note, however, that it is almost always preferable to define a small struct - to hold the result of a function with multiple return values. A struct - trivially generalizes to more than two values, and allows more descriptive - member names than \c{first} and \c{second}: - - \snippet code/doc_src_qpair.cpp struct - - The advent of C++11 automatic variable type deduction (\c{auto}) shifts the - emphasis from the type name to the name of functions and members. Thus, QPair, - like \c{std::pair} and \c{std::tuple}, is mostly useful in generic (template) - code, where defining a dedicated type is not possible. - - QPair's template data types (T1 and T2) must be \l{assignable - data types}. You cannot, for example, store a QWidget as a value; - instead, store a QWidget *. A few functions have additional - requirements; these requirements are documented on a per-function - basis. + QPair\<T1, T2\> is a typedef for std::pair\<T1, T2\>. + It is provided for backwards compatibility. Use std::pair directly + instead. \sa {Container Classes} */ -/*! \typedef QPair::first_type - - The type of the first element in the pair (T1). - - \sa first -*/ - -/*! \typedef QPair::second_type - - The type of the second element in the pair (T2). - - \sa second -*/ - -/*! \variable QPair::first - - The first element in the pair. -*/ - -/*! \variable QPair::second - - The second element in the pair. -*/ - -/*! \fn template <class T1, class T2> QPair<T1, T2>::QPair() - - Constructs an empty pair. The \c first and \c second elements are - initialized with \l{default-constructed value}s. -*/ - -/*! - \fn template <class T1, class T2> QPair<T1, T2>::QPair(const T1 &value1, const T2 &value2) - - Constructs a pair and initializes the \c first element with \a - value1 and the \c second element with \a value2. - - \sa qMakePair() -*/ - -/*! -\fn template <class T1, class T2> void QPair<T1, T2>::swap(QPair &other) - - \since 5.5 - Swaps this pair with \a other. - - Equivalent to - \code - qSwap(this->first, other.first); - qSwap(this->second, other.second); - \endcode - - Swap overloads are found in namespace \c std as well as via - argument-dependent lookup (ADL) in the namespace of \c{T} . -*/ - -/*! -\fn template <class T1, class T2> void swap(QPair<T1, T2> &lhs, QPair<T1, T2> &rhs) - \overload - \relates QPair - \since 5.5 - - Swaps \a lhs with \a rhs. -*/ - -/*! - \fn template <class T1, class T2> template <typename TT1, typename TT2> QPair<T1, T2>::QPair(const QPair<TT1, TT2> &p) - \since 5.2 - - Constructs a pair from the other pair \a p, of types TT1 and TT2. This - constructor will fail if \c first cannot be initialized from \c p.first or - if \c second cannot be initialized from \c p.second. - - \sa qMakePair() -*/ - -/*! - \fn template <class T1, class T2> template <typename TT1, typename TT2> QPair<T1, T2>::QPair(QPair<TT1, TT2> &&p) - \since 5.2 - - Move-constructs a QPair instance, making it point to the same object that \a p was pointing to. -*/ - -/*! - \fn template <class T1, class T2> template <typename TT1, typename TT2> QPair & QPair<T1, T2>::operator=(const QPair<TT1, TT2> &p) - \since 5.2 - - Copies pair \a p into this pair. - - \sa qMakePair() -*/ - -/*! - \fn template <class T1, class T2> template <typename TT1, typename TT2> QPair & QPair<T1, T2>::operator=(QPair<TT1, TT2> &&p) - \since 5.2 - - Move-assigns pair \a p into this pair instance. -*/ - -/*! \fn template <class T1, class T2> bool operator==(const QPair<T1, T2> &p1, const QPair<T1, T2> &p2) - - \relates QPair - - Returns \c true if \a p1 is equal to \a p2; otherwise returns \c false. - Two pairs compare equal if their \c first data members compare - equal and if their \c second data members compare equal. - - This function requires the T1 and T2 types to have an - implementation of \c operator==(). -*/ - -/*! \fn template <class T1, class T2> bool operator!=(const QPair<T1, T2> &p1, const QPair<T1, T2> &p2) - - \relates QPair - - Returns \c true if \a p1 is not equal to \a p2; otherwise returns - false. Two pairs compare as not equal if their \c first data - members are not equal or if their \c second data members are not - equal. - - This function requires the T1 and T2 types to have an - implementation of \c operator==(). -*/ - -/*! \fn template <class T1, class T2> bool operator<(const QPair<T1, T2> &p1, const QPair<T1, T2> &p2) - - \relates QPair - - Returns \c true if \a p1 is less than \a p2; otherwise returns - false. The comparison is done on the \c first members of \a p1 - and \a p2; if they compare equal, the \c second members are - compared to break the tie. - - This function requires the T1 and T2 types to have an - implementation of \c operator<(). -*/ - -/*! \fn template <class T1, class T2> bool operator>(const QPair<T1, T2> &p1, const QPair<T1, T2> &p2) - - \relates QPair - - Returns \c true if \a p1 is greater than \a p2; otherwise returns - false. The comparison is done on the \c first members of \a p1 - and \a p2; if they compare equal, the \c second members are - compared to break the tie. - - This function requires the T1 and T2 types to have an - implementation of \c operator<(). -*/ - -/*! \fn template <class T1, class T2> bool operator<=(const QPair<T1, T2> &p1, const QPair<T1, T2> &p2) - - \relates QPair - - Returns \c true if \a p1 is less than or equal to \a p2; otherwise - returns \c false. The comparison is done on the \c first members of - \a p1 and \a p2; if they compare equal, the \c second members are - compared to break the tie. - - This function requires the T1 and T2 types to have an - implementation of \c operator<(). -*/ - -/*! \fn template <class T1, class T2> bool operator>=(const QPair<T1, T2> &p1, const QPair<T1, T2> &p2) - - \relates QPair - - Returns \c true if \a p1 is greater than or equal to \a p2; - otherwise returns \c false. The comparison is done on the \c first - members of \a p1 and \a p2; if they compare equal, the \c second - members are compared to break the tie. - - This function requires the T1 and T2 types to have an - implementation of \c operator<(). -*/ - /*! - \fn template <class T1, class T2> QPair<T1, T2> qMakePair(const T1 &value1, const T2 &value2) - - \relates QPair - - Returns a QPair\<T1, T2\> that contains \a value1 and \a value2. - Example: - - \snippet code/doc_src_qpair.cpp 2 - - This is equivalent to QPair<T1, T2>(\a value1, \a value2), but - usually requires less typing. -*/ - -/*! \fn template <class T1, class T2> QDataStream &operator>>(QDataStream &in, QPair<T1, T2> &pair) - - \relates QPair - - Reads a pair from stream \a in into \a pair. - - This function requires the T1 and T2 types to implement \c operator>>(). - - \sa {Serializing Qt Data Types} -*/ - -/*! \fn template <class T1, class T2> QDataStream &operator<<(QDataStream &out, const QPair<T1, T2> &pair) - + \fn template <class T1, class T2> QPair<T1, T2> qMakePair(T1 &&value1, T2 &&value2) + \obsolete \relates QPair - Writes the pair \a pair to stream \a out. - - This function requires the T1 and T2 types to implement \c operator<<(). - - \sa {Serializing Qt Data Types} + qMakePair forwards its arguments to std::make_pair, and returns + the resulting std::pair. It is provided for backwards compatibility. + Use std::make_pair directly instead. */ |