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 {
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 Alloc::pointer                                                                            pointer;                 // A pointer to an element. 
  typedef Alloc::const_pointer                                                                      const_pointer;           // A const pointer to the element. 
  typedef Alloc::reference                                                                          reference;               // A reference to an element. 
  typedef Alloc::const_reference                                                                    const_reference;         // A const reference to an element. 
  typedef Alloc::difference_type                                                                    difference_type;       
  typedef Alloc::size_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 boost::reverse_iterator< const_iterator >                                                 const_reverse_iterator;  // A const iterator used to iterate backwards through a circular_buffer. 
  typedef boost::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;           

  // construct/copy/destruct
  explicit circular_buffer(const allocator_type & = allocator_type());
  explicit circular_buffer(capacity_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 > &&);
  template<typename InputIterator> 
    circular_buffer(capacity_type, InputIterator, InputIterator, 
                    const allocator_type & = allocator_type());
  circular_buffer& operator=(const circular_buffer< T, Alloc > &);
  circular_buffer& operator=(circular_buffer< T, Alloc > &&);
  ~circular_buffer();

  // public member functions
  allocator_type get_allocator() const;
  allocator_type & get_allocator();
  iterator begin();
  iterator end();
  const_iterator begin() const;
  const_iterator end() const;
  reverse_iterator rbegin();
  reverse_iterator rend();
  const_reverse_iterator rbegin() const;
  const_reverse_iterator rend() const;
  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;
  void rotate(const_iterator);
  size_type size() const;
  size_type max_size() const;
  bool empty() const;
  bool full() const;
  size_type reserve() const;
  capacity_type capacity() const;
  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());
   m_alloc(alloc);
  template<typename InputIterator>  is_integral();
  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 > &);
  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();

  // private member functions
  template<typename ValT> void push_back_impl(ValT);
  template<typename ValT> void push_front_impl(ValT);
  template<typename ValT> iterator insert_impl(iterator, ValT);
  template<typename ValT> iterator rinsert_impl(iterator, ValT);
  void check_position(size_type) const;
  template<typename Pointer> void increment(Pointer &) const;
  template<typename Pointer> void decrement(Pointer &) const;
  template<typename Pointer> Pointer add(Pointer, difference_type) const;
  template<typename Pointer> Pointer sub(Pointer, difference_type) const;
  pointer map_pointer(pointer) const;
  pointer allocate(size_type);
  void deallocate(pointer, size_type);
  bool is_uninitialized(const_pointer) const;
  void replace(pointer, param_value_type);
  void replace(pointer, rvalue_type);
  void construct_or_replace(bool, pointer, param_value_type);
  void construct_or_replace(bool, pointer, rvalue_type);
  void destroy_item(pointer);
  void destroy_if_constructed(pointer);
  void destroy_content();
  void destroy_content(const true_type &);
  void destroy_content(const false_type &);
  void destroy();
  void initialize_buffer(capacity_type);
  void initialize_buffer(capacity_type, param_value_type);
  template<typename IntegralType> 
    void initialize(IntegralType, IntegralType, const true_type &);
  template<typename Iterator> 
    void initialize(Iterator, Iterator, const false_type &);
  template<typename InputIterator> 
    void initialize(InputIterator, InputIterator, 
                    const std::input_iterator_tag &);
  template<typename ForwardIterator> 
    void initialize(ForwardIterator, ForwardIterator, 
                    const std::forward_iterator_tag &);
  template<typename IntegralType> 
    void initialize(capacity_type, IntegralType, IntegralType, 
                    const true_type &);
  template<typename Iterator> 
    void initialize(capacity_type, Iterator, Iterator, const false_type &);
  template<typename InputIterator> 
    void initialize(capacity_type, InputIterator, InputIterator, 
                    const std::input_iterator_tag &);
  template<typename ForwardIterator> 
    void initialize(capacity_type, ForwardIterator, ForwardIterator, 
                    const std::forward_iterator_tag &);
  template<typename ForwardIterator> 
    void initialize(capacity_type, ForwardIterator, ForwardIterator, 
                    size_type);
  void reset(pointer, pointer, capacity_type);
  void swap_allocator(circular_buffer< T, Alloc > &, const true_type &);
  void swap_allocator(circular_buffer< T, Alloc > &, const false_type &);
  template<typename IntegralType> 
    void assign(IntegralType, IntegralType, const true_type &);
  template<typename Iterator> 
    void assign(Iterator, Iterator, const false_type &);
  template<typename InputIterator> 
    void assign(InputIterator, InputIterator, const std::input_iterator_tag &);
  template<typename ForwardIterator> 
    void assign(ForwardIterator, ForwardIterator, 
                const std::forward_iterator_tag &);
  template<typename IntegralType> 
    void assign(capacity_type, IntegralType, IntegralType, const true_type &);
  template<typename Iterator> 
    void assign(capacity_type, Iterator, Iterator, const false_type &);
  template<typename InputIterator> 
    void assign(capacity_type, InputIterator, InputIterator, 
                const std::input_iterator_tag &);
  template<typename ForwardIterator> 
    void assign(capacity_type, ForwardIterator, ForwardIterator, 
                const std::forward_iterator_tag &);
  template<typename Functor> 
    void assign_n(capacity_type, size_type, const Functor &);
  template<typename ValT> iterator insert_item(const iterator &, ValT);
  template<typename IntegralType> 
    void insert(const iterator &, IntegralType, IntegralType, 
                const true_type &);
  template<typename Iterator> 
    void insert(const iterator &, Iterator, Iterator, const false_type &);
  template<typename InputIterator> 
    void insert(iterator, InputIterator, InputIterator, 
                const std::input_iterator_tag &);
  template<typename ForwardIterator> 
    void insert(const iterator &, ForwardIterator, ForwardIterator, 
                const std::forward_iterator_tag &);
  template<typename Wrapper> 
    void insert_n(const iterator &, size_type, const Wrapper &);
  template<typename IntegralType> 
    void rinsert(const iterator &, IntegralType, IntegralType, 
                 const true_type &);
  template<typename Iterator> 
    void rinsert(const iterator &, Iterator, Iterator, const false_type &);
  template<typename InputIterator> 
    void rinsert(iterator, InputIterator, InputIterator, 
                 const std::input_iterator_tag &);
  template<typename ForwardIterator> 
    void rinsert(const iterator &, ForwardIterator, ForwardIterator, 
                 const std::forward_iterator_tag &);
  template<typename Wrapper> 
    void rinsert_n(const iterator &, size_type, const Wrapper &);
  void erase_begin(size_type, const true_type &);
  void erase_begin(size_type, const false_type &);
  void erase_end(size_type, const true_type &);
  void erase_end(size_type, const false_type &);

  // public data members
   __pad0__;  // Create a full circular_buffer with the specified capacity and filled with n copies of item. 
   __pad1__;  // Create a full circular_buffer filled with a copy of the range. 
   last;
};

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 Alloc::difference_type difference_type;

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

`circular_buffer` public construct/copy/destruct

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

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.

See Also:

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

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:

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

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

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

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);
```
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(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:

`alloc`	The allocator.
`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.

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

See Also:

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

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& operator=(circular_buffer< T, Alloc > && cb);
```
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.
```
~circular_buffer();
```
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` public member functions

```
allocator_type get_allocator() const;
```
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();
```
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();

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

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;

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 end() const;

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.

reverse_iterator rbegin();

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

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;

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;

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;

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

See Also:

rset_capacity(capacity_type), resize(size_type, const_reference)

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

See Also:

rresize(size_type, const_reference), set_capacity(capacity_type)

Parameters:

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

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

See Also:

set_capacity(capacity_type), rresize(size_type, const_reference)

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

See Also:

resize(size_type, const_reference), rset_capacity(capacity_type)

Parameters:

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

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.

```
 m_alloc(alloc);
```

template<typename InputIterator>  is_integral();

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

See Also:

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

Parameters:

`item`	The element the `circular_buffer` will be filled with.
`n`	The number of elements 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).

See Also:

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

Parameters:

`buffer_capacity`	The new capacity.
`item`	The element the `circular_buffer` will be filled with.
`n`	The number of elements 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)).

See Also:

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

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

See Also:

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

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

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

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)

Parameters:

`item`	The element to be inserted.
`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:

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

See Also:

Parameters:

`item`	The element to be inserted.
`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(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())).

See Also:

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

See Also:

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

Parameters:

`item`	The element whose copies will be inserted.
`n`	The number of `item`s the to be inserted.
`pos`	An iterator specifying the position where the `item`s 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|.

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)

Parameters:

`first`	The beginning of the range to be inserted.
`last`	The end of the range to be inserted.
`pos`	An iterator specifying the position where the range will 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)).

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)

Parameters:

`item`	The element to be inserted.
`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:

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

See Also:

Parameters:

`item`	The element to be inserted.
`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(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)).

See Also:

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

See Also:

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

Parameters:

`item`	The element whose copies will be inserted.
`n`	The number of `item`s the to be inserted.
`pos`	An iterator specifying the position where the `item`s 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|.

See Also:

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

Parameters:

`first`	The beginning of the range to be inserted.
`last`	The end of the range to be inserted.
`pos`	An iterator specifying the position where the range will 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())).

See Also:

erase(iterator, iterator), rerase(iterator), rerase(iterator, iterator), erase_begin(size_type), erase_end(size_type), clear()

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

See Also:

erase(iterator), rerase(iterator), rerase(iterator, iterator), erase_begin(size_type), erase_end(size_type), clear()

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

See Also:

erase(iterator), erase(iterator, iterator), rerase(iterator, iterator), erase_begin(size_type), erase_end(size_type), clear()

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

See Also:

erase(iterator), erase(iterator, iterator), rerase(iterator), erase_begin(size_type), erase_end(size_type), clear()

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

See Also:

erase(iterator), erase(iterator, iterator), rerase(iterator), rerase(iterator, iterator), erase_end(size_type), clear()

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

See Also:

erase(iterator), erase(iterator, iterator), rerase(iterator), rerase(iterator, iterator), erase_begin(size_type), clear()

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

`circular_buffer` private member functions

template<typename ValT> void push_back_impl(ValT item);

template<typename ValT> void push_front_impl(ValT item);

template<typename ValT> iterator insert_impl(iterator pos, ValT item);

template<typename ValT> iterator rinsert_impl(iterator pos, ValT item);

void check_position(size_type index) const;

Check if the index is valid.

template<typename Pointer> void increment(Pointer & p) const;

Increment the pointer.

template<typename Pointer> void decrement(Pointer & p) const;

Decrement the pointer.

template<typename Pointer> Pointer add(Pointer p, difference_type n) const;

Add n to the pointer.

template<typename Pointer> Pointer sub(Pointer p, difference_type n) const;

Subtract n from the pointer.

```
pointer map_pointer(pointer p) const;
```
Map the null pointer to virtual end of circular buffer.
```
pointer allocate(size_type n);
```
Allocate memory.

void deallocate(pointer p, size_type n);

Deallocate memory.

```
bool is_uninitialized(const_pointer p) const;
```
Does the pointer point to the uninitialized memory?

void replace(pointer pos, param_value_type item);

Replace an element.

void replace(pointer pos, rvalue_type item);

Replace an element.

```
void construct_or_replace(bool construct, pointer pos, param_value_type item);
```
Construct or replace an element.
construct has to be set to true if and only if pos points to an uninitialized memory.
```
void construct_or_replace(bool construct, pointer pos, rvalue_type item);
```
Construct or replace an element.
construct has to be set to true if and only if pos points to an uninitialized memory.
```
void destroy_item(pointer p);
```
Destroy an item.
```
void destroy_if_constructed(pointer pos);
```
Destroy an item only if it has been constructed.
```
void destroy_content();
```
Destroy the whole content of the circular buffer.

void destroy_content(const true_type &);

Specialized destroy_content method.

void destroy_content(const false_type &);

Specialized destroy_content method.

```
void destroy();
```
Destroy content and free allocated memory.

void initialize_buffer(capacity_type buffer_capacity);

Initialize the internal buffer.

void initialize_buffer(capacity_type buffer_capacity, param_value_type item);

Initialize the internal buffer.

template<typename IntegralType> 
  void initialize(IntegralType n, IntegralType item, const true_type &);

Specialized initialize method.

template<typename Iterator> 
  void initialize(Iterator first, Iterator last, const false_type &);

Specialized initialize method.

template<typename InputIterator> 
  void initialize(InputIterator first, InputIterator last, 
                  const std::input_iterator_tag &);

Specialized initialize method.

template<typename ForwardIterator> 
  void initialize(ForwardIterator first, ForwardIterator last, 
                  const std::forward_iterator_tag &);

Specialized initialize method.

template<typename IntegralType> 
  void initialize(capacity_type buffer_capacity, IntegralType n, 
                  IntegralType item, const true_type &);

Specialized initialize method.

template<typename Iterator> 
  void initialize(capacity_type buffer_capacity, Iterator first, 
                  Iterator last, const false_type &);

Specialized initialize method.

template<typename InputIterator> 
  void initialize(capacity_type buffer_capacity, InputIterator first, 
                  InputIterator last, const std::input_iterator_tag &);

Specialized initialize method.

template<typename ForwardIterator> 
  void initialize(capacity_type buffer_capacity, ForwardIterator first, 
                  ForwardIterator last, const std::forward_iterator_tag &);

Specialized initialize method.

template<typename ForwardIterator> 
  void initialize(capacity_type buffer_capacity, ForwardIterator first, 
                  ForwardIterator last, size_type distance);

Initialize the circular buffer.

void reset(pointer buff, pointer last, capacity_type new_capacity);

Reset the circular buffer.

void swap_allocator(circular_buffer< T, Alloc > &, const true_type &);

Specialized method for swapping the allocator.

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

Specialized method for swapping the allocator.

template<typename IntegralType> 
  void assign(IntegralType n, IntegralType item, const true_type &);

Specialized assign method.

template<typename Iterator> 
  void assign(Iterator first, Iterator last, const false_type &);

Specialized assign method.

template<typename InputIterator> 
  void assign(InputIterator first, InputIterator last, 
              const std::input_iterator_tag &);

Specialized assign method.

template<typename ForwardIterator> 
  void assign(ForwardIterator first, ForwardIterator last, 
              const std::forward_iterator_tag &);

Specialized assign method.

template<typename IntegralType> 
  void assign(capacity_type new_capacity, IntegralType n, IntegralType item, 
              const true_type &);

Specialized assign method.

template<typename Iterator> 
  void assign(capacity_type new_capacity, Iterator first, Iterator last, 
              const false_type &);

Specialized assign method.

template<typename InputIterator> 
  void assign(capacity_type new_capacity, InputIterator first, 
              InputIterator last, const std::input_iterator_tag &);

Specialized assign method.

template<typename ForwardIterator> 
  void assign(capacity_type new_capacity, ForwardIterator first, 
              ForwardIterator last, const std::forward_iterator_tag &);

Specialized assign method.

template<typename Functor> 
  void assign_n(capacity_type new_capacity, size_type n, const Functor & fnc);

Helper assign method.

template<typename ValT> iterator insert_item(const iterator & pos, ValT item);

Helper insert method.

template<typename IntegralType> 
  void insert(const iterator & pos, IntegralType n, IntegralType item, 
              const true_type &);

Specialized insert method.

template<typename Iterator> 
  void insert(const iterator & pos, Iterator first, Iterator last, 
              const false_type &);

Specialized insert method.

template<typename InputIterator> 
  void insert(iterator pos, InputIterator first, InputIterator last, 
              const std::input_iterator_tag &);

Specialized insert method.

template<typename ForwardIterator> 
  void insert(const iterator & pos, ForwardIterator first, 
              ForwardIterator last, const std::forward_iterator_tag &);

Specialized insert method.

template<typename Wrapper> 
  void insert_n(const iterator & pos, size_type n, const Wrapper & wrapper);

Helper insert method.

template<typename IntegralType> 
  void rinsert(const iterator & pos, IntegralType n, IntegralType item, 
               const true_type &);

Specialized rinsert method.

template<typename Iterator> 
  void rinsert(const iterator & pos, Iterator first, Iterator last, 
               const false_type &);

Specialized rinsert method.

template<typename InputIterator> 
  void rinsert(iterator pos, InputIterator first, InputIterator last, 
               const std::input_iterator_tag &);

Specialized insert method.

template<typename ForwardIterator> 
  void rinsert(const iterator & pos, ForwardIterator first, 
               ForwardIterator last, const std::forward_iterator_tag &);

Specialized rinsert method.

template<typename Wrapper> 
  void rinsert_n(const iterator & pos, size_type n, const Wrapper & wrapper);

Helper rinsert method.

void erase_begin(size_type n, const true_type &);

Specialized erase_begin method.

void erase_begin(size_type n, const false_type &);

Specialized erase_begin method.

void erase_end(size_type n, const true_type &);

Specialized erase_end method.

void erase_end(size_type n, const false_type &);

Specialized erase_end method.

`circular_buffer` public public data members

```
 __pad0__;
```
Complexity. Linear (in the n).
```
 __pad1__;
```
Complexity. Linear (in the std::distance(first, last)).

	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