*/
#if __cplusplus >= 201103L
- /// piecewise_construct_t
+ /// Tag type for piecewise construction of std::pair objects.
struct piecewise_construct_t { explicit piecewise_construct_t() = default; };
- /// piecewise_construct
+ /// Tag for piecewise construction of std::pair objects.
_GLIBCXX17_INLINE constexpr piecewise_construct_t piecewise_construct =
piecewise_construct_t();
+ /// @cond undocumented
+
// Forward declarations.
template<typename...>
class tuple;
#endif // C++11
};
+ /// @endcond
+
/**
* @brief Struct holding two objects of arbitrary type.
*
* @tparam _T1 Type of first object.
* @tparam _T2 Type of second object.
+ *
+ * <https://gcc.gnu.org/onlinedocs/libstdc++/manual/utilities.html>
*/
template<typename _T1, typename _T2>
struct pair
: private __pair_base<_T1, _T2>
{
- typedef _T1 first_type; /// @c first_type is the first bound type
- typedef _T2 second_type; /// @c second_type is the second bound type
+ typedef _T1 first_type; ///< The type of the `first` member
+ typedef _T2 second_type; ///< The type of the `second` member
- _T1 first; /// @c first is a copy of the first object
- _T2 second; /// @c second is a copy of the second object
+ _T1 first; ///< The first member
+ _T2 second; ///< The second member
// _GLIBCXX_RESOLVE_LIB_DEFECTS
// 265. std::pair::pair() effects overly restrictive
: first(), second() { }
#endif
- /** Two objects may be passed to a @c pair constructor to be copied. */
#if __cplusplus < 201103L
+ /// Two objects may be passed to a @c pair constructor to be copied.
pair(const _T1& __a, const _T2& __b)
: first(__a), second(__b) { }
#else
// Shortcut for constraining the templates that don't take pairs.
+ /// @cond undocumented
using _PCCP = _PCC<true, _T1, _T2>;
+ /// @endcond
+ /// Construct from two const lvalues, allowing implicit conversions.
template<typename _U1 = _T1, typename _U2=_T2, typename
enable_if<_PCCP::template
_ConstructiblePair<_U1, _U2>()
constexpr pair(const _T1& __a, const _T2& __b)
: first(__a), second(__b) { }
+ /// Construct from two const lvalues, disallowing implicit conversions.
template<typename _U1 = _T1, typename _U2=_T2, typename
enable_if<_PCCP::template
_ConstructiblePair<_U1, _U2>()
explicit constexpr pair(const _T1& __a, const _T2& __b)
: first(__a), second(__b) { }
#endif
+ //@}
- /** There is also a templated copy ctor for the @c pair class itself. */
#if __cplusplus < 201103L
+ /// There is also a templated constructor to convert from other pairs.
template<typename _U1, typename _U2>
pair(const pair<_U1, _U2>& __p)
: first(__p.first), second(__p.second) { }
#else
// Shortcut for constraining the templates that take pairs.
+ /// @cond undocumented
template <typename _U1, typename _U2>
using _PCCFP = _PCC<!is_same<_T1, _U1>::value
|| !is_same<_T2, _U2>::value,
_T1, _T2>;
+ /// @endcond
template<typename _U1, typename _U2, typename
enable_if<_PCCFP<_U1, _U2>::template
bool>::type=false>
explicit constexpr pair(const pair<_U1, _U2>& __p)
: first(__p.first), second(__p.second) { }
+#endif
- constexpr pair(const pair&) = default;
- constexpr pair(pair&&) = default;
+#if __cplusplus >= 201103L
+ constexpr pair(const pair&) = default; ///< Copy constructor
+ constexpr pair(pair&&) = default; ///< Move constructor
// DR 811.
template<typename _U1, typename
return *this;
}
+ /// Swap the first members and then the second members.
void
swap(pair& __p)
noexcept(__and_<__is_nothrow_swappable<_T1>,
#endif
};
+ /// @relates pair @{
+
#if __cpp_deduction_guides >= 201606
template<typename _T1, typename _T2> pair(_T1, _T2) -> pair<_T1, _T2>;
#endif
operator==(const pair<_T1, _T2>& __x, const pair<_T1, _T2>& __y)
{ return __x.first == __y.first && __x.second == __y.second; }
- /// <http://gcc.gnu.org/onlinedocs/libstdc++/manual/utilities.html>
+ /** Defines a lexicographical order for pairs.
+ *
+ * For two pairs of the same type, `P` is ordered before `Q` if
+ * `P.first` is less than `Q.first`, or if `P.first` and `Q.first`
+ * are equivalent (neither is less than the other) and `P.second` is less
+ * than `Q.second`.
+ */
template<typename _T1, typename _T2>
inline _GLIBCXX_CONSTEXPR bool
operator<(const pair<_T1, _T2>& __x, const pair<_T1, _T2>& __y)
{ return !(__x < __y); }
#if __cplusplus >= 201103L
- /// See std::pair::swap().
- // Note: no std::swap overloads in C++03 mode, this has performance
- // implications, see, eg, libstdc++/38466.
+ /** Swap overload for pairs. Calls std::pair::swap().
+ *
+ * @note This std::swap overload is not declared in C++03 mode,
+ * which has performance implications, e.g. see https://gcc.gnu.org/PR38466
+ */
template<typename _T1, typename _T2>
inline
#if __cplusplus > 201402L || !defined(__STRICT_ANSI__) // c++1z or gnu++11
#endif
#endif // __cplusplus >= 201103L
+ // @} relates pair
+
/**
* @brief A convenience wrapper for creating a pair from two objects.
* @param __x The first object.
* @param __y The second object.
* @return A newly-constructed pair<> object of the appropriate type.
*
- * The standard requires that the objects be passed by reference-to-const,
- * but LWG issue #181 says they should be passed by const value. We follow
- * the LWG by default.
+ * The C++98 standard says the objects are passed by reference-to-const,
+ * but C++03 says they are passed by value (this was LWG issue #181).
+ *
+ * Since C++11 they have been passed by forwarding reference and then
+ * forwarded to the new members of the pair. To create a pair with a
+ * member of reference type, pass a `reference_wrapper` to this function.
*/
// _GLIBCXX_RESOLVE_LIB_DEFECTS
// 181. make_pair() unintended behavior
projects / thirdparty / gcc.git / commitdiff
