boost/circular_buffer
2
0
Fork 0
mirror of https://github.com/boostorg/circular_buffer.git synced 2026-01-31 08:02:15 +00:00
Code Issues Projects Releases Wiki Activity
Files
06fa553274a94a25d5d0f8debba5d3cc9eb6af62
circular_buffer/doc/circular_buffer.html
Jan Gaspar 38449949aa Documentation update. 
[SVN r2773]
2005-12-07 00:23:20 +00:00

2924 lines
109 KiB
HTML
Raw Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>Templated Circular Buffer Container</title>
</head>
<body bgcolor="#ffffff">
<table id="title" border="0">
<tr>
<td>
<h1>Templated Circular Buffer Container</h1>
<h1>circular_buffer&lt;T, Alloc&gt;</h1>
</td>
<td>
<a href="../../../"><img src="../../../boost.png" width="277" height="86" border="0" alt="Boost"></a>
</td>
</tr>
</table>
<h2>Contents</h2>
<a href="#description">Description</a><br>
<a href="#simpleexample">Simple Example</a><br>
<a href="#rationale">Rationale</a><br>
<a href="#synopsis">Synopsis</a><br>
<a href="#header">Header Files</a><br>
<a href="#model">Modeled Concepts</a><br>
<a href="#parameters">Template Parameters</a><br>
<a href="#types">Public Types</a><br>
<a href="#constructors">Constructors and Destructor</a><br>
<a href="#methods">Public Member Functions</a><br>
<a href="#functions">Standalone Functions</a><br>
<a href="#semantics">Semantics</a><br>
<a href="#caveats">Caveats</a><br>
<a href="#debug">Debug Support</a><br>
<a href="#example">Example</a><br>
<a href="#notes">Notes</a><br>
<a href="#see">See also</a><br>
<a href="#ack">Acknowledgments</a>
<table id="table_figure" align="right" border="0">
<tr>
<td>
<img src="circular_buffer.png" width="300" height="332" alt="Circular Buffer">
</td>
</tr>
<tr>
<td width="300">
<table id="table_figure_desc" cellpadding="5" align="right" border="0">
<tr>
<td valign="top"><b>Figure:</b></td>
<td valign="top">The circular buffer (for someone known as <i>ring</i> or <i>cyclic buffer</i>).</td>
</tr>
</table>
</td>
</tr>
</table>
<h2><a name="description">Description</a></h2>
<p>
In general the term <i>circular buffer</i> 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. <a
href="#1">[1]</a> (Also see the Figure.)
</p>
<p>
The <code>circular_buffer</code> is a STL compliant container. It is a kind of
sequence that, like <code>std::vector</code> or <code>std::deque</code>,
supports random access iterators. In addition, it supports constant time insert
and erase operations at the beginning or the end of the buffer. The
<code>circular_buffer</code> is specially 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.
<p>
There are also several container adaptors which are bundled with the
<code>circular_buffer</code>:<br>
TODO<br>
The <code> circular_buffer </code> 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 <code><a
href="circular_buffer_space_optimized.html">circular_buffer_space_optimized</a>
</code> available. It is an adaptor of the <code> circular_buffer </code> which
does not allocate memory at once when created rather it allocates memory as
needed.
</p>
<h2>
<a name="simpleexample">Simple Example</a>
</h2>
<p>
A brief example using the
<code>
circular_buffer
</code>
:
</p>
<pre>
#include &lt;boost/circular_buffer.hpp&gt;
int main(int argc, char* argv[]) {
// Create a circular buffer with a capacity for 3 integers.
boost::circular_buffer&lt;int&gt; 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;
}
</pre>
<h2>
<a name="rationale">Rationale</a>
</h2>
<p>
TODO motivation
The most likely usage of the <code>circular_buffer</code> is as a storage of
the most recently received samples, overwriting the oldest as new samples
arrive.
</p>
<p>
A contiguous region of memory utilized as a circular buffer has several unique
and useful characteristics:
</p>
<ol>
<li>
Fixed memory use and no implicit or unexpected memory allocation.
</li>
<li>
Fast constant-time insertion and removal of elements from the front and back.
</li>
<li>
Fast constant-time random access of elements.
</li>
<li>
Suitability for real-time and performance critical applications.</li>
</ol>
<p>
The
<code>
circular_buffer
</code>
container provides a similar interface to
<code>
std::vector
</code>,
<code>
std::deque
</code>
and
<code>
std::list
</code>
including
<code>
push
</code>,
<code>
pop
</code>,
<code>
insert
</code>,
<code>
erase
</code>, iterators and
compatibility with
<code>
std
</code>
algorithms.
</p>
<p>
The design of the
<code>
circular_buffer
</code>
container is guided by the
following principles:
</p>
<ol>
<li>Maximum
<em>
efficiency
</em>
for envisaged applications.
</li>
<li>Suitable for
<em>
general purpose
</em>
use.
</li>
<li>
<em>
Interoperable
</em>
with other
<code>
std
</code>
containers and algorithms.
</li>
<li>The behaviour of the buffer as
<em>
intuitive
</em>
as possible.
</li>
<li>Suitable for
<em>
specialization
</em>
by means of adaptors. (The
<code>
<a href="circular_buffer_space_optimized.html">circular_buffer_space_optimized</a>
</code>
is such an example of the adaptor.)
</li>
<li>Guarantee of (at least)
<em>
basic exception safety
</em>.</li>
</ol>
<h4>
<a name="threadsafety">Thread-Safety</a>
</h4>
<p>
Like all STL containers, also the circular_buffer is
<b>not thread-safe</b>.
E.g. if one thread writes to a
<code>
std::vector
</code>
and another reads from
it, the threads have to be synchronized. The same applies to threads
accessing the
<code>
circular_buffer
</code>.
</p>
<h4>Writing to a Full Buffer</h4>
<p>
There are several options how to cope with the case if a data source produces
more data than can fit in the buffer [link to wikipedia]:
</p>
<ul>
<li>
If possible, tell the data source to wait until there is room in the buffer.
</li>
<li>
If the latest data is the most important, write over the oldest data that has
not been read, and move the read pointer to the position of the oldest
remaining data.
</li>
<li>
If the oldest data is the most important, ignore new data from the source until
there is room again in the buffer.</li>
</ul>
<h4>Reading from an Empty Buffer</h4>
<p>
TODO
</p>
<h4>Iterator Invalidation</h4>
<p>
According to the STL container specification [link to container SGI STL] the
<code>
circular_buffer
</code>
provides several types of iterator. An iterator is usually considered to be
invalidated if an element, the iterator pointed to, had been removed or
overwritten by another element. The source documentation refers to this
definition of iterator invalidation and this definition is also enforced by the
Debug Support [link]. However, some applications utilizing
<code>
circular_buffer
</code>
may require less strict definition: an iterator is invalidated only if it
points to an uninitialized memory. Consider following example:
</p>
<pre> #include &lt;boost/circular_buffer.hpp&gt;
#include &lt;assert.h&gt;
int main(int argc, char* argv[]) {
boost::circular_buffer&lt;int&gt; cb(3);
cb.push_back(1);
cb.push_back(2);
cb.push_back(3);
boost::circular_buffer&lt;int&gt;::iterator it = cb.begin();
assert(*it == 1);
cb.push_back(4); // The iterator is still valid.
assert(*it == 4);
return 0;
}</pre>
<p>
TODO This example works only if the Debug Support is disabled otherwise the
code will produce a runtime error. [link how to disable debug support]
</p>
<h4>Overwrite Operation</h4>
<p>
There was a discussion what exactly "overwriting of an element" means. It can be
either a destruction of the original element and a consequent inplace
construction of a new element or it can be an assignment of a new element into
an old one.
</p>
<h4>Producer-Consumer Mode</h4>
<p>
It it misleading to claim that the
<code>
circular_buffer
</code>
can be used as a
<i>
bounded buffer</i>
in a producer-consumer mode. Similarly to the
<code>
circular_buffer
</code>
the bounded buffer has a fixed size, but it was primarily designed to be used
in the producer-consumer mode when one thread is writing to the buffer and
another is reading from it, which implies the bounded buffer is thread-safe. As
discussed in the
<a href="#threadsafety">Thread-Safety</a>
section the
<code>
circular_buffer
</code>
is not thread-safe which prevents the
<code>
circular_buffer
</code>
to be used
as a bounded buffer or at least to be used directly. It is of course possible
to write a wrapper or an adaptor which will then synchronize the read/write
access to the
<code>
circular_buffer
</code>.
</p>
<p>
Moreover the
<code>
circular_buffer
</code>
was designed to overwrite old elements
with new ones when its capacity is exhauted. Although this behaviour is very
useful it represents only one option how a bounded buffer can behave. E.g. when
a bounded buffer is full and one thread tries to push an element into it the
buffer suspends the thread until some other thread performs a pop operation.
Another example is that it can throw an overflow exception when the buffer is
full or an underflow exception when it is empty. Considering writing an adaptor
which would then serve as a bounded buffer, the
<code>
circular_buffer
</code>
does
not have to be always the best choice. The
<code>
circular_buffer
</code>
bears
an overhead for its "circular" behavior, so containers like
<code>
std::vector
</code>
or
<code>
std::deque
</code>
suit better if you do not require the bounded buffer
to be circular.
</p>
<h2>
<a name="synopsis">Synopsis</a>
</h2>
<div id="srcdoc_synopsis">
<table id="table_synopsis" border="0" cellpadding="10">
<tr>
<td>
<pre>
namespace boost {
template &lt;class <a href="#templateparam_T">T</a>, class <a href="#templateparam_Alloc">Alloc</a>&gt;
class circular_buffer
{
public:
   typedef Alloc <a href="#classboost_1_1circular__buffer_1w0">allocator_type</a>;
   typedef <i>implementation-defined</i> <a href="#classboost_1_1circular__buffer_1w1">array_range</a>;
   typedef <i>implementation-defined</i> <a href="#classboost_1_1circular__buffer_1w2">const_array_range</a>;
   typedef <i>implementation-defined</i> <a href="#classboost_1_1circular__buffer_1w3">const_iterator</a>;
   typedef typename Alloc::const_pointer <a href="#classboost_1_1circular__buffer_1w4">const_pointer</a>;
   typedef typename Alloc::const_reference <a href="#classboost_1_1circular__buffer_1w5">const_reference</a>;
   typedef <i>implementation-defined</i> <a href="#classboost_1_1circular__buffer_1w6">const_reverse_iterator</a>;
   typedef typename Alloc::difference_type <a href="#classboost_1_1circular__buffer_1w7">difference_type</a>;
   typedef <i>implementation-defined</i> <a href="#classboost_1_1circular__buffer_1w8">iterator</a>;
   typedef typename Alloc::pointer <a href="#classboost_1_1circular__buffer_1w10">pointer</a>;
   typedef typename Alloc::reference <a href="#classboost_1_1circular__buffer_1w11">reference</a>;
   typedef <i>implementation-defined</i> <a href="#classboost_1_1circular__buffer_1w13">reverse_iterator</a>;
   typedef typename Alloc::size_type <a href="#classboost_1_1circular__buffer_1w14">size_type</a>;
   typedef typename Alloc::value_type <a href="#classboost_1_1circular__buffer_1w15">value_type</a>;
   template &lt;class InputIterator&gt;
      <a href="#classboost_1_1circular__buffer_1a15">circular_buffer</a>(size_type capacity,
         InputIterator first, InputIterator last,
         const allocator_type&amp; alloc = allocator_type());
   template &lt;class InputIterator&gt;
      <a href="#classboost_1_1circular__buffer_1a16">circular_buffer</a>(InputIterator first,
         InputIterator last, const allocator_type&amp; alloc = allocator_type());
   template &lt;class InputIterator&gt;
      <a href="#classboost_1_1circular__buffer_1a17">circular_buffer</a>(size_type capacity, InputIterator first, InputIterator last);
   template &lt;class InputIterator&gt;
      <a href="#classboost_1_1circular__buffer_1a18">circular_buffer</a>(InputIterator first, InputIterator last);
   <a href="#classboost_1_1circular__buffer_1a19">circular_buffer</a>(const circular_buffer&lt;T,Alloc&gt;&amp; cb);
   <a href="#classboost_1_1circular__buffer_1a20">circular_buffer</a>(size_type capacity,
      size_type n, value_type item,
      const allocator_type&amp; alloc = allocator_type());
   <a href="#classboost_1_1circular__buffer_1a21">circular_buffer</a>(size_type n,
      value_type item, const allocator_type&amp; alloc = allocator_type());
   explicit <a href="#classboost_1_1circular__buffer_1a22">circular_buffer</a>(size_type capacity, const allocator_type&amp; alloc = allocator_type());
   explicit <a href="#classboost_1_1circular__buffer_1a23">circular_buffer</a>(const allocator_type&amp; alloc = allocator_type());
   <a href="#classboost_1_1circular__buffer_1a62">~circular_buffer</a>();
   const_array_range <a href="#classboost_1_1circular__buffer_1a0">array_one</a>() const;
   array_range <a href="#classboost_1_1circular__buffer_1a1">array_one</a>();
   const_array_range <a href="#classboost_1_1circular__buffer_1a2">array_two</a>() const;
   array_range <a href="#classboost_1_1circular__buffer_1a3">array_two</a>();
   template &lt;class InputIterator&gt;
      void <a href="#classboost_1_1circular__buffer_1a4">assign</a>(size_type capacity, InputIterator first, InputIterator last);
   template &lt;class InputIterator&gt;
      void <a href="#classboost_1_1circular__buffer_1a5">assign</a>(InputIterator first, InputIterator last);
   void <a href="#classboost_1_1circular__buffer_1a6">assign</a>(size_type capacity, size_type n, value_type item);
   void <a href="#classboost_1_1circular__buffer_1a7">assign</a>(size_type n, value_type item);
   value_type <a href="#classboost_1_1circular__buffer_1a8">at</a>(size_type index) const;
   reference <a href="#classboost_1_1circular__buffer_1a9">at</a>(size_type index);
   value_type <a href="#classboost_1_1circular__buffer_1a10">back</a>() const;
   reference <a href="#classboost_1_1circular__buffer_1a11">back</a>();
   const_iterator <a href="#classboost_1_1circular__buffer_1a12">begin</a>() const;
   iterator <a href="#classboost_1_1circular__buffer_1a13">begin</a>();
   size_type <a href="#classboost_1_1circular__buffer_1a14">capacity</a>() const;
   void <a href="#classboost_1_1circular__buffer_1a24">clear</a>();
   bool <a href="#classboost_1_1circular__buffer_1a25">empty</a>() const;
   const_iterator <a href="#classboost_1_1circular__buffer_1a26">end</a>() const;
   iterator <a href="#classboost_1_1circular__buffer_1a27">end</a>();
   iterator <a href="#classboost_1_1circular__buffer_1a28">erase</a>(iterator first, iterator last);
   iterator <a href="#classboost_1_1circular__buffer_1a29">erase</a>(iterator pos);
   value_type <a href="#classboost_1_1circular__buffer_1a30">front</a>() const;
   reference <a href="#classboost_1_1circular__buffer_1a31">front</a>();
   bool <a href="#classboost_1_1circular__buffer_1a32">full</a>() const;
   allocator_type&amp; <a href="#classboost_1_1circular__buffer_1a33">get_allocator</a>();
   allocator_type <a href="#classboost_1_1circular__buffer_1a34">get_allocator</a>() const;
   template &lt;class InputIterator&gt;
      void <a href="#classboost_1_1circular__buffer_1a35">insert</a>(iterator pos, InputIterator first, InputIterator last);
   void <a href="#classboost_1_1circular__buffer_1a36">insert</a>(iterator pos, size_type n, value_type item);
   iterator <a href="#classboost_1_1circular__buffer_1a37">insert</a>(iterator pos, value_type item = value_type());
   pointer <a href="#classboost_1_1circular__buffer_1a38">linearize</a>();
   size_type <a href="#classboost_1_1circular__buffer_1a39">max_size</a>() const;
   circular_buffer&lt;T,Alloc&gt;&amp; <a href="#classboost_1_1circular__buffer_1a40">operator=</a>(const circular_buffer&lt;T,Alloc&gt;&amp; cb);
   value_type <a href="#classboost_1_1circular__buffer_1a41">operator[]</a>(size_type index) const;
   reference <a href="#classboost_1_1circular__buffer_1a42">operator[]</a>(size_type index);
   void <a href="#classboost_1_1circular__buffer_1a43">pop_back</a>();
   void <a href="#classboost_1_1circular__buffer_1a44">pop_front</a>();
   void <a href="#classboost_1_1circular__buffer_1a45">push_back</a>(value_type item = value_type());
   void <a href="#classboost_1_1circular__buffer_1a46">push_front</a>(value_type item = value_type());
   const_reverse_iterator <a href="#classboost_1_1circular__buffer_1a47">rbegin</a>() const;
   reverse_iterator <a href="#classboost_1_1circular__buffer_1a48">rbegin</a>();
   const_reverse_iterator <a href="#classboost_1_1circular__buffer_1a49">rend</a>() const;
   reverse_iterator <a href="#classboost_1_1circular__buffer_1a50">rend</a>();
   iterator <a href="#classboost_1_1circular__buffer_1a51">rerase</a>(iterator first, iterator last);
   iterator <a href="#classboost_1_1circular__buffer_1a52">rerase</a>(iterator pos);
   void <a href="#classboost_1_1circular__buffer_1a53">resize</a>(size_type new_size, value_type item = value_type());
   template &lt;class InputIterator&gt;
      void <a href="#classboost_1_1circular__buffer_1a54">rinsert</a>(iterator pos, InputIterator first, InputIterator last);
   void <a href="#classboost_1_1circular__buffer_1a55">rinsert</a>(iterator pos, size_type n, value_type item);
   iterator <a href="#classboost_1_1circular__buffer_1a56">rinsert</a>(iterator pos, value_type item = value_type());
   void <a href="#classboost_1_1circular__buffer_1a57">rresize</a>(size_type new_size, value_type item = value_type());
   void <a href="#classboost_1_1circular__buffer_1a58">rset_capacity</a>(size_type new_capacity);
   void <a href="#classboost_1_1circular__buffer_1a59">set_capacity</a>(size_type new_capacity);
   size_type <a href="#classboost_1_1circular__buffer_1a60">size</a>() const;
   void <a href="#classboost_1_1circular__buffer_1a61">swap</a>(circular_buffer&lt;T,Alloc&gt;&amp; cb);
};
template &lt;class T, class Alloc&gt;
   bool <a href="#namespaceboost_1a2">operator!=</a>(const circular_buffer&lt;T,Alloc&gt;&amp; lhs, const circular_buffer&lt;T,Alloc&gt;&amp; rhs);
template &lt;class T, class Alloc&gt;
   bool <a href="#namespaceboost_1a1">operator&lt;</a>(const circular_buffer&lt;T,Alloc&gt;&amp; lhs, const circular_buffer&lt;T,Alloc&gt;&amp; rhs);
template &lt;class T, class Alloc&gt;
   bool <a href="#namespaceboost_1a4">operator&lt;=</a>(const circular_buffer&lt;T,Alloc&gt;&amp; lhs, const circular_buffer&lt;T,Alloc&gt;&amp; rhs);
template &lt;class T, class Alloc&gt;
   bool <a href="#namespaceboost_1a0">operator==</a>(const circular_buffer&lt;T,Alloc&gt;&amp; lhs, const circular_buffer&lt;T,Alloc&gt;&amp; rhs);
template &lt;class T, class Alloc&gt;
   bool <a href="#namespaceboost_1a3">operator&gt;</a>(const circular_buffer&lt;T,Alloc&gt;&amp; lhs, const circular_buffer&lt;T,Alloc&gt;&amp; rhs);
template &lt;class T, class Alloc&gt;
   bool <a href="#namespaceboost_1a5">operator&gt;=</a>(const circular_buffer&lt;T,Alloc&gt;&amp; lhs, const circular_buffer&lt;T,Alloc&gt;&amp; rhs);
template &lt;class T, class Alloc&gt;
   void <a href="#namespaceboost_1a6">swap</a>(circular_buffer&lt;T,Alloc&gt;&amp; lhs, circular_buffer&lt;T,Alloc&gt;&amp; rhs);
} // namespace boost
</pre>
</td>
</tr>
</table>
</div>
<h2>
<a name="header">Header Files</a>
</h2>
<p>
The
<code>
circular_buffer
</code>
is defined in the file
<code>
<a href="../../../boost/circular_buffer.hpp">boost/circular_buffer.hpp</a>
</code>. There is also a forward
declaration for the
<code>
circular_buffer
</code>
in the header file
<code>
<a href="../../../boost/circular_buffer_fwd.hpp">boost/circular_buffer_fwd.hpp</a>
</code>.
</p>
<h2>
<a name="model">Modeled Concepts</a>
</h2>
<p>
<a href="http://www.sgi.com/tech/stl/RandomAccessContainer.html">
Random AccessContainer</a>,
<a href="http://www.sgi.com/tech/stl/FrontInsertionSequence.html">Front Insertion Sequence</a>,
<a href="http://www.sgi.com/tech/stl/BackInsertionSequence.html">Back Insertion Sequence</a>,
<a href="http://www.sgi.com/tech/stl/Assignable.html">Assignable</a>
(SGI specific),
<a href="http://www.sgi.com/tech/stl/EqualityComparable.html">Equality Comparable</a>,
<a href="http://www.sgi.com/tech/stl/LessThanComparable.html">LessThan Comparable</a>
(SGI specific)
</p>
<h2>
<a name="parameters">Template Parameters</a>
</h2>
<div id="srcdoc_params">
<table id="table_template_params" border="1">
<tr>
<th>Parameter</th>
<th>Description</th>
<th>Default</th>
</tr>
<tr>
<td>
<a name="templateparam_T">
<code>T</code>
</a>
</td>
<td>
The type of the elements stored in the circular buffer. </td>
<td> </td>
</tr>
<tr>
<td>
<a name="templateparam_Alloc">
<code>Alloc</code>
</a>
</td>
<td>
The allocator type used for all internal memory management. </td>
<td>
<code>std::allocator&lt;T&gt; </code>
</td>
</tr>
</table>
</div>
<br>
<h2>
<a name="types">Public Types</a>
</h2>
<div id="srcdoc_types">
<table id="table_public_types" border="1">
<tr>
<th>Type</th>
<th>Description</th>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1w0">
<code>allocator_type</code>
</a>
</td>
<td>
The type of the allocator used in the circular buffer. </td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1w1">
<code>array_range</code>
</a>
</td>
<td>
An array range. </td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1w2">
<code>const_array_range</code>
</a>
</td>
<td>
A range of a const array. </td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1w3">
<code>const_iterator</code>
</a>
</td>
<td>
Const (random access) iterator used to iterate through a circular buffer. </td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1w4">
<code>const_pointer</code>
</a>
</td>
<td>
Const pointer to the element. </td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1w5">
<code>const_reference</code>
</a>
</td>
<td>
Const reference to the element. </td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1w6">
<code>const_reverse_iterator</code>
</a>
</td>
<td>
Const iterator used to iterate backwards through a circular buffer. </td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1w7">
<code>difference_type</code>
</a>
</td>
<td>
Distance type. </td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1w8">
<code>iterator</code>
</a>
</td>
<td>
Iterator (random access) used to iterate through a circular buffer. </td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1w10">
<code>pointer</code>
</a>
</td>
<td>
Pointer to the element. </td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1w11">
<code>reference</code>
</a>
</td>
<td>
Reference to the element. </td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1w13">
<code>reverse_iterator</code>
</a>
</td>
<td>
Iterator used to iterate backwards through a circular buffer. </td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1w14">
<code>size_type</code>
</a>
</td>
<td>
Size type. </td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1w15">
<code>value_type</code>
</a>
</td>
<td>
The type of the elements stored in the circular buffer. </td>
</tr>
</table>
</div>
<h2>
<a name="constructors">Constructors and Destructor</a>
</h2>
<div id="srcdoc_constructors">
<table id="table_constructors" border="1">
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a15"></a>
<code>
<b>
template &lt;class InputIterator&gt;<br>   
circular_buffer(<a href="#classboost_1_1circular__buffer_1w14">size_type</a> capacity, <br>   
   InputIterator first, InputIterator last, <br>   
   const <a href="#classboost_1_1circular__buffer_1w0">allocator_type</a>&amp; alloc = allocator_type());</b>
</code>
<br>
<table id="table_function_desc_id4488374">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4488494"><tr><td>
Create a circular buffer with a copy of a range. </td></tr></table>
<table id="table_pre_desc_id4488505"><tr>
<td valign="top"><b>Precondition:</b></td>
<td>Valid range <code>[first, last)</code>. </td>
</tr></table>
<table id="table_post_desc_id4488515"><tr>
<td valign="top"><b>Postcondition:</b></td>
<td>
<code>(*this).<a href="#classboost_1_1circular__buffer_1a14">capacity()</a> == capacity</code><br>
If the number of items to copy from the range <code>[first, last)</code> is greater than the specified <code>capacity</code> then only elements from the range <code>[last - capacity, last)</code> will be copied. </td>
</tr></table> </td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a16"></a>
<code>
<b>
template &lt;class InputIterator&gt;<br>   
circular_buffer(InputIterator first, <br>   
   InputIterator last, const <a href="#classboost_1_1circular__buffer_1w0">allocator_type</a>&amp; alloc = allocator_type());</b>
</code>
<br>
<table id="table_function_desc_id4488631">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4488734"><tr><td>
TODO doc. </td></tr></table>
</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a17"></a>
<code>
<b>
template &lt;class InputIterator&gt;<br>   
circular_buffer(<a href="#classboost_1_1circular__buffer_1w14">size_type</a> capacity, InputIterator first, InputIterator last);</b>
</code>
<br>
<table id="table_function_desc_id4488786">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4488875"><tr><td>
</td></tr></table>
</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a18"></a>
<code>
<b>
template &lt;class InputIterator&gt;<br>   
circular_buffer(InputIterator first, InputIterator last);</b>
</code>
<br>
<table id="table_function_desc_id4488923">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4488995"><tr><td>
</td></tr></table>
</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a19"></a>
<code>
<b>circular_buffer(const circular_buffer&lt;T,Alloc&gt;&amp; cb);</b>
</code>
<br>
<table id="table_function_desc_id4489043">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4489097"><tr><td>
Copy constructor. </td></tr></table>
<table id="table_post_desc_id4489107"><tr>
<td valign="top"><b>Postcondition:</b></td>
<td>
<code>*this == cb</code> </td>
</tr></table> </td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a20"></a>
<code>
<b>circular_buffer(<a href="#classboost_1_1circular__buffer_1w14">size_type</a> capacity, <br>   
<a href="#classboost_1_1circular__buffer_1w14">size_type</a> n, <a href="#classboost_1_1circular__buffer_1w15">value_type</a> item, <br>   
const <a href="#classboost_1_1circular__buffer_1w0">allocator_type</a>&amp; alloc = allocator_type());</b>
</code>
<br>
<table id="table_function_desc_id4489297">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4489412"><tr><td>
TODO doc. </td></tr></table>
</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a21"></a>
<code>
<b>circular_buffer(<a href="#classboost_1_1circular__buffer_1w14">size_type</a> n, <br>   
<a href="#classboost_1_1circular__buffer_1w15">value_type</a> item, const <a href="#classboost_1_1circular__buffer_1w0">allocator_type</a>&amp; alloc = allocator_type());</b>
</code>
<br>
<table id="table_function_desc_id4489487">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4489584"><tr><td>
Create a full circular buffer with a given capacity and filled with copies of <code>item</code>. </td></tr></table>
<table id="table_post_desc_id4489599"><tr>
<td valign="top"><b>Postcondition:</b></td>
<td>
<code><a href="#classboost_1_1circular__buffer_1a14">capacity()</a> == n &amp;&amp; <a href="#classboost_1_1circular__buffer_1a60">size()</a> == n &amp;&amp; (*this)[0] == (*this)[1] == ... == (*this)[n - 1] == item</code> </td>
</tr></table> </td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a22"></a>
<code>
<b>explicit circular_buffer(<a href="#classboost_1_1circular__buffer_1w14">size_type</a> capacity, const <a href="#classboost_1_1circular__buffer_1w0">allocator_type</a>&amp; alloc = allocator_type());</b>
</code>
<br>
<table id="table_function_desc_id4489721">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4489802"><tr><td>
Create an empty circular buffer with a given capacity. </td></tr></table>
<table id="table_post_desc_id4489813"><tr>
<td valign="top"><b>Postcondition:</b></td>
<td>
<code>(*this).<a href="#classboost_1_1circular__buffer_1a14">capacity()</a> == capacity &amp;&amp; (*this).size == 0</code> </td>
</tr></table> </td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a23"></a>
<code>
<b>explicit circular_buffer(const <a href="#classboost_1_1circular__buffer_1w0">allocator_type</a>&amp; alloc = allocator_type());</b>
</code>
<br>
<table id="table_function_desc_id4489912">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4489976"><tr><td>
Create an empty circular buffer with a maximum capacity. </td></tr></table>
<table id="table_post_desc_id4489987"><tr>
<td valign="top"><b>Postcondition:</b></td>
<td>
<code><a href="#classboost_1_1circular__buffer_1a14">capacity()</a> == <a href="#classboost_1_1circular__buffer_1a39">max_size()</a> &amp;&amp; <a href="#classboost_1_1circular__buffer_1a60">size()</a> == 0</code> </td>
</tr></table> </td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a62"></a>
<code>
<b>~circular_buffer();</b>
</code>
<br>
<table id="table_function_desc_id4500078">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4500112"><tr><td>
Destructor. </td></tr></table>
</td>
</tr>
</table>
</td>
</tr>
</table>
</div>
<h2>
<a name="methods">Public Member Functions</a>
</h2>
<div id="srcdoc_methods">
<table id="table_methods" border="1">
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a0"></a>
<code>
<b><a href="#classboost_1_1circular__buffer_1w2">const_array_range</a> array_one() const;</b>
</code>
<br>
<table id="table_function_desc_id4486022">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4486063"><tr><td>
TODO doc. </td></tr></table>
</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a1"></a>
<code>
<b><a href="#classboost_1_1circular__buffer_1w1">array_range</a> array_one();</b>
</code>
<br>
<table id="table_function_desc_id4486137">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4486177"><tr><td>
TODO doc. </td></tr></table>
</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a2"></a>
<code>
<b><a href="#classboost_1_1circular__buffer_1w2">const_array_range</a> array_two() const;</b>
</code>
<br>
<table id="table_function_desc_id4486249">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4486290"><tr><td>
TODO doc. </td></tr></table>
</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a3"></a>
<code>
<b><a href="#classboost_1_1circular__buffer_1w1">array_range</a> array_two();</b>
</code>
<br>
<table id="table_function_desc_id4486362">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4486403"><tr><td>
TODO doc. </td></tr></table>
</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a4"></a>
<code>
<b>
template &lt;class InputIterator&gt;<br>   
void assign(<a href="#classboost_1_1circular__buffer_1w14">size_type</a> capacity, InputIterator first, InputIterator last);</b>
</code>
<br>
<table id="table_function_desc_id4486474">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4486563"><tr><td>
TODO doc. </td></tr></table>
</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a5"></a>
<code>
<b>
template &lt;class InputIterator&gt;<br>   
void assign(InputIterator first, InputIterator last);</b>
</code>
<br>
<table id="table_function_desc_id4486603">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4486682"><tr><td>
Assign a copy of range. </td></tr></table>
<table id="table_pre_desc_id4486692"><tr>
<td valign="top"><b>Precondition:</b></td>
<td>Valid range <code>[first, last)</code>. </td>
</tr></table>
<table id="table_post_desc_id4486703"><tr>
<td valign="top"><b>Postcondition:</b></td>
<td>
<code>(*this).<a href="#classboost_1_1circular__buffer_1a14">capacity()</a> == std::distance(first, last) &amp;&amp; (*this).<a href="#classboost_1_1circular__buffer_1a60">size()</a> == std::distance(first, last)</code> </td>
</tr></table>
<table id="table_note_desc_id4486774"><tr>
<td valign="top"><b>Note:</b></td>
<td>For iterator invalidation see the <a href="../circular_buffer.html#invalidation">documentation</a>. </td>
</tr></table> </td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a6"></a>
<code>
<b>void assign(<a href="#classboost_1_1circular__buffer_1w14">size_type</a> capacity, <a href="#classboost_1_1circular__buffer_1w14">size_type</a> n, <a href="#classboost_1_1circular__buffer_1w15">value_type</a> item);</b>
</code>
<br>
<table id="table_function_desc_id4486819">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4486902"><tr><td>
TODO doc. </td></tr></table>
</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a7"></a>
<code>
<b>void assign(<a href="#classboost_1_1circular__buffer_1w14">size_type</a> n, <a href="#classboost_1_1circular__buffer_1w15">value_type</a> item);</b>
</code>
<br>
<table id="table_function_desc_id4486953">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4487027"><tr><td>
Assign <code>n</code> items into the circular buffer. </td></tr></table>
<table id="table_post_desc_id4487040"><tr>
<td valign="top"><b>Postcondition:</b></td>
<td>
<code>(*this).<a href="#classboost_1_1circular__buffer_1a14">capacity()</a> == n &amp;&amp; (*this).<a href="#classboost_1_1circular__buffer_1a60">size()</a> == n &amp;&amp; (*this)[0] == (*this)[1] == ... == (*this).<a href="#classboost_1_1circular__buffer_1a11">back()</a> == item</code> </td>
</tr></table>
<table id="table_note_desc_id4487118"><tr>
<td valign="top"><b>Note:</b></td>
<td>For iterator invalidation see the <a href="../circular_buffer.html#invalidation">documentation</a>. </td>
</tr></table> </td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a8"></a>
<code>
<b><a href="#classboost_1_1circular__buffer_1w15">value_type</a> at(<a href="#classboost_1_1circular__buffer_1w14">size_type</a> index) const;</b>
</code>
<br>
<table id="table_function_desc_id4487187">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4487244"><tr><td>
Return the element at the <code>index</code> position. </td></tr></table>
</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a9"></a>
<code>
<b><a href="#classboost_1_1circular__buffer_1w11">reference</a> at(<a href="#classboost_1_1circular__buffer_1w14">size_type</a> index);</b>
</code>
<br>
<table id="table_function_desc_id4487316">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4487372"><tr><td>
Return the element at the <code>index</code> position. </td></tr></table>
</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a10"></a>
<code>
<b><a href="#classboost_1_1circular__buffer_1w15">value_type</a> back() const;</b>
</code>
<br>
<table id="table_function_desc_id4487444">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4487484"><tr><td>
Return the last (rightmost) element. </td></tr></table>
<table id="table_pre_desc_id4487494"><tr>
<td valign="top"><b>Precondition:</b></td>
<td>
<code>!*(this).<a href="#classboost_1_1circular__buffer_1a25">empty()</a></code> </td>
</tr></table> </td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a11"></a>
<code>
<b><a href="#classboost_1_1circular__buffer_1w11">reference</a> back();</b>
</code>
<br>
<table id="table_function_desc_id4487575">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4487615"><tr><td>
Return the last (rightmost) element. </td></tr></table>
<table id="table_pre_desc_id4487626"><tr>
<td valign="top"><b>Precondition:</b></td>
<td>
<code>!*(this).<a href="#classboost_1_1circular__buffer_1a25">empty()</a></code> </td>
</tr></table> </td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a12"></a>
<code>
<b><a href="#classboost_1_1circular__buffer_1w3">const_iterator</a> begin() const;</b>
</code>
<br>
<table id="table_function_desc_id4487707">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4487747"><tr><td>
Return a const iterator pointing to the beginning of the circular buffer. </td></tr></table>
</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a13"></a>
<code>
<b><a href="#classboost_1_1circular__buffer_1w8">iterator</a> begin();</b>
</code>
<br>
<table id="table_function_desc_id4487798">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4487838"><tr><td>
Return an iterator pointing to the beginning of the circular buffer. </td></tr></table>
</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a14"></a>
<code>
<b><a href="#classboost_1_1circular__buffer_1w14">size_type</a> capacity() const;</b>
</code>
<br>
<table id="table_function_desc_id4488113">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4488160"><tr><td>
Return the capacity of the circular buffer. </td></tr></table>
</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a24"></a>
<code>
<b>void clear();</b>
</code>
<br>
<table id="table_function_desc_id4490113">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4490154"><tr><td>
Erase all stored elements. </td></tr></table>
<table id="table_post_desc_id4490164"><tr>
<td valign="top"><b>Postcondition:</b></td>
<td>(*this).<a href="#classboost_1_1circular__buffer_1a60">size()</a> == 0 </td>
</tr></table>
<table id="table_note_desc_id4490180"><tr>
<td valign="top"><b>Note:</b></td>
<td>For iterator invalidation see the <a href="../circular_buffer.html#invalidation">documentation</a>. </td>
</tr></table> </td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a25"></a>
<code>
<b>bool empty() const;</b>
</code>
<br>
<table id="table_function_desc_id4490251">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4490286"><tr><td>
Is the circular buffer empty? </td></tr></table>
<table id="table_return_desc_id4490296"><tr>
<td valign="top"><b>Returns:</b></td>
<td>
<code>true</code> if there are no elements stored in the circular buffer. <code>false</code> otherwise. </td>
</tr></table> </td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a26"></a>
<code>
<b><a href="#classboost_1_1circular__buffer_1w3">const_iterator</a> end() const;</b>
</code>
<br>
<table id="table_function_desc_id4490712">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4490750"><tr><td>
Return a const iterator pointing to the end of the circular buffer. </td></tr></table>
</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a27"></a>
<code>
<b><a href="#classboost_1_1circular__buffer_1w8">iterator</a> end();</b>
</code>
<br>
<table id="table_function_desc_id4490776">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4490815"><tr><td>
Return an iterator pointing to the end of the circular buffer. </td></tr></table>
</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a28"></a>
<code>
<b><a href="#classboost_1_1circular__buffer_1w8">iterator</a> erase(<a href="#classboost_1_1circular__buffer_1w8">iterator</a> first, <a href="#classboost_1_1circular__buffer_1w8">iterator</a> last);</b>
</code>
<br>
<table id="table_function_desc_id4491003">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4491082"><tr><td>
Erase the range <code>[first, last)</code>. </td></tr></table>
<table id="table_pre_desc_id4491096"><tr>
<td valign="top"><b>Precondition:</b></td>
<td>Valid range <code>[first, last)</code>. <code>size_type old_size = (*this).<a href="#classboost_1_1circular__buffer_1a60">size()</a></code> </td>
</tr></table>
<table id="table_post_desc_id4491119"><tr>
<td valign="top"><b>Postcondition:</b></td>
<td>
<code>(*this).<a href="#classboost_1_1circular__buffer_1a60">size()</a> == old_size - std::distance(first, last)</code><br>
Removes the elements from the range <code>[first, last)</code>. </td>
</tr></table>
<table id="table_return_desc_id4491142"><tr>
<td valign="top"><b>Returns:</b></td>
<td>iterator to the first element remaining beyond the removed element or <code>(*this).<a href="#classboost_1_1circular__buffer_1a27">end()</a></code> if no such element exists. </td>
</tr></table>
<table id="table_note_desc_id4491162"><tr>
<td valign="top"><b>Note:</b></td>
<td>For iterator invalidation see the <a href="../circular_buffer.html#invalidation">documentation</a>. </td>
</tr></table> </td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a29"></a>
<code>
<b><a href="#classboost_1_1circular__buffer_1w8">iterator</a> erase(<a href="#classboost_1_1circular__buffer_1w8">iterator</a> pos);</b>
</code>
<br>
<table id="table_function_desc_id4491270">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4491333"><tr><td>
Erase the element at the given position. </td></tr></table>
<table id="table_pre_desc_id4491344"><tr>
<td valign="top"><b>Precondition:</b></td>
<td>Valid <code>pos</code> iterator. <code>size_type old_size = (*this).<a href="#classboost_1_1circular__buffer_1a60">size()</a></code> </td>
</tr></table>
<table id="table_post_desc_id4491366"><tr>
<td valign="top"><b>Postcondition:</b></td>
<td>
<code>(*this).<a href="#classboost_1_1circular__buffer_1a60">size()</a> == old_size - 1</code><br>
Removes an element at the position <code>pos</code>. </td>
</tr></table>
<table id="table_return_desc_id4491389"><tr>
<td valign="top"><b>Returns:</b></td>
<td>iterator to the first element remaining beyond the removed element or <code>(*this).<a href="#classboost_1_1circular__buffer_1a27">end()</a></code> if no such element exists. </td>
</tr></table>
<table id="table_note_desc_id4491408"><tr>
<td valign="top"><b>Note:</b></td>
<td>For iterator invalidation see the <a href="../circular_buffer.html#invalidation">documentation</a>. </td>
</tr></table> </td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a30"></a>
<code>
<b><a href="#classboost_1_1circular__buffer_1w15">value_type</a> front() const;</b>
</code>
<br>
<table id="table_function_desc_id4491556">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4491597"><tr><td>
Return the first (leftmost) element. </td></tr></table>
<table id="table_pre_desc_id4491608"><tr>
<td valign="top"><b>Precondition:</b></td>
<td>
<code>!*(this).<a href="#classboost_1_1circular__buffer_1a25">empty()</a></code> </td>
</tr></table> </td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a31"></a>
<code>
<b><a href="#classboost_1_1circular__buffer_1w11">reference</a> front();</b>
</code>
<br>
<table id="table_function_desc_id4490427">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4490468"><tr><td>
Return the first (leftmost) element. </td></tr></table>
<table id="table_pre_desc_id4490478"><tr>
<td valign="top"><b>Precondition:</b></td>
<td>
<code>!*(this).<a href="#classboost_1_1circular__buffer_1a25">empty()</a></code> </td>
</tr></table> </td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a32"></a>
<code>
<b>bool full() const;</b>
</code>
<br>
<table id="table_function_desc_id4490536">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4490577"><tr><td>
Is the circular buffer full? </td></tr></table>
<table id="table_return_desc_id4490587"><tr>
<td valign="top"><b>Returns:</b></td>
<td>
<code>true</code> if the number of elements stored in the circular buffer equals the capacity of the circular buffer. <code>false</code> otherwise. </td>
</tr></table> </td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a33"></a>
<code>
<b><a href="#classboost_1_1circular__buffer_1w0">allocator_type</a>&amp; get_allocator();</b>
</code>
<br>
<table id="table_function_desc_id4493876">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4493918"><tr><td>
Return the allocator. </td></tr></table>
<table id="table_note_desc_id4493929"><tr>
<td valign="top"><b>Note:</b></td>
<td>This method was added in order to optimize obtaining of the allocator with a state, although use of stateful allocators in STL is discouraged. </td>
</tr></table> </td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a34"></a>
<code>
<b><a href="#classboost_1_1circular__buffer_1w0">allocator_type</a> get_allocator() const;</b>
</code>
<br>
<table id="table_function_desc_id4493967">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4494008"><tr><td>
Return the allocator. </td></tr></table>
</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a35"></a>
<code>
<b>
template &lt;class InputIterator&gt;<br>   
void insert(<a href="#classboost_1_1circular__buffer_1w8">iterator</a> pos, InputIterator first, InputIterator last);</b>
</code>
<br>
<table id="table_function_desc_id4494059">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4494154"><tr><td>
Insert the range <code>[first, last)</code> before the given position. </td></tr></table>
<table id="table_pre_desc_id4494168"><tr>
<td valign="top"><b>Precondition:</b></td>
<td>Valid <code>pos</code> iterator and valid range <code>[first, last)</code>. </td>
</tr></table>
<table id="table_post_desc_id4494182"><tr>
<td valign="top"><b>Postcondition:</b></td>
<td>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).<code><br>
Example:<br>
array to insert: int array[] = { 5, 6, 7, 8, 9 };<br>
original circular buffer |1|2|3|4| | | - capacity: 6, size: 4<br>
position ---------------------^<br>
insert(position, array, array + 5);<br>
(If the operation won't preserve capacity, the buffer would look like this |1|2|5|6|7|8|9|3|4|)<br>
RESULTING circular buffer |6|7|8|9|3|4| - capacity: 6, size: 6</code> </td>
</tr></table>
<table id="table_note_desc_id4494259"><tr>
<td valign="top"><b>Note:</b></td>
<td>For iterator invalidation see the <a href="../circular_buffer.html#invalidation">documentation</a>. </td>
</tr></table> </td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a36"></a>
<code>
<b>void insert(<a href="#classboost_1_1circular__buffer_1w8">iterator</a> pos, <a href="#classboost_1_1circular__buffer_1w14">size_type</a> n, <a href="#classboost_1_1circular__buffer_1w15">value_type</a> item);</b>
</code>
<br>
<table id="table_function_desc_id4494303">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4494392"><tr><td>
Insert <code>n</code> copies of the item before the given position. </td></tr></table>
<table id="table_pre_desc_id4494406"><tr>
<td valign="top"><b>Precondition:</b></td>
<td>Valid <code>pos</code> iterator. </td>
</tr></table>
<table id="table_post_desc_id4494416"><tr>
<td valign="top"><b>Postcondition:</b></td>
<td>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 <code>n</code> elements will be inserted or both.<code><br>
Example:<br>
original circular buffer |1|2|3|4| | | - capacity: 6, size: 4<br>
position ---------------------^<br>
insert(position, (size_t)5, 6);<br>
(If the operation won't preserve capacity, the buffer would look like this |1|2|6|6|6|6|6|3|4|)<br>
RESULTING circular buffer |6|6|6|6|3|4| - capacity: 6, size: 6</code> </td>
</tr></table>
<table id="table_note_desc_id4494491"><tr>
<td valign="top"><b>Note:</b></td>
<td>For iterator invalidation see the <a href="../circular_buffer.html#invalidation">documentation</a>. </td>
</tr></table> </td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a37"></a>
<code>
<b><a href="#classboost_1_1circular__buffer_1w8">iterator</a> insert(<a href="#classboost_1_1circular__buffer_1w8">iterator</a> pos, <a href="#classboost_1_1circular__buffer_1w15">value_type</a> item = value_type());</b>
</code>
<br>
<table id="table_function_desc_id4494562">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4494652"><tr><td>
Insert the <code>item</code> before the given position. </td></tr></table>
<table id="table_pre_desc_id4494666"><tr>
<td valign="top"><b>Precondition:</b></td>
<td>Valid <code>pos</code> iterator. </td>
</tr></table>
<table id="table_post_desc_id4494676"><tr>
<td valign="top"><b>Postcondition:</b></td>
<td>The <code>item</code> will be inserted at the position <code>pos</code>.<br>
If the circular buffer is full, the first (leftmost) element will be removed. </td>
</tr></table>
<table id="table_return_desc_id4494694"><tr>
<td valign="top"><b>Returns:</b></td>
<td>iterator to the inserted element. </td>
</tr></table>
<table id="table_note_desc_id4494737"><tr>
<td valign="top"><b>Note:</b></td>
<td>For iterator invalidation see the <a href="../circular_buffer.html#invalidation">documentation</a>. </td>
</tr></table> </td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a38"></a>
<code>
<b><a href="#classboost_1_1circular__buffer_1w10">pointer</a> linearize();</b>
</code>
<br>
<table id="table_function_desc_id4494850">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4494890"><tr><td>
TODO doc - Return pointer to data stored in the circular buffer as a continuous array of values. </td></tr></table>
<table id="table_detailed_desc_id4494900"><tr><td>This method can be useful e.g. when passing the stored data into the legacy C API.
</td></tr></table>
<table id="table_post_desc_id4494904"><tr>
<td valign="top"><b>Postcondition:</b></td>
<td>
<code>&amp;(*this)[0] &lt; &amp;(*this)[1] &lt; ... &lt; &amp;(*this).<a href="#classboost_1_1circular__buffer_1a11">back()</a></code> </td>
</tr></table>
<table id="table_return_desc_id4494921"><tr>
<td valign="top"><b>Returns:</b></td>
<td>0 if empty. </td>
</tr></table>
<table id="table_note_desc_id4494964"><tr>
<td valign="top"><b>Note:</b></td>
<td>For iterator invalidation see the <a href="../circular_buffer.html#invalidation">documentation</a>. </td>
</tr></table> </td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a39"></a>
<code>
<b><a href="#classboost_1_1circular__buffer_1w14">size_type</a> max_size() const;</b>
</code>
<br>
<table id="table_function_desc_id4495145">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4495186"><tr><td>
Return the largest possible size (or capacity) of the circular buffer. </td></tr></table>
</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a40"></a>
<code>
<b>circular_buffer&lt;T,Alloc&gt;&amp; operator=(const circular_buffer&lt;T,Alloc&gt;&amp; cb);</b>
</code>
<br>
<table id="table_function_desc_id4495251">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4495314"><tr><td>
Assignment operator. </td></tr></table>
<table id="table_post_desc_id4495324"><tr>
<td valign="top"><b>Postcondition:</b></td>
<td>
<code>*this == cb</code> </td>
</tr></table>
<table id="table_note_desc_id4495373"><tr>
<td valign="top"><b>Note:</b></td>
<td>For iterator invalidation see the <a href="../circular_buffer.html#invalidation">documentation</a>. </td>
</tr></table> </td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a41"></a>
<code>
<b><a href="#classboost_1_1circular__buffer_1w15">value_type</a> operator[](<a href="#classboost_1_1circular__buffer_1w14">size_type</a> index) const;</b>
</code>
<br>
<table id="table_function_desc_id4495456">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4495520"><tr><td>
Return the element at the <code>index</code> position. </td></tr></table>
<table id="table_pre_desc_id4495534"><tr>
<td valign="top"><b>Precondition:</b></td>
<td>
<code>*(this).<a href="#classboost_1_1circular__buffer_1a60">size()</a> &gt; index</code> </td>
</tr></table> </td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a42"></a>
<code>
<b><a href="#classboost_1_1circular__buffer_1w11">reference</a> operator[](<a href="#classboost_1_1circular__buffer_1w14">size_type</a> index);</b>
</code>
<br>
<table id="table_function_desc_id4495608">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4495671"><tr><td>
Return the element at the <code>index</code> position. </td></tr></table>
<table id="table_pre_desc_id4495685"><tr>
<td valign="top"><b>Precondition:</b></td>
<td>
<code>*(this).<a href="#classboost_1_1circular__buffer_1a60">size()</a> &gt; index</code> </td>
</tr></table> </td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a43"></a>
<code>
<b>void pop_back();</b>
</code>
<br>
<table id="table_function_desc_id4495758">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4495799"><tr><td>
Remove the last (rightmost) element. </td></tr></table>
<table id="table_pre_desc_id4495809"><tr>
<td valign="top"><b>Precondition:</b></td>
<td>
<code>!*(this).<a href="#classboost_1_1circular__buffer_1a25">empty()</a></code> <code>iterator it = ((*this).<a href="#classboost_1_1circular__buffer_1a27">end()</a> - 1)</code> </td>
</tr></table>
<table id="table_post_desc_id4495839"><tr>
<td valign="top"><b>Postcondition:</b></td>
<td>
<code>((*this).<a href="#classboost_1_1circular__buffer_1a27">end()</a> - 1) != it</code> </td>
</tr></table>
<table id="table_note_desc_id4495856"><tr>
<td valign="top"><b>Note:</b></td>
<td>For iterator invalidation see the <a href="../circular_buffer.html#invalidation">documentation</a>. </td>
</tr></table> </td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a44"></a>
<code>
<b>void pop_front();</b>
</code>
<br>
<table id="table_function_desc_id4495951">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4495992"><tr><td>
Remove the first (leftmost) element. </td></tr></table>
<table id="table_pre_desc_id4496002"><tr>
<td valign="top"><b>Precondition:</b></td>
<td>
<code>!*(this).<a href="#classboost_1_1circular__buffer_1a25">empty()</a></code> <code>iterator it = (*this).<a href="#classboost_1_1circular__buffer_1a13">begin()</a></code> </td>
</tr></table>
<table id="table_post_desc_id4496030"><tr>
<td valign="top"><b>Postcondition:</b></td>
<td>
<code>(*this).<a href="#classboost_1_1circular__buffer_1a13">begin()</a> != it</code> </td>
</tr></table>
<table id="table_note_desc_id4496048"><tr>
<td valign="top"><b>Note:</b></td>
<td>For iterator invalidation see the <a href="../circular_buffer.html#invalidation">documentation</a>. </td>
</tr></table> </td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a45"></a>
<code>
<b>void push_back(<a href="#classboost_1_1circular__buffer_1w15">value_type</a> item = value_type());</b>
</code>
<br>
<table id="table_function_desc_id4496143">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4496211"><tr><td>
Insert a new element at the end. </td></tr></table>
<table id="table_post_desc_id4496221"><tr>
<td valign="top"><b>Postcondition:</b></td>
<td>
<code>(*this).<a href="#classboost_1_1circular__buffer_1a11">back()</a> == item</code><br>
If the circular buffer is full, the first (leftmost) element will be removed. </td>
</tr></table>
<table id="table_note_desc_id4496262"><tr>
<td valign="top"><b>Note:</b></td>
<td>For iterator invalidation see the <a href="../circular_buffer.html#invalidation">documentation</a>. </td>
</tr></table> </td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a46"></a>
<code>
<b>void push_front(<a href="#classboost_1_1circular__buffer_1w15">value_type</a> item = value_type());</b>
</code>
<br>
<table id="table_function_desc_id4496391">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4496459"><tr><td>
Insert a new element at the start. </td></tr></table>
<table id="table_post_desc_id4496469"><tr>
<td valign="top"><b>Postcondition:</b></td>
<td>
<code>(*this).<a href="#classboost_1_1circular__buffer_1a31">front()</a> == item</code><br>
If the circular buffer is full, the last (rightmost) element will be removed. </td>
</tr></table>
<table id="table_note_desc_id4496509"><tr>
<td valign="top"><b>Note:</b></td>
<td>For iterator invalidation see the <a href="../circular_buffer.html#invalidation">documentation</a>. </td>
</tr></table> </td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a47"></a>
<code>
<b><a href="#classboost_1_1circular__buffer_1w6">const_reverse_iterator</a> rbegin() const;</b>
</code>
<br>
<table id="table_function_desc_id4496652">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4496693"><tr><td>
Return a const reverse iterator pointing to the beginning of the reversed circular buffer. </td></tr></table>
</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a48"></a>
<code>
<b><a href="#classboost_1_1circular__buffer_1w13">reverse_iterator</a> rbegin();</b>
</code>
<br>
<table id="table_function_desc_id4496800">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4496841"><tr><td>
Return a reverse iterator pointing to the beginning of the reversed circular buffer. </td></tr></table>
</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a49"></a>
<code>
<b><a href="#classboost_1_1circular__buffer_1w6">const_reverse_iterator</a> rend() const;</b>
</code>
<br>
<table id="table_function_desc_id4496881">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4496922"><tr><td>
Return a const reverse iterator pointing to the end of the reversed circular buffer. </td></tr></table>
</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a50"></a>
<code>
<b><a href="#classboost_1_1circular__buffer_1w13">reverse_iterator</a> rend();</b>
</code>
<br>
<table id="table_function_desc_id4496962">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4497003"><tr><td>
Return a reverse iterator pointing to the end of the reversed circular buffer. </td></tr></table>
</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a51"></a>
<code>
<b><a href="#classboost_1_1circular__buffer_1w8">iterator</a> rerase(<a href="#classboost_1_1circular__buffer_1w8">iterator</a> first, <a href="#classboost_1_1circular__buffer_1w8">iterator</a> last);</b>
</code>
<br>
<table id="table_function_desc_id4497043">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4497122"><tr><td>
Erase the range <code>[first, last)</code>. </td></tr></table>
<table id="table_pre_desc_id4497136"><tr>
<td valign="top"><b>Precondition:</b></td>
<td>Valid range <code>[first, last)</code>. <code>size_type old_size = (*this).<a href="#classboost_1_1circular__buffer_1a60">size()</a></code> </td>
</tr></table>
<table id="table_post_desc_id4497158"><tr>
<td valign="top"><b>Postcondition:</b></td>
<td>
<code>(*this).<a href="#classboost_1_1circular__buffer_1a60">size()</a> == old_size - std::distance(first, last)</code><br>
Removes the elements from the range <code>[first, last)</code>. </td>
</tr></table>
<table id="table_return_desc_id4497182"><tr>
<td valign="top"><b>Returns:</b></td>
<td>iterator to the first element remaining in front of the removed element or <code>(*this).<a href="#classboost_1_1circular__buffer_1a13">begin()</a></code> if no such element exists. </td>
</tr></table>
<table id="table_note_desc_id4497201"><tr>
<td valign="top"><b>Note:</b></td>
<td>For iterator invalidation see the <a href="../circular_buffer.html#invalidation">documentation</a>. </td>
</tr></table> </td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a52"></a>
<code>
<b><a href="#classboost_1_1circular__buffer_1w8">iterator</a> rerase(<a href="#classboost_1_1circular__buffer_1w8">iterator</a> pos);</b>
</code>
<br>
<table id="table_function_desc_id4497338">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4497401"><tr><td>
Erase the element at the given position. </td></tr></table>
<table id="table_pre_desc_id4497411"><tr>
<td valign="top"><b>Precondition:</b></td>
<td>Valid <code>pos</code> iterator. <code>size_type old_size = (*this).<a href="#classboost_1_1circular__buffer_1a60">size()</a></code> </td>
</tr></table>
<table id="table_post_desc_id4497433"><tr>
<td valign="top"><b>Postcondition:</b></td>
<td>
<code>(*this).<a href="#classboost_1_1circular__buffer_1a60">size()</a> == old_size - 1</code><br>
Removes an element at the position <code>pos</code>. </td>
</tr></table>
<table id="table_return_desc_id4497456"><tr>
<td valign="top"><b>Returns:</b></td>
<td>iterator to the first element remaining in front of the removed element or <code>(*this).<a href="#classboost_1_1circular__buffer_1a13">begin()</a></code> if no such element exists. </td>
</tr></table>
<table id="table_note_desc_id4497476"><tr>
<td valign="top"><b>Note:</b></td>
<td>For iterator invalidation see the <a href="../circular_buffer.html#invalidation">documentation</a>. </td>
</tr></table> </td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a53"></a>
<code>
<b>void resize(<a href="#classboost_1_1circular__buffer_1w14">size_type</a> new_size, <a href="#classboost_1_1circular__buffer_1w15">value_type</a> item = value_type());</b>
</code>
<br>
<table id="table_function_desc_id4497598">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4497682"><tr><td>
Change the size of the circular buffer. </td></tr></table>
<table id="table_post_desc_id4497756"><tr>
<td valign="top"><b>Postcondition:</b></td>
<td>
<code>(*this).<a href="#classboost_1_1circular__buffer_1a60">size()</a> == new_size</code><br>
If the new size is greater than the current size, the rest of the circular buffer is filled with copies of <code>item</code>. In case the resulting size exceeds the current capacity the capacity is set to <code>new_size</code>. If the new size is lower than the current size then <code>((*this).<a href="#classboost_1_1circular__buffer_1a60">size()</a> - new_size)</code> elements will be removed according to the <code>remove_front</code> parameter. </td>
</tr></table>
<table id="table_note_desc_id4497843"><tr>
<td valign="top"><b>Note:</b></td>
<td>For iterator invalidation see the <a href="../circular_buffer.html#invalidation">documentation</a>. </td>
</tr></table> </td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a54"></a>
<code>
<b>
template &lt;class InputIterator&gt;<br>   
void rinsert(<a href="#classboost_1_1circular__buffer_1w8">iterator</a> pos, InputIterator first, InputIterator last);</b>
</code>
<br>
<table id="table_function_desc_id4497942">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4498037"><tr><td>
Insert the range <code>[first, last)</code> before the given position. </td></tr></table>
<table id="table_pre_desc_id4498051"><tr>
<td valign="top"><b>Precondition:</b></td>
<td>Valid <code>pos</code> iterator and valid range <code>[first, last)</code>. </td>
</tr></table>
<table id="table_post_desc_id4498065"><tr>
<td valign="top"><b>Postcondition:</b></td>
<td>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).<code><br>
Example:<br>
array to insert: int array[] = { 5, 6, 7, 8, 9 };<br>
original circular buffer |1|2|3|4| | | - capacity: 6, size: 4<br>
position ---------------------^<br>
insert(position, array, array + 5);<br>
(If the operation won't preserve capacity, the buffer would look like this |1|2|5|6|7|8|9|3|4|)<br>
RESULTING circular buffer |1|2|5|6|7|8| - capacity: 6, size: 6</code> </td>
</tr></table>
<table id="table_note_desc_id4498141"><tr>
<td valign="top"><b>Note:</b></td>
<td>For iterator invalidation see the <a href="../circular_buffer.html#invalidation">documentation</a>. </td>
</tr></table> </td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a55"></a>
<code>
<b>void rinsert(<a href="#classboost_1_1circular__buffer_1w8">iterator</a> pos, <a href="#classboost_1_1circular__buffer_1w14">size_type</a> n, <a href="#classboost_1_1circular__buffer_1w15">value_type</a> item);</b>
</code>
<br>
<table id="table_function_desc_id4498186">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4498275"><tr><td>
Insert <code>n</code> copies of the item before the given position. </td></tr></table>
<table id="table_pre_desc_id4498289"><tr>
<td valign="top"><b>Precondition:</b></td>
<td>Valid <code>pos</code> iterator. </td>
</tr></table>
<table id="table_post_desc_id4498299"><tr>
<td valign="top"><b>Postcondition:</b></td>
<td>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 <code>n</code> elements will be inserted or both.<code><br>
Example:<br>
original circular buffer |1|2|3|4| | | - capacity: 6, size: 4<br>
position ---------------------^<br>
insert(position, (size_t)5, 6);<br>
(If the operation won't preserve capacity, the buffer would look like this |1|2|6|6|6|6|6|3|4|)<br>
RESULTING circular buffer |1|2|6|6|6|6| - capacity: 6, size: 6</code> </td>
</tr></table>
<table id="table_note_desc_id4498373"><tr>
<td valign="top"><b>Note:</b></td>
<td>For iterator invalidation see the <a href="../circular_buffer.html#invalidation">documentation</a>. </td>
</tr></table> </td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a56"></a>
<code>
<b><a href="#classboost_1_1circular__buffer_1w8">iterator</a> rinsert(<a href="#classboost_1_1circular__buffer_1w8">iterator</a> pos, <a href="#classboost_1_1circular__buffer_1w15">value_type</a> item = value_type());</b>
</code>
<br>
<table id="table_function_desc_id4498418">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4498509"><tr><td>
Insert an <code>item</code> before the given position. </td></tr></table>
<table id="table_pre_desc_id4498523"><tr>
<td valign="top"><b>Precondition:</b></td>
<td>Valid <code>pos</code> iterator. </td>
</tr></table>
<table id="table_post_desc_id4498533"><tr>
<td valign="top"><b>Postcondition:</b></td>
<td>The <code>item</code> will be inserted before the position <code>pos</code>.<br>
If the circular buffer is full, the last element (rightmost) will be removed. </td>
</tr></table>
<table id="table_return_desc_id4498550"><tr>
<td valign="top"><b>Returns:</b></td>
<td>iterator to the inserted element. </td>
</tr></table>
<table id="table_note_desc_id4498594"><tr>
<td valign="top"><b>Note:</b></td>
<td>For iterator invalidation see the <a href="../circular_buffer.html#invalidation">documentation</a>. </td>
</tr></table> </td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a57"></a>
<code>
<b>void rresize(<a href="#classboost_1_1circular__buffer_1w14">size_type</a> new_size, <a href="#classboost_1_1circular__buffer_1w15">value_type</a> item = value_type());</b>
</code>
<br>
<table id="table_function_desc_id4498781">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4498865"><tr><td>
TODO doc. </td></tr></table>
</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a58"></a>
<code>
<b>void rset_capacity(<a href="#classboost_1_1circular__buffer_1w14">size_type</a> new_capacity);</b>
</code>
<br>
<table id="table_function_desc_id4498957">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4499015"><tr><td>
TODO doc. </td></tr></table>
</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a59"></a>
<code>
<b>void set_capacity(<a href="#classboost_1_1circular__buffer_1w14">size_type</a> new_capacity);</b>
</code>
<br>
<table id="table_function_desc_id4499132">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4499189"><tr><td>
Change the capacity of the circular buffer. </td></tr></table>
<table id="table_post_desc_id4499247"><tr>
<td valign="top"><b>Postcondition:</b></td>
<td>
<code>(*this).<a href="#classboost_1_1circular__buffer_1a14">capacity()</a> == new_capacity</code><br>
If the current number of elements stored in the circular buffer is greater than the desired new capacity then <code>((*this).<a href="#classboost_1_1circular__buffer_1a60">size()</a> - new_capacity)</code> elements will be removed according to the <code>remove_front</code> parameter. </td>
</tr></table>
<table id="table_note_desc_id4499325"><tr>
<td valign="top"><b>Note:</b></td>
<td>For iterator invalidation see the <a href="../circular_buffer.html#invalidation">documentation</a>. </td>
</tr></table> </td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a60"></a>
<code>
<b><a href="#classboost_1_1circular__buffer_1w14">size_type</a> size() const;</b>
</code>
<br>
<table id="table_function_desc_id4499463">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4499503"><tr><td>
Return the number of elements currently stored in the circular buffer. </td></tr></table>
</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="classboost_1_1circular__buffer_1a61"></a>
<code>
<b>void swap(circular_buffer&lt;T,Alloc&gt;&amp; cb);</b>
</code>
<br>
<table id="table_function_desc_id4499861">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4499913"><tr><td>
Swap the contents of two circular buffers. </td></tr></table>
<table id="table_post_desc_id4499924"><tr>
<td valign="top"><b>Postcondition:</b></td>
<td>
<code>this</code> contains elements of <code>cb</code> and vice versa. </td>
</tr></table>
<table id="table_note_desc_id4499937"><tr>
<td valign="top"><b>Note:</b></td>
<td>For iterator invalidation see the <a href="../circular_buffer.html#invalidation">documentation</a>. </td>
</tr></table> </td>
</tr>
</table>
</td>
</tr>
</table>
</div>
<h2>
<a name="functions">Standalone Functions</a>
</h2>
<div id="srcdoc_functions">
<table id="table_functions" border="1">
<tr>
<td>
<a name="namespaceboost_1a2"></a>
<code>
<b>
template &lt;class T, class Alloc&gt;<br>   
bool operator!=(const circular_buffer&lt;T,Alloc&gt;&amp; lhs, const circular_buffer&lt;T,Alloc&gt;&amp; rhs);</b>
</code>
<br>
<table id="table_function_desc_id4481602">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4481705"><tr><td>
Test two circular buffers for non-equality. </td></tr></table>
</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="namespaceboost_1a1"></a>
<code>
<b>
template &lt;class T, class Alloc&gt;<br>   
bool operator&lt;(const circular_buffer&lt;T,Alloc&gt;&amp; lhs, const circular_buffer&lt;T,Alloc&gt;&amp; rhs);</b>
</code>
<br>
<table id="table_function_desc_id4513411">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4513514"><tr><td>
Lexicographical comparison. </td></tr></table>
</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="namespaceboost_1a4"></a>
<code>
<b>
template &lt;class T, class Alloc&gt;<br>   
bool operator&lt;=(const circular_buffer&lt;T,Alloc&gt;&amp; lhs, const circular_buffer&lt;T,Alloc&gt;&amp; rhs);</b>
</code>
<br>
<table id="table_function_desc_id4513674">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4513778"><tr><td>
Lexicographical comparison. </td></tr></table>
</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="namespaceboost_1a0"></a>
<code>
<b>
template &lt;class T, class Alloc&gt;<br>   
bool operator==(const circular_buffer&lt;T,Alloc&gt;&amp; lhs, const circular_buffer&lt;T,Alloc&gt;&amp; rhs);</b>
</code>
<br>
<table id="table_function_desc_id4513938">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4514042"><tr><td>
Test two circular buffers for equality. </td></tr></table>
</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="namespaceboost_1a3"></a>
<code>
<b>
template &lt;class T, class Alloc&gt;<br>   
bool operator&gt;(const circular_buffer&lt;T,Alloc&gt;&amp; lhs, const circular_buffer&lt;T,Alloc&gt;&amp; rhs);</b>
</code>
<br>
<table id="table_function_desc_id4514215">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4514318"><tr><td>
Lexicographical comparison. </td></tr></table>
</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="namespaceboost_1a5"></a>
<code>
<b>
template &lt;class T, class Alloc&gt;<br>   
bool operator&gt;=(const circular_buffer&lt;T,Alloc&gt;&amp; lhs, const circular_buffer&lt;T,Alloc&gt;&amp; rhs);</b>
</code>
<br>
<table id="table_function_desc_id4514478">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4514582"><tr><td>
Lexicographical comparison. </td></tr></table>
</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<a name="namespaceboost_1a6"></a>
<code>
<b>
template &lt;class T, class Alloc&gt;<br>   
void swap(circular_buffer&lt;T,Alloc&gt;&amp; lhs, circular_buffer&lt;T,Alloc&gt;&amp; rhs);</b>
</code>
<br>
<table id="table_function_desc_id4514738">
<tr>
<td>   </td>
<td>
<table id="table_detailed_desc_id4514838"><tr><td>
Swap the contents of two circular buffers. </td></tr></table>
</td>
</tr>
</table>
</td>
</tr>
</table>
</div>
<h2>
<a name="semantics">Semantics</a>
</h2>
<p>
TODO remove this section
</p>
<p>
The behaviour of insertion for
<code>
circular_buffer
</code>
is as follows:
</p>
<ul>
<li>The capacity of a
<code>
circular_buffer
</code>
remains fixed unless adjusted
via
<code>
set_capacity
</code>
or
<code>
resize
</code>.
</li>
<li>
<code>
insert
</code>
will overwrite front elements as necessary.
</li>
<li>
<code>
rinsert
</code>
will overwrite back elements as necessary.</li>
</ul>
<p>
The behaviour of resizing a
<code>
circular_buffer
</code>
is as follows:
</p>
<ul>
<li>The capacity will be adjusted to accommodate a
<code>
resize
</code>. (The
capacity can be only increased, not decreased.)</li>
</ul>
<p>
The behaviour of assigning to a
<code>
circular_buffer
</code>
is as follows:
</p>
<ul>
<li>The capacity will be adjusted to accommodate an
<code>
assign
</code>. (The
capacity can be only increased, not decreased.)</li>
</ul>
<p>
<a name="invalidation"></a>
The rules for iterator (and result of
<code>
data()
</code>
)
invalidation for
<code>
circular_buffer
</code>
are as follows:
</p>
<ul>
<li>
<code>
insert
</code>
at the end of the
<code>
circular_buffer
</code>
(including
<code>
push_back
</code>
) does not invalidate any iterator except the case the
iterator points to the overwritten element.
</li>
<li>
<code>
rinsert
</code>
at the beginning of the
<code>
circular_buffer
</code>
(including
<code>
push_front
</code>
) does not invalidate any iterator except the case
the iterator points to the overwritten element.
</li>
<li>
<code>
insert
</code>
in the middle of the
<code>
circular_buffer
</code>
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).
</li>
<li>
<code>
rinsert
</code>
in the middle of the
<code>
circular_buffer
</code>
invalidates iterators pointing to the elements before the insertion point and
iterators pointing to the overwritten element(s).
</li>
<li>
<code>
erase
</code>
at the end of the
<code>
circular_buffer
</code>
(including
<code>
pop_back
</code>
)
invalidates only iterators pointing to the erased element(s).
</li>
<li>
<code>
pop_front
</code>
invalidates only iterators pointing to the erased element.
</li>
<li>
<code>
erase
</code>
at the beginning or in the middle of the
<code>
circular_buffer
</code>
invalidates iterators pointing to the erased element(s) and iterators pointing
to the elements behind the erase point.
</li>
<li>
<code>
data
</code>,
<code>
set_capacity
</code>,
<code>
resize
</code>,
<code>
operator=
</code>,
<code>
assign
</code>,
<code>
swap
</code>
and
<code>
clear
</code>
invalidate all
iterators pointing to the
<code>
circular_buffer
</code>.</li>
</ul>
<p>
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
<code>
circular_buffer
</code>
). They get
invalidated in that sense they do not point to the same element as before but
they do still point to the same
<b>valid</b>
place in the memory. If you want
to rely on this feature you have to turn of the
<a href="#debug">Debug Support</a>
otherwise an assertion will report an error if such invalidated iterator is
used.
</p>
<h2>
<a name="caveats">Caveats</a>
</h2>
<p>
The
<code>
circular_buffer
</code>
should not be used for storing pointers to
dynamically allocated objects. When a
<code>
circular_buffer
</code>
becomes
full, further insertion will overwrite the stored pointers - resulting in a
<b>
memoryleak</b>. One recommend alternative is the use of smart pointers
<a href="#2">[2]</a>.
(Any container of
<code>
std::auto_ptr
</code>
is considered particularly
hazardous.
<a href="#3">[3]</a>
)
</p>
<p>
Elements inserted near the front of a full
<code>
circular_buffer
</code>
can be
lost. According to the
<a href="#semantics">semantics</a>
of
<code>
insert
</code>,
insertion overwrites front-most items as necessary - possibly including
elements currently being
<b>inserted at the front</b>
of the buffer.
Conversely,
<code>
push_front
</code>
to a full
<code>
circular_buffer
</code>
is
guaranteed to overwrite the back-most element.
</p>
<p>
Elements inserted near the back of a full
<code>
circular_buffer
</code>
can be
lost. According to the
<a href="#semantics">semantics</a>
of
<code>
rinsert
</code>,
insertion overwrites front-most items as necessary - possibly including
elements currently being
<b>inserted at the back</b>
of the buffer. Conversely,
<code>
push_back
</code>
to a full
<code>
circular_buffer
</code>
is guaranteed to
overwrite the front-most element.
</p>
<p>
While internals of a
<code>
circular_buffer
</code>
are circular, iterators are
<b>not</b>.
Iterators of a
<code>
circular_buffer
</code>
are only valid for the range
<code>
[begin(),
end()]
</code>. E.g. iterators
<code>
(begin() - 1)
</code>
and
<code>
(end() + 1)
</code>
are invalid.
</p>
<h2>
<a name="debug">Debug Support</a>
</h2>
<p>
In order to help a programmer to avoid and find common bugs, the
<code>
circular_buffer
</code>
contains a kind of debug support.
</p>
<p>
The
<code>
circular_buffer
</code>
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 (
<a href="../../../libs/utility/assert.html">
<code>
BOOST_ASSERT
</code></a>
macros) which ensure the
<code>
circular_buffer
</code>
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.
</p>
<p>
Moreover, the uninitialized memory allocated by
<code>
circular_buffer
</code>
is
filled with the value
<code>
0xcc
</code>
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
<a href="../../../boost/circular_buffer/base.hpp">source code</a>.
</p>
<p>
The debug support is enabled only in the debug mode (when the
<code>
NDEBUG
</code>
is not defined). It can also be explicitly disabled by defining
<code>
BOOST_CB_DISABLE_DEBUG
</code>
macro.
</p>
<h2>
<a name="example">Example</a>
</h2>
<p>
The following example includes various usage of the
<code>
circular_buffer
</code>.
</p>
<pre> #include &lt;boost/circular_buffer.hpp&gt;
#include &lt;numeric&gt;
#include &lt;assert.h&gt;
int main(int argc, char* argv[])
{
// create a circular buffer of capacity 3
boost::circular_buffer&lt;int&gt; 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;
}
</pre>
<p>
The
<code>
circular_buffer
</code>
has a capacity of three
<code>
int
</code>.
Therefore, the size of the buffer will not exceed three. The
<code>
<a href="http://www.sgi.com/tech/stl/accumulate.html">accumulate</a>
</code>
algorithm evaluates the sum of the stored
elements. The semantics of the
<code>
circular_buffer
</code>
can be inferred
from the assertions.
</p>
<h2>
<a name="notes">Notes</a>
</h2>
<p>
<a name="1">[1]</a>
A detailed description can be found at <a href="http://en.wikipedia.org/wiki/Circular_buffer">Wikipedia</a>.
</p>
<p>
<a name="2">[2]</a>
A good implementation of smart pointers is included in
<a href="../../../libs/smart_ptr/">Boost</a>.
</p>
<p>
<a name="3">[3]</a>
Never create a circular buffer of
<code>
std::auto_ptr
</code>.
Refer to
<a href="http://www.aristeia.com">Scott Meyers</a>
' excellent book
<em>
Effective
STL
</em>
for a detailed discussion. (Meyers S.,
<i>
Effective STL: 50 SpecificWays to Improve Your Use of the Standard Template Library</i>.
Addison-Wesley, 2001.)
</p>
<h2>
<a name="see">See also</a>
</h2>
<p>
<code>
<a href="circular_buffer_space_optimized.html">boost::circular_buffer_space_optimized</a>,
<a href="http://www.sgi.com/tech/stl/Vector.html">std::vector</a>,
<a href="http://www.sgi.com/tech/stl/List.html">std::list</a>,
<a href="http://www.sgi.com/tech/stl/Deque.html">std::deque</a>
</code>
</p>
<h2>
<a name="ack">Acknowledgments</a>
</h2>
<p>
The
<code>
circular_buffer
</code>
has a short history. Its first version was a
<code>
std::deque
</code>
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.
</p>
<p>
The second version adapted
<code>
std::vector
</code>
but it has been abandoned
soon because of limited control over iterator invalidation.
</p>
<p>
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.
</p>
<hr align="left" size="1">
<table id="footer" width="100%" border="0">
<tr>
<td valign="top" align="left">
<small>Copyright © 2003-2005
<a href="mailto:jano_gaspar%5Bat%5Dyahoo.com">Jan Gaspar</a></small>
</td>
<td valign="top" align="right">
<a href="http://validator.w3.org/check?url=referer">
<img src="valid-html40.png" width="88" height="31" alt="Valid HTML 4.0!" border="0"></a>
</td>
</tr>
</table>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink