|
|
Boost-Commit : |
From: jano_gaspar_at_[hidden]
Date: 2008-01-23 18:36:39
Author: jano_gaspar
Date: 2008-01-23 18:36:38 EST (Wed, 23 Jan 2008)
New Revision: 42942
URL: http://svn.boost.org/trac/boost/changeset/42942
Log:
circular_buffer: updated documentation
Text files modified:
branches/release/boost/circular_buffer/base.hpp | 10 ++++++-
branches/release/boost/circular_buffer/debug.hpp | 2
branches/release/boost/circular_buffer/details.hpp | 2
branches/release/boost/circular_buffer/space_optimized.hpp | 7 ++++
branches/release/libs/circular_buffer/doc/circular_buffer.html | 52 +++++++++++++++++++++++++++++++++------
branches/release/libs/circular_buffer/doc/space_optimized.html | 22 ++++++++++++++++
branches/release/libs/circular_buffer/test/common.ipp | 4 +++
7 files changed, 85 insertions(+), 14 deletions(-)
Modified: branches/release/boost/circular_buffer/base.hpp
==============================================================================
--- branches/release/boost/circular_buffer/base.hpp (original)
+++ branches/release/boost/circular_buffer/base.hpp 2008-01-23 18:36:38 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: branches/release/boost/circular_buffer/debug.hpp
==============================================================================
--- branches/release/boost/circular_buffer/debug.hpp (original)
+++ branches/release/boost/circular_buffer/debug.hpp 2008-01-23 18:36:38 EST (Wed, 23 Jan 2008)
@@ -121,7 +121,7 @@
*/
void unregister_iterator(const debug_iterator_base* it) const {
const debug_iterator_base* previous = 0;
- for (const debug_iterator_base* p = m_iterators; p != it; previous = p, p = p->next());
+ for (const debug_iterator_base* p = m_iterators; p != it; previous = p, p = p->next()) {}
remove(it, previous);
}
Modified: branches/release/boost/circular_buffer/details.hpp
==============================================================================
--- branches/release/boost/circular_buffer/details.hpp (original)
+++ branches/release/boost/circular_buffer/details.hpp 2008-01-23 18:36:38 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: branches/release/boost/circular_buffer/space_optimized.hpp
==============================================================================
--- branches/release/boost/circular_buffer/space_optimized.hpp (original)
+++ branches/release/boost/circular_buffer/space_optimized.hpp 2008-01-23 18:36:38 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>
*/
@@ -1230,7 +1235,7 @@
if (new_size > new_capacity) {
if (new_capacity == 0)
new_capacity = 1;
- for (; new_size > new_capacity; new_capacity *= 2);
+ for (; new_size > new_capacity; new_capacity *= 2) {}
circular_buffer<T, Alloc>::set_capacity(
ensure_reserve(new_capacity, new_size));
}
Modified: branches/release/libs/circular_buffer/doc/circular_buffer.html
==============================================================================
--- branches/release/libs/circular_buffer/doc/circular_buffer.html (original)
+++ branches/release/libs/circular_buffer/doc/circular_buffer.html 2008-01-23 18:36:38 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: branches/release/libs/circular_buffer/doc/space_optimized.html
==============================================================================
--- branches/release/libs/circular_buffer/doc/space_optimized.html (original)
+++ branches/release/libs/circular_buffer/doc/space_optimized.html 2008-01-23 18:36:38 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: branches/release/libs/circular_buffer/test/common.ipp
==============================================================================
--- branches/release/libs/circular_buffer/test/common.ipp (original)
+++ branches/release/libs/circular_buffer/test/common.ipp 2008-01-23 18:36:38 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