Class template circular_buffer

boost::circular_buffer — Circular buffer - a STL compliant container.

Synopsis

// In header: <boost/circular_buffer/base.hpp>

template<typename T, typename Alloc> 
class circular_buffer : private empty_value< Alloc > {
public:
  // types
  typedef circular_buffer< T, Alloc >                                                               this_type;               // The type of this circular_buffer. 
  typedef Alloc::value_type                                                                         value_type;              // The type of elements stored in the circular_buffer. 
  typedef allocator_pointer< Alloc >::type                                                          pointer;                 // A pointer to an element. 
  typedef allocator_const_pointer< Alloc >::type                                                    const_pointer;           // A const pointer to the element. 
  typedef value_type &                                                                              reference;               // A reference to an element. 
  typedef const value_type &                                                                        const_reference;         // A const reference to an element. 
  typedef allocator_difference_type< Alloc >::type                                                  difference_type;       
  typedef allocator_size_type< Alloc >::type                                                        size_type;             
  typedef Alloc                                                                                     allocator_type;          // The type of an allocator used in the circular_buffer. 
  typedef cb_details::iterator< circular_buffer< T, Alloc >, cb_details::const_traits< Alloc > >    const_iterator;          // A const (random access) iterator used to iterate through the circular_buffer. 
  typedef cb_details::iterator< circular_buffer< T, Alloc >, cb_details::nonconst_traits< Alloc > > iterator;                // A (random access) iterator used to iterate through the circular_buffer. 
  typedef std::reverse_iterator< const_iterator >                                                   const_reverse_iterator;  // A const iterator used to iterate backwards through a circular_buffer. 
  typedef std::reverse_iterator< iterator >                                                         reverse_iterator;        // An iterator used to iterate backwards through a circular_buffer. 
  typedef std::pair< pointer, size_type >                                                           array_range;           
  typedef std::pair< const_pointer, size_type >                                                     const_array_range;     
  typedef size_type                                                                                 capacity_type;         
  typedef const value_type &                                                                        param_value_type;        // A type representing the "best" way to pass the value_type to a method. 
  typedef value_type &&                                                                             rvalue_type;           

  // public member functions
  allocator_type get_allocator() const noexcept;
  allocator_type & get_allocator() noexcept;
  iterator begin() noexcept;
  iterator end() noexcept;
  const_iterator begin() const noexcept;
  const_iterator cbegin() const noexcept;
  const_iterator end() const noexcept;
  const_iterator cend() const noexcept;
  reverse_iterator rbegin() noexcept;
  reverse_iterator rend() noexcept;
  const_reverse_iterator rbegin() const noexcept;
  const_reverse_iterator rend() const noexcept;
  reference operator[](size_type);
  const_reference operator[](size_type) const;
  reference at(size_type);
  const_reference at(size_type) const;
  reference front();
  reference back();
  const_reference front() const;
  const_reference back() const;
  array_range array_one();
  array_range array_two();
  const_array_range array_one() const;
  const_array_range array_two() const;
  pointer linearize();
  bool is_linearized() const noexcept;
  void rotate(const_iterator);
  size_type size() const noexcept;
  size_type max_size() const noexcept;
  bool empty() const noexcept;
  bool full() const noexcept;
  size_type reserve() const noexcept;
  capacity_type capacity() const noexcept;
  void set_capacity(capacity_type);
  void resize(size_type, param_value_type = value_type());
  void rset_capacity(capacity_type);
  void rresize(size_type, param_value_type = value_type());
  explicit circular_buffer(const allocator_type & = allocator_type()) noexcept;
  explicit circular_buffer(capacity_type, 
                           const allocator_type & = allocator_type());
  circular_buffer(size_type, param_value_type, 
                  const allocator_type & = allocator_type());
  circular_buffer(capacity_type, size_type, param_value_type, 
                  const allocator_type & = allocator_type());
  circular_buffer(const circular_buffer< T, Alloc > &);
  circular_buffer(circular_buffer< T, Alloc > &&) noexcept;
  template<typename InputIterator> 
    circular_buffer(InputIterator, InputIterator, 
                    const allocator_type & = allocator_type());
  template<typename InputIterator> 
    circular_buffer(capacity_type, InputIterator, InputIterator, 
                    const allocator_type & = allocator_type());
  ~circular_buffer() noexcept;
  circular_buffer< T, Alloc > & operator=(const circular_buffer< T, Alloc > &);
  circular_buffer< T, Alloc > & 
  operator=(circular_buffer< T, Alloc > &&) noexcept;
  void assign(size_type, param_value_type);
  void assign(capacity_type, size_type, param_value_type);
  template<typename InputIterator> void assign(InputIterator, InputIterator);
  template<typename InputIterator> 
    void assign(capacity_type, InputIterator, InputIterator);
  void swap(circular_buffer< T, Alloc > &) noexcept;
  void push_back(param_value_type);
  void push_back(rvalue_type);
  void push_back();
  void push_front(param_value_type);
  void push_front(rvalue_type);
  void push_front();
  void pop_back();
  void pop_front();
  iterator insert(iterator, param_value_type);
  iterator insert(iterator, rvalue_type);
  iterator insert(iterator);
  void insert(iterator, size_type, param_value_type);
  template<typename InputIterator> 
    void insert(iterator, InputIterator, InputIterator);
  iterator rinsert(iterator, param_value_type);
  iterator rinsert(iterator, rvalue_type);
  iterator rinsert(iterator);
  void rinsert(iterator, size_type, param_value_type);
  template<typename InputIterator> 
    void rinsert(iterator, InputIterator, InputIterator);
  iterator erase(iterator);
  iterator erase(iterator, iterator);
  iterator rerase(iterator);
  iterator rerase(iterator, iterator);
  void erase_begin(size_type);
  void erase_end(size_type);
  void clear() noexcept;
};

Description

Type Requirements T. The T has to be SGIAssignable (SGI STL defined combination of Assignable and CopyConstructible). Moreover T has to be DefaultConstructible if supplied as a default parameter when invoking some of the circular_buffer's methods e.g. insert(iterator pos, const value_type& item = value_type()). And EqualityComparable and/or LessThanComparable if the circular_buffer will be compared with another container.

Type Requirements Alloc. The Alloc has to meet the allocator requirements imposed by STL.

Default Alloc. std::allocator<T>

For detailed documentation of the circular_buffer visit: http://www.boost.org/libs/circular_buffer/doc/circular_buffer.html

Template Parameters

```
typename T
```
The type of the elements stored in the circular_buffer.
```
typename Alloc
```
The allocator type used for all internal memory management.

`circular_buffer` public types

typedef allocator_difference_type< Alloc >::type difference_type;

(A signed integral type used to represent the distance between two iterators.)
typedef allocator_size_type< Alloc >::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.

`circular_buffer` public member functions

```
allocator_type get_allocator() const noexcept;
```
Get the allocator.

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.

Returns:

The allocator.

Throws:
Nothing.
```
allocator_type & get_allocator() noexcept;
```
Get the allocator reference.

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

Returns:

A reference to the allocator.

Throws:
Nothing.

iterator begin() noexcept;

Get the iterator pointing to the beginning of the circular_buffer.

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

Returns:	A random access iterator pointing to the first element of the `circular_buffer`. If the `circular_buffer` is empty it returns an iterator equal to the one returned by `end()`.
Throws:	Nothing.

iterator end() noexcept;

Get the iterator pointing to the end of the circular_buffer.

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

Returns:	A random access iterator pointing to the element "one behind" the last element of the `circular_buffer`. If the `circular_buffer` is empty it returns an iterator equal to the one returned by `begin()`.
Throws:	Nothing.

const_iterator begin() const noexcept;

Get the const iterator pointing to the beginning of the circular_buffer.

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

Returns:	A const random access iterator pointing to the first element of the `circular_buffer`. If the `circular_buffer` is empty it returns an iterator equal to the one returned by `end() const`.
Throws:	Nothing.

```
const_iterator cbegin() const noexcept;
```

const_iterator end() const noexcept;

Get the const iterator pointing to the end of the circular_buffer.

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

Returns:	A const random access iterator pointing to the element "one behind" the last element of the `circular_buffer`. If the `circular_buffer` is empty it returns an iterator equal to the one returned by `begin() const` const.
Throws:	Nothing.

```
const_iterator cend() const noexcept;
```

reverse_iterator rbegin() noexcept;

Get the iterator pointing to the beginning of the "reversed" circular_buffer.

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

Returns:	A reverse random access iterator pointing to the last element of the `circular_buffer`. If the `circular_buffer` is empty it returns an iterator equal to the one returned by `rend()`.
Throws:	Nothing.

reverse_iterator rend() noexcept;

Get the iterator pointing to the end of the "reversed" circular_buffer.

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

Returns:	A reverse random access iterator pointing to the element "one before" the first element of the `circular_buffer`. If the `circular_buffer` is empty it returns an iterator equal to the one returned by `rbegin()`.
Throws:	Nothing.

const_reverse_iterator rbegin() const noexcept;

Get the const iterator pointing to the beginning of the "reversed" circular_buffer.

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

Returns:	A const reverse random access iterator pointing to the last element of the `circular_buffer`. If the `circular_buffer` is empty it returns an iterator equal to the one returned by `rend() const`.
Throws:	Nothing.

const_reverse_iterator rend() const noexcept;

Get the const iterator pointing to the end of the "reversed" circular_buffer.

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

Returns:	A const reverse random access iterator pointing to the element "one before" the first element of the `circular_buffer`. If the `circular_buffer` is empty it returns an iterator equal to the one returned by `rbegin() const`.
Throws:	Nothing.

```
reference operator[](size_type index);
```
Get the element at the index position.

Exception Safety. No-throw.

Iterator Invalidation. Does not invalidate any iterators.

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

See Also: at()

Parameters:

index

The position of the element.

Requires:

0 <= index && index < size()

Returns:

A reference to the element at the index position.

Throws:
Nothing.
```
const_reference operator[](size_type index) const;
```
Get the element at the index position.

Exception Safety. No-throw.

Iterator Invalidation. Does not invalidate any iterators.

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

See Also: at() const

Parameters:

index

The position of the element.

Requires:

0 <= index && index < size()

Returns:

A const reference to the element at the index position.

Throws:
Nothing.

reference at(size_type index);

Get the element at the index position.

Exception Safety. Strong.

Iterator Invalidation. Does not invalidate any iterators.

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

See Also: operator[]

Parameters:

index

The position of the element.

Returns:

A reference to the element at the index position.

Throws:

<code>std::out_of_range</code> when the index is invalid (when index >= size()).

const_reference at(size_type index) const;

Get the element at the index position.

Exception Safety. Strong.

Iterator Invalidation. Does not invalidate any iterators.

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

See Also: operator[] const

Parameters:

index

The position of the element.

Returns:

A const reference to the element at the index position.

Throws:

<code>std::out_of_range</code> when the index is invalid (when index >= size()).

```
reference front();
```
Get the first element.

Exception Safety. No-throw.

Iterator Invalidation. Does not invalidate any iterators.

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

See Also: back()

Requires:

!empty()

Returns:

A reference to the first element of the circular_buffer.

Throws:
Nothing.
```
reference back();
```
Get the last element.

Exception Safety. No-throw.

Iterator Invalidation. Does not invalidate any iterators.

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

See Also: front()

Requires:

!empty()

Returns:

A reference to the last element of the circular_buffer.

Throws:
Nothing.
```
const_reference front() const;
```
Get the first element.

Exception Safety. No-throw.

Iterator Invalidation. Does not invalidate any iterators.

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

See Also: back() const

Requires:

!empty()

Returns:

A const reference to the first element of the circular_buffer.

Throws:
Nothing.
```
const_reference back() const;
```
Get the last element.

Exception Safety. No-throw.

Iterator Invalidation. Does not invalidate any iterators.

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

See Also: front() const

Requires:

!empty()

Returns:

A const reference to the last element of the circular_buffer.

Throws:
Nothing.

array_range array_one();

Get the first continuous array of the internal buffer.

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

Returns:	The array range of the first continuous array of the internal buffer. In the case the `circular_buffer` is empty the size of the returned array is `0`.
Throws:	Nothing.

array_range array_two();

Get the second continuous array of the internal buffer.

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

Returns:	The array range of the second continuous array of the internal buffer. In the case the internal buffer is linear or the `circular_buffer` is empty the size of the returned array is `0`.
Throws:	Nothing.

```
const_array_range array_one() const;
```
Get the first continuous array of the internal buffer.
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.

Returns:

The array range of the first continuous array of the internal buffer. In the case the circular_buffer is empty the size of the returned array is 0.

Throws:
Nothing.

const_array_range array_two() const;

Get the second continuous array of the internal buffer.

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

Returns:	The array range of the second continuous array of the internal buffer. In the case the internal buffer is linear or the `circular_buffer` is empty the size of the returned array is `0`.
Throws:	Nothing.

pointer linearize();

Linearize the internal buffer into a continuous array.

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)

Postconditions:	`&(this)[0] < &(this)[1] < ... < &(*this)[size() - 1]`
Returns:	A pointer to the beginning of the array or `0` if empty.
Throws:	<a href="circular_buffer/implementation.html#circular_buffer.implementation.exceptions_of_move_if_noexcept_t">Exceptions of move_if_noexcept(T&).

bool is_linearized() const noexcept;

Is the circular_buffer linearized?

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

Returns:	`true` if the internal buffer is linearized into a continuous array (i.e. the `circular_buffer` meets a condition `&(this)[0] < &(this)[1] < ... < &(*this)[size() - 1]`); `false` otherwise.
Throws:	Nothing.

void rotate(const_iterator new_begin);

Rotate elements in the circular_buffer.

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

Parameters:

new_begin

The new beginning.

Requires:

new_begin is a valid iterator pointing to the circular_buffer except its end.

Postconditions:

Before calling the method suppose:

m == std::distance(new_begin, end())
n == std::distance(begin(), new_begin)
val_0 == *new_begin, val_1 == *(new_begin + 1), ... val_m == *(new_begin + m)
val_r1 == *(new_begin - 1), val_r2 == *(new_begin - 2), ... val_rn == *(new_begin - n)

then after call to the method:

val_0 == (*this)[0] && val_1 == (*this)[1] && ... && val_m == (*this)[m - 1] && val_r1 == (*this)[m + n - 1] && val_r2 == (*this)[m + n - 2] && ... && val_rn == (*this)[m]

Throws:

See Exceptions of move_if_noexcept(T&).

```
size_type size() const noexcept;
```
Get the number of elements currently stored in the circular_buffer.

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)

Returns:

The number of elements stored in the circular_buffer.

Throws:
Nothing.
```
size_type max_size() const noexcept;
```
Get the largest possible size or capacity of the circular_buffer. (It depends on allocator's max_size()).

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

Returns:

The maximum size/capacity the circular_buffer can be set to.

Throws:
Nothing.
```
bool empty() const noexcept;
```
Is the circular_buffer empty?

Exception Safety. No-throw.

Iterator Invalidation. Does not invalidate any iterators.

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

See Also: full()

Returns:

true if there are no elements stored in the circular_buffer; false otherwise.

Throws:
Nothing.
```
bool full() const noexcept;
```
Is the 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: empty()

Returns:

true if the number of elements stored in the circular_buffer equals the capacity of the circular_buffer; false otherwise.

Throws:
Nothing.
```
size_type reserve() const noexcept;
```
Get the maximum number of elements which can be inserted into the circular_buffer without overwriting any of already stored elements.

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

Returns:

capacity() - size()

Throws:
Nothing.
```
capacity_type capacity() const noexcept;
```
Get the capacity of the circular_buffer.

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)

Returns:

The maximum number of elements which can be stored in the circular_buffer.

Throws:
Nothing.

void set_capacity(capacity_type new_capacity);

Change the capacity of the circular_buffer.

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

Parameters:

new_capacity

The new capacity.

Requires:

If T is a move only type, then compiler shall support noexcept modifiers and move constructor of T must be marked with it (must not throw exceptions).

Postconditions:

capacity() == new_capacity && size() <= new_capacity

If the current number of elements stored in the circular_buffer is greater than the desired new capacity then number of [size() - new_capacity] last elements will be removed and the new size will be equal to new_capacity.

Throws:

An allocation error if memory is exhausted, (std::bad_alloc if the standard allocator is used). Whatever T::T(const T&) throws or nothing if T::T(T&&) is noexcept.

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

Change the size of the circular_buffer.

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

Parameters:

`new_size`	The new size.
`item`	The element the `circular_buffer` will be filled with in order to gain the requested size. (See the Effect.)

Postconditions:

size() == new_size && capacity() >= new_size

If the new size is greater than the current size, copies of item will be inserted at the back of the of the circular_buffer in order to achieve the desired size. In the case the resulting size exceeds the current capacity the capacity will be set to new_size.
If the current number of elements stored in the circular_buffer is greater than the desired new size then number of [size() - new_size] last elements will be removed. (The capacity will remain unchanged.)

Throws:

An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is used). Whatever T::T(const T&) throws or nothing if T::T(T&&) is noexcept.

void rset_capacity(capacity_type new_capacity);

Change the capacity of the circular_buffer.

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

Parameters:

new_capacity

The new capacity.

Requires:

If T is a move only type, then compiler shall support noexcept modifiers and move constructor of T must be marked with it (must not throw exceptions).

Postconditions:

capacity() == new_capacity && size() <= new_capacity

If the current number of elements stored in the circular_buffer is greater than the desired new capacity then number of [size() - new_capacity] first elements will be removed and the new size will be equal to new_capacity.

Throws:

An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is used). Whatever T::T(const T&) throws or nothing if T::T(T&&) is noexcept.

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

Change the size of the circular_buffer.

Exception Safety. Basic.

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

Parameters:

`new_size`	The new size.
`item`	The element the `circular_buffer` will be filled with in order to gain the requested size. (See the Effect.)

Postconditions:

size() == new_size && capacity() >= new_size

If the new size is greater than the current size, copies of item will be inserted at the front of the of the circular_buffer in order to achieve the desired size. In the case the resulting size exceeds the current capacity the capacity will be set to new_size.
If the current number of elements stored in the circular_buffer is greater than the desired new size then number of [size() - new_size] first elements will be removed. (The capacity will remain unchanged.)

Throws:

An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is used). Whatever T::T(const T&) throws or nothing if T::T(T&&) is noexcept.

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

Create an empty circular_buffer with zero capacity.

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.

Parameters:

alloc

The allocator.

Postconditions:

capacity() == 0 && size() == 0

Throws:

Nothing.

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

Create an empty circular_buffer with the specified capacity.

Complexity. Constant.

Parameters:

`buffer_capacity`	The maximum number of elements which can be stored in the `circular_buffer`.
`alloc`	The allocator.

Postconditions:

capacity() == buffer_capacity && size() == 0

Throws:

An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is used).

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

Create a full circular_buffer with the specified capacity and filled with n copies of item.

Complexity. Linear (in the n).

Parameters:

`n`	The number of elements the created `circular_buffer` will be filled with.
`item`	The element the created `circular_buffer` will be filled with.
`alloc`	The allocator.

Postconditions:

capacity() == n && full() && (*this)[0] == item && (*this)[1] == item && ... && (*this)[n - 1] == item

Throws:

An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is used). Whatever T::T(const T&) throws.

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

Create a circular_buffer with the specified capacity and filled with n copies of item.

Complexity. Linear (in the n).

Parameters:

`buffer_capacity`	The capacity of the created `circular_buffer`.
`n`	The number of elements the created `circular_buffer` will be filled with.
`item`	The element the created `circular_buffer` will be filled with.
`alloc`	The allocator.

Requires:

buffer_capacity >= n

Postconditions:

capacity() == buffer_capacity && size() == n && (*this)[0] == item && (*this)[1] == item && ... && (*this)[n - 1] == item

Throws:

An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is used). Whatever T::T(const T&) throws.

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

The copy constructor.

Creates a copy of the specified circular_buffer.

Complexity. Linear (in the size of cb).

Parameters:

`cb`	The `circular_buffer` to be copied.

Postconditions:

*this == cb

Throws:

An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is used). Whatever T::T(const T&) throws.

```
circular_buffer(circular_buffer< T, Alloc > && cb) noexcept;
```
The move constructor.
Move constructs a circular_buffer from cb, leaving cb empty.

Constant.

Parameters:

cb

circular_buffer to 'steal' value from.

Requires:

C++ compiler with rvalue references support.

Postconditions:

cb.empty()

Throws:
Nothing.

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

Create a full circular_buffer filled with a copy of the range.

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

Parameters:

`first`	The beginning of the range to be copied.
`last`	The end of the range to be copied.
`alloc`	The allocator.

Requires:

Valid range [first, last).
first and last have to meet the requirements of InputIterator.

Postconditions:

capacity() == std::distance(first, last) && full() && (*this)[0]== *first && (*this)[1] == *(first + 1) && ... && (*this)[std::distance(first, last) - 1] == *(last - 1)

Throws:

An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is used). Whatever T::T(const T&) throws.

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

Create a circular_buffer with the specified capacity and filled with a copy of the range.

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

Parameters:

`buffer_capacity`	The capacity of the created `circular_buffer`.
`first`	The beginning of the range to be copied.
`last`	The end of the range to be copied.
`alloc`	The allocator.

Requires:

Valid range [first, last).
first and last have to meet the requirements of InputIterator.

Postconditions:

capacity() == buffer_capacity && size() <= std::distance(first, last) && (*this)[0]== *(last - buffer_capacity) && (*this)[1] == *(last - buffer_capacity + 1) && ... && (*this)[buffer_capacity - 1] == *(last - 1)

If the number of items to be copied from the range [first, last) is greater than the specified buffer_capacity then only elements from the range [last - buffer_capacity, last) will be copied.

Throws:

An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is used). Whatever T::T(const T&) throws.

```
~circular_buffer() noexcept;
```
The destructor.
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()

Throws:
Nothing.

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

The assign operator.

Makes this circular_buffer to become a copy of the specified circular_buffer.

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

Parameters:

`cb`	The `circular_buffer` to be copied.

Postconditions:

*this == cb

Throws:

An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is used). Whatever T::T(const T&) throws.

```
circular_buffer< T, Alloc > & 
operator=(circular_buffer< T, Alloc > && cb) noexcept;
```
Move assigns content of cb to *this, leaving cb empty.

Complexity. Constant.

Parameters:

cb

circular_buffer to 'steal' value from.

Requires:

C++ compiler with rvalue references support.

Postconditions:

cb.empty()

Throws:
Nothing.

void assign(size_type n, param_value_type item);

Assign n items into the circular_buffer.

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

Parameters:

`n`	The number of elements the `circular_buffer` will be filled with.
`item`	The element the `circular_buffer` will be filled with.

Postconditions:

capacity() == n && size() == n && (*this)[0] == item && (*this)[1] == item && ... && (*this) [n - 1] == item

Throws:

An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is used). Whatever T::T(const T&) throws.

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

Assign n items into the circular_buffer specifying the capacity.

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

Parameters:

`buffer_capacity`	The new capacity.
`n`	The number of elements the `circular_buffer` will be filled with.
`item`	The element the `circular_buffer` will be filled with.

Requires:

capacity >= n

Postconditions:

capacity() == buffer_capacity && size() == n && (*this)[0] == item && (*this)[1] == item && ... && (*this) [n - 1] == item

Throws:

An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is used). Whatever T::T(const T&) throws.

template<typename InputIterator> 
  void assign(InputIterator first, InputIterator last);

Assign a copy of the range into the circular_buffer.

The content of the circular_buffer will be removed and replaced with copies of elements from the specified range.

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

Parameters:

`first`	The beginning of the range to be copied.
`last`	The end of the range to be copied.

Requires:

Valid range [first, last).
first and last have to meet the requirements of InputIterator.

Postconditions:

capacity() == std::distance(first, last) && size() == std::distance(first, last) && (*this)[0]== *first && (*this)[1] == *(first + 1) && ... && (*this)[std::distance(first, last) - 1] == *(last - 1)

Throws:

An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is used). Whatever T::T(const T&) throws.

template<typename InputIterator> 
  void assign(capacity_type buffer_capacity, InputIterator first, 
              InputIterator last);

Assign a copy of the range into the circular_buffer specifying the capacity.

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 copies of elements from the specified range.

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

Parameters:

`buffer_capacity`	The new capacity.
`first`	The beginning of the range to be copied.
`last`	The end of the range to be copied.

Requires:

Valid range [first, last).
first and last have to meet the requirements of InputIterator.

Postconditions:

Throws:

An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is used). Whatever T::T(const T&) throws.

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

Swap the contents of two circular_buffers.

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

Parameters:

`cb`	The `circular_buffer` whose content will be swapped.

Postconditions:

this contains elements of cb and vice versa; the capacity of this equals to the capacity of cb and vice versa.

Throws:

Nothing.

void push_back(param_value_type item);

Insert a new element at the end of the circular_buffer.

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

Parameters:

item

The element to be inserted.

Postconditions:

if capacity() > 0 then back() == item
If the circular_buffer is full, the first element will be removed. If the capacity is 0, nothing will be inserted.

Throws:

Whatever T::T(const T&) throws. Whatever T::operator = (const T&) throws.

void push_back(rvalue_type item);

Insert a new element at the end of the circular_buffer using rvalue references or rvalues references emulation.

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

Parameters:

item

The element to be inserted.

Postconditions:

if capacity() > 0 then back() == item
If the circular_buffer is full, the first element will be removed. If the capacity is 0, nothing will be inserted.

Throws:

Whatever T::T(T&&) throws. Whatever T::operator = (T&&) throws.

void push_back();

Insert a new default-constructed element at the end of the circular_buffer.

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

Postconditions:	if `capacity() > 0` then `back() == item` If the `circular_buffer` is full, the first element will be removed. If the capacity is `0`, nothing will be inserted.
Throws:	Whatever `T::T()` throws. Whatever `T::T(T&&)` throws. Whatever `T::operator = (T&&)` throws.

void push_front(param_value_type item);

Insert a new element at the beginning of the circular_buffer.

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

Parameters:

item

The element to be inserted.

Postconditions:

if capacity() > 0 then front() == item
If the circular_buffer is full, the last element will be removed. If the capacity is 0, nothing will be inserted.

Throws:

Whatever T::T(const T&) throws. Whatever T::operator = (const T&) throws.

void push_front(rvalue_type item);

Insert a new element at the beginning of the circular_buffer using rvalue references or rvalues references emulation.

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

Parameters:

item

The element to be inserted.

Postconditions:

if capacity() > 0 then front() == item
If the circular_buffer is full, the last element will be removed. If the capacity is 0, nothing will be inserted.

Throws:

Whatever T::T(T&&) throws. Whatever T::operator = (T&&) throws.

void push_front();

Insert a new default-constructed element at the beginning of the circular_buffer.

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

Postconditions:	if `capacity() > 0` then `front() == item` If the `circular_buffer` is full, the last element will be removed. If the capacity is `0`, nothing will be inserted.
Throws:	Whatever `T::T()` throws. Whatever `T::T(T&&)` throws. Whatever `T::operator = (T&&)` throws.

```
void pop_back();
```
Remove the last element from the circular_buffer.

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)

Requires:

!empty()

Postconditions:

The last element is removed from the circular_buffer.

Throws:
Nothing.
```
void pop_front();
```
Remove the first element from the circular_buffer.

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)

Requires:

!empty()

Postconditions:

The first element is removed from the circular_buffer.

Throws:
Nothing.

iterator insert(iterator pos, param_value_type item);

Insert an element at the specified position.

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

Parameters:

`pos`	An iterator specifying the position where the `item` will be inserted.
`item`	The element to be inserted.

Requires:

pos is a valid iterator pointing to the circular_buffer or its end.

Postconditions:

The item will be inserted at the position pos.
If the circular_buffer is full, the first element will be overwritten. If the circular_buffer is full and the pos points to begin(), then the item will not be inserted. If the capacity is 0, nothing will be inserted.

Returns:

Iterator to the inserted element or begin() if the item is not inserted. (See the Effect.)

Throws:

Whatever T::T(const T&) throws. Whatever T::operator = (const T&) throws. Exceptions of move_if_noexcept(T&).

iterator insert(iterator pos, rvalue_type item);

Insert an element at the specified position.

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

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

Parameters:

`pos`	An iterator specifying the position where the `item` will be inserted.
`item`	The element to be inserted.

Requires:

pos is a valid iterator pointing to the circular_buffer or its end.

Postconditions:

Returns:

Iterator to the inserted element or begin() if the item is not inserted. (See the Effect.)

Throws:

Whatever T::T(T&&) throws. Whatever T::operator = (T&&) throws. Exceptions of move_if_noexcept(T&).

iterator insert(iterator pos);

Insert a default-constructed element at the specified position.

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

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

Parameters:

pos

An iterator specifying the position where the item will be inserted.

Requires:

pos is a valid iterator pointing to the circular_buffer or its end.

Postconditions:

Returns:

Iterator to the inserted element or begin() if the item is not inserted. (See the Effect.)

Throws:

Whatever T::T() throws. Whatever T::T(T&&) throws. Whatever T::operator = (T&&) throws. Exceptions of move_if_noexcept(T&).

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

Insert n copies of the item at the specified position.

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

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

Parameters:

`pos`	An iterator specifying the position where the `item`s will be inserted.
`n`	The number of `item`s the to be inserted.
`item`	The element whose copies will be inserted.

Requires:

pos is a valid iterator pointing to the circular_buffer or its end.

Postconditions:

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

Throws:

Whatever T::T(const T&) throws. Whatever T::operator = (const T&) throws. Exceptions of move_if_noexcept(T&).

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

Insert the range [first, last) at the specified position.

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

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

Parameters:

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

Requires:

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.

Postconditions:

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

Throws:

Whatever T::T(const T&) throws if the InputIterator is not a move iterator. Whatever T::operator = (const T&) throws if the InputIterator is not a move iterator. Whatever T::T(T&&) throws if the InputIterator is a move iterator. Whatever T::operator = (T&&) throws if the InputIterator is a move iterator.

iterator rinsert(iterator pos, param_value_type item);

Insert an element before the specified position.

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

Parameters:

`pos`	An iterator specifying the position before which the `item` will be inserted.
`item`	The element to be inserted.

Requires:

pos is a valid iterator pointing to the circular_buffer or its end.

Postconditions:

The item will be inserted before the position pos.
If the circular_buffer is full, the last element will be overwritten. If the circular_buffer is full and the pos points to end(), then the item will not be inserted. If the capacity is 0, nothing will be inserted.

Returns:

Iterator to the inserted element or end() if the item is not inserted. (See the Effect.)

Throws:

Whatever T::T(const T&) throws. Whatever T::operator = (const T&) throws. Exceptions of move_if_noexcept(T&).

iterator rinsert(iterator pos, rvalue_type item);

Insert an element before the specified position.

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

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

Parameters:

`pos`	An iterator specifying the position before which the `item` will be inserted.
`item`	The element to be inserted.

Requires:

pos is a valid iterator pointing to the circular_buffer or its end.

Postconditions:

Returns:

Iterator to the inserted element or end() if the item is not inserted. (See the Effect.)

Throws:

Whatever T::T(T&&) throws. Whatever T::operator = (T&&) throws. Exceptions of move_if_noexcept(T&).

iterator rinsert(iterator pos);

Insert an element before the specified position.

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

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

Parameters:

pos

An iterator specifying the position before which the item will be inserted.

Requires:

pos is a valid iterator pointing to the circular_buffer or its end.

Postconditions:

Returns:

Iterator to the inserted element or end() if the item is not inserted. (See the Effect.)

Throws:

Whatever T::T() throws. Whatever T::T(T&&) throws. Whatever T::operator = (T&&) throws. Exceptions of move_if_noexcept(T&).

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

Insert n copies of the item before the specified position.

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

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

Parameters:

`pos`	An iterator specifying the position where the `item`s will be inserted.
`n`	The number of `item`s the to be inserted.
`item`	The element whose copies will be inserted.

Requires:

pos is a valid iterator pointing to the circular_buffer or its end.

Postconditions:

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

Throws:

Whatever T::T(const T&) throws. Whatever T::operator = (const T&) throws. Exceptions of move_if_noexcept(T&).

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

Insert the range [first, last) before the specified position.

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

Complexity. Linear (in [std::distance(begin(), pos) + std::distance(first, last)]; in min[capacity(), std::distance(begin(), pos) + 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 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 rinsert 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|.

Parameters:

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

Requires:

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.

Postconditions:

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

Throws:

iterator erase(iterator pos);

Remove an element at the specified position.

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 the erased element (towards the end; except iterators equal to end()).

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

Parameters:

pos

An iterator pointing at the element to be removed.

Requires:

pos is a valid iterator pointing to the circular_buffer (but not an end()).

Postconditions:

The element at the position pos is removed.

Returns:

Iterator to the first element remaining beyond the removed element or end() if no such element exists.

Throws:

<a href="circular_buffer/implementation.html#circular_buffer.implementation.exceptions_of_move_if_noexcept_t">Exceptions of move_if_noexcept(T&).

iterator erase(iterator first, iterator last);

Erase the range [first, last).

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 the erased range (towards the end; except iterators equal to end()).

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

Parameters:

`first`	The beginning of the range to be removed.
`last`	The end of the range to be removed.

Requires:

Valid range [first, last).

Postconditions:

The elements from the range [first, last) are removed. (If first == last nothing is removed.)

Returns:

Iterator to the first element remaining beyond the removed elements or end() if no such element exists.

Throws:

<a href="circular_buffer/implementation.html#circular_buffer.implementation.exceptions_of_move_if_noexcept_t">Exceptions of move_if_noexcept(T&).

iterator rerase(iterator pos);

Remove an element at the specified position.

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 the erased element (towards the beginning).

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

	Note
	This method is symmetric to the `erase(iterator)` method and is more effective than `erase(iterator)` if the iterator `pos` is close to the beginning of the `circular_buffer`. (See the Complexity.)

Parameters:

pos

An iterator pointing at the element to be removed.

Requires:

pos is a valid iterator pointing to the circular_buffer (but not an end()).

Postconditions:

The element at the position pos is removed.

Returns:

Iterator to the first element remaining in front of the removed element or begin() if no such element exists.

Throws:

<a href="circular_buffer/implementation.html#circular_buffer.implementation.exceptions_of_move_if_noexcept_t">Exceptions of move_if_noexcept(T&).

iterator rerase(iterator first, iterator last);

Erase the range [first, last).

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 the erased range (towards the beginning).

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

	Note
	This method is symmetric to the `erase(iterator, iterator)` method and is more effective than `erase(iterator, iterator)` if `std::distance(begin(), first)` is lower that `std::distance(last, end())`.

Parameters:

`first`	The beginning of the range to be removed.
`last`	The end of the range to be removed.

Requires:

Valid range [first, last).

Postconditions:

The elements from the range [first, last) are removed. (If first == last nothing is removed.)

Returns:

Iterator to the first element remaining in front of the removed elements or begin() if no such element exists.

Throws:

<a href="circular_buffer/implementation.html#circular_buffer.implementation.exceptions_of_move_if_noexcept_t">Exceptions of move_if_noexcept(T&).

void erase_begin(size_type n);

Remove first n elements (with constant complexity for scalar types).

Exception Safety. Basic; no-throw if the operation in the Throws section does not throw anything. (I.e. no throw in case of scalars.)

Iterator Invalidation. Invalidates iterators pointing to the first n erased elements.

Complexity. Constant (in n) for scalar types; linear for other types.

Note

This method has been specially designed for types which do not require an explicit destructruction (e.g. integer, float or a pointer). For these scalar types a call to a destructor is not required which makes it possible to implement the "erase from beginning" operation with a constant complexity. For non-sacalar types the complexity is linear (hence the explicit destruction is needed) and the implementation is actually equivalent to rerase(begin(), begin() + n).

Parameters:

`n`	The number of elements to be removed.

Requires:

n <= size()

Postconditions:

The n elements at the beginning of the circular_buffer will be removed.

Throws:

<a href="circular_buffer/implementation.html#circular_buffer.implementation.exceptions_of_move_if_noexcept_t">Exceptions of move_if_noexcept(T&).

void erase_end(size_type n);

Remove last n elements (with constant complexity for scalar types).

Exception Safety. Basic; no-throw if the operation in the Throws section does not throw anything. (I.e. no throw in case of scalars.)

Iterator Invalidation. Invalidates iterators pointing to the last n erased elements.

Complexity. Constant (in n) for scalar types; linear for other types.

Note

This method has been specially designed for types which do not require an explicit destructruction (e.g. integer, float or a pointer). For these scalar types a call to a destructor is not required which makes it possible to implement the "erase from end" operation with a constant complexity. For non-sacalar types the complexity is linear (hence the explicit destruction is needed) and the implementation is actually equivalent to erase(end() - n, end()).

Parameters:

`n`	The number of elements to be removed.

Requires:

n <= size()

Postconditions:

The n elements at the end of the circular_buffer will be removed.

Throws:

<a href="circular_buffer/implementation.html#circular_buffer.implementation.exceptions_of_move_if_noexcept_t">Exceptions of move_if_noexcept(T&).

```
void clear() noexcept;
```
Remove all stored elements from the circular_buffer.

Exception Safety. No-throw.

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

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

See Also: ~circular_buffer(), erase(iterator), erase(iterator, iterator), rerase(iterator), rerase(iterator, iterator), erase_begin(size_type), erase_end(size_type)

Postconditions:

size() == 0

Throws:
Nothing.

	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.

Requires:	`!empty()`
Returns:	A reference to the first element of the `circular_buffer`.
Throws:	Nothing.

Returns:	The number of elements stored in the `circular_buffer`.
Throws:	Nothing.

Returns:	The maximum size/capacity the `circular_buffer` can be set to.
Throws:	Nothing.

Returns:	`true` if there are no elements stored in the `circular_buffer`; `false` otherwise.
Throws:	Nothing.

Returns:	`true` if the number of elements stored in the `circular_buffer` equals the capacity of the `circular_buffer`; `false` otherwise.
Throws:	Nothing.

Boost C++ Libraries