Тип элементов, хранящихся в circular_buffer.

The type of the elements stored in the circular_buffer.

typename Alloc

The allocator type used for all internal memory management.

typedef boost::container::allocator_traits< Alloc >::difference_type difference_type;

(A signed integral type used to represent the distance between two iterators.)

typedef boost::container::allocator_traits< Alloc >::size_type size_type;

(An unsigned integral type that can represent any non-negative value of the container's distance type.)

typedef std::pair< pointer, size_type > array_range;

(A typedef for the std::pair where its first element is a pointer to a beginning of an array and its second element represents a size of the array.)

typedef std::pair< const_pointer, size_type > const_array_range;

(A typedef for the std::pair where its first element is a pointer to a beginning of a const array and its second element represents a size of the const array.)

typedef size_type capacity_type;

(Same as size_type - defined for consistency with the __cbso class.

typedef value_type && rvalue_type;

A type representing rvalue from param type. On compilers without rvalue references support this type is the Boost.Moves type used for emulation.

explicit circular_buffer(const allocator_type & alloc = allocator_type()) noexcept;

Complexity. Constant.

	Warning
	Since Boost version 1.36 the behaviour of this constructor has changed. Now the constructor does not allocate any memory and both capacity and size are set to zero. Also note when inserting an element into a circular_buffer with zero capacity (e.g. by push_back(const_reference) or insert(iterator, value_type)) nothing will be inserted and the size (as well as capacity) remains zero.

	Note
	You can explicitly set the capacity by calling the set_capacity(capacity_type) method or you can use the other constructor with the capacity specified.

See Also:

circular_buffer(capacity_type, const allocator_type& alloc), set_capacity(capacity_type)

explicit circular_buffer(capacity_type buffer_capacity, 
                         const allocator_type & alloc = allocator_type());

Complexity. Constant.

circular_buffer(size_type n, param_value_type item, 
                const allocator_type & alloc = allocator_type());

Complexity. Linear (in the n).

circular_buffer(capacity_type buffer_capacity, size_type n, 
                param_value_type item, 
                const allocator_type & alloc = allocator_type());

Complexity. Linear (in the n).

circular_buffer(const circular_buffer< T, Alloc > & cb);

Creates a copy of the specified circular_buffer.

Complexity. Linear (in the size of cb).

circular_buffer(circular_buffer< T, Alloc > && cb) noexcept;

Move constructs a circular_buffer from cb, leaving cb empty.

Constant. 

template<typename InputIterator> 
  circular_buffer(InputIterator first, InputIterator last, 
                  const allocator_type & alloc = allocator_type());

Complexity. Linear (in the std::distance(first, last)).

template<typename InputIterator> 
  circular_buffer(capacity_type buffer_capacity, InputIterator first, 
                  InputIterator last, 
                  const allocator_type & alloc = allocator_type());

Complexity. Linear (in std::distance(first, last); in min[capacity, std::distance(first, last)] if the InputIterator is a RandomAccessIterator).

Сохранность восприятия. Стенок.

Удостоверение генератора. Указывает все итераторы, указывающие на этот circular_buffer (за исключением итераторов, равных end()).

Сложность. Линеар (в размере cb).

См. также:

assign(size_type, const_reference), assign(capacity_type, size_type, const_reference), assign(InputIterator, InputIterator), assign(capacity_type, InputIterator, InputIterator)

Exception Safety. Strong.

Iterator Invalidation. Invalidates all iterators pointing to this circular_buffer (except iterators equal to end()).

Complexity. Linear (in the size of cb).

See Also:

assign(size_type, const_reference), assign(capacity_type, size_type, const_reference), assign(InputIterator, InputIterator), assign(capacity_type, InputIterator, InputIterator)

Сложность. Состоян.

Complexity. Constant.

~circular_buffer();

Destroys the circular_buffer.

Iterator Invalidation. Invalidates all iterators pointing to the circular_buffer (including iterators equal to end()).

Complexity. Constant (in the size of the circular_buffer) for scalar types; linear for other types.

See Also:

clear()

allocator_type get_allocator() const noexcept;

Exception Safety. No-throw.

Iterator Invalidation. Does not invalidate any iterators.

Complexity. Constant (in the size of the circular_buffer).

See Also:

get_allocator() for obtaining an allocator reference.

allocator_type & get_allocator() noexcept;

Exception Safety. No-throw.

Iterator Invalidation. Does not invalidate any iterators.

Complexity. Constant (in the size of the circular_buffer).

	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.

See Also:

get_allocator() const

iterator begin() noexcept;

Exception Safety. No-throw.

Iterator Invalidation. Does not invalidate any iterators.

Complexity. Constant (in the size of the circular_buffer).

See Also:

end(), rbegin(), rend()

iterator end() noexcept;

Exception Safety. No-throw.

Iterator Invalidation. Does not invalidate any iterators.

Complexity. Constant (in the size of the circular_buffer).

See Also:

begin(), rbegin(), rend()

const_iterator begin() const noexcept;

Exception Safety. No-throw.

Iterator Invalidation. Does not invalidate any iterators.

Complexity. Constant (in the size of the circular_buffer).

See Also:

end() const, rbegin() const, rend() const

const_iterator end() const noexcept;

Exception Safety. No-throw.

Iterator Invalidation. Does not invalidate any iterators.

Complexity. Constant (in the size of the circular_buffer).

See Also:

begin() const, rbegin() const, rend() const

reverse_iterator rbegin() noexcept;

Exception Safety. No-throw.

Iterator Invalidation. Does not invalidate any iterators.

Complexity. Constant (in the size of the circular_buffer).

See Also:

rend(), begin(), end()

reverse_iterator rend() noexcept;

Exception Safety. No-throw.

Iterator Invalidation. Does not invalidate any iterators.

Complexity. Constant (in the size of the circular_buffer).

See Also:

rbegin(), begin(), end()

const_reverse_iterator rbegin() const noexcept;

Exception Safety. No-throw.

Iterator Invalidation. Does not invalidate any iterators.

Complexity. Constant (in the size of the circular_buffer).

See Also:

rend() const, begin() const, end() const

const_reverse_iterator rend() const noexcept;

Exception Safety. No-throw.

Iterator Invalidation. Does not invalidate any iterators.

Complexity. Constant (in the size of the circular_buffer).

See Also:

rbegin() const, begin() const, end() const

reference operator[](size_type index);

Exception Safety. No-throw.

Iterator Invalidation. Does not invalidate any iterators.

Complexity. Constant (in the size of the circular_buffer).

See Also:

at()

const_reference operator[](size_type index) const;

Exception Safety. No-throw.

Iterator Invalidation. Does not invalidate any iterators.

Complexity. Constant (in the size of the circular_buffer).

See Also:

at() const

Сохранность восприятия. Стенок.

Удостоверение.  Не аннулирует ни один итератор.

Сложность. Состояние (в размере circular_buffer).

См. также:

operator[]

Exception Safety. Strong.

Iterator Invalidation. Does not invalidate any iterators.

Complexity. Constant (in the size of the circular_buffer).

See Also:

operator[]

const_reference at(size_type index) const;

Exception Safety. Strong.

Iterator Invalidation. Does not invalidate any iterators.

Complexity. Constant (in the size of the circular_buffer).

See Also:

operator[] const

reference front();

Exception Safety. No-throw.

Iterator Invalidation. Does not invalidate any iterators.

Complexity. Constant (in the size of the circular_buffer).

See Also:

back()

Безопасность принятия. Нет-трой.

Удостоверение.  Не аннулирует ни один итератор.

Сложность. Состояние (в размере circular_buffer).

См. также:

front()

Exception Safety. No-throw.

Iterator Invalidation. Does not invalidate any iterators.

Complexity. Constant (in the size of the circular_buffer).

See Also:

front()

const_reference front() const;

Exception Safety. No-throw.

Iterator Invalidation. Does not invalidate any iterators.

Complexity. Constant (in the size of the circular_buffer).

See Also:

back() const

const_reference back() const;

Exception Safety. No-throw.

Iterator Invalidation. Does not invalidate any iterators.

Complexity. Constant (in the size of the circular_buffer).

See Also:

front() const

array_range array_one();

This method in combination with array_two() can be useful when passing the stored data into a legacy C API as an array. Suppose there is a circular_buffer of capacity 10, containing 7 characters 'a', 'b', ..., 'g' where buff[0] == 'a', buff[1] == 'b', ... and buff[6] == 'g':

circular_buffer<char> buff(10);

The internal representation is often not linear and the state of the internal buffer may look like this:

|e|f|g| | | |a|b|c|d|
end ___^
begin _______^

where |a|b|c|d| represents the "array one", |e|f|g| represents the "array two" and | | | | is a free space.
Now consider a typical C style function for writing data into a file:

int write(int file_desc, char* buff, int num_bytes);

There are two ways how to write the content of the circular_buffer into a file. Either relying on array_one() and array_two() methods and calling the write function twice:

array_range ar = buff.array_one();
write(file_desc, ar.first, ar.second);
ar = buff.array_two();
write(file_desc, ar.first, ar.second);

Or relying on the linearize() method:

write(file_desc, buff.linearize(), buff.size());

Since the complexity of array_one() and array_two() methods is constant the first option is suitable when calling the write method is "cheap". On the other hand the second option is more suitable when calling the write method is more "expensive" than calling the linearize() method whose complexity is linear.

Exception Safety. No-throw.

Iterator Invalidation. Does not invalidate any iterators.

Complexity. Constant (in the size of the circular_buffer).

	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).

	Note
	In the case the internal buffer is linear e.g. |a|b|c|d|e|f|g| | | | the "array one" is represented by |a|b|c|d|e|f|g| and the "array two" does not exist (the array_two() method returns an array with the size 0).

See Also:

array_two(), linearize()

array_range array_two();

This method in combination with array_one() can be useful when passing the stored data into a legacy C API as an array.

Exception Safety. No-throw.

Iterator Invalidation. Does not invalidate any iterators.

Complexity. Constant (in the size of the circular_buffer).

See Also:

array_one()

const_array_range array_one() const;

This method in combination with array_two() const can be useful when passing the stored data into a legacy C API as an array.

Exception Safety. No-throw.

Iterator Invalidation. Does not invalidate any iterators.

Complexity. Constant (in the size of the circular_buffer).

See Also:

array_two() const; array_one() for more details how to pass data into a legacy C API.

const_array_range array_two() const;

This method in combination with array_one() const can be useful when passing the stored data into a legacy C API as an array.

Exception Safety. No-throw.

Iterator Invalidation. Does not invalidate any iterators.

Complexity. Constant (in the size of the circular_buffer).

See Also:

array_one() const

pointer linearize();

This method can be useful when passing the stored data into a legacy C API as an array.

Exception Safety. Basic; no-throw if the operations in the Throws section do not throw anything.

Iterator Invalidation. Invalidates all iterators pointing to the circular_buffer (except iterators equal to end()); does not invalidate any iterators if the postcondition (the Effect) is already met prior calling this method.

Complexity. Linear (in the size of the circular_buffer); constant if the postcondition (the Effect) is already met.

	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.

See Also:

array_one() and array_two() for the other option how to pass data into a legacy C API; is_linearized(), rotate(const_iterator)

bool is_linearized() const noexcept;

Exception Safety. No-throw.

Iterator Invalidation. Does not invalidate any iterators.

Complexity. Constant (in the size of the circular_buffer).

See Also:

linearize(), array_one(), array_two()

void rotate(const_iterator new_begin);

A more effective implementation of std::rotate.

Exception Safety. Basic; no-throw if the circular_buffer is full or new_begin points to begin() or if the operations in the Throws section do not throw anything.

Iterator Invalidation. If m < n invalidates iterators pointing to the last m elements (including new_begin, but not iterators equal to end()) else invalidates iterators pointing to the first n elements; does not invalidate any iterators if the circular_buffer is full.

Complexity. Linear (in (std::min)(m, n)); constant if the circular_buffer is full.

See Also:

std::rotate

size_type size() const noexcept;

Exception Safety. No-throw.

Iterator Invalidation. Does not invalidate any iterators.

Complexity. Constant (in the size of the circular_buffer).

See Also:

capacity(), max_size(), reserve(), resize(size_type, const_reference)

size_type max_size() const noexcept;

Exception Safety. No-throw.

Iterator Invalidation. Does not invalidate any iterators.

Complexity. Constant (in the size of the circular_buffer).

See Also:

size(), capacity(), reserve()

Безопасность принятия. Нет-трой.

Удостоверение.  Не аннулирует ни один итератор.

Сложность. Состояние (в размере circular_buffer).

См. также:

full()

Exception Safety. No-throw.

Iterator Invalidation. Does not invalidate any iterators.

Complexity. Constant (in the size of the circular_buffer).

See Also:

full()

bool full() const noexcept;

Exception Safety. No-throw.

Iterator Invalidation. Does not invalidate any iterators.

Complexity. Constant (in the size of the circular_buffer).

See Also:

empty()

Безопасность принятия. Нет-трой.

Удостоверение.  Не аннулирует ни один итератор.

Сложность. Состояние (в размере circular_buffer).

См. также:

capacity(), size(), max_size()

Exception Safety. No-throw.

Iterator Invalidation. Does not invalidate any iterators.

Complexity. Constant (in the size of the circular_buffer).

See Also:

capacity(), size(), max_size()

capacity_type capacity() const noexcept;

Exception Safety. No-throw.

Iterator Invalidation. Does not invalidate any iterators.

Complexity. Constant (in the size of the circular_buffer).

See Also:

reserve(), size(), max_size(), set_capacity(capacity_type)

void set_capacity(capacity_type new_capacity);

Exception Safety. Strong.

Iterator Invalidation. Invalidates all iterators pointing to the circular_buffer (except iterators equal to end()) if the new capacity is different from the original.

Complexity. Linear (in min[size(), new_capacity]).

See Also:

rset_capacity(capacity_type), resize(size_type, const_reference)

void resize(size_type new_size, param_value_type item = value_type());

Exception Safety. Basic.

Iterator Invalidation. Invalidates all iterators pointing to the circular_buffer (except iterators equal to end()) if the new size is greater than the current capacity. Invalidates iterators pointing to the removed elements if the new size is lower that the original size. Otherwise it does not invalidate any iterator.

Complexity. Linear (in the new size of the circular_buffer).

See Also:

rresize(size_type, const_reference), set_capacity(capacity_type)

void rset_capacity(capacity_type new_capacity);

Exception Safety. Strong.

Iterator Invalidation. Invalidates all iterators pointing to the circular_buffer (except iterators equal to end()) if the new capacity is different from the original.

Complexity. Linear (in min[size(), new_capacity]).

See Also:

set_capacity(capacity_type), rresize(size_type, const_reference)

void rresize(size_type new_size, param_value_type item = value_type());

Exception Safety. Basic.

Iterator Invalidation. Invalidates all iterators pointing to the circular_buffer (except iterators equal to end()) if the new size is greater than the current capacity. Invalidates iterators pointing to the removed elements if the new size is lower that the original size. Otherwise it does not invalidate any iterator.

Complexity. Linear (in the new size of the circular_buffer).

See Also:

resize(size_type, const_reference), rset_capacity(capacity_type)

void assign(size_type n, param_value_type item);

The content of the circular_buffer will be removed and replaced with n copies of the item.

Exception Safety. Basic.

Iterator Invalidation. Invalidates all iterators pointing to the circular_buffer (except iterators equal to end()).

Complexity. Linear (in the n).

See Also:

operator=, assign(capacity_type, size_type, const_reference), assign(InputIterator, InputIterator), assign(capacity_type, InputIterator, InputIterator)

void assign(capacity_type buffer_capacity, size_type n, param_value_type item);

The capacity of the circular_buffer will be set to the specified value and the content of the circular_buffer will be removed and replaced with n copies of the item.

Exception Safety. Basic.

Iterator Invalidation. Invalidates all iterators pointing to the circular_buffer (except iterators equal to end()).

Complexity. Linear (in the n).

See Also:

operator=, assign(size_type, const_reference), assign(InputIterator, InputIterator), assign(capacity_type, InputIterator, InputIterator)

Безопасность принятия. Базовый.

Удостоверение. Указывает все итераторы, указывающие на circular_buffer (за исключением итераторов, равных end()).

Complexity. Linear (в std::distance(first, last)).

См. также:

operator=, assign(size_type, const_reference), assign(capacity_type, size_type, const_reference), assign(capacity_type, InputIterator, InputIterator)

Exception Safety. Basic.

Iterator Invalidation. Invalidates all iterators pointing to the circular_buffer (except iterators equal to end()).

Complexity. Linear (in the std::distance(first, last)).

See Also:

operator=, assign(size_type, const_reference), assign(capacity_type, size_type, const_reference), assign(capacity_type, InputIterator, InputIterator)

Безопасность принятия. Базовый.

Удостоверение. Указывает все итераторы, указывающие на circular_buffer (за исключением итераторов, равных end()).

См. также:

operator=, assign(size_type, const_reference), assign(capacity_type, size_type, const_reference), assign(InputIterator, InputIterator)

Exception Safety. Basic.

Iterator Invalidation. Invalidates all iterators pointing to the circular_buffer (except iterators equal to end()).

Complexity. Linear (in std::distance(first, last); in min[capacity, std::distance(first, last)] if the InputIterator is a RandomAccessIterator).

See Also:

operator=, assign(size_type, const_reference), assign(capacity_type, size_type, const_reference), assign(InputIterator, InputIterator)

void swap(circular_buffer< T, Alloc > & cb) noexcept;

Exception Safety. No-throw.

Iterator Invalidation. Invalidates all iterators of both circular_buffers. (On the other hand the iterators still point to the same elements but within another container. If you want to rely on this feature you have to turn the Debug Support off otherwise an assertion will report an error if such invalidated iterator is used.)

Complexity. Constant (in the size of the circular_buffer).

See Also:

swap(circular_buffer<T, Alloc>&, circular_buffer<T, Alloc>&)

void push_back(param_value_type item);

Exception Safety. Basic; no-throw if the operation in the Throws section does not throw anything.

Iterator Invalidation. Does not invalidate any iterators with the exception of iterators pointing to the overwritten element.

Complexity. Constant (in the size of the circular_buffer).

See Also:

push_front(const_reference), pop_back(), pop_front()

void push_back(rvalue_type item);

Exception Safety. Basic; no-throw if the operation in the Throws section does not throw anything.

Iterator Invalidation. Does not invalidate any iterators with the exception of iterators pointing to the overwritten element.

Complexity. Constant (in the size of the circular_buffer).

See Also:

push_front(const_reference), pop_back(), pop_front()

Сохранность восприятия. Basic; no-throw если операция в Throws раздел ничего не бросает.

Удостоверение.  Не аннулирует ни один итератор, за исключением итераторов, указывающих на записанные элементы.

Сложность. Состояние (в размере circular_buffer).

См. также:

push_front(const_reference), pop_back(), pop_front()

Exception Safety. Basic; no-throw if the operation in the Throws section does not throw anything.

Iterator Invalidation. Does not invalidate any iterators with the exception of iterators pointing to the overwritten element.

Complexity. Constant (in the size of the circular_buffer).

See Also:

push_front(const_reference), pop_back(), pop_front()

Сохранность восприятия. Basic; no-throw если операция в Throws раздел ничего не бросает.

Удостоверение.  Не аннулирует ни один итератор, за исключением итераторов, указывающих на записанные элементы.

Сложность. Состояние (в размере circular_buffer).

См. также:

push_back(const_reference), pop_back(), pop_front()

Exception Safety. Basic; no-throw if the operation in the Throws section does not throw anything.

Iterator Invalidation. Does not invalidate any iterators with the exception of iterators pointing to the overwritten element.

Complexity. Constant (in the size of the circular_buffer).

See Also:

push_back(const_reference), pop_back(), pop_front()

void push_front(rvalue_type item);

Exception Safety. Basic; no-throw if the operation in the Throws section does not throw anything.

Iterator Invalidation. Does not invalidate any iterators with the exception of iterators pointing to the overwritten element.

Complexity. Constant (in the size of the circular_buffer).

See Also:

push_back(const_reference), pop_back(), pop_front()

void push_front();

Exception Safety. Basic; no-throw if the operation in the Throws section does not throw anything.

Iterator Invalidation. Does not invalidate any iterators with the exception of iterators pointing to the overwritten element.

Complexity. Constant (in the size of the circular_buffer).

See Also:

push_back(const_reference), pop_back(), pop_front()

void pop_back();

Exception Safety. No-throw.

Iterator Invalidation. Invalidates only iterators pointing to the removed element.

Complexity. Constant (in the size of the circular_buffer).

See Also:

pop_front(), push_back(const_reference), push_front(const_reference)

void pop_front();

Exception Safety. No-throw.

Iterator Invalidation. Invalidates only iterators pointing to the removed element.

Complexity. Constant (in the size of the circular_buffer).

See Also:

pop_back(), push_back(const_reference), push_front(const_reference)

Сохранность восприятия. Basic; no-throw если операция в Throws раздел ничего не бросает.

Удостоверение. Установляет итераторы, указывающие на элементы в точке вставки (включая pos) и итераторы за точкой вставки (к концу; кроме итераторов, равных end()). Он также аннулирует итераторы, указывающие на переписанные элементы.

Complexity. Linear (в std::distance(pos, end())).

См. также:

insert(iterator, size_type, value_type), insert(iterator, InputIterator, InputIterator), rinsert(iterator, value_type), rinsert(iterator, size_type, value_type), rinsert(iterator, InputIterator, InputIterator)

Exception Safety. Basic; no-throw if the operation in the Throws section does not throw anything.

Iterator Invalidation. Invalidates iterators pointing to the elements at the insertion point (including pos) and iterators behind the insertion point (towards the end; except iterators equal to end()). It also invalidates iterators pointing to the overwritten element.

Complexity. Linear (in std::distance(pos, end())).

See Also:

insert(iterator, size_type, value_type), insert(iterator, InputIterator, InputIterator), rinsert(iterator, value_type), rinsert(iterator, size_type, value_type), rinsert(iterator, InputIterator, InputIterator)

Сохранность восприятия. Basic; no-throw если операция в Throws раздел ничего не бросает.

Удостоверение. Установляет итераторы, указывающие на элементы в точке вставки (включая pos) и итераторы за точкой вставки (к концу; кроме итераторов, равных end()). Он также аннулирует итераторы, указывающие на переписанные элементы.

Complexity. Linear (в std::distance(pos, end())).

См. также:

insert(iterator, size_type, value_type), insert(iterator, InputIterator, InputIterator), rinsert(iterator, value_type), rinsert(iterator, size_type, value_type), rinsert(iterator, InputIterator, InputIterator)

Exception Safety. Basic; no-throw if the operation in the Throws section does not throw anything.

Iterator Invalidation. Invalidates iterators pointing to the elements at the insertion point (including pos) and iterators behind the insertion point (towards the end; except iterators equal to end()). It also invalidates iterators pointing to the overwritten element.

Complexity. Linear (in std::distance(pos, end())).

See Also:

insert(iterator, size_type, value_type), insert(iterator, InputIterator, InputIterator), rinsert(iterator, value_type), rinsert(iterator, size_type, value_type), rinsert(iterator, InputIterator, InputIterator)

iterator insert(iterator pos);

Exception Safety. Basic; no-throw if the operation in the Throws section does not throw anything.

Iterator Invalidation. Invalidates iterators pointing to the elements at the insertion point (including pos) and iterators behind the insertion point (towards the end; except iterators equal to end()). It also invalidates iterators pointing to the overwritten element.

Complexity. Linear (in std::distance(pos, end())).

See Also:

insert(iterator, size_type, value_type), insert(iterator, InputIterator, InputIterator), rinsert(iterator, value_type), rinsert(iterator, size_type, value_type), rinsert(iterator, InputIterator, InputIterator)

void insert(iterator pos, size_type n, param_value_type item);

Exception Safety. Basic; no-throw if the operations in the Throws section do not throw anything.

Iterator Invalidation. Invalidates iterators pointing to the elements at the insertion point (including pos) and iterators behind the insertion point (towards the end; except iterators equal to end()). It also invalidates iterators pointing to the overwritten elements.

Complexity. Linear (in min[capacity(), std::distance(pos, end()) + n]).

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 5 elements at the position p:

insert(p, (size_t)5, 0);

actually only 4 elements get inserted and elements 1 and 2 are overwritten. This is due to the fact the insert operation preserves the capacity. After insertion the internal buffer looks like this:

|0|0|0|0|3|4|

For comparison if the capacity would not be preserved the internal buffer would then result in |1|2|0|0|0|0|0|3|4|.

See Also:

insert(iterator, value_type), insert(iterator, InputIterator, InputIterator), rinsert(iterator, value_type), rinsert(iterator, size_type, value_type), rinsert(iterator, InputIterator, InputIterator)

template<typename InputIterator> 
  void insert(iterator pos, InputIterator first, InputIterator last);

Exception Safety. Basic; no-throw if the operations in the Throws section do not throw anything.

Iterator Invalidation. Invalidates iterators pointing to the elements at the insertion point (including pos) and iterators behind the insertion point (towards the end; except iterators equal to end()). It also invalidates iterators pointing to the overwritten elements.

Complexity. Linear (in [std::distance(pos, end()) + std::distance(first, last)]; in min[capacity(), std::distance(pos, end()) + std::distance(first, last)] if the InputIterator is a RandomAccessIterator).

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 at the position p:

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

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

|6|7|8|9|3|4|

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|.

See Also:

insert(iterator, value_type), insert(iterator, size_type, value_type), rinsert(iterator, value_type), rinsert(iterator, size_type, value_type), rinsert(iterator, InputIterator, InputIterator)

iterator rinsert(iterator pos, param_value_type item);

Exception Safety. Basic; no-throw if the operations in the Throws section do not throw anything.

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 element.

Complexity. Linear (in std::distance(begin(), pos)).

See Also:

rinsert(iterator, size_type, value_type), rinsert(iterator, InputIterator, InputIterator), insert(iterator, value_type), insert(iterator, size_type, value_type), insert(iterator, InputIterator, InputIterator)

iterator rinsert(iterator pos, rvalue_type item);

Exception Safety. Basic; no-throw if the operations in the Throws section do not throw anything.

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 element.

Complexity. Linear (in std::distance(begin(), pos)).

See Also:

rinsert(iterator, size_type, value_type), rinsert(iterator, InputIterator, InputIterator), insert(iterator, value_type), insert(iterator, size_type, value_type), insert(iterator, InputIterator, InputIterator)

iterator rinsert(iterator pos);

Exception Safety. Basic; no-throw if the operations in the Throws section do not throw anything.

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 element.

Complexity. Linear (in std::distance(begin(), pos)).

See Also:

rinsert(iterator, size_type, value_type), rinsert(iterator, InputIterator, InputIterator), insert(iterator, value_type), insert(iterator, size_type, value_type), insert(iterator, InputIterator, InputIterator)

void rinsert(iterator pos, size_type n, param_value_type item);

Exception Safety. Basic; no-throw if the operations in the Throws section do not throw anything.

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.

Complexity. Linear (in min[capacity(), std::distance(begin(), pos) + n]).

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 5 elements before the position p:

rinsert(p, (size_t)5, 0);

actually only 4 elements get inserted and elements 3 and 4 are overwritten. This is due to the fact the rinsert operation preserves the capacity. After insertion the internal buffer looks like this:

|1|2|0|0|0|0|

For comparison if the capacity would not be preserved the internal buffer would then result in |1|2|0|0|0|0|0|3|4|.

See Also:

rinsert(iterator, value_type), rinsert(iterator, InputIterator, InputIterator), insert(iterator, value_type), insert(iterator, size_type, value_type), insert(iterator, InputIterator, InputIterator)