This is the mail archive of the
gcc-patches@gcc.gnu.org
mailing list for the GCC project.
[libstdc++] More doxygen markup (map, multimap, vector)
- From: Phil Edwards <phil at jaj dot com>
- To: libstdc++ at gcc dot gnu dot org, gcc-patches at gcc dot gnu dot org
- Date: Thu, 7 Feb 2002 21:19:47 -0500
- Subject: [libstdc++] More doxygen markup (map, multimap, vector)
2002-02-07 Stephan Buys <sbproxy@icon.co.za>
* include/bits/stl_map.h: Tweak doxygen markup.
* include/bits/stl_multimap.h: Doxygenate and remove extra spaces.
* include/bits/stl_vector.h: Likewise.
Index: include/bits/stl_map.h
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/include/bits/stl_map.h,v
retrieving revision 1.10
diff -u -3 -p -r1.10 stl_map.h
--- stl_map.h 2002/02/05 00:14:37 1.10
+++ stl_map.h 2002/02/08 02:17:31
@@ -212,6 +212,7 @@ public:
/**
* @brief Subscript ( [] ) access to map data.
* @param k The key for which data should be retrieved.
+ *
* Allows for easy lookup with the subscript ( [] ) operator. Returns the
* data associated with the key specified in subscript. If the key does
* not exist a pair with that key is created with a default value, which
@@ -278,19 +279,20 @@ public:
* This function erases an element, pointed to by the given iterator, from
* a map. Note that this function only erases the element, and that if
* the element is itself a pointer, the pointed-to memory is not touched
- * in any way. That is the user's responsibilty.
+ * in any way. Managing the pointer is the user's responsibilty.
*/
void erase(iterator __position) { _M_t.erase(__position); }
/**
* @brief Erases an element according to the provided key.
* @param x Key of element to be erased.
- * @return Doc me!
+ * @return Doc me! (Number of elements that match key? Only makes sense
+ * with multimap)
*
* This function erases an element, located by the given key, from a map.
* Note that this function only erases the element, and that if
* the element is itself a pointer, the pointed-to memory is not touched
- * in any way. That is the user's responsibilty.
+ * in any way. Managing the pointer is the user's responsibilty.
*/
size_type erase(const key_type& __x) { return _M_t.erase(__x); }
@@ -302,12 +304,16 @@ public:
* This function erases a sequence of elements from a map.
* Note that this function only erases the element, and that if
* the element is itself a pointer, the pointed-to memory is not touched
- * in any way. That is the user's responsibilty.
+ * in any way. Managing the pointer is the user's responsibilty.
*/
void erase(iterator __first, iterator __last)
{ _M_t.erase(__first, __last); }
- /** Erases all elements in a map. */
+ /** Erases all elements in a map. Note that this function only erases
+ * the elements, and that if the elements themselves are pointers, the
+ * pointed-to memory is not touched in any way. Managing the pointer is
+ * the user's responsibilty.
+ */
void clear() { _M_t.clear(); }
// map operations:
Index: include/bits/stl_multimap.h
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/include/bits/stl_multimap.h,v
retrieving revision 1.10
diff -u -3 -p -r1.10 stl_multimap.h
--- stl_multimap.h 2001/12/06 20:29:31 1.10
+++ stl_multimap.h 2002/02/08 02:17:31
@@ -65,22 +65,28 @@
namespace std
{
-
// Forward declaration of operators < and ==, needed for friend declaration.
-
-template <class _Key, class _Tp,
+template <class _Key, class _Tp,
class _Compare = less<_Key>,
class _Alloc = allocator<pair<const _Key, _Tp> > >
class multimap;
template <class _Key, class _Tp, class _Compare, class _Alloc>
-inline bool operator==(const multimap<_Key,_Tp,_Compare,_Alloc>& __x,
+inline bool operator==(const multimap<_Key,_Tp,_Compare,_Alloc>& __x,
const multimap<_Key,_Tp,_Compare,_Alloc>& __y);
template <class _Key, class _Tp, class _Compare, class _Alloc>
-inline bool operator<(const multimap<_Key,_Tp,_Compare,_Alloc>& __x,
+inline bool operator<(const multimap<_Key,_Tp,_Compare,_Alloc>& __x,
const multimap<_Key,_Tp,_Compare,_Alloc>& __y);
+/**
+ * @brief A standard container made up of pairs (see std::pair in <utility>)
+ * which can be retrieved based on a key.
+ *
+ * This is an associative container. Values contained within it can be
+ * quickly retrieved through a key element. In contrast with a map a
+ * multimap can have multiple duplicate keys.
+*/
template <class _Key, class _Tp, class _Compare, class _Alloc>
class multimap
{
@@ -110,7 +116,7 @@ public:
};
private:
- typedef _Rb_tree<key_type, value_type,
+ typedef _Rb_tree<key_type, value_type,
_Select1st<value_type>, key_compare, _Alloc> _Rep_type;
_Rep_type _M_t; // red-black tree representing multimap
public:
@@ -157,51 +163,271 @@ public:
value_compare value_comp() const { return value_compare(_M_t.key_comp()); }
allocator_type get_allocator() const { return _M_t.get_allocator(); }
+ /**
+ * Returns a read/write iterator that points to the first pair in the
+ * multimap. Iteration is done in ascending order according to the keys.
+ */
iterator begin() { return _M_t.begin(); }
+
+ /**
+ * Returns a read-only (constant) iterator that points to the first pair
+ * in the multimap. Iteration is done in ascending order according to the
+ * keys.
+ */
const_iterator begin() const { return _M_t.begin(); }
+
+ /**
+ * Returns a read/write iterator that points one past the last pair in the
+ * multimap. Iteration is done in ascending order according to the keys.
+ */
iterator end() { return _M_t.end(); }
+
+ /**
+ * Returns a read-only (constant) iterator that points one past the last
+ * pair in the multimap. Iteration is done in ascending order according
+ * to the keys.
+ */
const_iterator end() const { return _M_t.end(); }
+
+ /**
+ * Returns a read/write reverse iterator that points to the last pair in
+ * the multimap. Iteration is done in descending order according to the
+ * keys.
+ */
reverse_iterator rbegin() { return _M_t.rbegin(); }
+
+ /**
+ * Returns a read-only (constant) reverse iterator that points to the last
+ * pair in the multimap. Iteration is done in descending order according
+ * to the keys.
+ */
const_reverse_iterator rbegin() const { return _M_t.rbegin(); }
+
+ /**
+ * Returns a read/write reverse iterator that points to one before the
+ * first pair in the multimap. Iteration is done in descending order
+ * according to the keys.
+ */
reverse_iterator rend() { return _M_t.rend(); }
+
+ /**
+ * Returns a read-only (constant) reverse iterator that points to one
+ * before the first pair in the multimap. Iteration is done in descending
+ * order according to the keys.
+ */
const_reverse_iterator rend() const { return _M_t.rend(); }
+
+ /** Returns true if the map is empty. (Thus begin() would equal end().) */
bool empty() const { return _M_t.empty(); }
+
+ /** Returns the size of the map. */
size_type size() const { return _M_t.size(); }
+
+ /** Returns the maximum size of the map. */
size_type max_size() const { return _M_t.max_size(); }
+
void swap(multimap<_Key,_Tp,_Compare,_Alloc>& __x) { _M_t.swap(__x._M_t); }
// insert/erase
-
+ /**
+ * @brief Inserts a std::pair into the multimap.
+ * @param x Pair to be inserted (see std::make_pair for easy creation of
+ * pairs).
+ * @return An iterator that points to the inserted (key,value) pair.
+ *
+ * This function inserts a (key, value) pair into the multimap. Contrary
+ * to a std::map the multimap does not rely on unique keys and thus a
+ * multiple pairs with the same key can be inserted.
+ */
iterator insert(const value_type& __x) { return _M_t.insert_equal(__x); }
+
+ /**
+ * @brief Inserts a std::pair into the multimap.
+ * @param position An iterator that serves as a hint as to where the
+ * pair should be inserted.
+ * @param x Pair to be inserted (see std::make_pair for easy creation of
+ * pairs).
+ * @return An iterator that points to the inserted (key,value) pair.
+ *
+ * This function inserts a (key, value) pair into the multimap. Contrary
+ * to a std::map the multimap does not rely on unique keys and thus a
+ * multiple pairs with the same key can be inserted.
+ * Note that the first parameter is only a hint and can potentially
+ * improve the performance of the insertion process. A bad hint would
+ * cause no gains in efficiency.
+ */
iterator insert(iterator __position, const value_type& __x) {
return _M_t.insert_equal(__position, __x);
}
+
+ /**
+ * @brief A template function that attemps to insert elements from
+ * another range (possibly another multimap or standard container).
+ * @param first Iterator pointing to the start of the range to be
+ * inserted.
+ * @param last Iterator pointing to the end of the range to be inserted.
+ */
template <class _InputIterator>
void insert(_InputIterator __first, _InputIterator __last) {
_M_t.insert_equal(__first, __last);
}
+
+ /**
+ * @brief Erases an element from a multimap.
+ * @param position An iterator pointing to the element to be erased.
+ *
+ * This function erases an element, pointed to by the given iterator, from
+ * a mutlimap. Note that this function only erases the element, and that
+ * if the element is itself a pointer, the pointed-to memory is not
+ * touched in any way. Managing the pointer is the user's responsibilty.
+ */
void erase(iterator __position) { _M_t.erase(__position); }
+
+ /**
+ * @brief Erases an element according to the provided key.
+ * @param x Key of element to be erased.
+ * @return Doc me! (Number of elements erased?)
+ *
+ * This function erases all elements, located by the given key, from a
+ * multimap.
+ * Note that this function only erases the element, and that if
+ * the element is itself a pointer, the pointed-to memory is not touched
+ * in any way. Managing the pointer is the user's responsibilty.
+ */
size_type erase(const key_type& __x) { return _M_t.erase(__x); }
+
+ /**
+ * @brief Erases a [first,last) range of elements from a multimap.
+ * @param first Iterator pointing to the start of the range to be erased.
+ * @param last Iterator pointing to the end of the range to be erased.
+ *
+ * This function erases a sequence of elements from a multimap.
+ * Note that this function only erases the elements, and that if
+ * the elements themselves are pointers, the pointed-to memory is not
+ * touched in any way. Managing the pointer is the user's responsibilty.
+ */
void erase(iterator __first, iterator __last)
{ _M_t.erase(__first, __last); }
+
+ /** Erases all elements in a multimap. Note that this function only erases
+ * the elements, and that if the elements themselves are pointers, the
+ * pointed-to memory is not touched in any way. Managing the pointer is
+ * the user's responsibilty.
+ */
void clear() { _M_t.clear(); }
// multimap operations:
+ /**
+ * @brief Tries to locate an element in a multimap.
+ * @param x Key of (key, value) pair to be located.
+ * @return Iterator pointing to sought-after (first matching?) element,
+ * or end() if not found.
+ *
+ * This function takes a key and tries to locate the element with which
+ * the key matches. If successful the function returns an iterator
+ * pointing to the sought after pair. If unsuccessful it returns the
+ * one past the end ( end() ) iterator.
+ */
iterator find(const key_type& __x) { return _M_t.find(__x); }
+
+ /**
+ * @brief Tries to locate an element in a multimap.
+ * @param x Key of (key, value) pair to be located.
+ * @return Read-only (constant) iterator pointing to sought-after (first
+ * matching?) element, or end() if not found.
+ *
+ * This function takes a key and tries to locate the element with which
+ * the key matches. If successful the function returns a constant iterator
+ * pointing to the sought after pair. If unsuccessful it returns the
+ * one past the end ( end() ) iterator.
+ */
const_iterator find(const key_type& __x) const { return _M_t.find(__x); }
+
+ /**
+ * @brief Finds the number of elements with given key.
+ * @param x Key of (key, value) pairs to be located.
+ * @return Number of elements with specified key.
+ */
size_type count(const key_type& __x) const { return _M_t.count(__x); }
+
+ /**
+ * @brief Finds the beginning of a subsequence matching given key.
+ * @param x Key of (key, value) pair to be located.
+ * @return Iterator pointing to first element matching given key, or
+ * end() if not found.
+ *
+ * This function returns the first element of a subsequence of elements
+ * that matches the given key. If unsuccessful it returns an iterator
+ * pointing to the first element that has a greater value than given key
+ * or end() if no such element exists.
+ */
iterator lower_bound(const key_type& __x) {return _M_t.lower_bound(__x); }
+
+ /**
+ * @brief Finds the beginning of a subsequence matching given key.
+ * @param x Key of (key, value) pair to be located.
+ * @return Read-only (constant) iterator pointing to first element
+ * matching given key, or end() if not found.
+ *
+ * This function returns the first element of a subsequence of elements
+ * that matches the given key. If unsuccessful the iterator will point
+ * to the next greatest element or, if no such greater element exists, to
+ * end().
+ */
const_iterator lower_bound(const key_type& __x) const {
- return _M_t.lower_bound(__x);
+ return _M_t.lower_bound(__x);
}
+
+ /**
+ * @brief Finds the end of a subsequence matching given key.
+ * @param x Key of (key, value) pair to be located.
+ * @return Iterator pointing to last element matching given key.
+ */
iterator upper_bound(const key_type& __x) {return _M_t.upper_bound(__x); }
+
+ /**
+ * @brief Finds the end of a subsequence matching given key.
+ * @param x Key of (key, value) pair to be located.
+ * @return Read-only (constant) iterator pointing to last element matching
+ * given key.
+ */
const_iterator upper_bound(const key_type& __x) const {
- return _M_t.upper_bound(__x);
+ return _M_t.upper_bound(__x);
}
- pair<iterator,iterator> equal_range(const key_type& __x) {
+
+ /**
+ * @brief Finds a subsequence matching given key.
+ * @param x Key of (key, value) pairs to be located.
+ * @return Pair of iterators that possibly points to the subsequence
+ * matching given key.
+ *
+ * This function improves on lower_bound() and upper_bound() by giving a more
+ * elegant and efficient solution. It returns a pair of which the first
+ * element possibly points to the first element matching the given key
+ * and the second element possibly points to the last element matching the
+ * given key. If unsuccessful the first element of the returned pair will
+ * contain an iterator pointing to the next greatest element or, if no such
+ * greater element exists, to end().
+ */
+ pair<iterator,iterator> equal_range(const key_type& __x) {
return _M_t.equal_range(__x);
}
+
+ /**
+ * @brief Finds a subsequence matching given key.
+ * @param x Key of (key, value) pairs to be located.
+ * @return Pair of read-only (constant) iterators that possibly points to
+ * the subsequence matching given key.
+ *
+ * This function improves on lower_bound() and upper_bound() by giving a more
+ * elegant and efficient solution. It returns a pair of which the first
+ * element possibly points to the first element matching the given key
+ * and the second element possibly points to the last element matching the
+ * given key. If unsuccessful the first element of the returned pair will
+ * contain an iterator pointing to the next greatest element or, if no such
+ * a greater element exists, to end().
+ */
pair<const_iterator,const_iterator> equal_range(const key_type& __x) const {
return _M_t.equal_range(__x);
}
@@ -215,7 +441,7 @@ public:
};
template <class _Key, class _Tp, class _Compare, class _Alloc>
-inline bool operator==(const multimap<_Key,_Tp,_Compare,_Alloc>& __x,
+inline bool operator==(const multimap<_Key,_Tp,_Compare,_Alloc>& __x,
const multimap<_Key,_Tp,_Compare,_Alloc>& __y) {
return __x._M_t == __y._M_t;
}
Index: include/bits/stl_vector.h
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/include/bits/stl_vector.h,v
retrieving revision 1.16
diff -u -3 -p -r1.16 stl_vector.h
--- stl_vector.h 2001/12/31 16:16:16 1.16
+++ stl_vector.h 2002/02/08 02:17:31
@@ -66,7 +66,7 @@
#include <bits/concept_check.h>
namespace std
-{
+{
// The vector base class serves two purposes. First, its constructor
// and destructor allocate (but don't initialize) storage. This makes
@@ -83,9 +83,9 @@ public:
allocator_type get_allocator() const { return _M_data_allocator; }
_Vector_alloc_base(const allocator_type& __a)
- : _M_data_allocator(__a), _M_start(0), _M_finish(0), _M_end_of_storage(0)
+ : _M_data_allocator(__a), _M_start(0), _M_finish(0), _M_end_of_storage(0)
{}
-
+
protected:
allocator_type _M_data_allocator;
_Tp* _M_start;
@@ -99,7 +99,7 @@ protected:
};
// Specialization for allocators that have the property that we don't
-// actually have to store an allocator object.
+// actually have to store an allocator object.
template <class _Tp, class _Allocator>
class _Vector_alloc_base<_Tp, _Allocator, true> {
public:
@@ -108,9 +108,9 @@ public:
allocator_type get_allocator() const { return allocator_type(); }
_Vector_alloc_base(const allocator_type&)
- : _M_start(0), _M_finish(0), _M_end_of_storage(0)
+ : _M_start(0), _M_finish(0), _M_end_of_storage(0)
{}
-
+
protected:
_Tp* _M_start;
_Tp* _M_finish;
@@ -128,7 +128,7 @@ struct _Vector_base
: public _Vector_alloc_base<_Tp, _Alloc,
_Alloc_traits<_Tp, _Alloc>::_S_instanceless>
{
- typedef _Vector_alloc_base<_Tp, _Alloc,
+ typedef _Vector_alloc_base<_Tp, _Alloc,
_Alloc_traits<_Tp, _Alloc>::_S_instanceless>
_Base;
typedef typename _Base::allocator_type allocator_type;
@@ -141,11 +141,20 @@ struct _Vector_base
}
~_Vector_base() { _M_deallocate(_M_start, _M_end_of_storage - _M_start); }
-};
+};
+/**
+ * @brief A standard container which offers fixed time access to individual
+ * elements in any order.
+ *
+ * In some terminology a vector can be described as a dynamic C-style array,
+ * it offers fast and efficient access to individual elements in any order
+ * and saves the user from worrying about memory and size allocation.
+ * Subscripting ( [] ) access is also provided as with C-style arrays.
+*/
template <class _Tp, class _Alloc = allocator<_Tp> >
-class vector : protected _Vector_base<_Tp, _Alloc>
+class vector : protected _Vector_base<_Tp, _Alloc>
{
// concept requirements
__glibcpp_class_requires(_Tp, _SGIAssignableConcept)
@@ -182,31 +191,102 @@ protected:
void _M_insert_aux(iterator __position);
public:
+ /**
+ * Returns a read/write iterator that points to the first element in the
+ * vector. Iteration is done in ordinary element order.
+ */
iterator begin() { return iterator (_M_start); }
+
+ /**
+ * Returns a read-only (constant) iterator that points to the first element
+ * in the vector. Iteration is done in ordinary element order.
+ */
const_iterator begin() const
{ return const_iterator (_M_start); }
+
+ /**
+ * Returns a read/write iterator that points one past the last element in
+ * the vector. Iteration is done in ordinary element order.
+ */
iterator end() { return iterator (_M_finish); }
+
+ /**
+ * Returns a read-only (constant) iterator that points one past the last
+ * element in the vector. Iteration is done in ordinary element order.
+ */
const_iterator end() const { return const_iterator (_M_finish); }
+ /**
+ * Returns a read/write reverse iterator that points to the last element in
+ * the vector. Iteration is done in reverse element order.
+ */
reverse_iterator rbegin()
{ return reverse_iterator(end()); }
+
+ /**
+ * Returns a read-only (constant) reverse iterator that points to the last
+ * element in the vector. Iteration is done in reverse element order.
+ */
const_reverse_iterator rbegin() const
{ return const_reverse_iterator(end()); }
+
+ /**
+ * Returns a read/write reverse iterator that points to one before the
+ * first element in the vector. Iteration is done in reverse element
+ * order.
+ */
reverse_iterator rend()
{ return reverse_iterator(begin()); }
+
+ /**
+ * Returns a read-only (constant) reverse iterator that points to one
+ * before the first element in the vector. Iteration is done in reverse
+ * element order.
+ */
const_reverse_iterator rend() const
{ return const_reverse_iterator(begin()); }
+ /** Returns the number of elements in the vector. */
size_type size() const
{ return size_type(end() - begin()); }
+
+ /** Returns the size of the largest possible vector. */
size_type max_size() const
{ return size_type(-1) / sizeof(_Tp); }
+
+ /**
+ * Returns the amount of memory that has been alocated for the current
+ * elements (?).
+ */
size_type capacity() const
{ return size_type(const_iterator(_M_end_of_storage) - begin()); }
+
+ /**
+ * Returns true if the vector is empty. (Thus begin() would equal end().)
+ */
bool empty() const
{ return begin() == end(); }
+ /**
+ * @brief Subscript access to the data contained in the vector.
+ * @param n The element for which data should be accessed.
+ * @return Read/write reference to data.
+ *
+ * This operator allows for easy, array-style, data access.
+ * Note that data access with this operator is unchecked and out_of_range
+ * lookups are not defined. (For checked lookups see at().)
+ */
reference operator[](size_type __n) { return *(begin() + __n); }
+
+ /**
+ * @brief Subscript access to the data contained in the vector.
+ * @param n The element for which data should be accessed.
+ * @return Read-only (constant) reference to data.
+ *
+ * This operator allows for easy, array-style, data access.
+ * Note that data access with this operator is unchecked and out_of_range
+ * lookups are not defined. (For checked lookups see at().)
+ */
const_reference operator[](size_type __n) const { return *(begin() + __n); }
void _M_range_check(size_type __n) const {
@@ -214,16 +294,36 @@ public:
__throw_out_of_range("vector");
}
+ /**
+ * @brief Provides access to the data contained in the vector.
+ * @param n The element for which data should be accessed.
+ * @return Read/write reference to data.
+ *
+ * This function provides for safer data access. The parameter is first
+ * checked that it is in the range of the vector. The function throws
+ * out_of_range if the check fails.
+ */
reference at(size_type __n)
{ _M_range_check(__n); return (*this)[__n]; }
+
+ /**
+ * @brief Provides access to the data contained in the vector.
+ * @param n The element for which data should be accessed.
+ * @return Read-only (constant) reference to data.
+ *
+ * This function provides for safer data access. The parameter is first
+ * checked that it is in the range of the vector. The function throws
+ * out_of_range if the check fails.
+ */
const_reference at(size_type __n) const
{ _M_range_check(__n); return (*this)[__n]; }
+
explicit vector(const allocator_type& __a = allocator_type())
: _Base(__a) {}
vector(size_type __n, const _Tp& __value,
- const allocator_type& __a = allocator_type())
+ const allocator_type& __a = allocator_type())
: _Base(__n, __a)
{ _M_finish = uninitialized_fill_n(_M_start, __n, __value); }
@@ -231,7 +331,7 @@ public:
: _Base(__n, allocator_type())
{ _M_finish = uninitialized_fill_n(_M_start, __n, _Tp()); }
- vector(const vector<_Tp, _Alloc>& __x)
+ vector(const vector<_Tp, _Alloc>& __x)
: _Base(__x.size(), __x.get_allocator())
{ _M_finish = uninitialized_copy(__x.begin(), __x.end(), _M_start); }
@@ -249,7 +349,7 @@ public:
void _M_initialize_aux(_Integer __n, _Integer __value, __true_type)
{
_M_start = _M_allocate(__n);
- _M_end_of_storage = _M_start + __n;
+ _M_end_of_storage = _M_start + __n;
_M_finish = uninitialized_fill_n(_M_start, __n, __value);
}
@@ -265,6 +365,21 @@ public:
{ _Destroy(_M_start, _M_finish); }
vector<_Tp, _Alloc>& operator=(const vector<_Tp, _Alloc>& __x);
+
+ /**
+ * @brief Attempt to preallocate enough memory for specified number of
+ * elements.
+ * @param n Number of elements required
+ *
+ * This function attempts to reserve enough memory for the vector to hold
+ * the specified number of elements. If the number requested is more than
+ * max_size() length_error is thrown.
+ *
+ * The advantage of this function is that if optimal code is a necessity
+ * and the user can determine the number of elements that will be required
+ * the user can reserve the memory and thus prevent a possible
+ * reallocation of memory and copy of vector data.
+ */
void reserve(size_type __n) {
if (capacity() < __n) {
const size_type __old_size = size();
@@ -282,6 +397,17 @@ public:
// The range version is a member template, so we dispatch on whether
// or not the type is an integer.
+ /**
+ * @brief Assigns a given value or range to a vector.
+ * @param n Number of elements to be assigned.
+ * @param val Value to be assigned.
+ *
+ * This function can be used to assign a range to a vector or fill it
+ * with a specified number of 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.
+ */
void assign(size_type __n, const _Tp& __val) { _M_fill_assign(__n, __val); }
void _M_fill_assign(size_type __n, const _Tp& __val);
@@ -312,13 +438,41 @@ public:
template <class _ForwardIterator>
void _M_assign_aux(_ForwardIterator __first, _ForwardIterator __last,
- forward_iterator_tag);
+ forward_iterator_tag);
+ /**
+ * Returns a read/write reference to the data at the first element of the
+ * vector.
+ */
reference front() { return *begin(); }
+
+ /**
+ * Returns a read-only (constant) reference to the data at the first
+ * element of the vector.
+ */
const_reference front() const { return *begin(); }
+
+ /**
+ * Returns a read/write reference to the data at the last element of the
+ * vector.
+ */
reference back() { return *(end() - 1); }
+
+ /**
+ * Returns a read-only (constant) reference to the data at the first
+ * element of the vector.
+ */
const_reference back() const { return *(end() - 1); }
+ /**
+ * @brief Add data to the end of the vector.
+ * @param x Data to be added.
+ *
+ * This is a typical stack operation. The function creates an element at
+ * the end of the vector and assigns the given data to it.
+ * Due to the nature of a vector this operation can be done in constant
+ * time if the vector has preallocated space available.
+ */
void
push_back(const _Tp& __x)
{
@@ -330,6 +484,10 @@ public:
_M_insert_aux(end(), __x);
}
+ /**
+ * Add an element to the end of the vector. The element is
+ * default-constructed.
+ */
void
push_back()
{
@@ -349,6 +507,17 @@ public:
std::swap(_M_end_of_storage, __x._M_end_of_storage);
}
+ /**
+ * @brief Inserts given value into vector at specified element.
+ * @param position An iterator that points to the element where data
+ * should be inserted.
+ * @param x Data to be inserted.
+ * @return An iterator that points to the inserted data.
+ *
+ * This function will insert the given value into the specified location.
+ * Note that this kind of operation could be expensive for a vector and if
+ * it is frequently used the user should consider using std::list.
+ */
iterator
insert(iterator __position, const _Tp& __x)
{
@@ -362,6 +531,17 @@ public:
return begin() + __n;
}
+ /**
+ * @brief Inserts an empty element into the vector.
+ * @param position An iterator that points to the element where empty
+ * element should be inserted.
+ * @param x Data to be inserted.
+ * @return An iterator that points to the inserted element.
+ *
+ * This function will insert an empty element into the specified location.
+ * Note that this kind of operation could be expensive for a vector and if
+ * it is frequently used the user should consider using std::list.
+ */
iterator
insert(iterator __position)
{
@@ -399,15 +579,52 @@ public:
_M_range_insert(__pos, __first, __last, _IterCategory());
}
+ /**
+ * @brief Inserts a number of copies of given data into the vector.
+ * @param position An iterator that points to the element where data
+ * should be inserted.
+ * @param n Amount of elements to be inserted.
+ * @param x Data to be inserted.
+ *
+ * This function will insert a specified number of copies of the given data
+ * into the specified location.
+ *
+ * Note that this kind of operation could be expensive for a vector and if
+ * it is frequently used the user should consider using std::list.
+ */
void insert (iterator __pos, size_type __n, const _Tp& __x)
{ _M_fill_insert(__pos, __n, __x); }
void _M_fill_insert (iterator __pos, size_type __n, const _Tp& __x);
+ /**
+ * @brief Removes last element from vector.
+ *
+ * This is a typical stack operation. It allows us to shrink the vector by
+ * one.
+ *
+ * Note that no data is returned and if last element's data is needed it
+ * should be retrieved before pop_back() is called.
+ */
void pop_back() {
--_M_finish;
_Destroy(_M_finish);
}
+
+ /**
+ * @brief Remove element at given position
+ * @param position Iterator pointing to element to be erased.
+ * @return Doc Me! (Iterator pointing to new element at old location?)
+ *
+ * This function will erase the element at the given position and thus
+ * shorten the vector by one.
+ *
+ * Note This operation could be expensive and if it is frequently used the
+ * user should consider using std::list. The user is also cautioned that
+ * this function only erases the element, and that if the element is itself
+ * a pointer, the pointed-to memory is not touched in any way. Managing
+ * the pointer is the user's responsibilty.
+ */
iterator erase(iterator __position) {
if (__position + 1 != end())
copy(__position + 1, end(), __position);
@@ -415,6 +632,22 @@ public:
_Destroy(_M_finish);
return __position;
}
+
+ /**
+ * @brief Remove a range of elements from a vector.
+ * @param first Iterator pointing to the first element to be erased.
+ * @param last Iterator pointing to the last element to be erased.
+ * @return Doc Me! (Iterator pointing to new element at old location?)
+ *
+ * This function will erase the elements in the given range and shorten the
+ * vector accordingly.
+ *
+ * Note This operation could be expensive and if it is frequently used the
+ * user should consider using std::list. The user is also cautioned that
+ * this function only erases the elements, and that if the elements
+ * themselves are pointers, the pointed-to memory is not touched in any
+ * way. Managing the pointer is the user's responsibilty.
+ */
iterator erase(iterator __first, iterator __last) {
iterator __i(copy(__last, end(), __first));
_Destroy(__i, end());
@@ -422,19 +655,46 @@ public:
return __first;
}
+ /**
+ * @brief Resizes the vector to the specified number of elements.
+ * @param new_size Number of elements the vector should contain.
+ * @param x Data with which new elements should be populated.
+ *
+ * This function will resize the vector to the specified number of
+ * elements. If the number is smaller than the vector's current size the
+ * vector is truncated, otherwise the vector is extended and new elements
+ * are populated with given data.
+ */
void resize(size_type __new_size, const _Tp& __x) {
- if (__new_size < size())
+ if (__new_size < size())
erase(begin() + __new_size, end());
else
insert(end(), __new_size - size(), __x);
}
+
+ /**
+ * @brief Resizes the vector to the specified number of elements.
+ * @param new_size Number of elements the vector should contain.
+ *
+ * This function will resize the vector to the specified number of
+ * elements. If the number is smaller than the vector's current size the
+ * vector is truncated, otherwise the vector is extended and new elements
+ * are left uninitialized.
+ */
void resize(size_type __new_size) { resize(__new_size, _Tp()); }
+
+ /**
+ * Erases all elements in vector. Note that this function only erases the
+ * elements, and that if the elements themselves are pointers, the
+ * pointed-to memory is not touched in any way. Managing the pointer is
+ * the user's responsibilty.
+ */
void clear() { erase(begin(), end()); }
protected:
template <class _ForwardIterator>
- pointer _M_allocate_and_copy(size_type __n, _ForwardIterator __first,
+ pointer _M_allocate_and_copy(size_type __n, _ForwardIterator __first,
_ForwardIterator __last)
{
pointer __result = _M_allocate(__n);
@@ -443,21 +703,21 @@ protected:
return __result;
}
catch(...)
- {
+ {
_M_deallocate(__result, __n);
__throw_exception_again;
}
}
template <class _InputIterator>
- void _M_range_initialize(_InputIterator __first,
+ void _M_range_initialize(_InputIterator __first,
_InputIterator __last, input_iterator_tag)
{
for ( ; __first != __last; ++__first)
push_back(*__first);
}
- // This function is only called by the constructor.
+ // This function is only called by the constructor.
template <class _ForwardIterator>
void _M_range_initialize(_ForwardIterator __first,
_ForwardIterator __last, forward_iterator_tag)
@@ -480,7 +740,7 @@ protected:
};
template <class _Tp, class _Alloc>
-inline bool
+inline bool
operator==(const vector<_Tp, _Alloc>& __x, const vector<_Tp, _Alloc>& __y)
{
return __x.size() == __y.size() &&
@@ -488,10 +748,10 @@ operator==(const vector<_Tp, _Alloc>& __
}
template <class _Tp, class _Alloc>
-inline bool
+inline bool
operator<(const vector<_Tp, _Alloc>& __x, const vector<_Tp, _Alloc>& __y)
{
- return lexicographical_compare(__x.begin(), __x.end(),
+ return lexicographical_compare(__x.begin(), __x.end(),
__y.begin(), __y.end());
}
@@ -526,7 +786,7 @@ operator>=(const vector<_Tp, _Alloc>& __
}
template <class _Tp, class _Alloc>
-vector<_Tp,_Alloc>&
+vector<_Tp,_Alloc>&
vector<_Tp,_Alloc>::operator=(const vector<_Tp, _Alloc>& __x)
{
if (&__x != this) {
@@ -552,7 +812,7 @@ vector<_Tp,_Alloc>::operator=(const vect
}
template <class _Tp, class _Alloc>
-void vector<_Tp, _Alloc>::_M_fill_assign(size_t __n, const value_type& __val)
+void vector<_Tp, _Alloc>::_M_fill_assign(size_t __n, const value_type& __val)
{
if (__n > capacity()) {
vector<_Tp, _Alloc> __tmp(__n, __val, get_allocator());
@@ -605,7 +865,7 @@ vector<_Tp, _Alloc>::_M_assign_aux(_Forw
}
template <class _Tp, class _Alloc>
-void
+void
vector<_Tp, _Alloc>::_M_insert_aux(iterator __position, const _Tp& __x)
{
if (_M_finish != _M_end_of_storage) {
@@ -629,8 +889,8 @@ vector<_Tp, _Alloc>::_M_insert_aux(itera
__new_finish);
}
catch(...)
- {
- _Destroy(__new_start,__new_finish);
+ {
+ _Destroy(__new_start,__new_finish);
_M_deallocate(__new_start.base(),__len);
__throw_exception_again;
}
@@ -643,13 +903,13 @@ vector<_Tp, _Alloc>::_M_insert_aux(itera
}
template <class _Tp, class _Alloc>
-void
+void
vector<_Tp, _Alloc>::_M_insert_aux(iterator __position)
{
if (_M_finish != _M_end_of_storage) {
_Construct(_M_finish, *(_M_finish - 1));
++_M_finish;
- copy_backward(__position, iterator(_M_finish - 2),
+ copy_backward(__position, iterator(_M_finish - 2),
iterator(_M_finish - 1));
*__position = _Tp();
}
@@ -659,16 +919,16 @@ vector<_Tp, _Alloc>::_M_insert_aux(itera
pointer __new_start = _M_allocate(__len);
pointer __new_finish = __new_start;
try {
- __new_finish = uninitialized_copy(iterator(_M_start), __position,
+ __new_finish = uninitialized_copy(iterator(_M_start), __position,
__new_start);
_Construct(__new_finish);
++__new_finish;
- __new_finish = uninitialized_copy(__position, iterator(_M_finish),
+ __new_finish = uninitialized_copy(__position, iterator(_M_finish),
__new_finish);
}
catch(...)
{
- _Destroy(__new_start,__new_finish);
+ _Destroy(__new_start,__new_finish);
_M_deallocate(__new_start,__len);
__throw_exception_again;
}
@@ -681,7 +941,7 @@ vector<_Tp, _Alloc>::_M_insert_aux(itera
}
template <class _Tp, class _Alloc>
-void vector<_Tp, _Alloc>::_M_fill_insert(iterator __position, size_type __n,
+void vector<_Tp, _Alloc>::_M_fill_insert(iterator __position, size_type __n,
const _Tp& __x)
{
if (__n != 0) {
@@ -704,7 +964,7 @@ void vector<_Tp, _Alloc>::_M_fill_insert
}
}
else {
- const size_type __old_size = size();
+ const size_type __old_size = size();
const size_type __len = __old_size + max(__old_size, __n);
iterator __new_start(_M_allocate(__len));
iterator __new_finish(__new_start);
@@ -716,7 +976,7 @@ void vector<_Tp, _Alloc>::_M_fill_insert
}
catch(...)
{
- _Destroy(__new_start,__new_finish);
+ _Destroy(__new_start,__new_finish);
_M_deallocate(__new_start.base(),__len);
__throw_exception_again;
}
@@ -730,9 +990,9 @@ void vector<_Tp, _Alloc>::_M_fill_insert
}
template <class _Tp, class _Alloc> template <class _InputIterator>
-void
-vector<_Tp, _Alloc>::_M_range_insert(iterator __pos,
- _InputIterator __first,
+void
+vector<_Tp, _Alloc>::_M_range_insert(iterator __pos,
+ _InputIterator __first,
_InputIterator __last,
input_iterator_tag)
{
@@ -743,7 +1003,7 @@ vector<_Tp, _Alloc>::_M_range_insert(ite
}
template <class _Tp, class _Alloc> template <class _ForwardIterator>
-void
+void
vector<_Tp, _Alloc>::_M_range_insert(iterator __position,
_ForwardIterator __first,
_ForwardIterator __last,
@@ -776,7 +1036,7 @@ vector<_Tp, _Alloc>::_M_range_insert(ite
iterator __new_start(_M_allocate(__len));
iterator __new_finish(__new_start);
try {
- __new_finish = uninitialized_copy(iterator(_M_start),
+ __new_finish = uninitialized_copy(iterator(_M_start),
__position, __new_start);
__new_finish = uninitialized_copy(__first, __last, __new_finish);
__new_finish
@@ -797,7 +1057,7 @@ vector<_Tp, _Alloc>::_M_range_insert(ite
}
}
-} // namespace std
+} // namespace std
#endif /* __GLIBCPP_INTERNAL_VECTOR_H */