Boost logo

Boost-Commit :

From: jano_gaspar_at_[hidden]
Date: 2008-01-23 18:04:58


Author: jano_gaspar
Date: 2008-01-23 18:04:57 EST (Wed, 23 Jan 2008)
New Revision: 42938
URL: http://svn.boost.org/trac/boost/changeset/42938

Log:
circular_buffer: updated documentation
Text files modified:
   trunk/boost/circular_buffer/base.hpp | 10 ++++++-
   trunk/boost/circular_buffer/details.hpp | 2
   trunk/boost/circular_buffer/space_optimized.hpp | 5 +++
   trunk/libs/circular_buffer/doc/circular_buffer.html | 52 +++++++++++++++++++++++++++++++++------
   trunk/libs/circular_buffer/doc/space_optimized.html | 22 ++++++++++++++++
   trunk/libs/circular_buffer/test/base_test.cpp | 1
   trunk/libs/circular_buffer/test/common.ipp | 4 +++
   7 files changed, 83 insertions(+), 13 deletions(-)

Modified: trunk/boost/circular_buffer/base.hpp
==============================================================================
--- trunk/boost/circular_buffer/base.hpp (original)
+++ trunk/boost/circular_buffer/base.hpp 2008-01-23 18:04:57 EST (Wed, 23 Jan 2008)
@@ -909,8 +909,8 @@
                 used).
         \par Complexity
              Constant.
- \note This constructor has been defined only due to compatibility with the STL container definition. Avoid
- using it because it may allocate very large amount of memory.
+ \warning This constructor has been defined only due to compatibility with the STL container definition. Avoid
+ using it because it may allocate <b>very large</b> amount of memory.
     */
     explicit circular_buffer(const allocator_type& alloc = allocator_type())
     : m_size(0), m_alloc(alloc) {
@@ -1781,6 +1781,9 @@
              the erased element (towards the beginning).
         \par Complexity
              Linear (in <code>std::distance(begin(), pos)</code>).
+ \note This method is symetric to the <code>erase(iterator)</code> method and is more effective than
+ <code>erase(iterator)</code> if the iterator <code>pos</code> is close to the beginning of the
+ <code>circular_buffer</code>. (See the <i>Complexity</i>.)
         \sa <code>erase(iterator)</code>, <code>erase(iterator, iterator)</code>,
             <code>rerase(iterator, iterator)</code>, <code>clear()</code>
     */
@@ -1818,6 +1821,9 @@
              the erased range (towards the beginning).
         \par Complexity
              Linear (in <code>std::distance(begin(), last)</code>).
+ \note This method is symetric to the <code>erase(iterator, iterator)</code> method and is more effective than
+ <code>erase(iterator, iterator)</code> if <code>std::distance(begin(), first)</code> is lower that
+ <code>std::distance(last, end())</code>.
         \sa <code>erase(iterator)</code>, <code>erase(iterator, iterator)</code>, <code>rerase(iterator)</code>,
             <code>clear()</code>
     */

Modified: trunk/boost/circular_buffer/details.hpp
==============================================================================
--- trunk/boost/circular_buffer/details.hpp (original)
+++ trunk/boost/circular_buffer/details.hpp 2008-01-23 18:04:57 EST (Wed, 23 Jan 2008)
@@ -227,7 +227,7 @@
     //! Difference type.
     typedef typename base_iterator::difference_type difference_type;
 
-#if !defined(BOOST_CB_TEST) && !BOOST_CB_ENABLE_DEBUG
+#if !defined(BOOST_CB_TEST) && BOOST_CB_ENABLE_DEBUG == 0
 private:
 #endif
 // Member variables

Modified: trunk/boost/circular_buffer/space_optimized.hpp
==============================================================================
--- trunk/boost/circular_buffer/space_optimized.hpp (original)
+++ trunk/boost/circular_buffer/space_optimized.hpp 2008-01-23 18:04:57 EST (Wed, 23 Jan 2008)
@@ -1141,6 +1141,8 @@
              equal to <code>end()</code>).
         \par Complexity
              Linear (in the size of the <code>circular_buffer_space_optimized</code>).
+ \note Basically there is no difference between <code>erase(iterator)</code> and this method. It is implemented
+ only for consistency with the base <code>circular_buffer</code>.
         \sa <code>erase(iterator)</code>, <code>erase(iterator, iterator)</code>,
             <code>rerase(iterator, iterator)</code>, <code>clear()</code>
     */
@@ -1171,6 +1173,9 @@
              equal to <code>end()</code>).
         \par Complexity
              Linear (in the size of the <code>circular_buffer_space_optimized</code>).
+ \note Basically there is no difference between <code>erase(iterator, iterator)</code> and this method. It is
+ implemented only for consistency with the base
+ <code>circular_buffer</code>.
         \sa <code>erase(iterator)</code>, <code>erase(iterator, iterator)</code>, <code>rerase(iterator)</code>,
             <code>clear()</code>
     */

Modified: trunk/libs/circular_buffer/doc/circular_buffer.html
==============================================================================
--- trunk/libs/circular_buffer/doc/circular_buffer.html (original)
+++ trunk/libs/circular_buffer/doc/circular_buffer.html 2008-01-23 18:04:57 EST (Wed, 23 Jan 2008)
@@ -30,6 +30,11 @@
     <a href="#briefexample">Introductory Example</a><br>
     <a href="#synopsis">Synopsis</a><br>
     <a href="#rationale">Rationale</a><br>
+ - Thread-Safety<br>
+ - Overwrite Operation<br>
+ - Writing to a Full Buffer<br>
+ - Reading/Removing from an Empty Buffer<br>
+ - Iterator Invalidation<br>
     <a href="#caveats">Caveats</a><br>
     <a href="#debug">Debug Support</a><br>
     <a href="#examples">More Examples</a><br>
@@ -366,9 +371,10 @@
     </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.
+ implementations. This means the <code>circular_buffer</code> is <b>not</b> thread-safe. The thread-safety is
+ guarantied only in the sense that simultaneous accesses to <b>distinct</b> 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
@@ -378,7 +384,7 @@
       Buffer Example</a>.)
     </p>
     <h4>
- Overwrite Operation
+ <a name="overwrite" id="overwrite">Overwrite Operation</a>
     </h4>
     <p>
       Overwrite operation occurs when an element is inserted into a full <code>circular_buffer</code> - the old element
@@ -397,7 +403,7 @@
       being shifted (e.g. as a result of insertion into the middle of container).
     </p>
     <h4>
- Writing to a Full Buffer
+ <a name="fullbuffer" id="fullbuffer">Writing to a Full Buffer</a>
     </h4>
     <p>
       There are several options how to cope with the case if a data source produces more data than can fit in the
@@ -429,7 +435,7 @@
       contrary to <code>std::vector</code>, it bears an overhead for its circular behaviour.
     </p>
     <h4>
- Reading/Removing from an Empty Buffer
+ <a name="emptybuffer" id="emptybuffer">Reading/Removing from an Empty Buffer</a>
     </h4>
     <p>
       When reading or removing an element from an empty buffer, the buffer should be able to notify the data consumer
@@ -450,7 +456,7 @@
       which throws an exception when the index is out of range.
     </p>
     <h4>
- Iterator Invalidation
+ <a name="iteratorinvalidation" id="iteratorinvalidation">Iterator Invalidation</a>
     </h4>
     <p>
       An iterator is usually considered to be invalidated if an element, the iterator pointed to, had been removed or
@@ -933,11 +939,11 @@
             </dl>
             <dl>
               <dt>
- <b>Note:</b>
+ <b>Warning:</b>
               </dt>
               <dd>
                 This constructor has been defined only due to compatibility with the STL container definition. Avoid
- using it because it may allocate very large amount of memory.
+ using it because it may allocate <b>very large</b> amount of memory.
               </dd>
             </dl>
           </td>
@@ -5986,6 +5992,19 @@
             </dl>
             <dl>
               <dt>
+ <b>Note:</b>
+ </dt>
+ <dd>
+ This method is symetric to the <code><a href=
+ "#classboost_1_1circular__buffer_197155de712db1759e1698455b49a0be3">erase(iterator)</a></code> method
+ and is more effective than <code><a href=
+ "#classboost_1_1circular__buffer_197155de712db1759e1698455b49a0be3">erase(iterator)</a></code> if the
+ iterator <code>pos</code> is close to the beginning of the <code>circular_buffer</code>. (See the
+ <i>Complexity</i>.)
+ </dd>
+ </dl>
+ <dl>
+ <dt>
                 <b>See Also:</b>
               </dt>
               <dd>
@@ -6097,6 +6116,21 @@
             </dl>
             <dl>
               <dt>
+ <b>Note:</b>
+ </dt>
+ <dd>
+ This method is symetric to the <code><a href=
+ "#classboost_1_1circular__buffer_1a96415389509a18bd7d7b5d8e4dda9bd">erase(iterator,
+ iterator)</a></code> method and is more effective than <code><a href=
+ "#classboost_1_1circular__buffer_1a96415389509a18bd7d7b5d8e4dda9bd">erase(iterator,
+ iterator)</a></code> if <code>std::distance(<a href=
+ "#classboost_1_1circular__buffer_158d1ede2e85f5d46eda8db3f0c4efef0">begin()</a>, first)</code> is lower
+ that <code>std::distance(last, <a href=
+ "#classboost_1_1circular__buffer_1babfa093dad7801223b80626b598dee1">end()</a>)</code>.
+ </dd>
+ </dl>
+ <dl>
+ <dt>
                 <b>See Also:</b>
               </dt>
               <dd>

Modified: trunk/libs/circular_buffer/doc/space_optimized.html
==============================================================================
--- trunk/libs/circular_buffer/doc/space_optimized.html (original)
+++ trunk/libs/circular_buffer/doc/space_optimized.html 2008-01-23 18:04:57 EST (Wed, 23 Jan 2008)
@@ -3922,6 +3922,17 @@
             </dl>
             <dl>
               <dt>
+ <b>Note:</b>
+ </dt>
+ <dd>
+ Basically there is no difference between <code><a href=
+ "#classboost_1_1circular__buffer__space__optimized_136feadef225bd8a10962a92c4ffcdfd3">erase(iterator)</a></code>
+ and this method. It is implemented only for consistency with the base <code><a href=
+ "circular_buffer.html">circular_buffer</a></code>.
+ </dd>
+ </dl>
+ <dl>
+ <dt>
                 <b>See Also:</b>
               </dt>
               <dd>
@@ -4043,6 +4054,17 @@
             </dl>
             <dl>
               <dt>
+ <b>Note:</b>
+ </dt>
+ <dd>
+ Basically there is no difference between <code><a href=
+ "#classboost_1_1circular__buffer__space__optimized_19e9a4e0dfca27329da78e014d97201ca">erase(iterator,
+ iterator)</a></code> and this method. It is implemented only for consistency with the base
+ <code>circular_buffer</code>.
+ </dd>
+ </dl>
+ <dl>
+ <dt>
                 <b>See Also:</b>
               </dt>
               <dd>

Modified: trunk/libs/circular_buffer/test/base_test.cpp
==============================================================================
--- trunk/libs/circular_buffer/test/base_test.cpp (original)
+++ trunk/libs/circular_buffer/test/base_test.cpp 2008-01-23 18:04:57 EST (Wed, 23 Jan 2008)
@@ -189,7 +189,6 @@
     BOOST_CHECK(!(end - 1 < it));
 }
 
-// TODO add insert, push_back etc.
 void iterator_invalidation_test() {
 
 #if !defined(NDEBUG) && !defined(BOOST_CB_DISABLE_DEBUG)

Modified: trunk/libs/circular_buffer/test/common.ipp
==============================================================================
--- trunk/libs/circular_buffer/test/common.ipp (original)
+++ trunk/libs/circular_buffer/test/common.ipp 2008-01-23 18:04:57 EST (Wed, 23 Jan 2008)
@@ -534,9 +534,11 @@
     BOOST_CHECK(cb1.reserve() == 0);
     BOOST_CHECK(cb1.full());
     BOOST_CHECK(cb1.empty());
+ BOOST_CHECK(cb1.reserve() == cb1.capacity() - cb1.size());
     BOOST_CHECK(cb2.capacity() == 10);
     BOOST_CHECK(cb2.size() == 0);
     BOOST_CHECK(cb2.reserve() == 10);
+ BOOST_CHECK(cb2.reserve() == cb2.capacity() - cb2.size());
 
     cb1.push_back(1);
     cb2.push_back(2);
@@ -548,9 +550,11 @@
     BOOST_CHECK(cb1.reserve() == 0);
     BOOST_CHECK(cb1.full());
     BOOST_CHECK(cb1.empty());
+ BOOST_CHECK(cb1.reserve() == cb1.capacity() - cb1.size());
     BOOST_CHECK(cb2.capacity() == 10);
     BOOST_CHECK(cb2.size() == 3);
     BOOST_CHECK(cb2.reserve() == 7);
+ BOOST_CHECK(cb2.reserve() == cb2.capacity() - cb2.size());
 
     generic_test(cb1);
     generic_test(cb2);


Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk