Templated Circular Buffer Container
+circular_buffer<T, Alloc>
+
+ Templated Circular Buffer Container+circular_buffer<T, Alloc>+ |
+ |
+
Synopsis
+ Rationale
+ Simple Example
+ Definition
+ Template Parameters
+ Members
+ Friend Functions
+ Model of
+ Type Requirements
+ Semantics
+ Caveats
+ Debug Support
+ Example
+ Notes
+ See also
+ Acknowledgments
+
 |
+ ||
+
|
+
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.)
+
A contiguous region of memory utilized as a circular buffer has several unique + and useful characteristics: +
+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:
+
std
+ containers and algorithms.
+ circular_buffer_space_optimized
+ is such an example of the adaptor.)
+ 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;
+ }
+
+ #include <boost/circular_buffer.hpp>
+
+ In fact the circular_buffer is defined in the file
+ boost/circular_buffer/base.hpp, but it is necessary to
+ include the boost/circular_buffer.hpp
+ in order to use this container. Also, there is a forward declaration for circular_buffer
+ in the header boost/circular_buffer_fwd.hpp.
+
| + 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 |
+
Refer the source code documentation for a + detailed description.
+| + Type | ++ Description |
|---|---|
value_type
+ |
+ The type of the elements stored in the circular buffer. + | +
allocator_type |
+ The type of the allocator used in the circular buffer. | +
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. + | +
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. A signed integral type used to represent the distance between + two iterators. + | +
size_type
+ |
+ Size type. An unsigned integral type that can represent any nonnegative value + of the container's distance type. + | +
| + Method + | ++ Description + | +
|---|---|
circular_buffer(size_type
+ capacity, const allocator_type& alloc = allocator_type())
+ |
+ Create an empty circular buffer with a given capacity. + | +
circular_buffer(size_type
+ capacity, const T& item, const allocator_type& alloc =
+ allocator_type())
+ |
+ Create a full circular buffer with a given capacity and filled with copies of
+ item.
+ |
+
circular_buffer(const
+ circular_buffer& cb)
+ |
+ Copy constructor. + | +
template<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. + | +
~circular_buffer()
+ |
+ Destructor. + | +
template<InputIterator>
+ assign(InputIterator first, InputIterator last)
+ |
+ Assign a copy of range. + | +
assign(size_type
+ n, const T& item)
+ |
+ Assign n items into the circular buffer.
+ |
+
push_back()
+ |
+ Insert a new element with the default value at the end. + | +
push_back(const
+ T& item)
+ |
+ Insert a new element at the end. + | +
push_front()
+ |
+ Inserts a new element with the default value at the start. + | +
push_front(const
+ T& item)
+ |
+ Insert a new element at the start. + | +
pop_back()
+ |
+ Remove the last (rightmost) element. + | +
pop_front()
+ |
+ Remove the first (left-most) element. + | +
front()*
+ |
+ Return the first (leftmost) element. + | +
back()*
+ |
+ Return the last (rightmost) element. + | +
at(size_type
+ index)*
+ |
+ Return the element at the index position.
+ |
+
operator[](size_type
+ index)*
+ |
+ Return the element at the index position.
+ |
+
data()
+ |
+ Return pointer to data stored in the circular buffer as a continuous array of + values. + | +
insert(iterator
+ pos)
+ |
+ Insert a new element with the default value before the given position. + | +
insert(iterator
+ pos, const T& item)
+ |
+ Insert the item before the given position.
+ |
+
insert(iterator
+ pos, size_type n, const T& item)
+ |
+ Insert n copies of the item before the given
+ position.
+ |
+
template<InputIterator>
+ insert(iterator pos, InputIterator first, InputIterator last)
+ |
+ Insert the range [first, last) before the given position.
+ |
+
rinsert(iterator
+ pos)
+ |
+ Insert a new element with the default value before the given position. + | +
rinsert(iterator
+ pos, const T& item)
+ |
+ Insert the item before the given position.
+ |
+
rinsert(iterator
+ pos, size_type n, const T& item)
+ |
+ Insert n copies of the item before the given
+ position.
+ |
+
template<InputIterator>
+ rinsert(iterator pos, InputIterator first, InputIterator last)
+ |
+ Insert the range [first, last) before the given position.
+ |
+
erase(iterator
+ pos)
+ |
+ Erase the element at the given position. + | +
erase(iterator
+ first, iterator last)
+ |
+ Erase the range [first, last).
+ |
+
clear()
+ |
+ Erase all the stored elements. + | +
empty() const
+ |
+ Is the circular buffer empty? + | +
full() const
+ |
+ Is the circular buffer full? + | +
size() const
+ |
+ Return the number of elements currently stored in the circular buffer. + | +
resize(size_type
+ new_size, param_value_type item = T(), bool remove_front = true)
+ |
+ Change the size of the circular buffer. + | +
max_size() const
+ |
+ Return the largest possible size (or capacity) of the circular buffer. + | +
capacity() const
+ |
+ Return the capacity of the circular buffer. + | +
set_capacity(size_type
+ new_capacity, bool remove_front = true)
+ |
+ Change the capacity of the circular buffer. + | +
begin()*
+ |
+ Return an iterator pointing to the beginning of the circular buffer. + | +
end()*
+ |
+ Return an iterator pointing to the end of the circular buffer. + | +
rbegin()*
+ |
+ Return a reverse iterator pointing to the beginning of the reversed circular + buffer. + | +
rend()*
+ |
+ Return a reverse iterator pointing to the end of the reversed circular buffer. + | +
get_allocator()*
+ |
+ Return the allocator. + | +
operator=(const
+ circular_buffer& cb)
+ |
+ Assignment operator. + | +
swap(circular_buffer&
+ cb)
+ |
+ Swap the contents of two circular buffers. + | +
const counterpart.
+ | + Method + | ++ Description + | +
|---|---|
operator<(const circular_buffer& lhs, const circular_buffer& rhs) |
+ Lexicographical comparison. | +
operator==(const circular_buffer& lhs, const circular_buffer& rhs)
+ |
+ Test two circular buffers for equality. + | +
Random Access + Container, + Front Insertion Sequence, + Back Insertion Sequence, + Assignable (SGI), + Equality Comparable, + LessThan Comparable (SGI) +
+T is CopyConstructible.
+ The behaviour of insertion for circular_buffer is as follows:
+
circular_buffer remains fixed unless adjusted
+ via set_capacity or resize.
+ insert
+ will overwrite front elements as necessary.
+ rinsert will overwrite back elements as necessary.
+ The behaviour of resizing a circular_buffer is as follows:
+
resize. (The
+ capacity can be only increased, not decreased.)
+ The behaviour of assigning to a circular_buffer is as follows:
+
assign. (The
+ capacity can be only increased, not decreased.)
+ The rules for iterator (and result of data())
+ invalidation for circular_buffer are as follows:
+
insert at the end of the circular_buffer (including
+ push_back) does not invalidate any iterator except the case the
+ iterator points to the overwritten element.
+ rinsert at the beginning of the circular_buffer (including
+ push_front) does not invalidate any iterator except the case
+ the iterator points to the overwritten element.
+ insert in the middle of the circular_buffer
+ invalidates iterators pointing to the elements at the insertion point and
+ behind the insertion point. It also invalidates iterators pointing to the
+ overwritten element(s).
+ rinsert in the middle of the circular_buffer
+ invalidates iterators pointing to the elements before the insertion point and
+ iterators pointing to the overwritten element(s).
+ erase at the end of the circular_buffer (including pop_back)
+ invalidates only iterators pointing to the erased element(s).
+ pop_front
+ invalidates only iterators pointing to the erased element.
+ erase at the beginning or in the middle of the circular_buffer
+ invalidates iterators pointing to the erased element(s) and iterators pointing
+ to the elements behind the erase point.
+ data, set_capacity, resize, operator=,
+ assign, swap and clear invalidate all
+ iterators pointing to the circular_buffer.
+ 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.
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.
+
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.
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);
+ int sum = std::accumulate(cb.begin(), cb.end(), 0); // evaluate sum
+
+ // 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 the circular_buffer can be inferred from
+ the assertions.
+
[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.)
+
boost::circular_buffer_space_optimized,
+ std::vector,
+ std::list, std::deque
+
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. +
+
+ circular_buffer_space_optimized<T, Alloc>+ |
+ |
+
Synopsis
+ Rationale
+ Definition
+ Template Parameters, Members and Friend
+ Functions
+ Model of
+ Type Requirements
+ Semantics
+ See also
+ Acknowledgments
+
The circular_buffer_space_optimized container is an adaptor of the
+ circular_buffer. The
+ functionality of the circular_buffer_space_optimized is similar to
+ the base circular_buffer except it does not allocate memory at
+ once when created rather it allocates memory as needed. (The predictive memory
+ allocation is similar to typical std::vector implementation.)
+ Moreover the memory is automatically freed as the size of the container
+ decreases.
+
| + |  |
+
| Figure: | +The memory allocation process of the space optimized circular
+ buffer. The min_capacity represents the minimal guaranteed amount
+ of allocated memory. The allocated memory will never drop under this value. By
+ default the min_capacity is set to 0.
+ |
+
The auto-resizing mode of the space optimized circular buffer can be useful in
+ situations when the container can possibly store large number of elements but
+ most of its lifetime the container stores just few of them. The usage of the circular_buffer_space_optimized
+ will result in decreased memory consumption and can improve the CPU cache
+ effectiveness.
+
#include <boost/circular_buffer.hpp>
+
In fact the circular_buffer_space_optimized is defined in the file
+ boost/circular_buffer/adaptor.hpp,
+ but it is necessary to include the boost/circular_buffer.hpp
+ in order to use this container. Also, there is a forward declaration for circular_buffer_space_optimized
+ in the header boost/circular_buffer_fwd.hpp.
+
Template parameters, members and friend functions of the circular_buffer_space_optimized
+ are almost the same as for the base circular_buffer. Refer the circular_buffer
+ documentation and also its
+ source code documentation for a detailed description.
+
The specific methods of the circular_buffer_space_optimized are
+ listed below.
+
| + Method + | ++ Description + | +
|---|---|
circular_buffer_space_optimized(size_type
+ capacity, size_type min_capacity = 0, const allocator_type& alloc =
+ allocator_type())
+ |
+ Create an empty space optimized circular buffer with a given capacity. + | +
circular_buffer_space_optimized
+ (size_type capacity, size_type min_capacity, const T& item, const
+ allocator_type& alloc = allocator_type())
+ |
+ Create a full space optimized circular buffer filled with copies of item.
+ |
+
template<InputIterator>
+ circular_buffer_space_optimized(size_type capacity, size_type
+ min_capacity, InputIterator first, InputIterator last, const
+ allocator_type& alloc = allocator_type())
+ |
+ Create a space optimized circular buffer with a copy of a range. + | +
min_capacity()
+ const
+ |
+ Return the minimal guaranteed amount of allocated memory. + | +
set_min_capacity()
+ |
+ Change the minimal guaranteed amount of allocated memory. + | +
Random Access + Container, + Front Insertion Sequence, + Back Insertion Sequence, + Assignable (SGI), + Equality Comparable, + LessThan Comparable (SGI) +
+T is CopyConstructible.
+ The behaviour of memory auto-resizing is as follows: +
+circular_buffer_space_optimized
+ is created.
+ circular_buffer_space_optimized
+ container is created the allocated memory reflects the size of the container.
+ push_back, push_front, insert and rinsert
+ will predictively increase the allocated memory if necessary. (The predictive
+ memory allocation is similar to std::vector.)
+ set_capacity, resize, assign, insert
+ (range or n items), rinsert (range or n items), erase
+ (range) and clear
+ will accommodate the allocated memory as necessary.
+ pop_back, pop_front, erase and clear
+ will predictively decrease the allocated memory.
+ The semantics of the circular_buffer_space_optimized then follows
+ the semantics of the base circular_buffer
+ except the invalidation rules.
+
The rule for iterator invalidation for circular_buffer_space_optimized
+ is as follows:
+
data, set_capacity, resize, operator=,
+ assign, swap, push_back, push_front,
+ pop_back, pop_front, insert, rinsert,
+ erase and clear invalidate all iterators pointing to
+ the circular_buffer_space_optimized.
+ boost::circular_buffer,
+ std::vector
+
The idea of the space optimized circular buffer has been introduced by Pavel + Vozenilek. +
+| Copyright © 2003-2004 Jan + Gaspar | + |
+ Generated by doxygen + $doxygenversion. | +