doc/html/circular_buffer.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   5 <title>Chapter&#160;8.&#160;Boost.Circular Buffer</title>
   6 <link rel="stylesheet" href="../../doc/src/boostbook.css" type="text/css">
   7 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   8 <link rel="home" href="index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
   9 <link rel="up" href="libraries.html" title="Part&#160;I.&#160;The Boost C++ Libraries (BoostBook Subset)">
  10 <link rel="prev" href="chrono/appendices.html" title="Appendices">
  11 <link rel="next" href="circular_buffer/example.html" title="Circular_buffer example">
  12 </head>
  13 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  14 <table cellpadding="2" width="100%"><tr>
  15 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../boost.png"></td>
  16 <td align="center"><a href="../../index.html">Home</a></td>
  17 <td align="center"><a href="../../libs/libraries.htm">Libraries</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  19 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  20 <td align="center"><a href="../../more/index.htm">More</a></td>
  21 </tr></table>
  22 <hr>
  23 <div class="spirit-nav">
  24 <a accesskey="p" href="chrono/appendices.html"><img src="../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="libraries.html"><img src="../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="circular_buffer/example.html"><img src="../../doc/src/images/next.png" alt="Next"></a>
  25 </div>
  26 <div class="chapter">
  27 <div class="titlepage"><div>
  28 <div><h2 class="title">
  29 <a name="circular_buffer"></a>Chapter&#160;8.&#160;Boost.Circular Buffer</h2></div>
  30 <div><div class="authorgroup"><div class="author"><h3 class="author">
  31 <span class="firstname">Jan</span> <span class="surname">Gaspar</span>
  32 </h3></div></div></div>
  33 <div><p class="copyright">Copyright &#169; 2003-2013 Jan Gaspar</p></div>
  34 <div><div class="legalnotice">
  35 <a name="circular_buffer.legal"></a><p>
  36         Distributed under the Boost Software License, Version 1.0. (See accompanying
  37         file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
  38       </p>
  39 </div></div>
  40 </div></div>
  41 <div class="toc">
  42 <p><b>Table of Contents</b></p>
  43 <dl class="toc">
  44 <dt><span class="section"><a href="circular_buffer.html#circular_buffer.intro">Introduction</a></span></dt>
  45 <dt><span class="section"><a href="circular_buffer/example.html">Circular_buffer example</a></span></dt>
  46 <dt><span class="section"><a href="circular_buffer/rationale.html">Rationale</a></span></dt>
  47 <dt><span class="section"><a href="circular_buffer/implementation.html">Implementation </a></span></dt>
  48 <dt><span class="section"><a href="circular_buffer/examples.html">More Examples</a></span></dt>
  49 <dt><span class="section"><a href="circular_buffer/headers.html">Header Files</a></span></dt>
  50 <dt><span class="section"><a href="circular_buffer/concepts.html">Modelled Concepts</a></span></dt>
  51 <dt><span class="section"><a href="circular_buffer/template_params.html">Template Parameters</a></span></dt>
  52 <dt><span class="section"><a href="circular_buffer/tickets.html">Trac Tickets</a></span></dt>
  53 <dt><span class="section"><a href="circular_buffer/release.html">Release Notes</a></span></dt>
  54 <dt><span class="section"><a href="circular_buffer/acknowledgements.html">Acknowledgements</a></span></dt>
  55 <dt><span class="section"><a href="circular_buffer/version_id.html">Documentation Version Info</a></span></dt>
  56 <dt><span class="section"><a href="boost_circular_buffer_c___reference.html">Boost.Circular_buffer C++ Reference</a></span></dt>
  57 <dd><dl>
  58 <dt><span class="section"><a href="boost_circular_buffer_c___reference.html#header.boost.circular_buffer_hpp">Header &lt;boost/circular_buffer.hpp&gt;</a></span></dt>
  59 <dt><span class="section"><a href="boost_circular_buffer_c___reference.html#header.boost.circular_buffer.base_hpp">Header &lt;boost/circular_buffer/base.hpp&gt;</a></span></dt>
  60 <dt><span class="section"><a href="boost_circular_buffer_c___reference.html#header.boost.circular_buffer.space_optimized_hpp">Header &lt;boost/circular_buffer/space_optimized.hpp&gt;</a></span></dt>
  61 </dl></dd>
  62 <dt><span class="section"><a href="circular_buffer/s14.html">Index</a></span></dt>
  63 </dl>
  64 </div>
  65 <div class="note"><table border="0" summary="Note">
  66 <tr>
  67 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../doc/src/images/note.png"></td>
  68 <th align="left">Note</th>
  69 </tr>
  70 <tr><td align="left" valign="top"><p>
  71       A printer-friendly PDF version of this manual is also available.
  72     </p></td></tr>
  73 </table></div>
  74 <div class="section">
  75 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  76 <a name="circular_buffer.intro"></a><a class="link" href="circular_buffer.html#circular_buffer.intro" title="Introduction">Introduction</a>
  77 </h2></div></div></div>
  78 <p>
  79       A Circular Buffer.
  80     </p>
  81 <h3>
  82 <a name="circular_buffer.intro.h0"></a>
  83       <span class="phrase"><a name="circular_buffer.intro.description"></a></span><a class="link" href="circular_buffer.html#circular_buffer.intro.description">Description</a>
  84     </h3>
  85 <p>
  86       The term <a href="http://en.wikipedia.org/wiki/Circular_buffer" target="_top">circular
  87       buffer</a> (also called a <span class="emphasis"><em>ring</em></span> or <span class="emphasis"><em>cyclic
  88       buffer</em></span>) refers to an area in memory which is used to store incoming
  89       data. When the buffer is filled, new data is written starting at the beginning
  90       of the buffer and overwriting the old.
  91     </p>
  92 <p>
  93       <code class="computeroutput"><a class="link" href="boost/circular_buffer.html" title="Class template circular_buffer">boost::circular_buffer</a></code>
  94       is a STL compliant container.
  95     </p>
  96 <p>
  97       It is a kind of sequence similar to <a href="https://www.boost.org/sgi/stl/List.html" target="_top">std::list</a>
  98       or <a href="https://www.boost.org/sgi/stl/Deque.html" target="_top">std::deque</a>.
  99       It supports random access iterators, constant time insert and erase operations
 100       at the beginning or the end of the buffer and interoperability with std algorithms.
 101     </p>
 102 <p>
 103       The <code class="computeroutput"><a class="link" href="boost/circular_buffer.html" title="Class template circular_buffer">circular_buffer</a></code> is
 104       especially designed to provide <span class="bold"><strong>fixed capacity</strong></span>
 105       storage. When its capacity is exhausted, newly inserted elements will cause
 106       elements to be overwritten, either at the beginning or end of the buffer (depending
 107       on what insert operation is used).
 108     </p>
 109 <p>
 110       The <code class="computeroutput"><a class="link" href="boost/circular_buffer.html" title="Class template circular_buffer">circular_buffer</a></code> only
 111       allocates memory when created, when the capacity is adjusted explicitly, or
 112       as necessary to accommodate resizing or assign operations.
 113     </p>
 114 <p>
 115       <span class="inlinemediaobject"><img src="../../libs/circular_buffer/doc/images/circular_buffer.png"></span>
 116     </p>
 117 <p>
 118       There is also a <code class="computeroutput"><a class="link" href="boost/circular_idm46495624036048.html" title="Class template circular_buffer_space_optimized">circular_buffer_space_optimized</a></code>
 119       version available.
 120     </p>
 121 <p>
 122       <span class="inlinemediaobject"><img src="../../libs/circular_buffer/doc/images/space_optimized.png"></span>
 123     </p>
 124 <p>
 125       <code class="computeroutput"><a class="link" href="boost/circular_idm46495624036048.html" title="Class template circular_buffer_space_optimized">circular_buffer_space_optimized</a></code>
 126       is an adaptation of the <code class="computeroutput"><a class="link" href="boost/circular_buffer.html" title="Class template circular_buffer">circular_buffer</a></code>
 127       which <span class="bold"><strong>does not allocate memory all at once when created</strong></span>,
 128       instead it allocates memory as needed.
 129     </p>
 130 <p>
 131       The predictive memory allocation is similar to typical <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span></code>
 132       implementation. Memory is automatically freed as the size of the container
 133       decreases.
 134     </p>
 135 <p>
 136       The memory allocation process of the space-optimized circular buffer. The
 137       <code class="computeroutput">min_capacity</code>
 138       of the capacity controller represents the minimal guaranteed amount of allocated
 139       memory. The allocated memory will never drop under this value. The default
 140       value of the <code class="computeroutput"><span class="identifier">min_capacity</span></code> is
 141       set to 0. The <code class="computeroutput"><span class="identifier">min_capacity</span></code>
 142       can be set using the constructor parameter <code class="computeroutput">()
 143       capacity_control </code> or the function <code class="computeroutput"><span class="identifier">set_capacity</span></code>.
 144     </p>
 145 <p>
 146       The space-optimized version is, of course, a little slower.
 147     </p>
 148 </div>
 149 </div>
 150 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 151 <td align="left"><p><small>Last revised: December 10, 2019 at 00:26:57 GMT</small></p></td>
 152 <td align="right"><div class="copyright-footer"></div></td>
 153 </tr></table>
 154 <hr>
 155 <div class="spirit-nav">
 156 <a accesskey="p" href="chrono/appendices.html"><img src="../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="libraries.html"><img src="../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="circular_buffer/example.html"><img src="../../doc/src/images/next.png" alt="Next"></a>
 157 </div>
 158 </body>
 159 </html>