From 0e7bd559e4ee3130ccd45c688af5d6f248831a94 Mon Sep 17 00:00:00 2001 From: Jonathan Wakely Date: Tue, 7 May 2019 23:46:56 +0100 Subject: [PATCH] Improve API docs for std::pair * include/bits/stl_pair.h: Improve docs. * include/std/tuple: Likewise. From-SVN: r270989 --- libstdc++-v3/ChangeLog | 3 ++ libstdc++-v3/include/bits/stl_pair.h | 65 ++++++++++++++++++++-------- libstdc++-v3/include/std/tuple | 8 ++++ 3 files changed, 59 insertions(+), 17 deletions(-) diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index 5c668bac172..acf58e9c22b 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,5 +1,8 @@ 2019-05-07 Jonathan Wakely + * include/bits/stl_pair.h: Improve docs. + * include/std/tuple: Likewise. + * doc/doxygen/doxygroups.cc (std::literals): Add documentation for inline namespace. * include/std/chrono: Improve docs. diff --git a/libstdc++-v3/include/bits/stl_pair.h b/libstdc++-v3/include/bits/stl_pair.h index 56565fd1ece..f99b774c21e 100644 --- a/libstdc++-v3/include/bits/stl_pair.h +++ b/libstdc++-v3/include/bits/stl_pair.h @@ -72,13 +72,15 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION */ #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 class tuple; @@ -198,21 +200,25 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION #endif // C++11 }; + /// @endcond + /** * @brief Struct holding two objects of arbitrary type. * * @tparam _T1 Type of first object. * @tparam _T2 Type of second object. + * + * */ template 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 @@ -243,14 +249,17 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION : 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; + /// @endcond + /// Construct from two const lvalues, allowing implicit conversions. template() @@ -260,6 +269,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION constexpr pair(const _T1& __a, const _T2& __b) : first(__a), second(__b) { } + /// Construct from two const lvalues, disallowing implicit conversions. template() @@ -269,18 +279,21 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION 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 pair(const pair<_U1, _U2>& __p) : first(__p.first), second(__p.second) { } #else // Shortcut for constraining the templates that take pairs. + /// @cond undocumented template using _PCCFP = _PCC::value || !is_same<_T2, _U2>::value, _T1, _T2>; + /// @endcond template::template @@ -299,9 +312,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION 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, @@ -438,6 +454,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION #endif }; + /// @relates pair @{ + #if __cpp_deduction_guides >= 201606 template pair(_T1, _T2) -> pair<_T1, _T2>; #endif @@ -448,7 +466,13 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION operator==(const pair<_T1, _T2>& __x, const pair<_T1, _T2>& __y) { return __x.first == __y.first && __x.second == __y.second; } - /// + /** 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 inline _GLIBCXX_CONSTEXPR bool operator<(const pair<_T1, _T2>& __x, const pair<_T1, _T2>& __y) @@ -480,9 +504,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION { 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 inline #if __cplusplus > 201402L || !defined(__STRICT_ANSI__) // c++1z or gnu++11 @@ -504,15 +530,20 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION #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 diff --git a/libstdc++-v3/include/std/tuple b/libstdc++-v3/include/std/tuple index fba28f963cd..956e031ae9d 100644 --- a/libstdc++-v3/include/std/tuple +++ b/libstdc++-v3/include/std/tuple @@ -1691,6 +1691,14 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION struct uses_allocator, _Alloc> : true_type { }; // See stl_pair.h... + /** "piecewise construction" using a tuple of arguments for each member. + * + * @param __first Arguments for the first member of the pair. + * @param __second Arguments for the second member of the pair. + * + * The elements of each tuple will be used as the constructor arguments + * for the data members of the pair. + */ template template inline -- 2.30.2