Skip to content

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

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
parent 94c32c00
Showing with 117 additions and 65 deletions
libstdc++-v3/ChangeLog
2016-07-14 Jonathan Wakely <jwakely@redhat.com>
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 <ville.voutilainen@gmail.com>
Implement P0032R3, Homogeneous interface for variant, any and optional,
......
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<typename _InputIterator,
typename = std::_RequireInputIter<_InputIterator>>
......@@ -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
......
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<value_type> __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<typename _InputIterator,
......@@ -1141,7 +1143,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.
*/
void
assign(initializer_list<value_type> __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
......
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<typename _InputIterator,
......@@ -1348,6 +1355,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
* 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(list& __x) _GLIBCXX_NOEXCEPT
......
libstdc++-v3/include/bits/stl_map.h
......@@ -179,8 +179,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
* @brief %Map copy constructor.
* @param __x A %map of identical element and allocator types.
*
* The newly-created %map uses a copy of the allocation object
* used by @a __x.
* The newly-created %map uses a copy of the allocator object used
* by @a __x (unless the allocator traits dictate a different object).
*/
map(const map& __x)
: _M_t(__x._M_t) { }
......@@ -289,8 +289,9 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
* @brief %Map assignment operator.
* @param __x A %map 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.
*/
map&
operator=(const map& __x)
......@@ -313,7 +314,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
*
* Note that the assignment completely changes the %map and
* that the resulting %map's size is the same as the number
* of elements assigned. Old data may be lost.
* of elements assigned.
*/
map&
operator=(initializer_list<value_type> __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)
......
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<value_type> __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)
......
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<value_type> __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)
......
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<value_type> __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)
......
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<value_type> __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<typename _InputIterator,
......@@ -533,7 +538,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.
*/
void
assign(initializer_list<value_type> __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
......
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<value_type> __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<value_type> __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(); }
......
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<value_type> __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<value_type> __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(); }
......
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