mirror of
https://github.com/boostorg/circular_buffer.git
synced 2026-01-29 19:32:16 +00:00
3495 lines
137 KiB
HTML
3495 lines
137 KiB
HTML
<!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>
|
||
<table id="title" border="0">
|
||
<tr>
|
||
<td>
|
||
<h1>
|
||
Templated Circular Buffer Container
|
||
</h1>
|
||
<h1>
|
||
circular_buffer<T, Alloc>
|
||
</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="#briefexample">Introductory Example</a> <br>
|
||
<a href="#synopsis">Synopsis</a> <br>
|
||
<a href="#rationale">Rationale</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="#examples">More Examples</a> <br>
|
||
<a href="#notes">Notes</a> <br>
|
||
<a href="#see">See also</a> <br>
|
||
<a href="#ack">Acknowledgments</a> <br>
|
||
|
||
<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><br>
|
||
|
||
<h2>
|
||
<a id="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="#note1">[1]</a> (Also see the Figure.)
|
||
</p>
|
||
<p>
|
||
The <code>circular_buffer</code> is a STL compliant container. It is a kind of sequence similar to
|
||
<code>std::vector</code> or <code>std::deque</code>. It supports random access iterators, constant time insert
|
||
and erase operations at the beginning or the end of the buffer and interoperability with <code>std</code>
|
||
algorithms. The <code>circular_buffer</code> is especially designed to provide fixed capacity storage. When its
|
||
capacity is exhausted, newly inserted elements will cause elements either at the beginning or end of the buffer
|
||
(depending on what insert operation is used) to be overwritten.
|
||
</p>
|
||
<p>
|
||
The <code>circular_buffer</code> only allocates memory when created, when the capacity is adjusted explicitly, or
|
||
as necessary to accommodate resizing or assign operations. On the other hand, there is also a <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><br>
|
||
|
||
<h2>
|
||
<a id="briefexample">Introductory Example</a>
|
||
</h2>
|
||
<p>
|
||
A brief example using the <code>circular_buffer</code>:
|
||
</p>
|
||
<pre>
|
||
#include <boost/circular_buffer.hpp>
|
||
|
||
int main(int /*argc*/, char* /*argv*/[]) {
|
||
|
||
// Create a circular buffer with a capacity for 3 integers.
|
||
boost::circular_buffer<int> cb(3);
|
||
|
||
// Insert some elements into the buffer.
|
||
cb.push_back(1);
|
||
cb.push_back(2);
|
||
cb.push_back(3);
|
||
|
||
int a = cb[0]; // a == 1
|
||
int b = cb[1]; // b == 2
|
||
int c = cb[2]; // c == 3
|
||
|
||
// The buffer is full now, pushing subsequent
|
||
// elements will overwrite the front-most elements.
|
||
|
||
cb.push_back(4); // Overwrite 1 with 4.
|
||
cb.push_back(5); // Overwrite 2 with 5.
|
||
|
||
// The buffer now contains 3, 4 and 5.
|
||
|
||
a = cb[0]; // a == 3
|
||
b = cb[1]; // b == 4
|
||
c = cb[2]; // c == 5
|
||
|
||
// Elements can be popped from either the front or the back.
|
||
|
||
cb.pop_back(); // 5 is removed.
|
||
cb.pop_front(); // 3 is removed.
|
||
|
||
int d = cb[0]; // d == 4
|
||
|
||
return 0;
|
||
}
|
||
</pre><br>
|
||
<h2>
|
||
<a id="synopsis">Synopsis</a>
|
||
</h2>
|
||
<div id="srcdoc_synopsis">
|
||
<table id="table_synopsis" border="0" cellpadding="10">
|
||
<tr>
|
||
<td>
|
||
<pre>
|
||
namespace boost {
|
||
|
||
template <class <a href="#templateparam_T">T</a>, class <a href="#templateparam_Alloc">Alloc</a>>
|
||
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 size_type <a href="#classboost_1_1circular__buffer_1w2">capacity_control</a>;
|
||
typedef <i>implementation-defined</i> <a href="#classboost_1_1circular__buffer_1w3">const_array_range</a>;
|
||
typedef <i>implementation-defined</i> <a href="#classboost_1_1circular__buffer_1w4">const_iterator</a>;
|
||
typedef typename Alloc::const_pointer <a href="#classboost_1_1circular__buffer_1w5">const_pointer</a>;
|
||
typedef typename Alloc::const_reference <a href="#classboost_1_1circular__buffer_1w6">const_reference</a>;
|
||
typedef <i>implementation-defined</i> <a href="#classboost_1_1circular__buffer_1w7">const_reverse_iterator</a>;
|
||
typedef typename Alloc::difference_type <a href="#classboost_1_1circular__buffer_1w8">difference_type</a>;
|
||
typedef <i>implementation-defined</i> <a href="#classboost_1_1circular__buffer_1w9">iterator</a>;
|
||
typedef typename Alloc::pointer <a href="#classboost_1_1circular__buffer_1w11">pointer</a>;
|
||
typedef typename Alloc::reference <a href="#classboost_1_1circular__buffer_1w12">reference</a>;
|
||
typedef <i>implementation-defined</i> <a href="#classboost_1_1circular__buffer_1w14">reverse_iterator</a>;
|
||
typedef typename Alloc::size_type <a href="#classboost_1_1circular__buffer_1w15">size_type</a>;
|
||
typedef typename Alloc::value_type <a href="#classboost_1_1circular__buffer_1w16">value_type</a>;
|
||
|
||
template <class InputIterator>
|
||
<a href="#classboost_1_1circular__buffer_1a15">circular_buffer</a>(size_type capacity,
|
||
InputIterator first, InputIterator last,
|
||
const allocator_type& alloc = allocator_type());
|
||
template <class InputIterator>
|
||
<a href="#classboost_1_1circular__buffer_1a16">circular_buffer</a>(InputIterator first,
|
||
InputIterator last, const allocator_type& alloc = allocator_type());
|
||
template <class InputIterator>
|
||
<a href=
|
||
"#classboost_1_1circular__buffer_1a17">circular_buffer</a>(size_type capacity, InputIterator first, InputIterator last);
|
||
template <class InputIterator>
|
||
<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<T,Alloc>& cb);
|
||
<a href="#classboost_1_1circular__buffer_1a20">circular_buffer</a>(size_type capacity,
|
||
size_type n, value_type item,
|
||
const allocator_type& alloc = allocator_type());
|
||
<a href="#classboost_1_1circular__buffer_1a21">circular_buffer</a>(size_type n,
|
||
value_type item, const allocator_type& alloc = allocator_type());
|
||
explicit <a href=
|
||
"#classboost_1_1circular__buffer_1a22">circular_buffer</a>(size_type capacity, const allocator_type& alloc = allocator_type());
|
||
explicit <a href=
|
||
"#classboost_1_1circular__buffer_1a23">circular_buffer</a>(const allocator_type& 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 <class InputIterator>
|
||
void <a href=
|
||
"#classboost_1_1circular__buffer_1a4">assign</a>(size_type capacity, InputIterator first, InputIterator last);
|
||
template <class InputIterator>
|
||
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& <a href="#classboost_1_1circular__buffer_1a33">get_allocator</a>();
|
||
allocator_type <a href="#classboost_1_1circular__buffer_1a34">get_allocator</a>() const;
|
||
template <class InputIterator>
|
||
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<T,Alloc>& <a href=
|
||
"#classboost_1_1circular__buffer_1a40">operator=</a>(const circular_buffer<T,Alloc>& 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 <class InputIterator>
|
||
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<T,Alloc>& cb);
|
||
};
|
||
|
||
template <class T, class Alloc>
|
||
bool <a href=
|
||
"#namespaceboost_1a2">operator!=</a>(const circular_buffer<T,Alloc>& lhs, const circular_buffer<T,Alloc>& rhs);
|
||
template <class T, class Alloc>
|
||
bool <a href=
|
||
"#namespaceboost_1a1">operator<</a>(const circular_buffer<T,Alloc>& lhs, const circular_buffer<T,Alloc>& rhs);
|
||
template <class T, class Alloc>
|
||
bool <a href=
|
||
"#namespaceboost_1a4">operator<=</a>(const circular_buffer<T,Alloc>& lhs, const circular_buffer<T,Alloc>& rhs);
|
||
template <class T, class Alloc>
|
||
bool <a href=
|
||
"#namespaceboost_1a0">operator==</a>(const circular_buffer<T,Alloc>& lhs, const circular_buffer<T,Alloc>& rhs);
|
||
template <class T, class Alloc>
|
||
bool <a href=
|
||
"#namespaceboost_1a3">operator></a>(const circular_buffer<T,Alloc>& lhs, const circular_buffer<T,Alloc>& rhs);
|
||
template <class T, class Alloc>
|
||
bool <a href=
|
||
"#namespaceboost_1a5">operator>=</a>(const circular_buffer<T,Alloc>& lhs, const circular_buffer<T,Alloc>& rhs);
|
||
template <class T, class Alloc>
|
||
void <a href=
|
||
"#namespaceboost_1a6">swap</a>(circular_buffer<T,Alloc>& lhs, circular_buffer<T,Alloc>& rhs);
|
||
|
||
} // namespace boost
|
||
</pre>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div><br>
|
||
<h2>
|
||
<a id="rationale">Rationale</a>
|
||
</h2>
|
||
<p>
|
||
The basic motivation behind the <code>circular_buffer</code> was to create a container which would work
|
||
seamlessly with STL. Additionally, the design of the <code>circular_buffer</code> was 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>
|
||
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>
|
||
Easy to <em>debug</em>. (See <a href="#debug">Debug Support</a> for details.)
|
||
</li>
|
||
</ol>
|
||
<p>
|
||
In order to achieve maximum efficiency, the <code>circular_buffer</code> stores its elements in a <em>contiguous
|
||
region of memory</em>, which then enables:
|
||
</p>
|
||
<ol>
|
||
<li>
|
||
Use of fixed memory 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>
|
||
Possible applications of the <code>circular_buffer</code> include:
|
||
</p>
|
||
<ul>
|
||
<li>
|
||
Storage of the most recently received samples, overwriting the oldest as new samples arrive.
|
||
</li>
|
||
<li>
|
||
As an underlying container for a <i>bounded buffer</i> (see the <a href="#boundedbuffer">Bounded Buffer
|
||
Example</a>).
|
||
</li>
|
||
<li>
|
||
A kind of cache storing a specified number of last inserted elements.
|
||
</li>
|
||
<li>
|
||
Efficient fixed capacity FIFO (First In, First Out) or LIFO (Last In, First Out) queue which removes the oldest
|
||
(inserted as first) elements when full.
|
||
</li>
|
||
</ul>
|
||
<p>
|
||
The following paragraphs describe issues that had to be considered during the implemenation of the
|
||
<code>circular_buffer</code>:
|
||
</p>
|
||
<h4>
|
||
<a id="threadsafety">Thread-Safety</a>
|
||
</h4>
|
||
<p>
|
||
The thread-safety of the <code>circular_buffer</code> is the same as the thread-safety of containers in most STL
|
||
implementations. This means the <code>circular_buffer</code> is thread-safe only in the sense that simultaneous
|
||
accesses to distinct instances of the <code>circular_buffer</code> are safe, and simultaneous read accesses to a
|
||
shared <code>circular_buffer</code> are safe.
|
||
</p>
|
||
<p>
|
||
If multiple threads access a single <code>circular_buffer</code>, and at least one of the threads may potentially
|
||
write, then the user is responsible for ensuring mutual exclusion between the threads during the container
|
||
accesses. The mutual exclusion between the threads can be achieved by wrapping operations of the underlying
|
||
<code>circular_buffer</code> with a lock acquisition and release. (See the <a href="#boundedbuffer">Bounded
|
||
Buffer Example</a>.)
|
||
</p>
|
||
<h4>
|
||
Overwrite Operation
|
||
</h4>
|
||
<p>
|
||
Overwrite operation occurs when an element is inserted into a full <code>circular_buffer</code> - the old element
|
||
is being overwriten by the new one. There was a discussion what exactly "overwriting of an element"
|
||
means during the formal review. It may be either a destruction of the original element and a consequent inplace
|
||
construction of a new element or it may be an assignment of a new element into an old one. The
|
||
<code>circular_buffer</code> implements <b>assignment</b> because it is more effective.
|
||
</p>
|
||
<p>
|
||
From the point of business logic of a stored element, the destruction/construction operation and assignment
|
||
usually mean the same. However, in very rare cases (if in any) they may differ. If there is a requirement for
|
||
elements to be destructed/constructed instead of being assigned, consider implementing a wrapper of the element
|
||
which would implement the assign operator, and store the wrappers instead. It is necessary to note that storing
|
||
such wrappers has a drawback. The destruction/construction will be invoked on every assignment of the wrapper -
|
||
not only when a wrapper is being overwritten (when the buffer is full) but also when the stored wrappers are
|
||
being shifted (e.g. as a result of insertion into the middle of container).
|
||
</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
|
||
fixed-sized buffer:
|
||
</p>
|
||
<ol>
|
||
<li>
|
||
Inform the data source to wait until there is room in the buffer (e.g. by throwing an overflow exception).
|
||
</li>
|
||
<li>
|
||
If the oldest data is the most important, ignore new data from the source until there is room in the buffer
|
||
again.
|
||
</li>
|
||
<li>
|
||
If the latest data is the most important, write over the oldest data.
|
||
</li>
|
||
<li>
|
||
Let the producer to be responsible for checking the size of the buffer prior writing into it.
|
||
</li>
|
||
</ol>
|
||
<p>
|
||
It is apparent that the <code>circular_buffer</code> implements the third option. But it may be less apparent it
|
||
<b>does not</b> implement any other option - especially the first two. One can get an impression that the
|
||
<code>circular_buffer</code> should implement first three options and offer a mechanism of choosing among them.
|
||
This impression is wrong. The <code>circular_buffer</code> was designed and optimized to be circular (which means
|
||
overwriting the oldest data when full). If such a controlling mechanism had been enabled, it would just
|
||
complicate the matters and the usage of the <code>circular_buffer</code> would be probably less straightforward.
|
||
</p>
|
||
<p>
|
||
Moreover, the first two options (and the fouth option as well) do not require the buffer to be circular at all.
|
||
If there is a need for the first or second option, consider implementing an adaptor of e.g.
|
||
<code>std::vector</code>. In this case the <code>circular_buffer</code> is not suitable for adapting, because, in
|
||
contrary to <code>std::vector</code>, it bears an overhead for its circular behavior.
|
||
</p>
|
||
<h4>
|
||
Reading/Removing from an Empty Buffer
|
||
</h4>
|
||
<p>
|
||
When reading or removing an element from an empty buffer, the buffer should be able to notify the data consumer
|
||
(e.g. by throwing underflow exception) that there are no elements stored in it. The <code>circular_buffer</code>
|
||
does not implement such a behaviour for two reasons:
|
||
</p>
|
||
<ol>
|
||
<li>
|
||
It would introduce performance overhead.
|
||
</li>
|
||
<li>
|
||
No other <code>std</code> container implements it this way.
|
||
</li>
|
||
</ol>
|
||
<p>
|
||
It is considered to be a bug to read or remove an element (e.g. by calling <code>front()</code> or
|
||
<code>pop_back()</code>) from an empty <code>std</code> container and from an emtpy <code>circular_buffer</code>
|
||
as well. The data consumer has to test if the container is not empty before reading/removing from it. However,
|
||
when reading from the <code>circular_buffer</code>, there is an option to rely on the <code>at()</code> method
|
||
which throws an exception when the index is out of range.
|
||
</p>
|
||
<h4>
|
||
Iterator Invalidation
|
||
</h4>
|
||
<p>
|
||
An iterator is usually considered to be invalidated if an element, the iterator pointed to, had been removed or
|
||
overwritten by an another element. This definition is enforced by the <a href="#debug">Debug Support</a> and
|
||
refered as <b>strict</b> in the source code documentation. However, some applications utilizing
|
||
<code>circular_buffer</code> may require less strict definition: an iterator is invalid only if it points to an
|
||
uninitialized memory. Consider following example:
|
||
</p>
|
||
<pre>
|
||
#define BOOST_CB_DISABLE_DEBUG // The Debug Support has to be disabled, otherwise the code produces a runtime error.
|
||
|
||
#include <boost/circular_buffer.hpp>
|
||
#include <assert.h>
|
||
|
||
int main(int /*argc*/, char* /*argv*/[]) {
|
||
|
||
boost::circular_buffer<int> cb(3);
|
||
|
||
cb.push_back(1);
|
||
cb.push_back(2);
|
||
cb.push_back(3);
|
||
|
||
boost::circular_buffer<int>::iterator it = cb.begin();
|
||
|
||
assert(*it == 1);
|
||
|
||
cb.push_back(4);
|
||
|
||
assert(*it == 4); // The iterator still points to the initialized memory.
|
||
|
||
return 0;
|
||
}
|
||
</pre>
|
||
<p>
|
||
The iterator does not point to the original element any more (and is considered to be invalid from the
|
||
"strict" point of view) but it still points to the same <em>valid</em> place in the memory. This
|
||
meaning of iterator invalidation is then marked as <b>loose</b> in the source code documentation.
|
||
</p>
|
||
<h2>
|
||
<a id="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><br>
|
||
|
||
<h2>
|
||
<a id="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> and <a href=
|
||
"http://www.sgi.com/tech/stl/BackInsertionSequence.html">Back Insertion Sequence</a>.
|
||
</p><br>
|
||
|
||
<h2>
|
||
<a id="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<T></code>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div><br>
|
||
|
||
<h2>
|
||
<a id="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. TODO - better doc.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<a name="classboost_1_1circular__buffer_1w2"><code>capacity_control</code></a>
|
||
</td>
|
||
<td>
|
||
Capacity type (defined just for consistency with circular_buffer_space_optimized).
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<a name="classboost_1_1circular__buffer_1w3"><code>const_array_range</code></a>
|
||
</td>
|
||
<td>
|
||
A range of a const array. TODO - better doc.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<a name="classboost_1_1circular__buffer_1w4"><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_1w5"><code>const_pointer</code></a>
|
||
</td>
|
||
<td>
|
||
Const pointer to the element.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<a name="classboost_1_1circular__buffer_1w6"><code>const_reference</code></a>
|
||
</td>
|
||
<td>
|
||
Const reference to the element.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<a name="classboost_1_1circular__buffer_1w7"><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_1w8"><code>difference_type</code></a>
|
||
</td>
|
||
<td>
|
||
Distance type.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<a name="classboost_1_1circular__buffer_1w9"><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_1w11"><code>pointer</code></a>
|
||
</td>
|
||
<td>
|
||
Pointer to the element.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<a name="classboost_1_1circular__buffer_1w12"><code>reference</code></a>
|
||
</td>
|
||
<td>
|
||
Reference to the element.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<a name="classboost_1_1circular__buffer_1w14"><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_1w15"><code>size_type</code></a>
|
||
</td>
|
||
<td>
|
||
Size type.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<a name="classboost_1_1circular__buffer_1w16"><code>value_type</code></a>
|
||
</td>
|
||
<td>
|
||
The type of the elements stored in the circular buffer.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div><br>
|
||
|
||
<h2>
|
||
<a id="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 <class InputIterator><br>
|
||
circular_buffer(<a href="#classboost_1_1circular__buffer_1w15">size_type</a> capacity,<br>
|
||
InputIterator first, InputIterator last,<br>
|
||
const <a href="#classboost_1_1circular__buffer_1w0">allocator_type</a>& alloc =
|
||
allocator_type());</b></code><br>
|
||
|
||
<table id="table_function_desc_id4488523">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4488644">
|
||
<tr>
|
||
<td>
|
||
Create a circular buffer with a copy of a range.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_pre_desc_id4488654">
|
||
<tr>
|
||
<td valign="top">
|
||
<b>Precondition:</b>
|
||
</td>
|
||
<td>
|
||
Valid range <code>[first, last)</code>.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_post_desc_id4488664">
|
||
<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 <class InputIterator><br>
|
||
circular_buffer(InputIterator first,<br>
|
||
InputIterator last, const <a href="#classboost_1_1circular__buffer_1w0">allocator_type</a>& alloc =
|
||
allocator_type());</b></code><br>
|
||
|
||
<table id="table_function_desc_id4488781">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4488884">
|
||
<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 <class InputIterator><br>
|
||
circular_buffer(<a href="#classboost_1_1circular__buffer_1w15">size_type</a> capacity, InputIterator
|
||
first, InputIterator last);</b></code><br>
|
||
|
||
<table id="table_function_desc_id4488935">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4489024">
|
||
<tr>
|
||
<td></td>
|
||
</tr>
|
||
</table>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<a name="classboost_1_1circular__buffer_1a18"></a> <code><b>template <class InputIterator><br>
|
||
circular_buffer(InputIterator first, InputIterator last);</b></code><br>
|
||
|
||
<table id="table_function_desc_id4489072">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4489145">
|
||
<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<T,Alloc>& cb);</b></code><br>
|
||
|
||
<table id="table_function_desc_id4489192">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4489246">
|
||
<tr>
|
||
<td>
|
||
Copy constructor.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_post_desc_id4489256">
|
||
<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_1w15">size_type</a> capacity,<br>
|
||
<a href="#classboost_1_1circular__buffer_1w15">size_type</a> n, <a href=
|
||
"#classboost_1_1circular__buffer_1w16">value_type</a> item,<br>
|
||
const <a href="#classboost_1_1circular__buffer_1w0">allocator_type</a>& alloc =
|
||
allocator_type());</b></code><br>
|
||
|
||
<table id="table_function_desc_id4489682">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4489791">
|
||
<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_1w15">size_type</a> n,<br>
|
||
<a href="#classboost_1_1circular__buffer_1w16">value_type</a> item, const <a href=
|
||
"#classboost_1_1circular__buffer_1w0">allocator_type</a>& alloc = allocator_type());</b></code><br>
|
||
|
||
<table id="table_function_desc_id4489864">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4489961">
|
||
<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_id4489975">
|
||
<tr>
|
||
<td valign="top">
|
||
<b>Postcondition:</b>
|
||
</td>
|
||
<td>
|
||
<code><a href="#classboost_1_1circular__buffer_1a14">capacity()</a> == n && <a href=
|
||
"#classboost_1_1circular__buffer_1a60">size()</a> == n && (*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_1w15">size_type</a> capacity, const <a href=
|
||
"#classboost_1_1circular__buffer_1w0">allocator_type</a>& alloc = allocator_type());</b></code><br>
|
||
|
||
<table id="table_function_desc_id4490097">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4490179">
|
||
<tr>
|
||
<td>
|
||
Create an empty circular buffer with a given capacity.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_post_desc_id4490189">
|
||
<tr>
|
||
<td valign="top">
|
||
<b>Postcondition:</b>
|
||
</td>
|
||
<td>
|
||
<code>(*this).<a href="#classboost_1_1circular__buffer_1a14">capacity()</a> == capacity
|
||
&& (*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>& alloc = allocator_type());</b></code><br>
|
||
|
||
<table id="table_function_desc_id4490287">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4490352">
|
||
<tr>
|
||
<td>
|
||
Create an empty circular buffer with a maximum capacity.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_post_desc_id4490362">
|
||
<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> && <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_id4498314">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4498348">
|
||
<tr>
|
||
<td>
|
||
Destructor.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div><br>
|
||
|
||
<h2>
|
||
<a id="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_1w3">const_array_range</a> array_one() const;</b></code><br>
|
||
|
||
<table id="table_function_desc_id4486171">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4486212">
|
||
<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_id4486285">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4486325">
|
||
<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_1w3">const_array_range</a> array_two() const;</b></code><br>
|
||
|
||
<table id="table_function_desc_id4486398">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4486438">
|
||
<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_id4486511">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4486551">
|
||
<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 <class InputIterator><br>
|
||
void assign(<a href="#classboost_1_1circular__buffer_1w15">size_type</a> capacity, InputIterator first,
|
||
InputIterator last);</b></code><br>
|
||
|
||
<table id="table_function_desc_id4486623">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4486712">
|
||
<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 <class InputIterator><br>
|
||
void assign(InputIterator first, InputIterator last);</b></code><br>
|
||
|
||
<table id="table_function_desc_id4486751">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4486830">
|
||
<tr>
|
||
<td>
|
||
Assign a copy of range.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_pre_desc_id4486840">
|
||
<tr>
|
||
<td valign="top">
|
||
<b>Precondition:</b>
|
||
</td>
|
||
<td>
|
||
Valid range <code>[first, last)</code>.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_post_desc_id4486851">
|
||
<tr>
|
||
<td valign="top">
|
||
<b>Postcondition:</b>
|
||
</td>
|
||
<td>
|
||
<code>(*this).<a href="#classboost_1_1circular__buffer_1a14">capacity()</a> ==
|
||
std::distance(first, last) && (*this).<a href=
|
||
"#classboost_1_1circular__buffer_1a60">size()</a> == std::distance(first, last)</code>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_note_desc_id4486922">
|
||
<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_1w15">size_type</a> capacity, <a href=
|
||
"#classboost_1_1circular__buffer_1w15">size_type</a> n, <a href=
|
||
"#classboost_1_1circular__buffer_1w16">value_type</a> item);</b></code><br>
|
||
|
||
<table id="table_function_desc_id4486966">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4487050">
|
||
<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_1w15">size_type</a> n, <a href=
|
||
"#classboost_1_1circular__buffer_1w16">value_type</a> item);</b></code><br>
|
||
|
||
<table id="table_function_desc_id4487100">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4487174">
|
||
<tr>
|
||
<td>
|
||
Assign <code>n</code> items into the circular buffer.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_post_desc_id4487188">
|
||
<tr>
|
||
<td valign="top">
|
||
<b>Postcondition:</b>
|
||
</td>
|
||
<td>
|
||
<code>(*this).<a href="#classboost_1_1circular__buffer_1a14">capacity()</a> == n &&
|
||
(*this).<a href="#classboost_1_1circular__buffer_1a60">size()</a> == n && (*this)[0] ==
|
||
(*this)[1] == ... == (*this).<a href="#classboost_1_1circular__buffer_1a11">back()</a> ==
|
||
item</code>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_note_desc_id4487265">
|
||
<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_1w16">value_type</a> at(<a href=
|
||
"#classboost_1_1circular__buffer_1w15">size_type</a> index) const;</b></code><br>
|
||
|
||
<table id="table_function_desc_id4487334">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4487391">
|
||
<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_1w12">reference</a> at(<a href=
|
||
"#classboost_1_1circular__buffer_1w15">size_type</a> index);</b></code><br>
|
||
|
||
<table id="table_function_desc_id4487463">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4487519">
|
||
<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_1w16">value_type</a> back() const;</b></code><br>
|
||
|
||
<table id="table_function_desc_id4487590">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4487631">
|
||
<tr>
|
||
<td>
|
||
Return the last (rightmost) element.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_pre_desc_id4487642">
|
||
<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_1w12">reference</a> back();</b></code><br>
|
||
|
||
<table id="table_function_desc_id4487722">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4487763">
|
||
<tr>
|
||
<td>
|
||
Return the last (rightmost) element.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_pre_desc_id4487773">
|
||
<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_1w4">const_iterator</a> begin() const;</b></code><br>
|
||
|
||
<table id="table_function_desc_id4487854">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4487895">
|
||
<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_1w9">iterator</a> begin();</b></code><br>
|
||
|
||
<table id="table_function_desc_id4487945">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4487985">
|
||
<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_1w15">size_type</a> capacity() const;</b></code><br>
|
||
|
||
<table id="table_function_desc_id4488261">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4488308">
|
||
<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_id4490489">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4490529">
|
||
<tr>
|
||
<td>
|
||
Erase all stored elements.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_post_desc_id4490540">
|
||
<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_id4490555">
|
||
<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_id4490627">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4490661">
|
||
<tr>
|
||
<td>
|
||
Is the circular buffer empty?
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_return_desc_id4490671">
|
||
<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_1w4">const_iterator</a> end() const;</b></code><br>
|
||
|
||
<table id="table_function_desc_id4490850">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4490891">
|
||
<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_1w9">iterator</a> end();</b></code><br>
|
||
|
||
<table id="table_function_desc_id4490918">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4490957">
|
||
<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_1w9">iterator</a> erase(<a href=
|
||
"#classboost_1_1circular__buffer_1w9">iterator</a> first, <a href=
|
||
"#classboost_1_1circular__buffer_1w9">iterator</a> last);</b></code><br>
|
||
|
||
<table id="table_function_desc_id4491149">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4491228">
|
||
<tr>
|
||
<td>
|
||
Erase the range <code>[first, last)</code>.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_pre_desc_id4491242">
|
||
<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_id4491265">
|
||
<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_id4491288">
|
||
<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_id4491308">
|
||
<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_1w9">iterator</a> erase(<a href=
|
||
"#classboost_1_1circular__buffer_1w9">iterator</a> pos);</b></code><br>
|
||
|
||
<table id="table_function_desc_id4491416">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4491479">
|
||
<tr>
|
||
<td>
|
||
Erase the element at the given position.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_pre_desc_id4491490">
|
||
<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_id4491512">
|
||
<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_id4491535">
|
||
<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_id4491554">
|
||
<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_1w16">value_type</a> front() const;</b></code><br>
|
||
|
||
<table id="table_function_desc_id4491702">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4491743">
|
||
<tr>
|
||
<td>
|
||
Return the first (leftmost) element.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_pre_desc_id4491754">
|
||
<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_1w12">reference</a> front();</b></code><br>
|
||
|
||
<table id="table_function_desc_id4491812">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4491852">
|
||
<tr>
|
||
<td>
|
||
Return the first (leftmost) element.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_pre_desc_id4491863">
|
||
<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_id4491921">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4491962">
|
||
<tr>
|
||
<td>
|
||
Is the circular buffer full?
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_return_desc_id4491972">
|
||
<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>& get_allocator();</b></code><br>
|
||
|
||
<table id="table_function_desc_id4492111">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4492153">
|
||
<tr>
|
||
<td>
|
||
Return the allocator.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_note_desc_id4492164">
|
||
<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_id4492202">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4492243">
|
||
<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 <class InputIterator><br>
|
||
void insert(<a href="#classboost_1_1circular__buffer_1w9">iterator</a> pos, InputIterator first,
|
||
InputIterator last);</b></code><br>
|
||
|
||
<table id="table_function_desc_id4492294">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4492389">
|
||
<tr>
|
||
<td>
|
||
Insert the range <code>[first, last)</code> before the given position.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_pre_desc_id4492403">
|
||
<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_id4492417">
|
||
<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_id4492494">
|
||
<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_1w9">iterator</a> pos, <a href=
|
||
"#classboost_1_1circular__buffer_1w15">size_type</a> n, <a href=
|
||
"#classboost_1_1circular__buffer_1w16">value_type</a> item);</b></code><br>
|
||
|
||
<table id="table_function_desc_id4492538">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4492627">
|
||
<tr>
|
||
<td>
|
||
Insert <code>n</code> copies of the item before the given position.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_pre_desc_id4492641">
|
||
<tr>
|
||
<td valign="top">
|
||
<b>Precondition:</b>
|
||
</td>
|
||
<td>
|
||
Valid <code>pos</code> iterator.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_post_desc_id4492651">
|
||
<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_id4492726">
|
||
<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_1w9">iterator</a> insert(<a href=
|
||
"#classboost_1_1circular__buffer_1w9">iterator</a> pos, <a href=
|
||
"#classboost_1_1circular__buffer_1w16">value_type</a> item = value_type());</b></code><br>
|
||
|
||
<table id="table_function_desc_id4492797">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4492887">
|
||
<tr>
|
||
<td>
|
||
Insert the <code>item</code> before the given position.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_pre_desc_id4492901">
|
||
<tr>
|
||
<td valign="top">
|
||
<b>Precondition:</b>
|
||
</td>
|
||
<td>
|
||
Valid <code>pos</code> iterator.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_post_desc_id4492911">
|
||
<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_id4492929">
|
||
<tr>
|
||
<td valign="top">
|
||
<b>Returns:</b>
|
||
</td>
|
||
<td>
|
||
iterator to the inserted element.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_note_desc_id4492973">
|
||
<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_1w11">pointer</a> linearize();</b></code><br>
|
||
|
||
<table id="table_function_desc_id4493085">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4493125">
|
||
<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_id4493136">
|
||
<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_id4493139">
|
||
<tr>
|
||
<td valign="top">
|
||
<b>Postcondition:</b>
|
||
</td>
|
||
<td>
|
||
<code>&(*this)[0] < &(*this)[1] < ... < &(*this).<a href=
|
||
"#classboost_1_1circular__buffer_1a11">back()</a></code>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_return_desc_id4493157">
|
||
<tr>
|
||
<td valign="top">
|
||
<b>Returns:</b>
|
||
</td>
|
||
<td>
|
||
0 if empty.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_note_desc_id4493200">
|
||
<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_1w15">size_type</a> max_size() const;</b></code><br>
|
||
|
||
<table id="table_function_desc_id4493381">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4493421">
|
||
<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<T,Alloc>&
|
||
operator=(const circular_buffer<T,Alloc>& cb);</b></code><br>
|
||
|
||
<table id="table_function_desc_id4493487">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4493549">
|
||
<tr>
|
||
<td>
|
||
Assignment operator.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_post_desc_id4493559">
|
||
<tr>
|
||
<td valign="top">
|
||
<b>Postcondition:</b>
|
||
</td>
|
||
<td>
|
||
<code>*this == cb</code>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_note_desc_id4493609">
|
||
<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_1w16">value_type</a> operator[](<a href=
|
||
"#classboost_1_1circular__buffer_1w15">size_type</a> index) const;</b></code><br>
|
||
|
||
<table id="table_function_desc_id4493693">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4493756">
|
||
<tr>
|
||
<td>
|
||
Return the element at the <code>index</code> position.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_pre_desc_id4493770">
|
||
<tr>
|
||
<td valign="top">
|
||
<b>Precondition:</b>
|
||
</td>
|
||
<td>
|
||
<code>*(this).<a href="#classboost_1_1circular__buffer_1a60">size()</a> > 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_1w12">reference</a> operator[](<a href=
|
||
"#classboost_1_1circular__buffer_1w15">size_type</a> index);</b></code><br>
|
||
|
||
<table id="table_function_desc_id4493844">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4493907">
|
||
<tr>
|
||
<td>
|
||
Return the element at the <code>index</code> position.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_pre_desc_id4493921">
|
||
<tr>
|
||
<td valign="top">
|
||
<b>Precondition:</b>
|
||
</td>
|
||
<td>
|
||
<code>*(this).<a href="#classboost_1_1circular__buffer_1a60">size()</a> > 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_id4493995">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4494036">
|
||
<tr>
|
||
<td>
|
||
Remove the last (rightmost) element.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_pre_desc_id4494046">
|
||
<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_id4494075">
|
||
<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_id4494093">
|
||
<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_id4494188">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4494228">
|
||
<tr>
|
||
<td>
|
||
Remove the first (leftmost) element.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_pre_desc_id4494239">
|
||
<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_id4494267">
|
||
<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_id4494285">
|
||
<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_1w16">value_type</a> item = value_type());</b></code><br>
|
||
|
||
<table id="table_function_desc_id4494380">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4494448">
|
||
<tr>
|
||
<td>
|
||
Insert a new element at the end.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_post_desc_id4494458">
|
||
<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_id4494498">
|
||
<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_1w16">value_type</a> item = value_type());</b></code><br>
|
||
|
||
<table id="table_function_desc_id4494628">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4494695">
|
||
<tr>
|
||
<td>
|
||
Insert a new element at the start.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_post_desc_id4494706">
|
||
<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_id4494746">
|
||
<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_1w7">const_reverse_iterator</a> rbegin() const;</b></code><br>
|
||
|
||
<table id="table_function_desc_id4494888">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4494930">
|
||
<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_1w14">reverse_iterator</a> rbegin();</b></code><br>
|
||
|
||
<table id="table_function_desc_id4495037">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4495078">
|
||
<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_1w7">const_reverse_iterator</a> rend() const;</b></code><br>
|
||
|
||
<table id="table_function_desc_id4495117">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4495159">
|
||
<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_1w14">reverse_iterator</a> rend();</b></code><br>
|
||
|
||
<table id="table_function_desc_id4495199">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4495239">
|
||
<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_1w9">iterator</a> rerase(<a href=
|
||
"#classboost_1_1circular__buffer_1w9">iterator</a> first, <a href=
|
||
"#classboost_1_1circular__buffer_1w9">iterator</a> last);</b></code><br>
|
||
|
||
<table id="table_function_desc_id4495279">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4495359">
|
||
<tr>
|
||
<td>
|
||
Erase the range <code>[first, last)</code>.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_pre_desc_id4495372">
|
||
<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_id4495395">
|
||
<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_id4495418">
|
||
<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_id4495438">
|
||
<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_1w9">iterator</a> rerase(<a href=
|
||
"#classboost_1_1circular__buffer_1w9">iterator</a> pos);</b></code><br>
|
||
|
||
<table id="table_function_desc_id4495574">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4495637">
|
||
<tr>
|
||
<td>
|
||
Erase the element at the given position.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_pre_desc_id4495648">
|
||
<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_id4495670">
|
||
<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_id4495693">
|
||
<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_id4495712">
|
||
<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_1w15">size_type</a> new_size, <a href=
|
||
"#classboost_1_1circular__buffer_1w16">value_type</a> item = value_type());</b></code><br>
|
||
|
||
<table id="table_function_desc_id4495834">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4495919">
|
||
<tr>
|
||
<td>
|
||
Change the size of the circular buffer.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_post_desc_id4495992">
|
||
<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_id4496080">
|
||
<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 <class InputIterator><br>
|
||
void rinsert(<a href="#classboost_1_1circular__buffer_1w9">iterator</a> pos, InputIterator first,
|
||
InputIterator last);</b></code><br>
|
||
|
||
<table id="table_function_desc_id4496178">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4496273">
|
||
<tr>
|
||
<td>
|
||
Insert the range <code>[first, last)</code> before the given position.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_pre_desc_id4496288">
|
||
<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_id4496302">
|
||
<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_id4496378">
|
||
<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_1w9">iterator</a> pos, <a href=
|
||
"#classboost_1_1circular__buffer_1w15">size_type</a> n, <a href=
|
||
"#classboost_1_1circular__buffer_1w16">value_type</a> item);</b></code><br>
|
||
|
||
<table id="table_function_desc_id4496422">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4496512">
|
||
<tr>
|
||
<td>
|
||
Insert <code>n</code> copies of the item before the given position.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_pre_desc_id4496526">
|
||
<tr>
|
||
<td valign="top">
|
||
<b>Precondition:</b>
|
||
</td>
|
||
<td>
|
||
Valid <code>pos</code> iterator.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_post_desc_id4496536">
|
||
<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_id4496610">
|
||
<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_1w9">iterator</a> rinsert(<a href=
|
||
"#classboost_1_1circular__buffer_1w9">iterator</a> pos, <a href=
|
||
"#classboost_1_1circular__buffer_1w16">value_type</a> item = value_type());</b></code><br>
|
||
|
||
<table id="table_function_desc_id4496655">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4496745">
|
||
<tr>
|
||
<td>
|
||
Insert an <code>item</code> before the given position.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_pre_desc_id4496759">
|
||
<tr>
|
||
<td valign="top">
|
||
<b>Precondition:</b>
|
||
</td>
|
||
<td>
|
||
Valid <code>pos</code> iterator.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_post_desc_id4496769">
|
||
<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_id4496787">
|
||
<tr>
|
||
<td valign="top">
|
||
<b>Returns:</b>
|
||
</td>
|
||
<td>
|
||
iterator to the inserted element.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_note_desc_id4496830">
|
||
<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_1w15">size_type</a> new_size, <a href=
|
||
"#classboost_1_1circular__buffer_1w16">value_type</a> item = value_type());</b></code><br>
|
||
|
||
<table id="table_function_desc_id4497017">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4497101">
|
||
<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_1w15">size_type</a> new_capacity);</b></code><br>
|
||
|
||
<table id="table_function_desc_id4497194">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4497252">
|
||
<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_1w15">size_type</a> new_capacity);</b></code><br>
|
||
|
||
<table id="table_function_desc_id4497369">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4497426">
|
||
<tr>
|
||
<td>
|
||
Change the capacity of the circular buffer.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_post_desc_id4497484">
|
||
<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_id4497562">
|
||
<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_1w15">size_type</a> size() const;</b></code><br>
|
||
|
||
<table id="table_function_desc_id4497699">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4497740">
|
||
<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<T,Alloc>&
|
||
cb);</b></code><br>
|
||
|
||
<table id="table_function_desc_id4498097">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4498149">
|
||
<tr>
|
||
<td>
|
||
Swap the contents of two circular buffers.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<table id="table_post_desc_id4498160">
|
||
<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_id4498173">
|
||
<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><br>
|
||
|
||
<h2>
|
||
<a id="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 <class T, class Alloc><br>
|
||
bool operator!=(const circular_buffer<T,Alloc>& lhs, const circular_buffer<T,Alloc>&
|
||
rhs);</b></code><br>
|
||
|
||
<table id="table_function_desc_id4481602">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4481706">
|
||
<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 <class T, class Alloc><br>
|
||
bool operator<(const circular_buffer<T,Alloc>& lhs, const circular_buffer<T,Alloc>&
|
||
rhs);</b></code><br>
|
||
|
||
<table id="table_function_desc_id4511674">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4511778">
|
||
<tr>
|
||
<td>
|
||
Lexicographical comparison.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<a name="namespaceboost_1a4"></a> <code><b>template <class T, class Alloc><br>
|
||
bool operator<=(const circular_buffer<T,Alloc>& lhs, const
|
||
circular_buffer<T,Alloc>& rhs);</b></code><br>
|
||
|
||
<table id="table_function_desc_id4511937">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4512041">
|
||
<tr>
|
||
<td>
|
||
Lexicographical comparison.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<a name="namespaceboost_1a0"></a> <code><b>template <class T, class Alloc><br>
|
||
bool operator==(const circular_buffer<T,Alloc>& lhs, const circular_buffer<T,Alloc>&
|
||
rhs);</b></code><br>
|
||
|
||
<table id="table_function_desc_id4512202">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4512305">
|
||
<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 <class T, class Alloc><br>
|
||
bool operator>(const circular_buffer<T,Alloc>& lhs, const circular_buffer<T,Alloc>&
|
||
rhs);</b></code><br>
|
||
|
||
<table id="table_function_desc_id4512478">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4512582">
|
||
<tr>
|
||
<td>
|
||
Lexicographical comparison.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<a name="namespaceboost_1a5"></a> <code><b>template <class T, class Alloc><br>
|
||
bool operator>=(const circular_buffer<T,Alloc>& lhs, const
|
||
circular_buffer<T,Alloc>& rhs);</b></code><br>
|
||
|
||
<table id="table_function_desc_id4512741">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4512845">
|
||
<tr>
|
||
<td>
|
||
Lexicographical comparison.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<a name="namespaceboost_1a6"></a> <code><b>template <class T, class Alloc><br>
|
||
void swap(circular_buffer<T,Alloc>& lhs, circular_buffer<T,Alloc>&
|
||
rhs);</b></code><br>
|
||
|
||
<table id="table_function_desc_id4513001">
|
||
<tr>
|
||
<td></td>
|
||
<td>
|
||
<table id="table_detailed_desc_id4513101">
|
||
<tr>
|
||
<td>
|
||
Swap the contents of two circular buffers.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div><br>
|
||
|
||
<h2>
|
||
<a id="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 id="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><br>
|
||
|
||
<h2>
|
||
<a id="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="#note2">[2]</a>. (Any
|
||
container of <code>std::auto_ptr</code> is considered particularly hazardous. <a href="#note3">[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 back-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><br>
|
||
|
||
<h2>
|
||
<a id="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><br>
|
||
|
||
<h2>
|
||
<a id="examples">More Examples</a>
|
||
</h2>
|
||
<p>
|
||
The following example includes various usage of the <code>circular_buffer</code> .
|
||
</p>
|
||
<pre>
|
||
#include <boost/circular_buffer.hpp>
|
||
#include <numeric>
|
||
#include <assert.h>
|
||
|
||
int main(int /*argc*/, char* /*argv*/[])
|
||
{
|
||
// create a circular buffer of capacity 3
|
||
boost::circular_buffer<int> cb(3);
|
||
|
||
// insert some elements into the circular buffer
|
||
cb.push_back(1);
|
||
cb.push_back(2);
|
||
|
||
// assertions
|
||
assert(cb[0] == 1);
|
||
assert(cb[1] == 2);
|
||
assert(!cb.full());
|
||
assert(cb.size() == 2);
|
||
assert(cb.capacity() == 3);
|
||
|
||
// insert some other elements
|
||
cb.push_back(3);
|
||
cb.push_back(4);
|
||
|
||
// evaluate the sum
|
||
int sum = std::accumulate(cb.begin(), cb.end(), 0);
|
||
|
||
// assertions
|
||
assert(cb[0] == 2);
|
||
assert(cb[1] == 3);
|
||
assert(cb[2] == 4);
|
||
assert(*cb.begin() == 2);
|
||
assert(cb.front() == 2);
|
||
assert(cb.back() == 4);
|
||
assert(sum == 9);
|
||
assert(cb.full());
|
||
assert(cb.size() == 3);
|
||
assert(cb.capacity() == 3);
|
||
|
||
return 0;
|
||
}
|
||
</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>
|
||
<h4>
|
||
<a id="boundedbuffer">Bounded Buffer Example</a>
|
||
</h4>
|
||
<p>
|
||
The bounded buffer is normally used in a producer-consumer mode when producer threads produce items and store
|
||
them in the container and consumer threads remove these items and process them. The bounded buffer has to
|
||
guarantee that producers do not insert items into the container when the container is full, that consumers do not
|
||
try to remove items when the container is empty, and that each produced item is consumed by exactly one consumer.
|
||
</p>
|
||
<p>
|
||
The example below shows how the <code>circular_buffer</code> can be utilized as an underlying container of the
|
||
bounded buffer.
|
||
</p>
|
||
<pre>
|
||
#include <boost/circular_buffer.hpp>
|
||
#include <boost/thread/mutex.hpp>
|
||
#include <boost/thread/condition.hpp>
|
||
#include <boost/thread/thread.hpp>
|
||
#include <boost/progress.hpp>
|
||
#include <boost/bind.hpp>
|
||
|
||
template <class T>
|
||
class bounded_buffer {
|
||
public:
|
||
|
||
typedef boost::circular_buffer<T> container_type;
|
||
typedef typename container_type::size_type size_type;
|
||
typedef typename container_type::value_type value_type;
|
||
|
||
explicit bounded_buffer(size_type capacity) : m_unread(0), m_container(capacity) {}
|
||
|
||
void push_front(const value_type& item) {
|
||
boost::mutex::scoped_lock lock(m_mutex);
|
||
m_not_full.wait(lock, boost::bind(&bounded_buffer<value_type>::is_not_full, this));
|
||
m_container.push_front(item);
|
||
++m_unread;
|
||
lock.unlock();
|
||
m_not_empty.notify_one();
|
||
}
|
||
|
||
void pop_back(value_type* pItem) {
|
||
boost::mutex::scoped_lock lock(m_mutex);
|
||
m_not_empty.wait(lock, boost::bind(&bounded_buffer<value_type>::is_not_empty, this));
|
||
*pItem = m_container[--m_unread];
|
||
lock.unlock();
|
||
m_not_full.notify_one();
|
||
}
|
||
|
||
private:
|
||
bounded_buffer(const bounded_buffer&); // Disabled copy constructor
|
||
bounded_buffer& operator = (const bounded_buffer&); // Disabled assign operator
|
||
|
||
bool is_not_empty() const { return m_unread > 0; }
|
||
bool is_not_full() const { return m_unread < m_container.capacity(); }
|
||
|
||
size_type m_unread;
|
||
container_type m_container;
|
||
boost::mutex m_mutex;
|
||
boost::condition m_not_empty;
|
||
boost::condition m_not_full;
|
||
};
|
||
</pre>
|
||
<p>
|
||
The <code>bounded_buffer</code> uses <a href="../../thread/doc/">Boost Threads</a> and <a href=
|
||
"../../bind/bind.html">Boost Bind</a> libraries.
|
||
</p>
|
||
<p>
|
||
The <code>push_front()</code> method is called by the producer thread in order to insert a new item into the
|
||
buffer. The method locks the mutex and waits until there is a space for the new item. (The mutex is unlocked
|
||
during the waiting stage and has to be regained when the condition is met.) If there is a space in the buffer
|
||
available, the execution continues and the method inserts the item at the end of the
|
||
<code>circular_buffer</code>. Then it increments the number of unread items and unlocks the mutex (in case an
|
||
exception is thrown before the mutex is unlocked, the mutex is unlocked automatically by the destructor of the
|
||
<code>scoped_lock</code>). At last the method notifies one of the consumer threads waiting for a new item to be
|
||
inserted into the buffer.
|
||
</p>
|
||
<p>
|
||
The <code>pop_back()</code> method is called by the consumer thread in order to read the next item from the
|
||
buffer. The method locks the mutex and waits until there is an unread item in the buffer. If there is at least
|
||
one unread item, the method decrements the number of unread items and reads the next item from the
|
||
<code>circular_buffer</code>. Then it unlocks the mutex and notifies one of the producer threads waiting for the
|
||
buffer to free a space for the next item.
|
||
</p>
|
||
<p>
|
||
The <code>pop_back()</code> method does not remove the item but the item is left in the
|
||
<code>circular_buffer</code> which then replaces it with a new one (inserted by a producer) when the
|
||
<code>circular_buffer</code> is full. This technique is more effective than removing the item explicitly by
|
||
calling the <code>pop_back()</code> method of the <code>circular_buffer</code>. This claim is based on the
|
||
assumption that an assignment (replacement) of a new item into an old one is more effective than a destruction
|
||
(removal) of an old item and a consequent inplace construction (insertion) of a new item.
|
||
</p>
|
||
<p>
|
||
For comparison of bounded buffers based on different containers compile and run <a href=
|
||
"../test/bounded_buffer_comparison.cpp">bounded_buffer_comparison.cpp</a>. The test should reveal the bounded
|
||
buffer based on the <code>circular_buffer</code> is most effective closely followed by the
|
||
<code>std::deque</code> based bounded buffer. (In praxis the result may be different because the test is affected
|
||
by external factors such as immediate CPU load.)
|
||
</p>
|
||
<h2>
|
||
<a id="notes">Notes</a>
|
||
</h2>
|
||
<ol>
|
||
<li>
|
||
<a id="note1"></a>
|
||
<p>
|
||
An indepth definition of a circular buffer can be found at <a href=
|
||
"http://en.wikipedia.org/wiki/Circular_buffer">Wikipedia</a>.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<a id="note2"></a>
|
||
<p>
|
||
A good implementation of smart pointers is included in <a href="../../../libs/smart_ptr/">Boost</a>.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<a id="note3"></a>
|
||
<p>
|
||
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 Specific Ways to Improve Your Use of the Standard Template
|
||
Library</i>. Addison-Wesley, 2001.)
|
||
</p>
|
||
</li>
|
||
</ol><br>
|
||
|
||
<h2>
|
||
<a id="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><br>
|
||
|
||
<h2>
|
||
<a id="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 size="1">
|
||
<table id="footer" width="100%" border="0">
|
||
<tr valign="top">
|
||
<td valign="top" align="left">
|
||
<p>
|
||
<small>Copyright <20> 2003-2006 Jan Gaspar</small>
|
||
</p>
|
||
<p>
|
||
<small>Use, modification, and distribution is subject to the Boost Software License, Version 1.0. (See
|
||
accompanying file <code>LICENSE_1_0.txt</code> or copy at <a href=
|
||
"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</small>
|
||
</p>
|
||
</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>
|