diff --git a/doc/circular_buffer.html b/doc/circular_buffer.html index 22634ff..bfdba4f 100644 --- a/doc/circular_buffer.html +++ b/doc/circular_buffer.html @@ -4971,11 +4971,11 @@ template <class T, class Alloc> The number of min(n, (pos - begin()) + reserve()) elements will - inserted starting at the position pos.
+ be inserted at the position pos.
The number of min(pos - begin(), max(0, n - reserve())) elements - will be overwritten starting at the beginning of the circular_buffer.
+ will be overwritten at the beginning of the circular_buffer.
(See Example for the explanation.) @@ -5103,15 +5103,15 @@ template <class T, class Alloc> Postcondition:
- Elements from the range [first + max(0, last - (pos - begin()) + [first + max(0, distance(first, last) - (pos - begin()) - reserve()), last) will - inserted starting at the position pos.
+ be inserted at the position pos.
The number of min(pos - begin(), max(0, distance(first, last) - reserve())) elements - will be overwritten starting at the beginning of the circular_buffer.
+ will be overwritten at the beginning of the circular_buffer.
(See Example for the explanation.)
@@ -5344,14 +5344,14 @@ template <class T, class Alloc> Postcondition:
- TODO The number of min(n, (pos - begin()) + min(n, (end() - pos) + reserve()) elements will - inserted starting at the position pos.
- The number of min(pos - begin(), max(0, n - reserve())) elements - will be overwritten starting at the beginning of the circular_buffer.
+ be inserted before the position pos.
+ The number of min(end() - pos, max(0, n - + reserve())) + elements will be overwritten at the end of the circular_buffer.
(See Example for the explanation.)
@@ -5468,7 +5468,9 @@ template <class T, class Alloc> Precondition:
- Valid pos iterator and valid range [first, last). + pos is a valid iterator pointing to the circular_buffer or its end.
+ Valid range [first, last) where first and last meet the + requirements of an InputIterator.
@@ -5476,18 +5478,78 @@ template <class T, class Alloc> Postcondition:
- This operation preserves the capacity of the circular buffer. If the insertion would result in - exceeding the capacity of the circular buffer then the necessary number of elements from the end of the - circular buffer will be removed or not the whole range will be inserted or both. In case the whole - range cannot be inserted it will be inserted just some elements from the beginning of the range (see - the example).
- Example:
- array to insert: int array[] = { 5, 6, 7, 8, 9 };
- original circular buffer |1|2|3|4| | | - capacity: 6, size: 4
- position ---------------------^
- insert(position, array, array + 5);
- (If the operation won't preserve capacity, the buffer would look like this |1|2|5|6|7|8|9|3|4|)
- RESULTING circular buffer |1|2|5|6|7|8| - capacity: 6, size: 6 + Elements from the range [first, last - max(0, distance(first, last) - (end() - pos) - reserve())) will be + inserted before the position pos.
+ The number of min(end() - pos, max(0, + distance(first, last) - reserve())) elements + will be overwritten at the end of the circular_buffer.
+ (See Example for the explanation.) +
+
+
+
+ Parameter(s): +
+
+
+
+ pos +
+
+ An iterator specifying the position where the range will be inserted. +
+
+
+
+
+
+ first +
+
+ The beginning of the range to be inserted. +
+
+
+
+
+
+ last +
+
+ The end of the range to be inserted. +
+
+
+
+
+
+ Example: +
+
+ Consider a circular_buffer with the capacity of 6 and the size of 4. Its internal buffer + may look like the one below.
+
+ |1|2|3|4| | |
+ p ---^
+
+ After inserting a range of elements before the position p:
+
+ int array[] = { 5, 6, 7, 8, 9 };
+ insert(p, array, array + 5);
+
+ actually only elements 5, 6, 7 and 8 from the + specified range get inserted and elements 3 and 4 are overwritten. This is + due to the fact the insert operation preserves the capacity. After insertion the internal buffer looks + like this:
+
+ |1|2|5|6|7|8|
+
+ For comparison if the capacity would not be preserved the internal buffer would then result in + |1|2|5|6|7|8|9|3|4|.
@@ -5503,10 +5565,28 @@ template <class T, class Alloc>
- Note: + Iterator Invalidation:
- For iterator invalidation see the documentation. + Invalidates iterators pointing to the elements before the insertion point (towards the beginning and + excluding pos). It also invalidates iterators pointing to the overwritten elements. +
+
+
+
+ See Also: +
+
+ rinsert(iterator, + value_type), rinsert(iterator, size_type, + value_type), insert(iterator, + value_type), insert(iterator, size_type, + value_type), insert(iterator, InputIterator, + InputIterator)
diff --git a/include/boost/circular_buffer/base.hpp b/include/boost/circular_buffer/base.hpp index 0d7ff2e..ddcc301 100644 --- a/include/boost/circular_buffer/base.hpp +++ b/include/boost/circular_buffer/base.hpp @@ -1403,10 +1403,10 @@ public: //! Insert n copies of the item at the specified position. /*! \pre pos is a valid iterator pointing to the circular_buffer or its end. - \post The number of min(n, (pos - begin()) + reserve()) elements will inserted starting at the - position pos.
The number of min(pos - begin(), max(0, n - reserve())) - elements will be overwritten starting at the beginning of the circular_buffer.
(See - Example for the explanation.) + \post The number of min(n, (pos - begin()) + reserve()) elements will be inserted at the position + pos.
The number of min(pos - begin(), max(0, n - reserve())) elements will + be overwritten at the beginning of the circular_buffer.
(See Example for the + explanation.) \param pos An iterator specifying the position where the items will be inserted. \param n The number of items the to be inserted. \param item The element whose copies will be inserted. @@ -1450,9 +1450,10 @@ public: \pre pos is a valid iterator pointing to the circular_buffer or its end.
Valid range [first, last) where first and last meet the requirements of an InputIterator. - \post Elements from the range [first + max(0, last - (pos - begin()) + reserve()), last) will - inserted starting at the position pos.
The number of min(pos - begin(), max(0, - distance(first, last) - reserve())) elements will be overwritten starting at the beginning of the + \post Elements from the range + [first + max(0, distance(first, last) - (pos - begin()) - reserve()), last) will be + inserted at the position pos.
The number of min(pos - begin(), max(0, + distance(first, last) - reserve())) elements will be overwritten at the beginning of the circular_buffer.
(See Example for the explanation.) \param pos An iterator specifying the position where the range will be inserted. \param first The beginning of the range to be inserted. @@ -1560,10 +1561,9 @@ public: //! Insert n copies of the item before the specified position. /*! \pre pos is a valid iterator pointing to the circular_buffer or its end. - \post TODO The number of min(n, (pos - begin()) + reserve()) elements will inserted starting at the - position pos.
The number of min(pos - begin(), max(0, n - reserve())) - elements will be overwritten starting at the beginning of the circular_buffer.
(See - Example for the explanation.) + \post The number of min(n, (end() - pos) + reserve()) elements will be inserted before the + position pos.
The number of min(end() - pos, max(0, n - reserve())) elements + will be overwritten at the end of the circular_buffer.
(See Example for the explanation.) \param pos An iterator specifying the position where the items will be inserted. \param n The number of items the to be inserted. \param item The element whose copies will be inserted. @@ -1596,25 +1596,39 @@ public: //! Insert the range [first, last) before the specified position. /*! - \pre Valid pos iterator and valid range [first, last). - \post This operation preserves the capacity of the circular buffer. - If the insertion would result in exceeding the capacity - of the circular buffer then the necessary number of elements - from the end of the circular buffer will be removed - or not the whole range will be inserted or both. - In case the whole range cannot be inserted it will be inserted just - some elements from the beginning of the range (see the example).
- Example:
- array to insert: int array[] = { 5, 6, 7, 8, 9 };
- original circular buffer |1|2|3|4| | | - capacity: 6, size: 4
- position ---------------------^
- insert(position, array, array + 5);
- (If the operation won't preserve capacity, the buffer - would look like this |1|2|5|6|7|8|9|3|4|)
- RESULTING circular buffer |1|2|5|6|7|8| - capacity: 6, size: 6 + \pre pos is a valid iterator pointing to the circular_buffer or its end.
+ Valid range [first, last) where first and last meet the + requirements of an InputIterator. + \post Elements from the range + [first, last - max(0, distance(first, last) - (end() - pos) - reserve())) will be inserted + before the position pos.
The number of min(end() - pos, max(0, + distance(first, last) - reserve())) elements will be overwritten at the end of the + circular_buffer.
(See Example for the explanation.) + \param pos An iterator specifying the position where the range will be inserted. + \param first The beginning of the range to be inserted. + \param last The end of the range to be inserted. + \par Example + Consider a circular_buffer with the capacity of 6 and the size of 4. Its internal buffer may + look like the one below.

+ |1|2|3|4| | |
+ p ---^

After inserting a range of elements before the position p:

+ int array[] = { 5, 6, 7, 8, 9 };
insert(p, array, array + 5);

+ actually only elements 5, 6, 7 and 8 from the + specified range get inserted and elements 3 and 4 are overwritten. This is due + to the fact the insert operation preserves the capacity. After insertion the internal buffer looks like + this:

|1|2|5|6|7|8|

For comparison if the capacity would not be preserved the + internal buffer would then result in |1|2|5|6|7|8|9|3|4|. \throws Whatever T::T(const T&) throws. \throws Whatever T::operator = (const T&) throws. - \note For iterator invalidation see the documentation. + \par Iterator Invalidation + Invalidates iterators pointing to the elements before the insertion point (towards the beginning and + excluding pos). It also invalidates iterators pointing to the overwritten elements. + \sa \link rinsert(iterator, param_value_type) rinsert(iterator, value_type)\endlink, + \link rinsert(iterator, size_type, param_value_type) + rinsert(iterator, size_type, value_type)\endlink, \link insert(iterator, param_value_type) + insert(iterator, value_type)\endlink, \link insert(iterator, size_type, param_value_type) + insert(iterator, size_type, value_type)\endlink, + insert(iterator, InputIterator, InputIterator) */ template void rinsert(iterator pos, InputIterator first, InputIterator last) {