From 0a2bf18874eb2c54202b9890f3b82776b08e55a1 Mon Sep 17 00:00:00 2001 From: Jonathan Wakely Date: Thu, 14 Jul 2016 11:02:10 +0100 Subject: [PATCH] Improve doxygen comments for allocators in containers PR libstdc++/70716 * include/bits/forward_list.h (forward_list): Update doxygen comments to reflect allocator propagation semantics. Remove ambiguous statements about data being lost. * include/bits/stl_deque.h (deque): Likewise. * include/bits/stl_list.h (list): Likewise. * include/bits/stl_map.h (map): Likewise. * include/bits/stl_multimap.h (multimap): Likewise. * include/bits/stl_multiset.h (multiset): Likewise. * include/bits/stl_set.h (set): Likewise. * include/bits/stl_vector.h (vector): Likewise. * include/bits/unordered_map.h (unordered_map, unordered_multimap): Likewise. * include/bits/unordered_set.h (unordered_set, unordered_multiset): Likewise. From-SVN: r238332 --- libstdc++-v3/ChangeLog | 18 +++++++++++++ libstdc++-v3/include/bits/forward_list.h | 16 ++++++++---- libstdc++-v3/include/bits/stl_deque.h | 20 +++++++++------ libstdc++-v3/include/bits/stl_list.h | 21 ++++++++++----- libstdc++-v3/include/bits/stl_map.h | 13 ++++++---- libstdc++-v3/include/bits/stl_multimap.h | 13 ++++++---- libstdc++-v3/include/bits/stl_multiset.h | 13 ++++++---- libstdc++-v3/include/bits/stl_set.h | 13 ++++++---- libstdc++-v3/include/bits/stl_vector.h | 31 ++++++++++++++--------- libstdc++-v3/include/bits/unordered_map.h | 14 +++++----- libstdc++-v3/include/bits/unordered_set.h | 10 +++----- 11 files changed, 117 insertions(+), 65 deletions(-) diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index a34ca218797..491e0d81a43 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,3 +1,21 @@ +2016-07-14 Jonathan Wakely + + PR libstdc++/70716 + * include/bits/forward_list.h (forward_list): Update doxygen comments + to reflect allocator propagation semantics. Remove ambiguous + statements about data being lost. + * include/bits/stl_deque.h (deque): Likewise. + * include/bits/stl_list.h (list): Likewise. + * include/bits/stl_map.h (map): Likewise. + * include/bits/stl_multimap.h (multimap): Likewise. + * include/bits/stl_multiset.h (multiset): Likewise. + * include/bits/stl_set.h (set): Likewise. + * include/bits/stl_vector.h (vector): Likewise. + * include/bits/unordered_map.h (unordered_map, unordered_multimap): + Likewise. + * include/bits/unordered_set.h (unordered_set, unordered_multiset): + Likewise. + 2016-07-14 Ville Voutilainen Implement P0032R3, Homogeneous interface for variant, any and optional, diff --git a/libstdc++-v3/include/bits/forward_list.h b/libstdc++-v3/include/bits/forward_list.h index 2e8d39f712b..39615094131 100644 --- a/libstdc++-v3/include/bits/forward_list.h +++ b/libstdc++-v3/include/bits/forward_list.h @@ -566,8 +566,9 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * @param __list A %forward_list of identical element and allocator * types. * - * All the elements of @a __list are copied, but unlike the copy - * constructor, the allocator object is not copied. + * All the elements of @a __list are copied. + * + * Whether the allocator is copied depends on the allocator traits. */ forward_list& operator=(const forward_list& __list); @@ -579,7 +580,10 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * * The contents of @a __list are moved into this %forward_list * (without copying, if the allocators permit it). - * @a __list is a valid, but unspecified %forward_list + * + * Afterwards @a __list is a valid, but unspecified %forward_list + * + * Whether the allocator is moved depends on the allocator traits. */ forward_list& operator=(forward_list&& __list) @@ -617,7 +621,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * * Note that the assignment completely changes the %forward_list and * that the number of elements of the resulting %forward_list is the - * same as the number of elements assigned. Old data is lost. + * same as the number of elements assigned. */ template> @@ -636,7 +640,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * This function fills a %forward_list with @a __n copies of the * given value. Note that the assignment completely changes the * %forward_list, and that the resulting %forward_list has __n - * elements. Old data is lost. + * elements. */ void assign(size_type __n, const _Tp& __val) @@ -991,6 +995,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * time. Note that the global std::swap() function is * specialized such that std::swap(l1,l2) will feed to this * function. + * + * Whether the allocators are swapped depends on the allocator traits. */ void swap(forward_list& __list) noexcept diff --git a/libstdc++-v3/include/bits/stl_deque.h b/libstdc++-v3/include/bits/stl_deque.h index 66b8da6a854..7192f65a1c0 100644 --- a/libstdc++-v3/include/bits/stl_deque.h +++ b/libstdc++-v3/include/bits/stl_deque.h @@ -939,8 +939,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * @brief %Deque copy constructor. * @param __x A %deque of identical element and allocator types. * - * The newly-created %deque uses a copy of the allocation object used - * by @a __x. + * The newly-created %deque uses a copy of the allocator object used + * by @a __x (unless the allocator traits dictate a different object). */ deque(const deque& __x) : _Base(_Alloc_traits::_S_select_on_copy(__x._M_get_Tp_allocator()), @@ -1046,8 +1046,10 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * @brief %Deque assignment operator. * @param __x A %deque of identical element and allocator types. * - * All the elements of @a x are copied, but unlike the copy constructor, - * the allocator object is not copied. + * All the elements of @a x are copied. + * + * The newly-created %deque uses a copy of the allocator object used + * by @a __x (unless the allocator traits dictate a different object). */ deque& operator=(const deque& __x); @@ -1078,7 +1080,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * * Note that the assignment completely changes the %deque and that the * resulting %deque's size is the same as the number of elements - * assigned. Old data may be lost. + * assigned. */ deque& operator=(initializer_list __l) @@ -1097,7 +1099,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * This function fills a %deque with @a n copies of the given * value. Note that the assignment completely changes the * %deque and that the resulting %deque's size is the same as - * the number of elements assigned. Old data may be lost. + * the number of elements assigned. */ void assign(size_type __n, const value_type& __val) @@ -1113,7 +1115,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * * Note that the assignment completely changes the %deque and that the * resulting %deque's size is the same as the number of elements - * assigned. Old data may be lost. + * assigned. */ #if __cplusplus >= 201103L template __l) @@ -1803,6 +1805,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * (Four pointers, so it should be quite fast.) * Note that the global std::swap() function is specialized such that * std::swap(d1,d2) will feed to this function. + * + * Whether the allocators are swapped depends on the allocator traits. */ void swap(deque& __x) _GLIBCXX_NOEXCEPT diff --git a/libstdc++-v3/include/bits/stl_list.h b/libstdc++-v3/include/bits/stl_list.h index 1f875177a78..40e2d1862c4 100644 --- a/libstdc++-v3/include/bits/stl_list.h +++ b/libstdc++-v3/include/bits/stl_list.h @@ -643,7 +643,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 * @param __x A %list of identical element and allocator types. * * The newly-created %list uses a copy of the allocation object used - * by @a __x. + * by @a __x (unless the allocator traits dictate a different object). */ list(const list& __x) : _Base(_Node_alloc_traits:: @@ -718,6 +718,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 } #endif +#if __cplusplus >= 201103L /** * No explicit dtor needed as the _Base dtor takes care of * things. The _Base dtor only erases the elements, and note @@ -725,13 +726,16 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 * memory is not touched in any way. Managing the pointer is * the user's responsibility. */ + ~list() = default; +#endif /** * @brief %List assignment operator. * @param __x A %list of identical element and allocator types. * - * All the elements of @a __x are copied, but unlike the copy - * constructor, the allocator object is not copied. + * All the elements of @a __x are copied. + * + * Whether the allocator is copied depends on the allocator traits. */ list& operator=(const list& __x); @@ -742,7 +746,10 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 * @param __x A %list of identical element and allocator types. * * The contents of @a __x are moved into this %list (without copying). - * @a __x is a valid, but unspecified %list + * + * Afterwards @a __x is a valid, but unspecified %list + * + * Whether the allocator is moved depends on the allocator traits. */ list& operator=(list&& __x) @@ -778,7 +785,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 * This function fills a %list with @a __n copies of the given * value. Note that the assignment completely changes the %list * and that the resulting %list's size is the same as the number - * of elements assigned. Old data may be lost. + * of elements assigned. */ void assign(size_type __n, const value_type& __val) @@ -794,7 +801,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 * * Note that the assignment completely changes the %list and * that the resulting %list's size is the same as the number of - * elements assigned. Old data may be lost. + * elements assigned. */ #if __cplusplus >= 201103L template __l) @@ -1027,6 +1028,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * stateless and empty), so it should be quite fast.) Note * that the global std::swap() function is specialized such * that std::swap(m1,m2) will feed to this function. + * + * Whether the allocators are swapped depends on the allocator traits. */ void swap(map& __x) diff --git a/libstdc++-v3/include/bits/stl_multimap.h b/libstdc++-v3/include/bits/stl_multimap.h index 94ebf6ebc89..0bb379fed5f 100644 --- a/libstdc++-v3/include/bits/stl_multimap.h +++ b/libstdc++-v3/include/bits/stl_multimap.h @@ -177,8 +177,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * @brief %Multimap copy constructor. * @param __x A %multimap of identical element and allocator types. * - * The newly-created %multimap uses a copy of the allocation object - * used by @a __x. + * The newly-created %multimap uses a copy of the allocator object used + * by @a __x (unless the allocator traits dictate a different object). */ multimap(const multimap& __x) : _M_t(__x._M_t) { } @@ -284,8 +284,9 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * @brief %Multimap assignment operator. * @param __x A %multimap of identical element and allocator types. * - * All the elements of @a __x are copied, but unlike the copy - * constructor, the allocator object is not copied. + * All the elements of @a __x are copied. + * + * Whether the allocator is copied depends on the allocator traits. */ multimap& operator=(const multimap& __x) @@ -308,7 +309,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * * Note that the assignment completely changes the %multimap and * that the resulting %multimap's size is the same as the number - * of elements assigned. Old data may be lost. + * of elements assigned. */ multimap& operator=(initializer_list __l) @@ -701,6 +702,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * should be quite fast.) * Note that the global std::swap() function is specialized such that * std::swap(m1,m2) will feed to this function. + * + * Whether the allocators are swapped depends on the allocator traits. */ void swap(multimap& __x) diff --git a/libstdc++-v3/include/bits/stl_multiset.h b/libstdc++-v3/include/bits/stl_multiset.h index cc13b3cea38..13b253c64c5 100644 --- a/libstdc++-v3/include/bits/stl_multiset.h +++ b/libstdc++-v3/include/bits/stl_multiset.h @@ -189,8 +189,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * @brief %Multiset copy constructor. * @param __x A %multiset of identical element and allocator types. * - * The newly-created %multiset uses a copy of the allocation object used - * by @a __x. + * The newly-created %multiset uses a copy of the allocator object used + * by @a __x (unless the allocator traits dictate a different object). */ multiset(const multiset& __x) : _M_t(__x._M_t) { } @@ -255,8 +255,9 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * @brief %Multiset assignment operator. * @param __x A %multiset of identical element and allocator types. * - * All the elements of @a __x are copied, but unlike the copy - * constructor, the allocator object is not copied. + * All the elements of @a __x are copied. + * + * Whether the allocator is copied depends on the allocator traits. */ multiset& operator=(const multiset& __x) @@ -279,7 +280,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * * Note that the assignment completely changes the %multiset and * that the resulting %multiset's size is the same as the number - * of elements assigned. Old data may be lost. + * of elements assigned. */ multiset& operator=(initializer_list __l) @@ -403,6 +404,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * be quite fast.) * Note that the global std::swap() function is specialized such that * std::swap(s1,s2) will feed to this function. + * + * Whether the allocators are swapped depends on the allocator traits. */ void swap(multiset& __x) diff --git a/libstdc++-v3/include/bits/stl_set.h b/libstdc++-v3/include/bits/stl_set.h index f5e0603d42d..c104310f121 100644 --- a/libstdc++-v3/include/bits/stl_set.h +++ b/libstdc++-v3/include/bits/stl_set.h @@ -193,8 +193,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * @brief %Set copy constructor. * @param __x A %set of identical element and allocator types. * - * The newly-created %set uses a copy of the allocation object used - * by @a __x. + * The newly-created %set uses a copy of the allocator object used + * by @a __x (unless the allocator traits dictate a different object). */ set(const set& __x) : _M_t(__x._M_t) { } @@ -259,8 +259,9 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * @brief %Set assignment operator. * @param __x A %set of identical element and allocator types. * - * All the elements of @a __x are copied, but unlike the copy - * constructor, the allocator object is not copied. + * All the elements of @a __x are copied. + * + * Whether the allocator is copied depends on the allocator traits. */ set& operator=(const set& __x) @@ -283,7 +284,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * * Note that the assignment completely changes the %set and * that the resulting %set's size is the same as the number - * of elements assigned. Old data may be lost. + * of elements assigned. */ set& operator=(initializer_list __l) @@ -407,6 +408,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * stateless and empty), so it should be quite fast.) Note * that the global std::swap() function is specialized such * that std::swap(s1,s2) will feed to this function. + * + * Whether the allocators are swapped depends on the allocator traits. */ void swap(set& __x) diff --git a/libstdc++-v3/include/bits/stl_vector.h b/libstdc++-v3/include/bits/stl_vector.h index 85abf4a3cc0..9a05dd54f7d 100644 --- a/libstdc++-v3/include/bits/stl_vector.h +++ b/libstdc++-v3/include/bits/stl_vector.h @@ -314,10 +314,12 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * @brief %Vector copy constructor. * @param __x A %vector of identical element and allocator types. * - * The newly-created %vector uses a copy of the allocation - * object used by @a __x. All the elements of @a __x are copied, - * but any extra memory in - * @a __x (for fast expansion) will not be copied. + * All the elements of @a __x are copied, but any unused capacity in + * @a __x will not be copied + * (i.e. capacity() == size() in the new %vector). + * + * The newly-created %vector uses a copy of the allocator object used + * by @a __x (unless the allocator traits dictate a different object). */ vector(const vector& __x) : _Base(__x.size(), @@ -434,9 +436,10 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * @brief %Vector assignment operator. * @param __x A %vector of identical element and allocator types. * - * All the elements of @a __x are copied, but any extra memory in - * @a __x (for fast expansion) will not be copied. Unlike the - * copy constructor, the allocator object is not copied. + * All the elements of @a __x are copied, but any unused capacity in + * @a __x will not be copied. + * + * Whether the allocator is copied depends on the allocator traits. */ vector& operator=(const vector& __x); @@ -448,7 +451,9 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * * The contents of @a __x are moved into this %vector (without copying, * if the allocators permit it). - * @a __x is a valid, but unspecified %vector. + * Afterwards @a __x is a valid, but unspecified %vector. + * + * Whether the allocator is moved depends on the allocator traits. */ vector& operator=(vector&& __x) noexcept(_Alloc_traits::_S_nothrow_move()) @@ -469,7 +474,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * * Note that the assignment completely changes the %vector and * that the resulting %vector's size is the same as the number - * of elements assigned. Old data may be lost. + * of elements assigned. */ vector& operator=(initializer_list __l) @@ -488,7 +493,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * This function fills a %vector with @a __n copies of the given * value. Note that the assignment completely changes the * %vector and that the resulting %vector's size is the same as - * the number of elements assigned. Old data may be lost. + * the number of elements assigned. */ void assign(size_type __n, const value_type& __val) @@ -504,7 +509,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * * Note that the assignment completely changes the %vector and * that the resulting %vector's size is the same as the number - * of elements assigned. Old data may be lost. + * of elements assigned. */ #if __cplusplus >= 201103L template __l) @@ -1219,6 +1224,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * (Three pointers, so it should be quite fast.) * Note that the global std::swap() function is specialized such that * std::swap(v1,v2) will feed to this function. + * + * Whether the allocators are swapped depends on the allocator traits. */ void swap(vector& __x) _GLIBCXX_NOEXCEPT diff --git a/libstdc++-v3/include/bits/unordered_map.h b/libstdc++-v3/include/bits/unordered_map.h index d6f5ab7af00..a26ee1afa99 100644 --- a/libstdc++-v3/include/bits/unordered_map.h +++ b/libstdc++-v3/include/bits/unordered_map.h @@ -274,7 +274,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * * Note that the assignment completely changes the %unordered_map and * that the resulting %unordered_map's size is the same as the number - * of elements assigned. Old data may be lost. + * of elements assigned. */ unordered_map& operator=(initializer_list __l) @@ -283,8 +283,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER return *this; } - /// Returns the allocator object with which the %unordered_map was - /// constructed. + /// Returns the allocator object used by the %unordered_map. allocator_type get_allocator() const noexcept { return _M_h.get_allocator(); } @@ -1258,12 +1257,12 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * @brief %Unordered_multimap list assignment operator. * @param __l An initializer_list. * - * This function fills an %unordered_multimap with copies of the elements - * in the initializer list @a __l. + * This function fills an %unordered_multimap with copies of the + * elements in the initializer list @a __l. * * Note that the assignment completely changes the %unordered_multimap * and that the resulting %unordered_multimap's size is the same as the - * number of elements assigned. Old data may be lost. + * number of elements assigned. */ unordered_multimap& operator=(initializer_list __l) @@ -1272,8 +1271,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER return *this; } - /// Returns the allocator object with which the %unordered_multimap was - /// constructed. + /// Returns the allocator object used by the %unordered_multimap. allocator_type get_allocator() const noexcept { return _M_h.get_allocator(); } diff --git a/libstdc++-v3/include/bits/unordered_set.h b/libstdc++-v3/include/bits/unordered_set.h index 3efd1f94c7d..1e65b547522 100644 --- a/libstdc++-v3/include/bits/unordered_set.h +++ b/libstdc++-v3/include/bits/unordered_set.h @@ -268,7 +268,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * * Note that the assignment completely changes the %unordered_set and * that the resulting %unordered_set's size is the same as the number - * of elements assigned. Old data may be lost. + * of elements assigned. */ unordered_set& operator=(initializer_list __l) @@ -277,8 +277,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER return *this; } - /// Returns the allocator object with which the %unordered_set was - /// constructed. + /// Returns the allocator object used by the %unordered_set. allocator_type get_allocator() const noexcept { return _M_h.get_allocator(); } @@ -942,7 +941,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * * Note that the assignment completely changes the %unordered_multiset * and that the resulting %unordered_multiset's size is the same as the - * number of elements assigned. Old data may be lost. + * number of elements assigned. */ unordered_multiset& operator=(initializer_list __l) @@ -951,8 +950,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER return *this; } - /// Returns the allocator object with which the %unordered_multiset was - /// constructed. + /// Returns the allocator object used by the %unordered_multiset. allocator_type get_allocator() const noexcept { return _M_h.get_allocator(); } -- 2.30.2