Templated Circular Buffer Container

circular_buffer<T, Alloc>

 Boost

Contents

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

Description

The circular_buffer container provides fixed capacity storage with constant time insertion and removal of elements at each end of a circular buffer. When the capacity of the circular_buffer is exhausted, inserted elements will cause elements at the opposite end to be overwritten (see the Figure). The circular_buffer only allocates memory when created, when the capacity is adjusted explicitly, or as necessary to accommodate a resizing or assign operation. (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.)

Simple Example

A brief example using the circular_buffer: 

   #include <boost/circular_buffer.hpp>

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

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

      cb.push_back(1);  // Insert the first element.
      cb.push_back(2);  // Insert the second element.
      cb.push_back(3);  // Insert the third element.

      // 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.
      int a = cb[0];  // a == 3
      int b = cb[1];  // b == 4
      int c = cb[2];  // c == 5

      // Elements can be popped from either the front or 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 Alloc allocator_type;
   typedef implementation-defined const_iterator;
   typedef typename Alloc::const_pointer const_pointer;
   typedef typename Alloc::const_reference const_reference;
   typedef implementation-defined const_reverse_iterator;
   typedef typename Alloc::difference_type difference_type;
   typedef implementation-defined iterator;
   typedef typename Alloc::pointer pointer;
   typedef typename Alloc::reference reference;
   typedef implementation-defined reverse_iterator;
   typedef typename Alloc::size_type size_type;
   typedef typename Alloc::value_type value_type;

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

   template <class InputIterator>
      void assign(InputIterator first, InputIterator last);
   void assign(size_type n, value_type item);
   value_type at(size_type index) const;
   reference at(size_type index);
   value_type back() const;
   reference back();
   const_iterator begin() const;
   iterator begin();
   size_type capacity() const;
   void clear();
   pointer data();
   bool empty() const;
   const_iterator end() const;
   iterator end();
   iterator erase(iterator first, iterator last);
   iterator erase(iterator pos);
   value_type front() const;
   reference front();
   bool full() const;
   allocator_type& get_allocator();
   allocator_type get_allocator() const;
   template <class InputIterator>
      void insert(iterator pos, InputIterator first, InputIterator last);
   void insert(iterator pos, size_type n, value_type item);
   iterator insert(iterator pos);
   iterator insert(iterator pos, value_type item);
   size_type max_size() const;
   circular_buffer<T,Alloc>& operator=(const circular_buffer<T,Alloc>& cb);
   value_type operator[](size_type index) const;
   reference operator[](size_type index);
   void pop_back();
   void pop_front();
   void push_back();
   void push_back(value_type item);
   void push_front();
   void push_front(value_type item);
   const_reverse_iterator rbegin() const;
   reverse_iterator rbegin();
   const_reverse_iterator rend() const;
   reverse_iterator rend();
   void resize(size_type new_size, value_type item = T(), bool remove_front = true);
   template <class InputIterator>
      void rinsert(iterator pos, InputIterator first, InputIterator last);
   void rinsert(iterator pos, size_type n, value_type item);
   iterator rinsert(iterator pos);
   iterator rinsert(iterator pos, value_type item);
   void set_capacity(size_type new_capacity, bool remove_front = true);
   size_type size() const;
   void swap(circular_buffer& cb);
};

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

A contiguous region of memory utilized as a circular buffer has several unique and useful characteristics:

  1. Fixed memory use 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.

The circular_buffer container provides a similar interface to std::vector, std::deque and std::list including push, pop, insert, erase, iterators and compatibility with std algorithms.

Possible applications of the circular_buffer include:

The design of the circular_buffer container is guided by the following principles:

  1. Maximum efficiency for envisaged applications.
  2. Suitable for general purpose use.
  3. Interoperable with other std containers and algorithms.
  4. The behaviour of the buffer as intuitive as possible.
  5. Suitable for specialization by means of adaptors. (The circular_buffer_space_optimized is such an example of the adaptor.)
  6. Guarantee of basic exception safety.

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 Access Container, Front Insertion Sequence, Back Insertion Sequence, Assignable (SGI specific), Equality Comparable, LessThan Comparable (SGI specific)

Template Parameters

Parameter Description Default
T The type of the elements stored in the circular buffer.  
Alloc The allocator type used for all internal memory management. std::allocator<T>

Public Types

Type Description
allocator_type The type of the allocator used in the circular buffer.
const_iterator Const (random access) iterator used to iterate through a circular buffer.
const_pointer Const pointer to the element.
const_reference Const reference to the element.
const_reverse_iterator Const iterator used to iterate backwards through a circular buffer.
difference_type Distance type.
iterator Iterator (random access) used to iterate through a circular buffer.
pointer Pointer to the element.
reference Reference to the element.
reverse_iterator Iterator used to iterate backwards through a circular buffer.
size_type Size type.
value_type The type of the elements stored in the circular buffer.

Constructors / Destructor 

 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:
 circular_buffer(const circular_buffer< T, Alloc > & cb);
Copy constructor.
Postcondition:
*this == cb
Throws:
 circular_buffer(size_type capacity, param_value_type item, const allocator_type& alloc = allocator_type());
Create a full circular buffer with a given capacity and filled with copies of item.
Postcondition:
(*this).size() == capacity && (*this)[0] == (*this)[1] == ... == (*this).back() == item
Throws:
 explicit circular_buffer(size_type capacity, const allocator_type& alloc = allocator_type());
Create an empty circular buffer with a given capacity.
Postcondition:
(*this).capacity() == capacity && (*this).size == 0
Throws:
 ~circular_buffer();
Destructor.

Public Member Functions 

 template <class InputIterator>
      void assign(InputIterator first, InputIterator last);
Assign a copy of range.
Precondition:
Valid range [first, last).
Postcondition:
(*this).size() == std::distance(first, last)
If the number of items to be assigned exceeds the capacity of the circular buffer the capacity is set to that number otherwise is stays unchanged.
Throws:
Note:
For iterator invalidation see the documentation. 
 void assign(size_type n, param_value_type item);
Assign n items into the circular buffer.
Postcondition:
(*this).size() == n && (*this)[0] == (*this)[1] == ... == (*this).back() == item
If the number of items to be assigned exceeds the capacity of the circular buffer the capacity is increased to n otherwise it stays unchanged.
Throws:
Note:
For iterator invalidation see the documentation. 
 return_value_type at(size_type index) const;
Return the element at the index position.
Throws:
 reference at(size_type index);
Return the element at the index position.
Throws:
 return_value_type back() const;
Return the last (rightmost) element.
Precondition:
!*(this).empty() 
 reference back();
Return the last (rightmost) element.
Precondition:
!*(this).empty() 
 const_iterator begin() const;
Return a const iterator pointing to the beginning of the circular buffer. 
 iterator begin();
Return an iterator pointing to the beginning of the circular buffer. 
 size_type capacity() const;
Return the capacity of the circular buffer. 
 void clear();
Erase all the stored elements.
Postcondition:
(*this).size() == 0
Note:
For iterator invalidation see the documentation. 
 pointer data();
Return pointer to data stored in the circular buffer as a continuous array of values. This method can be useful e.g. when passing the stored data into the legacy C API.
Postcondition:
&(*this)[0] < &(*this)[1] < ... < &(*this).back()
Returns:
0 if empty.
Throws:
Note:
For iterator invalidation see the documentation. 
 bool empty() const;
Is the circular buffer empty?
Returns:
true if there are no elements stored in the circular buffer. false otherwise. 
 const_iterator end() const;
Return a const iterator pointing to the end of the circular buffer. 
 iterator end();
Return an iterator pointing to the end of the circular buffer. 
 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 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. 
 return_value_type front() const;
Return the first (leftmost) element.
Precondition:
!*(this).empty() 
 reference front();
Return the first (leftmost) element.
Precondition:
!*(this).empty() 
 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. 
 allocator_type& get_allocator();
Return the allocator.
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. 
 allocator_type get_allocator() const;
Return the allocator. 
 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:
Note:
For iterator invalidation see the documentation. 
 void insert(iterator pos, size_type n, param_value_type 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:
Note:
For iterator invalidation see the documentation. 
 iterator insert(iterator pos);
Insert a new element with the default value before the given position.
Postcondition:
value_type() 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:
Note:
For iterator invalidation see the documentation. 
 iterator insert(iterator pos, param_value_type item);
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:
Note:
For iterator invalidation see the documentation. 
 size_type max_size() const;
Return the largest possible size (or capacity) of the circular buffer. 
 circular_buffer< T, Alloc > & operator=(const circular_buffer< T, Alloc > & cb);
Assignment operator.
Postcondition:
*this == cb
Throws:
Note:
For iterator invalidation see the documentation. 
 return_value_type operator[](size_type index) const;
Return the element at the index position.
Precondition:
*(this).size() > index 
 reference operator[](size_type index);
Return the element at the index position.
Precondition:
*(this).size() > index 
 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. 
 void push_back();
Insert a new element with the default value at the end.
Postcondition:
(*this).back() == value_type()
If the circular buffer is full, the first (leftmost) element will be removed.
Throws:
Note:
For iterator invalidation see the documentation. 
 void push_back(param_value_type item);
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:
Note:
For iterator invalidation see the documentation. 
 void push_front();
Insert a new element with the default value at the start.
Postcondition:
(*this).front() == value_type()
If the circular buffer is full, the last (rightmost) element will be removed.
Throws:
Note:
For iterator invalidation see the documentation. 
 void push_front(param_value_type item);
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:
Note:
For iterator invalidation see the documentation. 
 const_reverse_iterator rbegin() const;
Return a const reverse iterator pointing to the beginning of the reversed circular buffer. 
 reverse_iterator rbegin();
Return a reverse iterator pointing to the beginning of the reversed circular buffer. 
 const_reverse_iterator rend() const;
Return a const reverse iterator pointing to the end of the reversed circular buffer. 
 reverse_iterator rend();
Return a reverse iterator pointing to the end of the reversed circular buffer. 
 void resize(size_type new_size, param_value_type item = T(), bool remove_front = true);
Change the size of the circular buffer.
Parameters:
Postcondition:
(*this).size() == new_size
If the new size is greater than the current size, the rest of the circular buffer is filled with copies of item. In case the resulting size exceeds the current capacity the capacity is set to new_size. If the new size is lower than the current size then ((*this).size() - new_size) elements will be removed according to the remove_front parameter.
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:
Note:
For iterator invalidation see the documentation. 
 void rinsert(iterator pos, size_type n, param_value_type 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:
Note:
For iterator invalidation see the documentation. 
 iterator rinsert(iterator pos);
Insert a new element with the default value before the given position.
Postcondition:
value_type() will be inserted at the position pos.
If the circular buffer is full, the last (rightmost) element will be removed.
Returns:
iterator to the inserted element.
Throws:
Note:
For iterator invalidation see the documentation. 
 iterator rinsert(iterator pos, param_value_type item);
Insert an 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 last element (rightmost) will be removed.
Returns:
iterator to the inserted element.
Throws:
Note:
For iterator invalidation see the documentation. 
 void set_capacity(size_type new_capacity, bool remove_front = true);
Change the capacity of the circular buffer.
Parameters:
Postcondition:
(*this).capacity() == new_capacity
If the current number of elements stored in the circular buffer is greater than the desired new capacity then ((*this).size() - new_capacity) elements will be removed according to the remove_front parameter.
Throws:
Note:
For iterator invalidation see the documentation. 
 size_type size() const;
Return the number of elements currently stored in the circular buffer. 
 void swap(circular_buffer& cb);
Swap the contents of two circular buffers.
Postcondition:
this contains elements of cb and vice versa.
Note:
For iterator invalidation see the documentation.

Standalone Functions

Semantics

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 overwritting (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 memory leak. One recommend alternative is the use of smart pointers [1]. (Any container of std::auto_ptr is considered particularly hazardous. [2])

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 front-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_DISABLE_CB_DEBUG macro.

Example

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

Notes

[1] A good implementation of smart pointers is included in Boost.

[2] 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

I would like to thank the Boost community for help when developing the circular_buffer.

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 and Nigel Stewart for valuable comments and ideas. And once again I want to thank Nigel Stewart for this document revision.