Templated Circular Buffer Container

circular_buffer<T, Alloc>

Boost

Contents

Description
Introductory Example
Synopsis
Rationale
Semantics
Caveats
Debug Support
More Examples
Header Files
Modeled Concepts
Template Parameters
Public Types
Constructors and Destructor
Public Member Functions
Standalone Functions
Notes
See also
Acknowledgments
Circular Buffer
Figure: The circular buffer (for someone known as ring or cyclic buffer).

Description

In general the term circular buffer refers to an area in memory which is used to store incoming data. When the buffer is filled, new data is written starting at the beginning of the buffer and overwriting the old. [1] (Also see the Figure.)

The circular_buffer is a STL compliant container. It is a kind of sequence similar to std::vector or std::deque. It supports random access iterators, constant time insert and erase operations at the beginning or the end of the buffer and interoperability with std algorithms. The circular_buffer is especially designed to provide fixed capacity storage. When its capacity is exhausted, newly inserted elements will cause elements either at the beginning or end of the buffer (depending on what insert operation is used) to be overwritten.

The circular_buffer only allocates memory when created, when the capacity is adjusted explicitly, or as necessary to accommodate resizing or assign operations. On the other hand, there is also a circular_buffer_space_optimized available. It is an adaptor of the circular_buffer which does not allocate memory at once when created, rather it allocates memory as needed.


Introductory Example

A brief example using the circular_buffer: 

   #include <boost/circular_buffer.hpp>

   int main(int /*argc*/, char* /*argv*/[]) {

      // Create a circular buffer with a capacity for 3 integers.
      boost::circular_buffer<int> cb(3);

      // Insert some elements into the buffer.
      cb.push_back(1);
      cb.push_back(2);
      cb.push_back(3);

      int a = cb[0];  // a == 1
      int b = cb[1];  // b == 2
      int c = cb[2];  // c == 3

      // The buffer is full now, pushing subsequent
      // elements will overwrite the front-most elements.

      cb.push_back(4);  // Overwrite 1 with 4.
      cb.push_back(5);  // Overwrite 2 with 5.

      // The buffer now contains 3, 4 and 5.

      a = cb[0];  // a == 3
      b = cb[1];  // b == 4
      c = cb[2];  // c == 5

      // Elements can be popped from either the front or the back.

      cb.pop_back();  // 5 is removed.
      cb.pop_front(); // 3 is removed.

      int d = cb[0];  // d == 4

      return 0;
   }

Synopsis 

namespace boost {

template <class T, class Alloc>
class circular_buffer
{
public:
   typedef typename Alloc::value_type value_type;
   typedef typename Alloc::pointer pointer;
   typedef typename Alloc::const_pointer const_pointer;
   typedef typename Alloc::reference reference;
   typedef typename Alloc::const_reference const_reference;
   typedef typename Alloc::difference_type difference_type;
   typedef typename Alloc::size_type size_type;
   typedef Alloc allocator_type;
   typedef implementation-defined const_iterator;
   typedef implementation-defined iterator;
   typedef reverse_iterator<const_iterator> const_reverse_iterator;
   typedef reverse_iterator<iterator> reverse_iterator;
   typedef std::pair<pointer, size_type> array_range;
   typedef std::pair<const_pointer, size_type> const_array_range;
   typedef size_type capacity_control;

   explicit circular_buffer(const allocator_type& alloc = allocator_type());
   explicit circular_buffer(size_type capacity, const allocator_type& alloc = allocator_type());
   circular_buffer(size_type n, const_reference item, const allocator_type& alloc = allocator_type());
   circular_buffer(size_type capacity, size_type n, const_reference item, const allocator_type& alloc = allocator_type());
   circular_buffer(const circular_buffer<T, Alloc>& cb);
   template <class InputIterator>
      circular_buffer(InputIterator first, InputIterator last);
   template <class InputIterator>
      circular_buffer(size_type capacity, InputIterator first, InputIterator last);
   template <class InputIterator>
      circular_buffer(InputIterator first, InputIterator last, const allocator_type& alloc = allocator_type());
   template <class InputIterator>
      circular_buffer(size_type capacity, InputIterator first, InputIterator last, const allocator_type& alloc = allocator_type());
   ~circular_buffer();

   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 index);
   const_reference operator[](size_type index) const;
   reference at(size_type index);
   const_reference at(size_type index) 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();
   size_type size() const;
   size_type max_size() const;
   bool empty() const;
   bool full() const;
   size_type capacity() const;
   void set_capacity(size_type new_capacity);
   void resize(size_type new_size, const_reference item = value_type());
   void rset_capacity(size_type new_capacity);
   void rresize(size_type new_size, const_reference item = value_type());
   circular_buffer<T, Alloc>& operator=(const circular_buffer<T, Alloc>& cb);
   void assign(size_type n, const_reference item);
   void assign(size_type capacity, size_type n, const_reference item);
   template <class InputIterator>
      void assign(InputIterator first, InputIterator last);
   template <class InputIterator>
      void assign(size_type capacity, InputIterator first, InputIterator last);
   void swap(circular_buffer<T, Alloc>& cb);
   void push_back(const_reference item = value_type());
   void push_front(const_reference item = value_type());
   void pop_back();
   void pop_front();
   iterator insert(iterator pos, const_reference item = value_type());
   void insert(iterator pos, size_type n, const_reference item);
   template <class InputIterator>
      void insert(iterator pos, InputIterator first, InputIterator last);
   iterator rinsert(iterator pos, const_reference item = value_type());
   void rinsert(iterator pos, size_type n, const_reference item);
   template <class InputIterator>
      void rinsert(iterator pos, InputIterator first, InputIterator last);
   iterator erase(iterator pos);
   iterator erase(iterator first, iterator last);
   iterator rerase(iterator pos);
   iterator rerase(iterator first, iterator last);
   void clear();
};

template <class T, class Alloc>
   bool operator==(const circular_buffer<T, Alloc>& lhs, const circular_buffer<T, Alloc>& rhs);
template <class T, class Alloc>
   bool operator<(const circular_buffer<T, Alloc>& lhs, const circular_buffer<T, Alloc>& rhs);
template <class T, class Alloc>
   bool operator!=(const circular_buffer<T, Alloc>& lhs, const circular_buffer<T, Alloc>& rhs);
template <class T, class Alloc>
   bool operator>(const circular_buffer<T, Alloc>& lhs, const circular_buffer<T, Alloc>& rhs);
template <class T, class Alloc>
   bool operator<=(const circular_buffer<T, Alloc>& lhs, const circular_buffer<T, Alloc>& rhs);
template <class T, class Alloc>
   bool operator>=(const circular_buffer<T, Alloc>& lhs, const circular_buffer<T, Alloc>& rhs);
template <class T, class Alloc>
   void swap(circular_buffer<T, Alloc>& lhs, circular_buffer<T, Alloc>& rhs);

} // namespace boost

Rationale

The basic motivation behind the circular_buffer was to create a container which would work seamlessly with STL. Additionally, the design of the circular_buffer was guided by the following principles:

  1. Maximum efficiency for envisaged applications.
  2. Suitable for general purpose use.
  3. The behaviour of the buffer as intuitive as possible.
  4. Suitable for specialization by means of adaptors. (The circular_buffer_space_optimized is such an example of the adaptor.)
  5. Easy to debug. (See Debug Support for details.)

In order to achieve maximum efficiency, the circular_buffer stores its elements in a contiguous region of memory, which then enables:

  1. Use of fixed memory and no implicit or unexpected memory allocation.
  2. Fast constant-time insertion and removal of elements from the front and back.
  3. Fast constant-time random access of elements.
  4. Suitability for real-time and performance critical applications.

Possible applications of the circular_buffer include:

The following paragraphs describe issues that had to be considered during the implemenation of the circular_buffer:

Thread-Safety

The thread-safety of the circular_buffer is the same as the thread-safety of containers in most STL implementations. This means the circular_buffer is thread-safe only in the sense that simultaneous accesses to distinct instances of the circular_buffer are safe, and simultaneous read accesses to a shared circular_buffer are safe.

If multiple threads access a single circular_buffer, and at least one of the threads may potentially write, then the user is responsible for ensuring mutual exclusion between the threads during the container accesses. The mutual exclusion between the threads can be achieved by wrapping operations of the underlying circular_buffer with a lock acquisition and release. (See the Bounded Buffer Example.)

Overwrite Operation

Overwrite operation occurs when an element is inserted into a full circular_buffer - the old element is being overwriten by the new one. There was a discussion what exactly "overwriting of an element" means during the formal review. It may be either a destruction of the original element and a consequent inplace construction of a new element or it may be an assignment of a new element into an old one. The circular_buffer implements assignment because it is more effective.

From the point of business logic of a stored element, the destruction/construction operation and assignment usually mean the same. However, in very rare cases (if in any) they may differ. If there is a requirement for elements to be destructed/constructed instead of being assigned, consider implementing a wrapper of the element which would implement the assign operator, and store the wrappers instead. It is necessary to note that storing such wrappers has a drawback. The destruction/construction will be invoked on every assignment of the wrapper - not only when a wrapper is being overwritten (when the buffer is full) but also when the stored wrappers are being shifted (e.g. as a result of insertion into the middle of container).

Writing to a Full Buffer

There are several options how to cope with the case if a data source produces more data than can fit in the fixed-sized buffer:

  1. Inform the data source to wait until there is room in the buffer (e.g. by throwing an overflow exception).
  2. If the oldest data is the most important, ignore new data from the source until there is room in the buffer again.
  3. If the latest data is the most important, write over the oldest data.
  4. Let the producer to be responsible for checking the size of the buffer prior writing into it.

It is apparent that the circular_buffer implements the third option. But it may be less apparent it does not implement any other option - especially the first two. One can get an impression that the circular_buffer should implement first three options and offer a mechanism of choosing among them. This impression is wrong. The circular_buffer was designed and optimized to be circular (which means overwriting the oldest data when full). If such a controlling mechanism had been enabled, it would just complicate the matters and the usage of the circular_buffer would be probably less straightforward.

Moreover, the first two options (and the fouth option as well) do not require the buffer to be circular at all. If there is a need for the first or second option, consider implementing an adaptor of e.g. std::vector. In this case the circular_buffer is not suitable for adapting, because, in contrary to std::vector, it bears an overhead for its circular behavior.

Reading/Removing from an Empty Buffer

When reading or removing an element from an empty buffer, the buffer should be able to notify the data consumer (e.g. by throwing underflow exception) that there are no elements stored in it. The circular_buffer does not implement such a behaviour for two reasons:

  1. It would introduce performance overhead.
  2. No other std container implements it this way.

It is considered to be a bug to read or remove an element (e.g. by calling front() or pop_back()) from an empty std container and from an emtpy circular_buffer as well. The data consumer has to test if the container is not empty before reading/removing from it. However, when reading from the circular_buffer, there is an option to rely on the at() method which throws an exception when the index is out of range.

Iterator Invalidation

An iterator is usually considered to be invalidated if an element, the iterator pointed to, had been removed or overwritten by an another element. This definition is enforced by the Debug Support and is documented for every method. However, some applications utilizing circular_buffer may require less strict definition: an iterator is invalid only if it points to an uninitialized memory. Consider following example: 

   #define BOOST_CB_DISABLE_DEBUG // The Debug Support has to be disabled, otherwise the code produces a runtime error.

   #include <boost/circular_buffer.hpp>
   #include <assert.h>

   int main(int /*argc*/, char* /*argv*/[]) {

      boost::circular_buffer<int> cb(3);

      cb.push_back(1);
      cb.push_back(2);
      cb.push_back(3);

      boost::circular_buffer<int>::iterator it = cb.begin();

      assert(*it == 1);

      cb.push_back(4);

      assert(*it == 4); // The iterator still points to the initialized memory.

      return 0;
   }

The iterator does not point to the original element any more (and is considered to be invalid from the "strict" point of view) but it still points to the same valid place in the memory. This "soft" definition of iterator invalidation is supported by the circular_buffer but should be considered as an implementation detail rather than a full-fledged feature. The rules when the iterator is still valid can be inferred from the code in soft_iterator_invalidation.cpp.

Semantics

TODO remove this section

The behaviour of insertion for circular_buffer is as follows:

The behaviour of resizing a circular_buffer is as follows:

The behaviour of assigning to a circular_buffer is as follows:

The rules for iterator (and result of data() ) invalidation for circular_buffer are as follows:

In addition to the preceding rules the iterators get also invalidated due to overwriting (e.g. iterator pointing to the front-most element gets invalidated when inserting into the full circular_buffer ). They get invalidated in that sense they do not point to the same element as before but they do still point to the same valid place in the memory. If you want to rely on this feature you have to turn of the Debug Support otherwise an assertion will report an error if such invalidated iterator is used.


Caveats

The circular_buffer should not be used for storing pointers to dynamically allocated objects. When a circular_buffer becomes full, further insertion will overwrite the stored pointers - resulting in a memoryleak. One recommend alternative is the use of smart pointers [2]. (Any container of std::auto_ptr is considered particularly hazardous. [3] )

Elements inserted near the front of a full circular_buffer can be lost. According to the semantics of insert , insertion overwrites front-most items as necessary - possibly including elements currently being inserted at the front of the buffer. Conversely, push_front to a full circular_buffer is guaranteed to overwrite the back-most element.

Elements inserted near the back of a full circular_buffer can be lost. According to the semantics of rinsert , insertion overwrites back-most items as necessary - possibly including elements currently being inserted at the back of the buffer. Conversely, push_back to a full circular_buffer is guaranteed to overwrite the front-most element.

While internals of a circular_buffer are circular, iterators are not. Iterators of a circular_buffer are only valid for the range [begin(), end()] . E.g. iterators (begin() - 1) and (end() + 1) are invalid.


Debug Support

In order to help a programmer to avoid and find common bugs, the circular_buffer contains a kind of debug support.

The circular_buffer maintains a list of valid iterators. As soon as any element gets destroyed all iterators pointing to this element are removed from this list and explicitly invalidated (an invalidation flag is set). The debug support also consists of many assertions (BOOST_ASSERT macros) which ensure the circular_buffer and its iterators are used in the correct manner at runtime. In case an invalid iterator is used the assertion will report an error. The connection of explicit iterator invalidation and assertions makes a very robust debug technique which catches most of the errors.

Moreover, the uninitialized memory allocated by circular_buffer is filled with the value 0xcc in the debug mode. This can help the programmer when debugging the code to recognize the initialized memory from the uninitialized. For details refer the source code.

The debug support is enabled only in the debug mode (when the NDEBUG is not defined). It can also be explicitly disabled by defining BOOST_CB_DISABLE_DEBUG macro.


More Examples

The following example includes various usage of the circular_buffer . 

   #include <boost/circular_buffer.hpp>
   #include <numeric>
   #include <assert.h>

   int main(int /*argc*/, char* /*argv*/[])
   {
      // create a circular buffer of capacity 3
      boost::circular_buffer<int> cb(3);

      // insert some elements into the circular buffer
      cb.push_back(1);
      cb.push_back(2);

      // assertions
      assert(cb[0] == 1);
      assert(cb[1] == 2);
      assert(!cb.full());
      assert(cb.size() == 2);
      assert(cb.capacity() == 3);

      // insert some other elements
      cb.push_back(3);
      cb.push_back(4);

      // evaluate the sum
      int sum = std::accumulate(cb.begin(), cb.end(), 0);

      // assertions
      assert(cb[0] == 2);
      assert(cb[1] == 3);
      assert(cb[2] == 4);
      assert(*cb.begin() == 2);
      assert(cb.front() == 2);
      assert(cb.back() == 4);
      assert(sum == 9);
      assert(cb.full());
      assert(cb.size() == 3);
      assert(cb.capacity() == 3);

      return 0;
   }

The circular_buffer has a capacity of three int. Therefore, the size of the buffer will not exceed three. The accumulate algorithm evaluates the sum of the stored elements. The semantics of the circular_buffer can be inferred from the assertions.

Bounded Buffer Example

The bounded buffer is normally used in a producer-consumer mode when producer threads produce items and store them in the container and consumer threads remove these items and process them. The bounded buffer has to guarantee that producers do not insert items into the container when the container is full, that consumers do not try to remove items when the container is empty, and that each produced item is consumed by exactly one consumer.

The example below shows how the circular_buffer can be utilized as an underlying container of the bounded buffer. 

   #include <boost/circular_buffer.hpp>
   #include <boost/thread/mutex.hpp>
   #include <boost/thread/condition.hpp>
   #include <boost/thread/thread.hpp>
   #include <boost/progress.hpp>
   #include <boost/bind.hpp>

   template <class T>
   class bounded_buffer {
   public:

      typedef boost::circular_buffer<T> container_type;
      typedef typename container_type::size_type size_type;
      typedef typename container_type::value_type value_type;

      explicit bounded_buffer(size_type capacity) : m_unread(0), m_container(capacity) {}

      void push_front(const value_type& item) {
         boost::mutex::scoped_lock lock(m_mutex);
         m_not_full.wait(lock, boost::bind(&bounded_buffer<value_type>::is_not_full, this));
         m_container.push_front(item);
         ++m_unread;
         lock.unlock();
         m_not_empty.notify_one();
      }

      void pop_back(value_type* pItem) {
         boost::mutex::scoped_lock lock(m_mutex);
         m_not_empty.wait(lock, boost::bind(&bounded_buffer<value_type>::is_not_empty, this));
         *pItem = m_container[--m_unread];
         lock.unlock();
         m_not_full.notify_one();
      }

   private:
      bounded_buffer(const bounded_buffer&);              // Disabled copy constructor
      bounded_buffer& operator = (const bounded_buffer&); // Disabled assign operator

      bool is_not_empty() const { return m_unread > 0; }
      bool is_not_full() const { return m_unread < m_container.capacity(); }

      size_type m_unread;
      container_type m_container;
      boost::mutex m_mutex;
      boost::condition m_not_empty;
      boost::condition m_not_full;
   };

The bounded_buffer uses Boost Threads and Boost Bind libraries.

The push_front() method is called by the producer thread in order to insert a new item into the buffer. The method locks the mutex and waits until there is a space for the new item. (The mutex is unlocked during the waiting stage and has to be regained when the condition is met.) If there is a space in the buffer available, the execution continues and the method inserts the item at the end of the circular_buffer. Then it increments the number of unread items and unlocks the mutex (in case an exception is thrown before the mutex is unlocked, the mutex is unlocked automatically by the destructor of the scoped_lock). At last the method notifies one of the consumer threads waiting for a new item to be inserted into the buffer.

The pop_back() method is called by the consumer thread in order to read the next item from the buffer. The method locks the mutex and waits until there is an unread item in the buffer. If there is at least one unread item, the method decrements the number of unread items and reads the next item from the circular_buffer. Then it unlocks the mutex and notifies one of the producer threads waiting for the buffer to free a space for the next item.

The pop_back() method does not remove the item but the item is left in the circular_buffer which then replaces it with a new one (inserted by a producer) when the circular_buffer is full. This technique is more effective than removing the item explicitly by calling the pop_back() method of the circular_buffer. This claim is based on the assumption that an assignment (replacement) of a new item into an old one is more effective than a destruction (removal) of an old item and a consequent inplace construction (insertion) of a new item.

For comparison of bounded buffers based on different containers compile and run bounded_buffer_comparison.cpp. The test should reveal the bounded buffer based on the circular_buffer is most effective closely followed by the std::deque based bounded buffer. (In praxis the result may be different because the test is affected by external factors such as immediate CPU load.)

Header Files

The circular_buffer is defined in the file boost/circular_buffer.hpp. There is also a forward declaration for the circular_buffer in the header file boost/circular_buffer_fwd.hpp.


Modeled Concepts

Random AccessContainer, Front Insertion Sequence and Back Insertion Sequence.


Template Parameters

Parameter Description Default
T The type of the elements stored in the circular buffer.
Type Requirements:
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()).

Alloc The allocator type used for all internal memory management.
Type Requirements:
The Alloc has to meet the allocator requirements imposed by STL.
std::allocator<T>

Public Types

Type Description
value_type The type of elements stored in the circular buffer.
pointer A pointer to an element.
const_pointer A const pointer to the element.
reference A reference to an element.
const_reference A const reference to an element.
difference_type The distance type. (A signed integral type used to represent the distance between two iterators.)
size_type The size type. (An unsigned integral type that can represent any nonnegative value of the container's distance type.)
allocator_type The type of an allocator used in the circular buffer.
const_iterator A const (random access) iterator used to iterate through the circular buffer.
iterator A (random access) iterator used to iterate through the circular buffer.
const_reverse_iterator A const iterator used to iterate backwards through a circular buffer.
reverse_iterator An iterator used to iterate backwards through a circular buffer.
array_range An 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.)
const_array_range A range of a const array. (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.)
capacity_control The capacity type. (Defined just for consistency with the circular_buffer_space_optimized.)

Constructors and Destructor

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

Create an empty circular buffer with a maximum capacity.
Postcondition:
capacity() == max_size() && size() == 0
Throws:
An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is used).
explicit circular_buffer(size_type capacity, const allocator_type& alloc = allocator_type());

Create an empty circular buffer with a given capacity.
Parameter(s):
capacity The maximum number of elements which can be stored in the circular_buffer.
Postcondition:
(*this).capacity() == capacity && (*this).size == 0
Throws:
An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is used).
circular_buffer(size_type n, const_reference item, const allocator_type& alloc = allocator_type());

Create a full circular buffer with a given capacity and filled with copies of item.
Postcondition:
capacity() == n && size() == n && (*this)[0] == (*this)[1] == ... == (*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(size_type capacity, size_type n, const_reference item, const allocator_type& alloc = allocator_type());

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

Copy constructor.
Postcondition:
*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.
template <class InputIterator>
circular_buffer(InputIterator first, InputIterator last);
template <class InputIterator>
circular_buffer(size_type capacity, InputIterator first, InputIterator last);
template <class InputIterator>
circular_buffer(InputIterator first, InputIterator last, const allocator_type& alloc = allocator_type());

TODO doc.
template <class InputIterator>
circular_buffer(size_type capacity, InputIterator first, InputIterator last, const allocator_type& alloc = allocator_type());

Create a circular buffer with a copy of a range.
Precondition:
Valid range [first, last).
Postcondition:
(*this).capacity() == capacity
If the number of items to copy from the range [first, last) is greater than the specified capacity then only elements from the range [last - 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();

Destructor.

Public Member Functions

allocator_type get_allocator() const;

Get the allocator.
Returns:
The allocator.
Throws:
Nothing.
Complexity:
Constant (in the size of the circular_buffer).
Exception Safety:
No-throw.
Iterator Invalidation:
Does not invalidate any iterator.
See Also:
get_allocator() for obtaining an allocator reference.
allocator_type& get_allocator();

Get the allocator reference.
Returns:
A reference to the allocator.
Throws:
Nothing.
Complexity:
Constant (in the size of the circular_buffer).
Exception Safety:
No-throw.
Iterator Invalidation:
Does not invalidate any iterator.
Note:
This method was added in order to optimize obtaining of the allocator with a state, although use of stateful allocators in STL is discouraged.
See Also:
get_allocator() const
iterator begin();

Get the iterator pointing to the beginning of the circular_buffer.
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.
Complexity:
Constant (in the size of the circular_buffer).
Exception Safety:
No-throw.
Iterator Invalidation:
Does not invalidate any iterator.
See Also:
end(), rbegin(), rend()
iterator end();

Get the iterator pointing to the end of the circular_buffer.
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.
Complexity:
Constant (in the size of the circular_buffer).
Exception Safety:
No-throw.
Iterator Invalidation:
Does not invalidate any iterator.
See Also:
begin(), rbegin(), rend()
const_iterator begin() const;

Get the const iterator pointing to the beginning of the circular_buffer.
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.
Complexity:
Constant (in the size of the circular_buffer).
Exception Safety:
No-throw.
Iterator Invalidation:
Does not invalidate any iterator.
See Also:
end() const, rbegin() const, rend() const
const_iterator end() const;

Get the const iterator pointing to the end of the circular_buffer.
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.
Complexity:
Constant (in the size of the circular_buffer).
Exception Safety:
No-throw.
Iterator Invalidation:
Does not invalidate any iterator.
See Also:
begin() const, rbegin() const, rend() const
reverse_iterator rbegin();

Get the iterator pointing to the beginning of the "reversed" circular_buffer.
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.
Complexity:
Constant (in the size of the circular_buffer).
Exception Safety:
No-throw.
Iterator Invalidation:
Does not invalidate any iterator.
See Also:
rend(), begin(), end()
reverse_iterator rend();

Get the iterator pointing to the end of the "reversed" circular_buffer.
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.
Complexity:
Constant (in the size of the circular_buffer).
Exception Safety:
No-throw.
Iterator Invalidation:
Does not invalidate any iterator.
See Also:
rbegin(), begin(), end()
const_reverse_iterator rbegin() const;

Get the const iterator pointing to the beginning of the "reversed" circular_buffer.
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.
Complexity:
Constant (in the size of the circular_buffer).
Exception Safety:
No-throw.
Iterator Invalidation:
Does not invalidate any iterator.
See Also:
rend() const, begin() const, end() const
const_reverse_iterator rend() const;

Get the const iterator pointing to the end of the "reversed" circular_buffer.
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.
Complexity:
Constant (in the size of the circular_buffer).
Exception Safety:
No-throw.
Iterator Invalidation:
Does not invalidate any iterator.
See Also:
rbegin() const, begin() const, end() const
reference operator[](size_type index);

Get the element at the index position.
Precondition:
0 <= index && index < size()
Parameter(s):
index The position of the element.
Returns:
A reference to the element at the index position.
Throws:
Nothing.
Complexity:
Constant (in the size of the circular_buffer).
Exception Safety:
No-throw.
Iterator Invalidation:
Does not invalidate any iterator.
See Also:
at()
const_reference operator[](size_type index) const;

Get the element at the index position.
Precondition:
0 <= index && index < size()
Parameter(s):
index The position of the element.
Returns:
A const reference to the element at the index position.
Throws:
Nothing.
Complexity:
No-throw.
Exception Safety:
Strong.
Iterator Invalidation:
Does not invalidate any iterator.
See Also:
at() const
reference at(size_type index);

Get the element at the index position.
Parameter(s):
index The position of the element.
Returns:
A const reference to the element at the index position.
Throws:
std::out_of_range when the index is invalid (when index >= size()).
Complexity:
Constant (in the size of the circular_buffer).
Exception Safety:
Strong.
Iterator Invalidation:
Does not invalidate any iterator.
See Also:
operator[]
const_reference at(size_type index) const;

Get the element at the index position.
Parameter(s):
index The position of the element.
Returns:
A const reference to the element at the index position.
Throws:
std::out_of_range when the index is invalid (when index >= size()).
Complexity:
Constant (in the size of the circular_buffer).
Exception Safety:
Strong.
Iterator Invalidation:
Does not invalidate any iterator.
See Also:
operator[] const
reference front();

Get the first (leftmost) element.
Precondition:
!empty()
Returns:
A reference to the first element of the circular_buffer.
Throws:
Nothing.
Complexity:
Constant (in the size of the circular_buffer).
Exception Safety:
No-throw.
Iterator Invalidation:
Does not invalidate any iterator.
See Also:
back()
reference back();

Get the last (rightmost) element.
Precondition:
!empty()
Returns:
A reference to the last element of the circular_buffer.
Throws:
Nothing.
Complexity:
Constant (in the size of the circular_buffer).
Exception Safety:
No-throw.
Iterator Invalidation:
Does not invalidate any iterator.
See Also:
front()
const_reference front() const;

Get the first (leftmost) element.
Precondition:
!empty()
Returns:
A const reference to the first element of the circular_buffer.
Throws:
Nothing.
Complexity:
Constant (in the size of the circular_buffer).
Exception Safety:
No-throw.
Iterator Invalidation:
Does not invalidate any iterator.
See Also:
back() const
const_reference back() const;

Get the last (rightmost) element.
Precondition:
!empty()
Returns:
A const reference to the last element of the circular_buffer.
Throws:
Nothing.
Complexity:
Constant (in the size of the circular_buffer).
Exception Safety:
No-throw.
Iterator Invalidation:
Does not invalidate any iterator.
See Also:
front() const
array_range array_one();

Get the first continuos 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 cbuff[0] == 'a', cbuff[1] == 'b', ... and cbuff[6] == 'g':

circular_buffer<char> cbuff(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 writting 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 = cbuff.array_one();
write(file_desc, ar.first, ar.second);
ar = cbuff.array_two();
write(file_desc, ar.first, ar.second);

Or relying on the linearize() method:

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

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

Returns:
The array range of the first continuos array of the internal buffer. In the case the circular_buffer is empty the size of the returned array is 0.
Throws:
Nothing.
Complexity:
Constant (in the size of the circular_buffer).
Exception Safety:
No-throw.
Iterator Invalidation:
Does not invalidate any iterator.
Note:
In the case the internal buffer is linear e.g. |a|b|c|d|e|f|g| | | | the "array one" is represented by |a|b|c|d|e|f|g| and the "array two" does not exist (the array_two() method returns an array with the size 0).
See Also:
array_two(), linearize()
array_range array_two();

Get the second continuos 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.

Returns:
The array range of the second continuos 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.
Complexity:
Constant (in the size of the circular_buffer).
Exception Safety:
No-throw.
Iterator Invalidation:
Does not invalidate any iterator.
See Also:
array_one()
const_array_range array_one() const;

Get the first continuos 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.

Returns:
The array range of the first continuos array of the internal buffer. In the case the circular_buffer is empty the size of the returned array is 0.
Throws:
Nothing.
Complexity:
Constant (in the size of the circular_buffer).
Exception Safety:
No-throw.
Iterator Invalidation:
Does not invalidate any iterator.
See Also:
array_two() const; array_one() for more details.how to pass data into a legacy C API.
const_array_range array_two() const;

Get the second continuos 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.

Returns:
The array range of the second continuos 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.
Complexity:
Constant (in the size of the circular_buffer).
Exception Safety:
No-throw.
Iterator Invalidation:
Does not invalidate any iterator.
See Also:
array_one() const
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.

Postcondition:
&(*this)[0] < &(*this)[1] < ... < &(*this)[size() - 1]
Returns:
A pointer to the beginning of the array or 0 if empty.
Throws:
Whatever T::T(const T&) throws.
Whatever T::operator = (const T&) throws.
Complexity:
Linear (in the size of the circular_buffer); constant if the postcondition is already met.
Exception Safety:
Basic; no-throw if the operations in the Throws do not throw anything.
Iterator Invalidation:
Invalidates all iterators pointing to the circular_buffer; does not invalidate any iterator if the postcondition is already met prior calling this method.
Warning:
In general invoking any method which modifies the internal state of the circular_buffer may delinearize the internal buffer and invalidate the returned pointer.
See Also:
array_one() and array_two() for the other option.how to pass data into a legacy C API.
size_type size() const;

Get the number of elements currently stored in the circular_buffer.
Returns:
The number of elements stored in the circular_buffer.
Throws:
Nothing.
Complexity:
Constant (in the size of the circular_buffer).
Exception Safety:
No-throw.
Iterator Invalidation:
Does not invalidate any iterator.
See Also:
capacity(), max_size(), resize()
size_type max_size() const;

Get the largest possible size or capacity of the circular_buffer.
Returns:
The maximum size/capacity the circular_buffer can be set to.
Throws:
Nothing.
Complexity:
Constant (in the size of the circular_buffer).
Exception Safety:
No-throw.
Iterator Invalidation:
Does not invalidate any iterator.
See Also:
size(), capacity()
bool empty() const;

Is the circular_buffer empty?
Returns:
true if there are no elements stored in the circular_buffer; false otherwise.
Throws:
Nothing.
Complexity:
Constant (in the size of the circular_buffer).
Exception Safety:
No-throw.
Iterator Invalidation:
Does not invalidate any iterator.
See Also:
full()
bool full() const;

Is the circular_buffer full?
Returns:
true if the number of elements stored in the circular_buffer equals the capacity of the circular_buffer; false otherwise.
Throws:
Nothing.
Complexity:
Constant (in the size of the circular_buffer).
Exception Safety:
No-throw.
Iterator Invalidation:
Does not invalidate any iterator.
See Also:
empty()
size_type capacity() const;

Get the capacity of the circular_buffer.
Returns:
The maximum number of elements which can be stored in the circular_buffer.
Throws:
Nothing.
Complexity:
Constant (in the size of the circular_buffer).
Exception Safety:
No-throw.
Iterator Invalidation:
Does not invalidate any iterator.
See Also:
size(), max_size(), set_capacity()
void set_capacity(size_type new_capacity);

Change the capacity of the circular_buffer.
Postcondition:
capacity() == 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 (leftmost) elements will be removed.
Parameter(s):
new_capacity The 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.
Complexity:
Linear (in the size/new capacity of the circular_buffer). The complexity of the allocator's allocate() and deallocate() methods which are used in set_capacity() is not considered.
Exception Safety:
Strong.
Iterator Invalidation:
Invalidates all iterators pointing to the circular_buffer.
See Also:
rset_capacity(), resize()
void resize(size_type new_size, const_reference item = value_type());

Change the size of the circular_buffer.
Postcondition:
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 (rightmost) elements will be removed. (The capacity will remain unchanged.)
Parameter(s):
new_size The new size.
item The element the circular_buffer will be filled with in order to gain the requested size. (See the postcondition.)
Throws:
An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is used).
Whatever T::T(const T&) throws.
Complexity:
Linear (in the size/new capacity of the circular_buffer). The complexity of the allocator's allocate() and deallocate() methods which are used in set_capacity() is not considered.
Exception Safety:
Strong.
Iterator Invalidation:
Invalidates all iterators pointing to the circular_buffer.
See Also:
rresize(), set_capacity()
void rset_capacity(size_type new_capacity);

Change the capacity of the circular_buffer.
Postcondition:
capacity() == 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 (rightmost) elements will be removed.
Parameter(s):
new_capacity The 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.
Complexity:
Linear (in the size/new capacity of the circular_buffer). The complexity of the allocator's allocate() and deallocate() methods which are used in rset_capacity() is not considered.
Exception Safety:
Basic.
Iterator Invalidation:
Invalidates all iterators pointing to the circular_buffer.
See Also:
set_capacity(), rresize()
void rresize(size_type new_size, const_reference item = value_type());

Change the size of the circular_buffer.
Postcondition:
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 (leftmost) elements will be removed. (The capacity will remain unchanged.)
Parameter(s):
new_size The new size.
item The element the circular_buffer will be filled with in order to gain the requested size. (See the postcondition.)
Throws:
An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is used).
Whatever T::T(const T&) throws.
Complexity:
Linear (in the size/new capacity of the circular_buffer). The complexity of the allocator's allocate() and deallocate() methods which are used in set_capacity() is not considered.
Exception Safety:
Strong.
Iterator Invalidation:
Invalidates all iterators pointing to the circular_buffer.
See Also:
rresize(), set_capacity()
circular_buffer<T,Alloc>& operator=(const circular_buffer<T,Alloc>& cb);

Assignment operator.
Postcondition:
*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.
Note:
For iterator invalidation see the documentation.
void assign(size_type n, const_reference item);

Assign n items into the circular buffer.
Postcondition:
(*this).capacity() == n && (*this).size() == n && (*this)[0] == (*this)[1] == ... == (*this).back() == item
Throws:
An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is used).
Whatever T::T(const T&) throws.
Note:
For iterator invalidation see the documentation.
void assign(size_type capacity, size_type n, const_reference item);

TODO doc.
template <class InputIterator>
void assign(InputIterator first, InputIterator last);

Assign a copy of range.
Precondition:
Valid range [first, last).
Postcondition:
(*this).capacity() == std::distance(first, last) && (*this).size() == std::distance(first, last)
Throws:
An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is used).
Whatever T::T(const T&) throws.
Note:
For iterator invalidation see the documentation.
template <class InputIterator>
void assign(size_type capacity, InputIterator first, InputIterator last);

TODO doc.
void swap(circular_buffer<T,Alloc>& cb);

Swap the contents of two circular_buffers.
Parameter(s):
cb The circular_buffer whose content should be swapped.
Throws:
Nothing.
Postcondition:
this contains elements of cb and vice versa.
Complexity:
Constant (in the size of the circular_buffer).
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.)
See Also:
swap(circular_buffer<T, Alloc>&, circular_buffer<T, Alloc>&)
void push_back(const_reference item = value_type());

Insert a new element at the end.
Postcondition:
(*this).back() == item
If the circular buffer is full, the first (leftmost) element will be removed.
Throws:
Whatever T::T(const T&) throws.
Note:
For iterator invalidation see the documentation.
void push_front(const_reference item = value_type());

Insert a new element at the start.
Postcondition:
(*this).front() == item
If the circular buffer is full, the last (rightmost) element will be removed.
Throws:
Whatever T::T(const T&) throws.
Note:
For iterator invalidation see the documentation.
void pop_back();

Remove the last (rightmost) element.
Precondition:
!*(this).empty() iterator it = ((*this).end() - 1)
Postcondition:
((*this).end() - 1) != it
Note:
For iterator invalidation see the documentation.
void pop_front();

Remove the first (leftmost) element.
Precondition:
!*(this).empty() iterator it = (*this).begin()
Postcondition:
(*this).begin() != it
Note:
For iterator invalidation see the documentation.
iterator insert(iterator pos, const_reference item = value_type());

Insert the item before the given position.
Precondition:
Valid pos iterator.
Postcondition:
The item will be inserted at the position pos.
If the circular buffer is full, the first (leftmost) element will be removed.
Returns:
iterator to the inserted element.
Throws:
Whatever T::T(const T&) throws.
Whatever T::operator = (const T&) throws.
Note:
For iterator invalidation see the documentation.
void insert(iterator pos, size_type n, const_reference item);

Insert n copies of the item before the given position.
Precondition:
Valid pos iterator.
Postcondition:
This operation preserves the capacity of the circular buffer. If the insertion would result in exceeding the capacity of the circular buffer then the necessary number of elements from the beginning (left) of the circular buffer will be removed or not all n elements will be inserted or both.
Example:
original circular buffer |1|2|3|4| | | - capacity: 6, size: 4
position ---------------------^
insert(position, (size_t)5, 6);
(If the operation won't preserve capacity, the buffer would look like this |1|2|6|6|6|6|6|3|4|)
RESULTING circular buffer |6|6|6|6|3|4| - capacity: 6, size: 6
Throws:
Whatever T::T(const T&) throws.
Whatever T::operator = (const T&) throws.
Note:
For iterator invalidation see the documentation.
template <class InputIterator>
void insert(iterator pos, InputIterator first, InputIterator last);

Insert the range [first, last) before the given position.
Precondition:
Valid pos iterator and valid range [first, last).
Postcondition:
This operation preserves the capacity of the circular buffer. If the insertion would result in exceeding the capacity of the circular buffer then the necessary number of elements from the beginning (left) of the circular buffer will be removed or not the whole range will be inserted or both. In case the whole range cannot be inserted it will be inserted just some elements from the end (right) of the range (see the example).
Example:
array to insert: int array[] = { 5, 6, 7, 8, 9 };
original circular buffer |1|2|3|4| | | - capacity: 6, size: 4
position ---------------------^
insert(position, array, array + 5);
(If the operation won't preserve capacity, the buffer would look like this |1|2|5|6|7|8|9|3|4|)
RESULTING circular buffer |6|7|8|9|3|4| - capacity: 6, size: 6
Throws:
Whatever T::T(const T&) throws.
Whatever T::operator = (const T&) throws.
Note:
For iterator invalidation see the documentation.
iterator rinsert(iterator pos, const_reference item = value_type());

Insert an item before the given position.
Precondition:
Valid pos iterator.
Postcondition:
The item will be inserted before the position pos.
If the circular buffer is full, the last element (rightmost) will be removed.
Returns:
iterator to the inserted element.
Throws:
Whatever T::T(const T&) throws.
Whatever T::operator = (const T&) throws.
Note:
For iterator invalidation see the documentation.
void rinsert(iterator pos, size_type n, const_reference item);

Insert n copies of the item before the given position.
Precondition:
Valid pos iterator.
Postcondition:
This operation preserves the capacity of the circular buffer. If the insertion would result in exceeding the capacity of the circular buffer then the necessary number of elements from the end (right) of the circular buffer will be removed or not all n elements will be inserted or both.
Example:
original circular buffer |1|2|3|4| | | - capacity: 6, size: 4
position ---------------------^
insert(position, (size_t)5, 6);
(If the operation won't preserve capacity, the buffer would look like this |1|2|6|6|6|6|6|3|4|)
RESULTING circular buffer |1|2|6|6|6|6| - capacity: 6, size: 6
Throws:
Whatever T::T(const T&) throws.
Whatever T::operator = (const T&) throws.
Note:
For iterator invalidation see the documentation.
template <class InputIterator>
void rinsert(iterator pos, InputIterator first, InputIterator last);

Insert the range [first, last) before the given position.
Precondition:
Valid pos iterator and valid range [first, last).
Postcondition:
This operation preserves the capacity of the circular buffer. If the insertion would result in exceeding the capacity of the circular buffer then the necessary number of elements from the end (right) of the circular buffer will be removed or not the whole range will be inserted or both. In case the whole range cannot be inserted it will be inserted just some elements from the beginning (left) of the range (see the example).
Example:
array to insert: int array[] = { 5, 6, 7, 8, 9 };
original circular buffer |1|2|3|4| | | - capacity: 6, size: 4
position ---------------------^
insert(position, array, array + 5);
(If the operation won't preserve capacity, the buffer would look like this |1|2|5|6|7|8|9|3|4|)
RESULTING circular buffer |1|2|5|6|7|8| - capacity: 6, size: 6
Throws:
Whatever T::T(const T&) throws.
Whatever T::operator = (const T&) throws.
Note:
For iterator invalidation see the documentation.
iterator erase(iterator pos);

Erase the element at the given position.
Precondition:
Valid pos iterator. size_type old_size = (*this).size()
Postcondition:
(*this).size() == old_size - 1
Removes an element at the position pos.
Returns:
iterator to the first element remaining beyond the removed element or (*this).end() if no such element exists.
Note:
For iterator invalidation see the documentation.
iterator erase(iterator first, iterator last);

Erase the range [first, last).
Precondition:
Valid range [first, last). size_type old_size = (*this).size()
Postcondition:
(*this).size() == old_size - std::distance(first, last)
Removes the elements from the range [first, last).
Returns:
iterator to the first element remaining beyond the removed element or (*this).end() if no such element exists.
Note:
For iterator invalidation see the documentation.
iterator rerase(iterator pos);

Erase the element at the given position.
Precondition:
Valid pos iterator. size_type old_size = (*this).size()
Postcondition:
(*this).size() == old_size - 1
Removes an element at the position pos.
Returns:
iterator to the first element remaining in front of the removed element or (*this).begin() if no such element exists.
Note:
For iterator invalidation see the documentation.
iterator rerase(iterator first, iterator last);

Erase the range [first, last).
Precondition:
Valid range [first, last). size_type old_size = (*this).size()
Postcondition:
(*this).size() == old_size - std::distance(first, last)
Removes the elements from the range [first, last).
Returns:
iterator to the first element remaining in front of the removed element or (*this).begin() if no such element exists.
Note:
For iterator invalidation see the documentation.
void clear();

Erase all stored elements.
Postcondition:
(*this).size() == 0
Note:
For iterator invalidation see the documentation.

Standalone Functions

template <class T, class Alloc>
bool operator==(const circular_buffer<T,Alloc>& lhs, const circular_buffer<T,Alloc>& rhs);

Test two circular buffers for equality.
template <class T, class Alloc>
bool operator<(const circular_buffer<T,Alloc>& lhs, const circular_buffer<T,Alloc>& rhs);

Lexicographical comparison.
template <class T, class Alloc>
bool operator!=(const circular_buffer<T,Alloc>& lhs, const circular_buffer<T,Alloc>& rhs);

Test two circular buffers for non-equality.
template <class T, class Alloc>
bool operator>(const circular_buffer<T,Alloc>& lhs, const circular_buffer<T,Alloc>& rhs);

Lexicographical comparison.
template <class T, class Alloc>
bool operator<=(const circular_buffer<T,Alloc>& lhs, const circular_buffer<T,Alloc>& rhs);

Lexicographical comparison.
template <class T, class Alloc>
bool operator>=(const circular_buffer<T,Alloc>& lhs, const circular_buffer<T,Alloc>& rhs);

Lexicographical comparison.
template <class T, class Alloc>
void swap(circular_buffer<T,Alloc>& lhs, circular_buffer<T,Alloc>& rhs);

Swap the contents of two circular buffers.

Notes

  1. An indepth definition of a circular buffer can be found at Wikipedia.

  2. A good implementation of smart pointers is included in Boost.

  3. Never create a circular buffer of std::auto_ptr . Refer to Scott Meyers ' excellent book Effective STL for a detailed discussion. (Meyers S., Effective STL: 50 Specific Ways to Improve Your Use of the Standard Template Library. Addison-Wesley, 2001.)


See also

boost::circular_buffer_space_optimized, std::vector, std::list, std::deque


Acknowledgments

The circular_buffer has a short history. Its first version was a std::deque adaptor. This container was not very effective because of many reallocations when inserting/removing an element. Thomas Wenish did a review of this version and motivated me to create a circular buffer which allocates memory at once when created.

The second version adapted std::vector but it has been abandoned soon because of limited control over iterator invalidation.

The current version is a full-fledged STL compliant container. Pavel Vozenilek did a thorough review of this version and came with many good ideas and improvements. Also, I would like to thank Howard Hinnant, Nigel Stewart and everyone who participated at the formal review for valuable comments and ideas.