From bfae9406c86fe213afb7c40ea006afc41b03be6b Mon Sep 17 00:00:00 2001 From: Jan Gaspar Date: Fri, 8 Dec 2006 23:02:20 +0000 Subject: [PATCH] updated srcdoc [SVN r3505] --- doc/circular_buffer.html | 545 ++++++++++++++++++++----- include/boost/circular_buffer/base.hpp | 223 ++++++---- 2 files changed, 584 insertions(+), 184 deletions(-) diff --git a/doc/circular_buffer.html b/doc/circular_buffer.html index 6362489..d649dd7 100644 --- a/doc/circular_buffer.html +++ b/doc/circular_buffer.html @@ -1489,6 +1489,14 @@ template <class T, class Alloc> Invalidates all iterators pointing to the circular_buffer. +
+
+ See Also: +
+
+ clear() +
+
@@ -1543,7 +1551,7 @@ template <class T, class Alloc> Iterator Invalidation:
- Does not invalidate any iterator. + Does not invalidate any iterators.
@@ -1603,7 +1611,7 @@ template <class T, class Alloc> Iterator Invalidation:
- Does not invalidate any iterator. + Does not invalidate any iterators.
@@ -1672,7 +1680,7 @@ template <class T, class Alloc> Iterator Invalidation:
- Does not invalidate any iterator. + Does not invalidate any iterators.
@@ -1734,7 +1742,7 @@ template <class T, class Alloc> Iterator Invalidation:
- Does not invalidate any iterator. + Does not invalidate any iterators.
@@ -1797,7 +1805,7 @@ template <class T, class Alloc> Iterator Invalidation:
- Does not invalidate any iterator. + Does not invalidate any iterators.
@@ -1862,7 +1870,7 @@ template <class T, class Alloc> Iterator Invalidation:
- Does not invalidate any iterator. + Does not invalidate any iterators.
@@ -1926,7 +1934,7 @@ template <class T, class Alloc> Iterator Invalidation:
- Does not invalidate any iterator. + Does not invalidate any iterators.
@@ -1989,7 +1997,7 @@ template <class T, class Alloc> Iterator Invalidation:
- Does not invalidate any iterator. + Does not invalidate any iterators.
@@ -2052,7 +2060,7 @@ template <class T, class Alloc> Iterator Invalidation:
- Does not invalidate any iterator. + Does not invalidate any iterators.
@@ -2117,7 +2125,7 @@ template <class T, class Alloc> Iterator Invalidation:
- Does not invalidate any iterator. + Does not invalidate any iterators.
@@ -2196,7 +2204,7 @@ template <class T, class Alloc> Iterator Invalidation:
- Does not invalidate any iterator. + Does not invalidate any iterators.
@@ -2272,7 +2280,7 @@ template <class T, class Alloc> Iterator Invalidation:
- Does not invalidate any iterator. + Does not invalidate any iterators.
@@ -2339,7 +2347,7 @@ template <class T, class Alloc> Iterator Invalidation:
- Does not invalidate any iterator. + Does not invalidate any iterators.
@@ -2407,7 +2415,7 @@ template <class T, class Alloc> Iterator Invalidation:
- Does not invalidate any iterator. + Does not invalidate any iterators.
@@ -2473,7 +2481,7 @@ template <class T, class Alloc> Iterator Invalidation:
- Does not invalidate any iterator. + Does not invalidate any iterators.
@@ -2538,7 +2546,7 @@ template <class T, class Alloc> Iterator Invalidation:
- Does not invalidate any iterator. + Does not invalidate any iterators.
@@ -2604,7 +2612,7 @@ template <class T, class Alloc> Iterator Invalidation:
- Does not invalidate any iterator. + Does not invalidate any iterators.
@@ -2671,7 +2679,7 @@ template <class T, class Alloc> Iterator Invalidation:
- Does not invalidate any iterator. + Does not invalidate any iterators.
@@ -2778,7 +2786,7 @@ template <class T, class Alloc> Iterator Invalidation:
- Does not invalidate any iterator. + Does not invalidate any iterators.
@@ -2870,7 +2878,7 @@ template <class T, class Alloc> Iterator Invalidation:
- Does not invalidate any iterator. + Does not invalidate any iterators.
@@ -2935,7 +2943,7 @@ template <class T, class Alloc> Iterator Invalidation:
- Does not invalidate any iterator. + Does not invalidate any iterators.
@@ -3003,7 +3011,7 @@ template <class T, class Alloc> Iterator Invalidation:
- Does not invalidate any iterator. + Does not invalidate any iterators.
@@ -3077,7 +3085,7 @@ template <class T, class Alloc>
Invalidates all iterators pointing to the circular_buffer; does not invalidate any - iterator if the postcondition is already met prior calling this method. + iterators if the postcondition is already met prior calling this method.
@@ -3148,7 +3156,7 @@ template <class T, class Alloc> Iterator Invalidation:
- Does not invalidate any iterator. + Does not invalidate any iterators.
@@ -3210,7 +3218,7 @@ template <class T, class Alloc> Iterator Invalidation:
- Does not invalidate any iterator. + Does not invalidate any iterators.
@@ -3269,7 +3277,7 @@ template <class T, class Alloc> Iterator Invalidation:
- Does not invalidate any iterator. + Does not invalidate any iterators.
@@ -3327,7 +3335,7 @@ template <class T, class Alloc> Iterator Invalidation:
- Does not invalidate any iterator. + Does not invalidate any iterators.
@@ -3385,7 +3393,7 @@ template <class T, class Alloc> Iterator Invalidation:
- Does not invalidate any iterator. + Does not invalidate any iterators.
@@ -4213,12 +4221,20 @@ template <class T, class Alloc> swap(circular_buffer<T,Alloc>& cb);

Swap the contents of two circular_buffers. +
+
+ Postcondition: +
+
+ this contains elements of cb and vice versa. +
+
Parameter(s):
- cb The circular_buffer whose content should be swapped. + cb The circular_buffer whose content will be swapped.
@@ -4229,14 +4245,6 @@ template <class T, class Alloc> Nothing.
-
-
- Postcondition: -
-
- this contains elements of cb and vice versa. -
-
Complexity: @@ -4282,15 +4290,25 @@ template <class T, class Alloc> "#classboost_1_1circular__buffer_1a8397191092f5bacee991b623ca4b910">const_reference item = value_type());

- Insert a new element at the end. + Insert a new element at the end of the circular_buffer.
Postcondition:
- (*this).back() == - item
- If the circular buffer is full, the first (leftmost) element will be removed. + if capacity() + > 0 then back() == item
+ If the circular_buffer is full, the first (leftmost) element will be removed. If the + capacity is 0, nothing will be inserted. +
+
+
+
+ Parameter(s): +
+
+ item The element to be inserted.
@@ -4303,10 +4321,39 @@ template <class T, class Alloc>
- Note: + Complexity:
- For iterator invalidation see the documentation. + Constant (in the size of the circular_buffer). +
+
+
+
+ Exception Safety: +
+
+ Basic; no-throw if the operation in the Throws section do not throw anything. +
+
+
+
+ Iterator Invalidation: +
+
+ Does not invalidate any iterators with the exception of iterators pointing to the overwritten element. +
+
+
+
+ See Also: +
+
+ push_front(), + pop_back(), + pop_front()
@@ -4318,15 +4365,25 @@ template <class T, class Alloc> "#classboost_1_1circular__buffer_1a8397191092f5bacee991b623ca4b910">const_reference item = value_type());

- Insert a new element at the start. + Insert a new element at the beginning of the circular_buffer.
Postcondition:
- (*this).front() - == item
- If the circular buffer is full, the last (rightmost) element will be removed. + if capacity() + > 0 then front() == item
+ If the circular_buffer is full, the last (rightmost) element will be removed. If the + capacity is 0, nothing will be inserted. +
+
+
+
+ Parameter(s): +
+
+ item The element to be inserted.
@@ -4339,10 +4396,39 @@ template <class T, class Alloc>
- Note: + Complexity:
- For iterator invalidation see the documentation. + Constant (in the size of the circular_buffer). +
+
+
+
+ Exception Safety: +
+
+ Basic; no-throw if the operation in the Throws section do not throw anything. +
+
+
+
+ Iterator Invalidation: +
+
+ Does not invalidate any iterators with the exception of iterators pointing to the overwritten element. +
+
+
+
+ See Also: +
+
+ push_back(), + pop_back(), + pop_front()
@@ -4353,16 +4439,13 @@ template <class T, class Alloc> "classboost_1_1circular__buffer_1df0da00cb501bea75afbbfab9f546a07">void pop_back();

- Remove the last (rightmost) element. + Remove the last (rightmost) element from the circular_buffer.
Precondition:
- !*(this).empty() iterator - it = ((*this).end() - - 1) + !empty()
@@ -4370,16 +4453,52 @@ template <class T, class Alloc> Postcondition:
- ((*this).end() - - 1) != it + The last (rightmost) element is removed from the circular_buffer.
- Note: + Throws:
- For iterator invalidation see the documentation. + Nothing. +
+
+
+
+ Complexity: +
+
+ Constant (in the size of the circular_buffer). +
+
+
+
+ Exception Safety: +
+
+ No-throw. +
+
+
+
+ Iterator Invalidation: +
+
+ Invalidates only iterators pointing to the removed element. +
+
+
+
+ See Also: +
+
+ pop_front(), + push_back(), + push_front()
@@ -4390,16 +4509,13 @@ template <class T, class Alloc> "classboost_1_1circular__buffer_18ac972dc24ef7236faa1875de92b9dd8">void pop_front();

- Remove the first (leftmost) element. + Remove the first (leftmost) element from the circular_buffer.
Precondition:
- !*(this).empty() iterator - it = (*this).begin() + !empty()
@@ -4407,16 +4523,52 @@ template <class T, class Alloc> Postcondition:
- (*this).begin() - != it + The first (leftmost) element is removed from the circular_buffer.
- Note: + Throws:
- For iterator invalidation see the documentation. + Nothing. +
+
+
+
+ Complexity: +
+
+ Constant (in the size of the circular_buffer). +
+
+
+
+ Exception Safety: +
+
+ No-throw. +
+
+
+
+ Iterator Invalidation: +
+
+ Invalidates only iterators pointing to the removed element. +
+
+
+
+ See Also: +
+
+ pop_back(), + push_back(), + push_front()
@@ -4766,14 +4918,13 @@ template <class T, class Alloc> "#classboost_1_1circular__buffer_11b8a33f2dc8519b8a7d344ed4408c532">iterator erase(iterator pos);

- Erase the element at the specified position. + Remove an element at the specified position.
Precondition:
- Valid pos iterator. size_type old_size = (*this).size() + pos is a valid iterator.
@@ -4781,9 +4932,7 @@ template <class T, class Alloc> Postcondition:
- (*this).size() == - old_size - 1
- Removes an element at the position pos. + The element at the position pos is removed.
@@ -4791,17 +4940,55 @@ template <class T, class Alloc> Returns:
- iterator to the first element remaining beyond the removed element or (*this).end() if no such element exists.
- Note: + Throws:
- For iterator invalidation see the documentation. + Whatever T::operator = (const T&) throws. +
+
+
+
+ Complexity: +
+
+ Linear (in the size of the circular_buffer). +
+
+
+
+ Exception Safety: +
+
+ Basic; no-throw if the operation in the Throws section does not throw anything. +
+
+
+
+ Iterator Invalidation: +
+
+ Invalidates iterators pointing to the erased element and iterators pointing to the elements behind (to + the right from) the erased element. +
+
+
+
+ See Also: +
+
+ erase(iterator, + iterator), rerase(iterator), + rerase(iterator, + iterator), clear()
@@ -4820,8 +5007,7 @@ template <class T, class Alloc> Precondition:
- Valid range [first, last). size_type old_size = (*this).size() + Valid range [first, last).
@@ -4829,9 +5015,7 @@ template <class T, class Alloc> Postcondition:
- (*this).size() == - old_size - std::distance(first, last)
- Removes the elements from the range [first, last). + The elements from the range [first, last) are removed.
@@ -4839,17 +5023,56 @@ template <class T, class Alloc> Returns:
- iterator to the first element remaining beyond the removed element or (*this).end() if no such element exists.
- Note: + Throws:
- For iterator invalidation see the documentation. + Whatever T::operator = (const T&) throws. +
+
+
+
+ Complexity: +
+
+ Linear (in the size of the circular_buffer). +
+
+
+
+ Exception Safety: +
+
+ Basic; no-throw if the operation in the Throws section does not throw anything. +
+
+
+
+ Iterator Invalidation: +
+
+ Invalidates iterators pointing to the erased elements and iterators pointing to the elements behind (to + the right from) the erased range. +
+
+
+
+ See Also: +
+
+ erase(iterator), + rerase(iterator), + rerase(iterator, + iterator), clear()
@@ -4861,14 +5084,13 @@ template <class T, class Alloc> "#classboost_1_1circular__buffer_11b8a33f2dc8519b8a7d344ed4408c532">iterator rerase(iterator pos);

- Erase the element at the specified position. + Remove an element at the specified position.
Precondition:
- Valid pos iterator. size_type old_size = (*this).size() + pos is a valid iterator.
@@ -4876,9 +5098,7 @@ template <class T, class Alloc> Postcondition:
- (*this).size() == - old_size - 1
- Removes an element at the position pos. + The element at the position pos is removed.
@@ -4886,17 +5106,56 @@ template <class T, class Alloc> Returns:
- iterator to the first element remaining in front of the removed element or (*this).begin() if no such element exists.
- Note: + Throws:
- For iterator invalidation see the documentation. + Whatever T::operator = (const T&) throws. +
+
+
+
+ Complexity: +
+
+ Linear (in the size of the circular_buffer). +
+
+
+
+ Exception Safety: +
+
+ Basic; no-throw if the operation in the Throws section does not throw anything. +
+
+
+
+ Iterator Invalidation: +
+
+ Invalidates iterators pointing to the erased element and iterators pointing to the elements in front of + (to the left from) the erased element. +
+
+
+
+ See Also: +
+
+ erase(iterator), + erase(iterator, + iterator), rerase(iterator, + iterator), clear()
@@ -4915,8 +5174,7 @@ template <class T, class Alloc> Precondition:
- Valid range [first, last). size_type old_size = (*this).size() + Valid range [first, last).
@@ -4924,9 +5182,7 @@ template <class T, class Alloc> Postcondition:
- (*this).size() == - old_size - std::distance(first, last)
- Removes the elements from the range [first, last). + The elements from the range [first, last) are removed.
@@ -4934,17 +5190,55 @@ template <class T, class Alloc> Returns:
- iterator to the first element remaining in front of the removed element or (*this).begin() if no such element exists.
- Note: + Throws:
- For iterator invalidation see the documentation. + Whatever T::operator = (const T&) throws. +
+
+
+
+ Complexity: +
+
+ Linear (in the size of the circular_buffer). +
+
+
+
+ Exception Safety: +
+
+ Basic; no-throw if the operation in the Throws section does not throw anything. +
+
+
+
+ Iterator Invalidation: +
+
+ Invalidates iterators pointing to the erased elements and iterators pointing to the elements in front + of (to the left from) the erased range. +
+
+
+
+ See Also: +
+
+ erase(iterator), + erase(iterator, + iterator), rerase(iterator), + clear()
@@ -4955,21 +5249,62 @@ template <class T, class Alloc> "classboost_1_1circular__buffer_1826f5770a40b8b752eb9587378464d1e">void clear();

- Erase all stored elements. + Remove all stored elements from the circular_buffer.
Postcondition:
- (*this).size() == 0 + size() == + 0
- Note: + Throws:
- For iterator invalidation see the documentation. + Nothing. +
+
+
+
+ Complexity: +
+
+ Linear (in the size of the circular_buffer). +
+
+
+
+ Exception Safety: +
+
+ No-throw. +
+
+
+
+ Iterator Invalidation: +
+
+ Invalidates all iterators pointing to the circular_buffer. +
+
+
+
+ See Also: +
+
+ ~circular_buffer(), + erase(iterator), + erase(iterator, + iterator), rerase(iterator), + rerase(iterator, + iterator)
diff --git a/include/boost/circular_buffer/base.hpp b/include/boost/circular_buffer/base.hpp index 1866c43..c7b3907 100644 --- a/include/boost/circular_buffer/base.hpp +++ b/include/boost/circular_buffer/base.hpp @@ -183,7 +183,7 @@ public: \par Exception Safety No-throw. \par Iterator Invalidation - Does not invalidate any iterator. + Does not invalidate any iterators. \sa get_allocator() for obtaining an allocator %reference. */ allocator_type get_allocator() const { return m_alloc; } @@ -197,7 +197,7 @@ public: \par Exception Safety No-throw. \par Iterator Invalidation - Does not invalidate any iterator. + Does not invalidate any iterators. \note This method was added in order to optimize obtaining of the allocator with a state, although use of stateful allocators in STL is discouraged. \sa get_allocator() const @@ -217,7 +217,7 @@ public: \par Exception Safety No-throw. \par Iterator Invalidation - Does not invalidate any iterator. + Does not invalidate any iterators. \sa end(), rbegin(), rend() */ iterator begin() { return iterator(this, empty() ? 0 : m_first); } @@ -233,7 +233,7 @@ public: \par Exception Safety No-throw. \par Iterator Invalidation - Does not invalidate any iterator. + Does not invalidate any iterators. \sa begin(), rbegin(), rend() */ iterator end() { return iterator(this, 0); } @@ -249,7 +249,7 @@ public: \par Exception Safety No-throw. \par Iterator Invalidation - Does not invalidate any iterator. + Does not invalidate any iterators. \sa end() const, rbegin() const, rend() const */ const_iterator begin() const { return const_iterator(this, empty() ? 0 : m_first); } @@ -265,7 +265,7 @@ public: \par Exception Safety No-throw. \par Iterator Invalidation - Does not invalidate any iterator. + Does not invalidate any iterators. \sa begin() const, rbegin() const, rend() const */ const_iterator end() const { return const_iterator(this, 0); } @@ -281,7 +281,7 @@ public: \par Exception Safety No-throw. \par Iterator Invalidation - Does not invalidate any iterator. + Does not invalidate any iterators. \sa rend(), begin(), end() */ reverse_iterator rbegin() { return reverse_iterator(end()); } @@ -297,7 +297,7 @@ public: \par Exception Safety No-throw. \par Iterator Invalidation - Does not invalidate any iterator. + Does not invalidate any iterators. \sa rbegin(), begin(), end() */ reverse_iterator rend() { return reverse_iterator(begin()); } @@ -313,7 +313,7 @@ public: \par Exception Safety No-throw. \par Iterator Invalidation - Does not invalidate any iterator. + Does not invalidate any iterators. \sa rend() const, begin() const, end() const */ const_reverse_iterator rbegin() const { return const_reverse_iterator(end()); } @@ -329,7 +329,7 @@ public: \par Exception Safety No-throw. \par Iterator Invalidation - Does not invalidate any iterator. + Does not invalidate any iterators. \sa rbegin() const, begin() const, end() const */ const_reverse_iterator rend() const { return const_reverse_iterator(begin()); } @@ -345,7 +345,7 @@ public: \par Exception Safety No-throw. \par Iterator Invalidation - Does not invalidate any iterator. + Does not invalidate any iterators. \sa at() */ reference operator [] (size_type index) { @@ -364,7 +364,7 @@ public: \par Exception Safety No-throw. \par Iterator Invalidation - Does not invalidate any iterator. + Does not invalidate any iterators. \sa \link at(size_type)const at() const \endlink */ return_value_type operator [] (size_type index) const { @@ -382,7 +382,7 @@ public: \par Exception Safety Strong. \par Iterator Invalidation - Does not invalidate any iterator. + Does not invalidate any iterators. \sa operator[] */ reference at(size_type index) { @@ -400,7 +400,7 @@ public: \par Exception Safety Strong. \par Iterator Invalidation - Does not invalidate any iterator. + Does not invalidate any iterators. \sa \link operator[](size_type)const operator[] const \endlink */ return_value_type at(size_type index) const { @@ -418,7 +418,7 @@ public: \par Exception Safety No-throw. \par Iterator Invalidation - Does not invalidate any iterator. + Does not invalidate any iterators. \sa back() */ reference front() { @@ -436,7 +436,7 @@ public: \par Exception Safety No-throw. \par Iterator Invalidation - Does not invalidate any iterator. + Does not invalidate any iterators. \sa front() */ reference back() { @@ -454,7 +454,7 @@ public: \par Exception Safety No-throw. \par Iterator Invalidation - Does not invalidate any iterator. + Does not invalidate any iterators. \sa back() const */ return_value_type front() const { @@ -472,7 +472,7 @@ public: \par Exception Safety No-throw. \par Iterator Invalidation - Does not invalidate any iterator. + Does not invalidate any iterators. \sa front() const */ return_value_type back() const { @@ -516,7 +516,7 @@ public: \par Exception Safety No-throw. \par Iterator Invalidation - Does not invalidate any iterator. + Does not invalidate any iterators. \warning In general invoking any method which modifies the internal state of the circular_buffer may delinearize the internal buffer and invalidate the array ranges returned by array_one() and array_two() (and their const versions). @@ -542,7 +542,7 @@ public: \par Exception Safety No-throw. \par Iterator Invalidation - Does not invalidate any iterator. + Does not invalidate any iterators. \sa array_one() */ array_range array_two() { @@ -561,7 +561,7 @@ public: \par Exception Safety No-throw. \par Iterator Invalidation - Does not invalidate any iterator. + Does not invalidate any iterators. \sa array_two() const; array_one() for more details.how to pass data into a legacy C API. */ @@ -582,7 +582,7 @@ public: \par Exception Safety No-throw. \par Iterator Invalidation - Does not invalidate any iterator. + Does not invalidate any iterators. \sa array_one() const */ const_array_range array_two() const { @@ -601,7 +601,7 @@ public: \par Exception Safety Basic; no-throw if the operations in the Throws section do not throw anything. \par Iterator Invalidation - Invalidates all iterators pointing to the circular_buffer; does not invalidate any iterator + Invalidates all iterators pointing to the circular_buffer; does not invalidate any iterators if the postcondition is already met prior calling this method. \warning In general invoking any method which modifies the internal state of the circular_buffer may delinearize the internal buffer and invalidate the returned pointer. @@ -662,7 +662,7 @@ public: \par Exception Safety No-throw. \par Iterator Invalidation - Does not invalidate any iterator. + Does not invalidate any iterators. \sa capacity(), max_size(), resize() */ size_type size() const { return m_size; } @@ -676,7 +676,7 @@ public: \par Exception Safety No-throw. \par Iterator Invalidation - Does not invalidate any iterator. + Does not invalidate any iterators. \sa size(), capacity() */ size_type max_size() const { @@ -693,7 +693,7 @@ public: \par Exception Safety No-throw. \par Iterator Invalidation - Does not invalidate any iterator. + Does not invalidate any iterators. \sa full() */ bool empty() const { return size() == 0; } @@ -708,7 +708,7 @@ public: \par Exception Safety No-throw. \par Iterator Invalidation - Does not invalidate any iterator. + Does not invalidate any iterators. \sa empty() */ bool full() const { return size() == capacity(); } @@ -722,7 +722,7 @@ public: \par Exception Safety No-throw. \par Iterator Invalidation - Does not invalidate any iterator. + Does not invalidate any iterators. \sa size(), max_size(), set_capacity() */ size_type capacity() const { return m_end - m_buff; } @@ -1051,6 +1051,7 @@ public: No-throw. \par Iterator Invalidation Invalidates all iterators pointing to the circular_buffer. + \sa clear() */ ~circular_buffer() { destroy(); } @@ -1216,9 +1217,9 @@ public: //! Swap the contents of two circular_buffers. /*! - \param cb The circular_buffer whose content should be swapped. - \throws Nothing. \post this contains elements of cb and vice versa. + \param cb The circular_buffer whose content will be swapped. + \throws Nothing. \par Complexity Constant (in the size of the circular_buffer). \par Exception Safety @@ -1245,12 +1246,20 @@ public: // push and pop - //! Insert a new element at the end. + //! Insert a new element at the end of the circular_buffer. /*! - \post (*this).back() == item
- If the circular buffer is full, the first (leftmost) element will be removed. + \post if capacity() > 0 then back() == item
+ If the circular_buffer is full, the first (leftmost) element will be removed. If the + capacity is 0, nothing will be inserted. + \param item The element to be inserted. \throws Whatever T::T(const T&) throws. - \note For iterator invalidation see the documentation. + \par Complexity + Constant (in the size of the circular_buffer). + \par Exception Safety + Basic; no-throw if the operation in the Throws section do not throw anything. + \par Iterator Invalidation + Does not invalidate any iterators with the exception of iterators pointing to the overwritten element. + \sa push_front(), pop_back(), pop_front() */ void push_back(param_value_type item = value_type()) { if (full()) { @@ -1266,12 +1275,20 @@ public: } } - //! Insert a new element at the start. + //! Insert a new element at the beginning of the circular_buffer. /*! - \post (*this).front() == item
- If the circular buffer is full, the last (rightmost) element will be removed. + \post if capacity() > 0 then front() == item
+ If the circular_buffer is full, the last (rightmost) element will be removed. If the + capacity is 0, nothing will be inserted. + \param item The element to be inserted. \throws Whatever T::T(const T&) throws. - \note For iterator invalidation see the documentation. + \par Complexity + Constant (in the size of the circular_buffer). + \par Exception Safety + Basic; no-throw if the operation in the Throws section do not throw anything. + \par Iterator Invalidation + Does not invalidate any iterators with the exception of iterators pointing to the overwritten element. + \sa push_back(), pop_back(), pop_front() */ void push_front(param_value_type item = value_type()) { BOOST_TRY { @@ -1293,12 +1310,18 @@ public: BOOST_CATCH_END } - //! Remove the last (rightmost) element. + //! Remove the last (rightmost) element from the circular_buffer. /*! - \pre !*(this).empty() - \pre iterator it = ((*this).end() - 1) - \post ((*this).end() - 1) != it - \note For iterator invalidation see the documentation. + \pre !empty() + \post The last (rightmost) element is removed from the circular_buffer. + \throws Nothing. + \par Complexity + Constant (in the size of the circular_buffer). + \par Exception Safety + No-throw. + \par Iterator Invalidation + Invalidates only iterators pointing to the removed element. + \sa pop_front(), push_back(), push_front() */ void pop_back() { BOOST_CB_ASSERT(!empty()); // check for empty buffer (back element not available) @@ -1307,12 +1330,18 @@ public: --m_size; } - //! Remove the first (leftmost) element. + //! Remove the first (leftmost) element from the circular_buffer. /*! - \pre !*(this).empty() - \pre iterator it = (*this).begin() - \post (*this).begin() != it - \note For iterator invalidation see the documentation. + \pre !empty() + \post The first (leftmost) element is removed from the circular_buffer. + \throws Nothing. + \par Complexity + Constant (in the size of the circular_buffer). + \par Exception Safety + No-throw. + \par Iterator Invalidation + Invalidates only iterators pointing to the removed element. + \sa pop_back(), push_back(), push_front() */ void pop_front() { BOOST_CB_ASSERT(!empty()); // check for empty buffer (front element not available) @@ -1510,15 +1539,22 @@ public: // Erase - //! Erase the element at the specified position. + //! Remove an element at the specified position. /*! - \pre Valid pos iterator. - \pre size_type old_size = (*this).size() - \post (*this).size() == old_size - 1
- Removes an element at the position pos. - \return iterator to the first element remaining beyond the removed - element or (*this).end() if no such element exists. - \note For iterator invalidation see the documentation. + \pre pos is a valid iterator. + \post The element at the position pos is removed. + \return Iterator to the first element remaining beyond the removed element or end() if no such + element exists. + \throws Whatever T::operator = (const T&) throws. + \par Complexity + Linear (in the size of the circular_buffer). + \par Exception Safety + Basic; no-throw if the operation in the Throws section does not throw anything. + \par Iterator Invalidation + Invalidates iterators pointing to the erased element and iterators pointing to the elements behind (to + the right from) the erased element. + \sa erase(iterator, iterator), rerase(iterator), + rerase(iterator, iterator), clear() */ iterator erase(iterator pos) { BOOST_CB_ASSERT(pos.is_valid()); // check for uninitialized or invalidated iterator @@ -1540,12 +1576,19 @@ public: //! Erase the range [first, last). /*! \pre Valid range [first, last). - \pre size_type old_size = (*this).size() - \post (*this).size() == old_size - std::distance(first, last)
- Removes the elements from the range [first, last). - \return iterator to the first element remaining beyond the removed - element or (*this).end() if no such element exists. - \note For iterator invalidation see the documentation. + \post The elements from the range [first, last) are removed. + \return Iterator to the first element remaining beyond the removed elements or end() if no such + element exists. + \throws Whatever T::operator = (const T&) throws. + \par Complexity + Linear (in the size of the circular_buffer). + \par Exception Safety + Basic; no-throw if the operation in the Throws section does not throw anything. + \par Iterator Invalidation + Invalidates iterators pointing to the erased elements and iterators pointing to the elements behind (to + the right from) the erased range. + \sa erase(iterator), rerase(iterator), rerase(iterator, iterator), + clear() */ iterator erase(iterator first, iterator last) { BOOST_CB_ASSERT(first.is_valid()); // check for uninitialized or invalidated iterator @@ -1565,15 +1608,22 @@ public: return m_last == p ? end() : iterator(this, p); } - //! Erase the element at the specified position. + //! Remove an element at the specified position. /*! - \pre Valid pos iterator. - \pre size_type old_size = (*this).size() - \post (*this).size() == old_size - 1
- Removes an element at the position pos. - \return iterator to the first element remaining in front of the removed - element or (*this).begin() if no such element exists. - \note For iterator invalidation see the documentation. + \pre pos is a valid iterator. + \post The element at the position pos is removed. + \return Iterator to the first element remaining in front of the removed element or begin() if no + such element exists. + \throws Whatever T::operator = (const T&) throws. + \par Complexity + Linear (in the size of the circular_buffer). + \par Exception Safety + Basic; no-throw if the operation in the Throws section does not throw anything. + \par Iterator Invalidation + Invalidates iterators pointing to the erased element and iterators pointing to the elements in front of + (to the left from) the erased element. + \sa erase(iterator), erase(iterator, iterator), + rerase(iterator, iterator), clear() */ iterator rerase(iterator pos) { BOOST_CB_ASSERT(pos.is_valid()); // check for uninitialized or invalidated iterator @@ -1595,12 +1645,19 @@ public: //! Erase the range [first, last). /*! \pre Valid range [first, last). - \pre size_type old_size = (*this).size() - \post (*this).size() == old_size - std::distance(first, last)
- Removes the elements from the range [first, last). - \return iterator to the first element remaining in front of the removed - element or (*this).begin() if no such element exists. - \note For iterator invalidation see the documentation. + \post The elements from the range [first, last) are removed. + \return Iterator to the first element remaining in front of the removed elements or begin() if no + such element exists. + \throws Whatever T::operator = (const T&) throws. + \par Complexity + Linear (in the size of the circular_buffer). + \par Exception Safety + Basic; no-throw if the operation in the Throws section does not throw anything. + \par Iterator Invalidation + Invalidates iterators pointing to the erased elements and iterators pointing to the elements in front of + (to the left from) the erased range. + \sa erase(iterator), erase(iterator, iterator), rerase(iterator), + clear() */ iterator rerase(iterator first, iterator last) { BOOST_CB_ASSERT(first.is_valid()); // check for uninitialized or invalidated iterator @@ -1627,10 +1684,18 @@ public: return iterator(this, last.m_it); } - //! Erase all stored elements. + //! Remove all stored elements from the circular_buffer. /*! - \post (*this).size() == 0 - \note For iterator invalidation see the documentation. + \post size() == 0 + \throws Nothing. + \par Complexity + Linear (in the size of the circular_buffer). + \par Exception Safety + No-throw. + \par Iterator Invalidation + Invalidates all iterators pointing to the circular_buffer. + \sa ~circular_buffer(), erase(iterator), erase(iterator, iterator), + rerase(iterator), rerase(iterator, iterator) */ void clear() { destroy_content();