boost/circular_buffer
2
0
Fork 0
mirror of https://github.com/boostorg/circular_buffer.git synced 2026-01-24 17:52:29 +00:00
Code Issues Projects Releases Wiki Activity
Files
d649fd7a89a2fdcac8af4df295fbdc43eca0faec
circular_buffer/doc/circular_buffer_space_optimized.html
Jan Gaspar d649fd7a89 Template parameters finished. 
[SVN r2533]
2005-03-15 17:24:27 +00:00

342 lines
19 KiB
HTML
Raw Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>Space Optimized Circular Buffer Container Adaptor</title>
</head>
<body bgcolor="#ffffff">
<h1>Space Optimized Circular Buffer Container Adaptor</h1>
<table id="title" border="0">
<tr>
<td>
<h1>circular_buffer_space_optimized&lt;T, Alloc&gt;</h1>
</td>
<td><a href="http://boost.org"><img height="86" src="../../../c++boost.gif" width="277" border="0" alt="Boost"></a></td>
</tr>
</table>
<h3>Contents</h3>
<dl>
<dd><a href="#description">Description</a></dd>
<dd><a href="#synopsis">Synopsis</a></dd>
<dd><a href="#rationale">Rationale</a></dd>
<dd><a href="#header">Header files</a></dd>
<dd><a href="#model">Modeled concepts</a></dd>
<dd><a href="#members">Template Parameters, Members and Standalone
Functions</a></dd>
<dd><a href="#semantics">Semantics</a></dd>
<dd><a href="#see">See also</a></dd>
<dd><a href="#ack">Acknowledgments</a></dd>
</dl>
<h3>
<a name="description">Description</a>
</h3>
<p>The <code>circular_buffer_space_optimized</code> container is an adaptor of the <code>
<a href="circular_buffer.html">circular_buffer</a></code>. The
functionality of the <code>circular_buffer_space_optimized</code> is similar to
the base <code>circular_buffer</code> except it does not allocate memory at
once when created rather it allocates memory as needed. (The predictive memory
allocation is similar to typical <code>std::vector</code> implementation.)
Moreover the memory is automatically freed as the size of the container
decreases.
</p>
<table id="figure" border="0">
<tr>
<td></td>
<td><img height="350" src="circular_buffer_space_optimized.png" width="700" alt="Space Optimized Circular Buffer"></td>
</tr>
<tr>
<td valign="top"><b>Figure:</b></td>
<td valign="top">The memory allocation process of the space optimized circular
buffer. The <code>min_capacity</code> represents the minimal guaranteed amount
of allocated memory. The allocated memory will never drop under this value. By
default the <code>min_capacity</code> is set to 0.
</td>
</tr>
</table>
<br>
<h3>
<a name="synopsis">Synopsis</a>
</h3>
<div id="srcdoc_synopsis">
<table border="0" cellpadding="5">
<tr>
<td></td>
<td>
<pre>
namespace boost {
template &lt;class <a href="circular_buffer.html#templateparam_T">T</a>, class <a href="circular_buffer.html#templateparam_Alloc">Alloc</a>&gt;
class circular_buffer_space_optimized
{
public:
   typedef Alloc <a href="circular_buffer.html#classboost_1_1circular__buffer_1w0">allocator_type</a>;
   typedef <i>implementation-defined</i> <a href="circular_buffer.html#classboost_1_1circular__buffer_1w1">const_iterator</a>;
   typedef typename Alloc::const_pointer <a href="circular_buffer.html#classboost_1_1circular__buffer_1w2">const_pointer</a>;
   typedef typename Alloc::const_reference <a href="circular_buffer.html#classboost_1_1circular__buffer_1w3">const_reference</a>;
   typedef <i>implementation-defined</i> <a href="circular_buffer.html#classboost_1_1circular__buffer_1w4">const_reverse_iterator</a>;
   typedef typename Alloc::difference_type <a href="circular_buffer.html#classboost_1_1circular__buffer_1w5">difference_type</a>;
   typedef <i>implementation-defined</i> <a href="circular_buffer.html#classboost_1_1circular__buffer_1w6">iterator</a>;
   typedef typename Alloc::pointer <a href="circular_buffer.html#classboost_1_1circular__buffer_1w8">pointer</a>;
   typedef typename Alloc::reference <a href="circular_buffer.html#classboost_1_1circular__buffer_1w9">reference</a>;
   typedef <i>implementation-defined</i> <a href="circular_buffer.html#classboost_1_1circular__buffer_1w11">reverse_iterator</a>;
   typedef typename Alloc::size_type <a href="circular_buffer.html#classboost_1_1circular__buffer_1w12">size_type</a>;
   typedef typename Alloc::value_type <a href="circular_buffer.html#classboost_1_1circular__buffer_1w13">value_type</a>;
   template &lt;class InputIterator&gt;
      <a href="#classboost_1_1circular__buffer__space__optimized_1a3">circular_buffer_space_optimized</a>(size_type capacity,
         size_type min_capacity, InputIterator first,
         InputIterator last, const allocator_type&amp; alloc = allocator_type());
   <a href="#classboost_1_1circular__buffer__space__optimized_1a4">circular_buffer_space_optimized</a>(size_type capacity,
      size_type min_capacity, value_type item,
      const allocator_type&amp; alloc = allocator_type());
   explicit <a href="#classboost_1_1circular__buffer__space__optimized_1a5">circular_buffer_space_optimized</a>(size_type capacity,
      size_type min_capacity = 0, const allocator_type&amp; alloc = allocator_type());
   template &lt;class InputIterator&gt;
      void <a href="circular_buffer.html#classboost_1_1circular__buffer_1a0">assign</a>(InputIterator first, InputIterator last);
   void <a href="circular_buffer.html#classboost_1_1circular__buffer_1a1">assign</a>(size_type n, value_type item);
   value_type <a href="circular_buffer.html#classboost_1_1circular__buffer_1a2">at</a>(size_type index) const;
   reference <a href="circular_buffer.html#classboost_1_1circular__buffer_1a3">at</a>(size_type index);
   value_type <a href="circular_buffer.html#classboost_1_1circular__buffer_1a4">back</a>() const;
   reference <a href="circular_buffer.html#classboost_1_1circular__buffer_1a5">back</a>();
   const_iterator <a href="circular_buffer.html#classboost_1_1circular__buffer_1a6">begin</a>() const;
   iterator <a href="circular_buffer.html#classboost_1_1circular__buffer_1a7">begin</a>();
   size_type <a href="circular_buffer.html#classboost_1_1circular__buffer_1a8">capacity</a>() const;
   void <a href="circular_buffer.html#classboost_1_1circular__buffer_1a13">clear</a>();
   pointer <a href="circular_buffer.html#classboost_1_1circular__buffer_1a14">data</a>();
   bool <a href="circular_buffer.html#classboost_1_1circular__buffer_1a15">empty</a>() const;
   const_iterator <a href="circular_buffer.html#classboost_1_1circular__buffer_1a16">end</a>() const;
   iterator <a href="circular_buffer.html#classboost_1_1circular__buffer_1a17">end</a>();
   iterator <a href="circular_buffer.html#classboost_1_1circular__buffer_1a18">erase</a>(iterator first, iterator last);
   iterator <a href="circular_buffer.html#classboost_1_1circular__buffer_1a19">erase</a>(iterator pos);
   value_type <a href="circular_buffer.html#classboost_1_1circular__buffer_1a20">front</a>() const;
   reference <a href="circular_buffer.html#classboost_1_1circular__buffer_1a21">front</a>();
   bool <a href="circular_buffer.html#classboost_1_1circular__buffer_1a22">full</a>() const;
   allocator_type&amp; <a href="circular_buffer.html#classboost_1_1circular__buffer_1a23">get_allocator</a>();
   allocator_type <a href="circular_buffer.html#classboost_1_1circular__buffer_1a24">get_allocator</a>() const;
   template &lt;class InputIterator&gt;
      void <a href="circular_buffer.html#classboost_1_1circular__buffer_1a25">insert</a>(iterator pos, InputIterator first, InputIterator last);
   void <a href="circular_buffer.html#classboost_1_1circular__buffer_1a26">insert</a>(iterator pos, size_type n, value_type item);
   iterator <a href="circular_buffer.html#classboost_1_1circular__buffer_1a27">insert</a>(iterator pos);
   iterator <a href="circular_buffer.html#classboost_1_1circular__buffer_1a28">insert</a>(iterator pos, value_type item);
   size_type <a href="circular_buffer.html#classboost_1_1circular__buffer_1a29">max_size</a>() const;
   size_type <a href="#classboost_1_1circular__buffer__space__optimized_1a15">min_capacity</a>() const;
   circular_buffer&lt;T,Alloc&gt;&amp; <a href="circular_buffer.html#classboost_1_1circular__buffer_1a30">operator=</a>(const circular_buffer&lt;T,Alloc&gt;&amp; cb);
   value_type <a href="circular_buffer.html#classboost_1_1circular__buffer_1a31">operator[]</a>(size_type index) const;
   reference <a href="circular_buffer.html#classboost_1_1circular__buffer_1a32">operator[]</a>(size_type index);
   void <a href="circular_buffer.html#classboost_1_1circular__buffer_1a33">pop_back</a>();
   void <a href="circular_buffer.html#classboost_1_1circular__buffer_1a34">pop_front</a>();
   void <a href="circular_buffer.html#classboost_1_1circular__buffer_1a35">push_back</a>();
   void <a href="circular_buffer.html#classboost_1_1circular__buffer_1a36">push_back</a>(value_type item);
   void <a href="circular_buffer.html#classboost_1_1circular__buffer_1a37">push_front</a>();
   void <a href="circular_buffer.html#classboost_1_1circular__buffer_1a38">push_front</a>(value_type item);
   const_reverse_iterator <a href="circular_buffer.html#classboost_1_1circular__buffer_1a39">rbegin</a>() const;
   reverse_iterator <a href="circular_buffer.html#classboost_1_1circular__buffer_1a40">rbegin</a>();
   const_reverse_iterator <a href="circular_buffer.html#classboost_1_1circular__buffer_1a41">rend</a>() const;
   reverse_iterator <a href="circular_buffer.html#classboost_1_1circular__buffer_1a42">rend</a>();
   void <a href="circular_buffer.html#classboost_1_1circular__buffer_1a43">resize</a>(size_type new_size, value_type item = T(), bool remove_front = true);
   template &lt;class InputIterator&gt;
      void <a href="circular_buffer.html#classboost_1_1circular__buffer_1a44">rinsert</a>(iterator pos, InputIterator first, InputIterator last);
   void <a href="circular_buffer.html#classboost_1_1circular__buffer_1a45">rinsert</a>(iterator pos, size_type n, value_type item);
   iterator <a href="circular_buffer.html#classboost_1_1circular__buffer_1a46">rinsert</a>(iterator pos);
   iterator <a href="circular_buffer.html#classboost_1_1circular__buffer_1a47">rinsert</a>(iterator pos, value_type item);
   void <a href="circular_buffer.html#classboost_1_1circular__buffer_1a48">set_capacity</a>(size_type new_capacity, bool remove_front = true);
   void <a href="#classboost_1_1circular__buffer__space__optimized_1a30">set_min_capacity</a>(size_type new_min_capacity);
   size_type <a href="circular_buffer.html#classboost_1_1circular__buffer_1a49">size</a>() const;
   void <a href="circular_buffer.html#classboost_1_1circular__buffer_1a50">swap</a>(circular_buffer&amp; cb);
};
template &lt;class T, class Alloc&gt;
   bool <a href="#namespaceboost_1a2">operator!=</a>(const circular_buffer_space_optimized&lt;T,Alloc&gt;&amp; lhs,
      const circular_buffer_space_optimized&lt;T,Alloc&gt;&amp; rhs);
template &lt;class T, class Alloc&gt;
   bool <a href="#namespaceboost_1a1">operator&lt;</a>(const circular_buffer_space_optimized&lt;T,Alloc&gt;&amp; lhs,
      const circular_buffer_space_optimized&lt;T,Alloc&gt;&amp; rhs);
template &lt;class T, class Alloc&gt;
   bool <a href="#namespaceboost_1a4">operator&lt;=</a>(const circular_buffer_space_optimized&lt;T,Alloc&gt;&amp; lhs,
      const circular_buffer_space_optimized&lt;T,Alloc&gt;&amp; rhs);
template &lt;class T, class Alloc&gt;
   bool <a href="#namespaceboost_1a0">operator==</a>(const circular_buffer_space_optimized&lt;T,Alloc&gt;&amp; lhs,
      const circular_buffer_space_optimized&lt;T,Alloc&gt;&amp; rhs);
template &lt;class T, class Alloc&gt;
   bool <a href="#namespaceboost_1a3">operator&gt;</a>(const circular_buffer_space_optimized&lt;T,Alloc&gt;&amp; lhs,
      const circular_buffer_space_optimized&lt;T,Alloc&gt;&amp; rhs);
template &lt;class T, class Alloc&gt;
   bool <a href="#namespaceboost_1a5">operator&gt;=</a>(const circular_buffer_space_optimized&lt;T,Alloc&gt;&amp; lhs,
      const circular_buffer_space_optimized&lt;T,Alloc&gt;&amp; rhs);
template &lt;class T, class Alloc&gt;
   void <a href="#namespaceboost_1a6">swap</a>(circular_buffer_space_optimized&lt;T,Alloc&gt;&amp; lhs,
      circular_buffer_space_optimized&lt;T,Alloc&gt;&amp; rhs);
} // namespace boost
</pre>
</td>
</tr>
</table>
</div>
<h3>
<a name="rationale">Rationale</a>
</h3>
<p>The auto-resizing mode of the space optimized circular buffer can be useful in
situations when the container can possibly store large number of elements but
most of its lifetime the container stores just few of them. The usage of the <code>circular_buffer_space_optimized</code>
will result in decreased memory consumption and can improve the CPU cache
effectiveness.
</p>
<h3>
<a name="header">Header files</a>
</h3>
<p>
The <code>circular_buffer_space_optimized</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_space_optimized</code> in the header file
<code><a href="../../../boost/circular_buffer_fwd.hpp">boost/circular_buffer_fwd.hpp</a></code>.
</p>
<h3>
<a name="model">Modeled concepts</a>
</h3>
<p><a href="http://www.sgi.com/tech/stl/RandomAccessContainer.html">Random Access
Container</a>, <a href="http://www.sgi.com/tech/stl/FrontInsertionSequence.html">
Front Insertion Sequence</a>, <a href="http://www.sgi.com/tech/stl/BackInsertionSequence.html">
Back Insertion Sequence</a>, <a href="http://www.sgi.com/tech/stl/Assignable.html">
Assignable</a> (SGI specific), <a href="http://www.sgi.com/tech/stl/EqualityComparable.html">
Equality Comparable</a>, <a href="http://www.sgi.com/tech/stl/LessThanComparable.html">
LessThan Comparable</a> (SGI specific)
</p>
<h3>
<a name="members">Template Parameters, Members and Friend Functions</a>
</h3>
<p>Template parameters, members and friend functions of the <code>circular_buffer_space_optimized</code>
are almost the same as for the base <code>circular_buffer</code>. Refer the <code>circular_buffer</code>
<a href="circular_buffer.html#parameters">documentation</a> and also its <a href="srcdoc/index.html">
source code documentation</a> for a detailed description.
</p>
<p>The specific methods of the <code>circular_buffer_space_optimized</code> are
listed below.
</p>
<table id="members_perations" width="85%" border="1">
<tr>
<th>
Method
</th>
<th>
Description
</th>
</tr>
<tr>
<td>
<code><a href="srcdoc/classboost_1_1circular__buffer__space__optimized.html#a9">circular_buffer_space_optimized</a>(size_type
capacity, size_type min_capacity = 0, const allocator_type&amp; alloc =
allocator_type())</code>
</td>
<td>Create an empty space optimized circular buffer with a given capacity.
</td>
</tr>
<tr>
<td>
<code><a href="srcdoc/classboost_1_1circular__buffer__space__optimized.html#a10">circular_buffer_space_optimized</a>
(size_type capacity, size_type min_capacity, const T&amp; item, const
allocator_type&amp; alloc = allocator_type())</code>
</td>
<td>Create a full space optimized circular buffer filled with copies of <code>item</code>.
</td>
</tr>
<tr>
<td>
<code>template&lt;InputIterator&gt; <a href="srcdoc/classboost_1_1circular__buffer__space__optimized.html#a11">
circular_buffer_space_optimized</a>(size_type capacity, size_type
min_capacity, InputIterator first, InputIterator last, const
allocator_type&amp; alloc = allocator_type())</code>
</td>
<td>Create a space optimized circular buffer with a copy of a range.
</td>
</tr>
<tr>
<td>
<code><a href="srcdoc/classboost_1_1circular__buffer__space__optimized.html#a3">min_capacity</a>()
const</code>
</td>
<td>Return the minimal guaranteed amount of allocated memory.
</td>
</tr>
<tr>
<td>
<code><a href="srcdoc/classboost_1_1circular__buffer__space__optimized.html#a4">set_min_capacity</a>()</code>
</td>
<td>Change the minimal guaranteed amount of allocated memory.
</td>
</tr>
</table>
<br>
<h3>
<a name="semantics">Semantics</a>
</h3>
<p>The behaviour of memory auto-resizing is as follows:
</p>
<ul>
<li>
Minimal capacity is allocated when an empty <code>circular_buffer_space_optimized</code>
is created.
</li>
<li>
When a non-empty <code>circular_buffer_space_optimized</code>
container is created the allocated memory reflects the size of the container.
</li>
<li>
<code>push_back</code>, <code>push_front</code>, <code>insert</code> and <code>rinsert</code>
will predictively increase the allocated memory if necessary. (The predictive
memory allocation is similar to <code>std::vector</code>.)
</li>
<li>
<code>set_capacity</code>, <code>resize</code>, <code>assign</code>, <code>insert</code>
(range or n items), <code>rinsert</code> (range or n items), <code>erase</code>
(range) and <code>clear</code>
will accommodate the allocated memory as necessary.
</li>
<li>
<code>pop_back</code>, <code>pop_front</code>, <code>erase</code> and <code>clear</code>
will predictively decrease the allocated memory.
</li>
</ul>
<p>The semantics of the <code>circular_buffer_space_optimized</code> then follows
the <a href="circular_buffer.html#semantics">semantics</a> of the base <code>circular_buffer</code>
except the invalidation rules.
</p>
<p><a name="invalidation"></a>The rule for iterator invalidation for <code>circular_buffer_space_optimized</code>
is as follows:
</p>
<ul>
<li>
<code>data</code>, <code>set_capacity</code>, <code>resize</code>, <code>operator=</code>,
<code>assign</code>, <code>swap</code>, <code>push_back</code>, <code>push_front</code>,
<code>pop_back</code>, <code>pop_front</code>, <code>insert</code>, <code>rinsert</code>,
<code>erase</code> and <code>clear</code> invalidate all iterators pointing to
the <code>circular_buffer_space_optimized</code>.
</li>
</ul>
<h3>
<a name="see">See also</a>
</h3>
<p><code><a href="circular_buffer.html">boost::circular_buffer</a>, <a href="http://www.sgi.com/tech/stl/Vector.html">
std::vector</a></code>
</p>
<h3>
<a name="ack">Acknowledgments</a>
</h3>
<p>The idea of the space optimized circular buffer has been introduced by Pavel
Vozenilek.
</p>
<hr align="left" size="1">
<table id="footer" border="0" width="100%">
<tr>
<td align="left" valign="top"><small>Copyright © 2003-2005 <a href="mailto:jano_gaspar%5Bat%5Dyahoo.com">Jan Gaspar</a></small></td>
<td align="right" valign="top">
<a href="http://validator.w3.org/check?url=http://www.boost.org/circular_buffer/libs/circular_buffer/doc/circular_buffer_space_optimized.html">
<img border="0" src="valid-html40.bmp" alt="Valid HTML 4.0!" height="31" width="88"></a>
</td>
</tr>
</table>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink