Skip to content

R
riscv-gcc-1
Commit 0e7bd559 by Jonathan Wakely Committed by Jonathan Wakely
Options

Improve API docs for std::pair 

	* include/bits/stl_pair.h: Improve docs.
	* include/std/tuple: Likewise.

From-SVN: r270989
parent c34d3fd3
Showing with 59 additions and 17 deletions
libstdc++-v3/ChangeLog
2019-05-07 Jonathan Wakely <jwakely@redhat.com>
* 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.
......
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<typename...>
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.
*
* <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
......@@ -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<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>()
......@@ -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<typename _U1 = _T1, typename _U2=_T2, typename
enable_if<_PCCP::template
_ConstructiblePair<_U1, _U2>()
......@@ -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<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
......@@ -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<typename _U1, typename
......@@ -420,6 +435,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
return *this;
}
/// Swap the first members and then the second members.
void
swap(pair& __p)
noexcept(__and_<__is_nothrow_swappable<_T1>,
......@@ -438,6 +454,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
#endif
};
/// @relates pair @{
#if __cpp_deduction_guides >= 201606
template<typename _T1, typename _T2> 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; }
/// <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)
......@@ -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<typename _T1, typename _T2>
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
......
libstdc++-v3/include/std/tuple
......@@ -1691,6 +1691,14 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
struct uses_allocator<tuple<_Types...>, _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<class _T1, class _T2>
template<typename... _Args1, typename... _Args2>
inline
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment