From 4fde9eda30fa34d07d4e9dd9930f39b6a668bfe6 Mon Sep 17 00:00:00 2001 From: Jan Gaspar Date: Thu, 23 Nov 2006 22:57:57 +0000 Subject: [PATCH] updated srcdoc [SVN r3447] --- doc/circular_buffer.html | 346 +++++++++++++++++++++++-- include/boost/circular_buffer/base.hpp | 80 +++++- 2 files changed, 393 insertions(+), 33 deletions(-) diff --git a/doc/circular_buffer.html b/doc/circular_buffer.html index 831162e..7cd1eb1 100644 --- a/doc/circular_buffer.html +++ b/doc/circular_buffer.html @@ -1321,6 +1321,15 @@ template <class T, class Alloc> Does not invalidate any iterator. +
+
+ See Also: +
+
+ get_allocator() +
+
@@ -1380,6 +1389,15 @@ template <class T, class Alloc> stateful allocators in STL is discouraged. +
+
+ See Also: +
+
+ get_allocator() + const +
+
@@ -1675,6 +1693,15 @@ template <class T, class Alloc> Does not invalidate any iterator. +
+
+ See Also: +
+
+ rend(), + begin() +
+
@@ -1728,6 +1755,14 @@ template <class T, class Alloc> Does not invalidate any iterator. +
+
+ See Also: +
+
+ rbegin() +
+
@@ -1780,6 +1815,15 @@ template <class T, class Alloc> Does not invalidate any iterator. +
+
+ See Also: +
+
+ rend() + const +
+
@@ -1833,6 +1877,15 @@ template <class T, class Alloc> Does not invalidate any iterator. +
+
+ See Also: +
+
+ rbegin() + const +
+
@@ -1892,6 +1945,15 @@ template <class T, class Alloc> Does not invalidate any iterator. +
+
+ See Also: +
+
+ at(size_type) +
+
@@ -1952,6 +2014,15 @@ template <class T, class Alloc> Does not invalidate any iterator. +
+
+ See Also: +
+
+ at(size_type) + const +
+
@@ -2003,6 +2074,15 @@ template <class T, class Alloc> Does not invalidate any iterator. +
+
+ See Also: +
+
+ operator[](size_type) +
+
@@ -2055,6 +2135,15 @@ template <class T, class Alloc> Does not invalidate any iterator. +
+
+ See Also: +
+
+ operator[](size_type) + const +
+
@@ -2112,6 +2201,14 @@ template <class T, class Alloc> Does not invalidate any iterator. +
+
+ See Also: +
+
+ back() +
+
@@ -2169,6 +2266,14 @@ template <class T, class Alloc> Does not invalidate any iterator. +
+
+ See Also: +
+
+ front() +
+
@@ -2227,6 +2332,15 @@ template <class T, class Alloc> Does not invalidate any iterator. +
+
+ See Also: +
+
+ back() + const +
+
@@ -2285,6 +2399,15 @@ template <class T, class Alloc> Does not invalidate any iterator. +
+
+ See Also: +
+
+ front() + const +
+
@@ -2312,7 +2435,7 @@ template <class T, class Alloc> end ---^
begin -------^

- where |a|b|c|d| represents the 'array one', |e|f|g| represents the 'array two' + where |a|b|c|d| represents the "array one", |e|f|g| represents the "array two" and | | | | is a free space.
Now consider a typical C style function for writting data into a file:

@@ -2337,8 +2460,8 @@ template <class T, class Alloc> As the complexity of array_one() and array_two() - methods is constant the first option is suitable when calling the write method is 'cheap'. On the other - hand the second option is more suitable when calling the write method is more 'expensive' than calling + methods is constant the first option is suitable when calling the write method is "cheap". On the other + hand the second option is more suitable when calling the write method is more "expensive" than calling the linearize() method whose complexity is linear. @@ -2348,7 +2471,87 @@ template <class T, class Alloc> Returns:
- The array range of the first continuos array of the internal buffer. + The array range of the first continuos array of the internal buffer. In the case the + circular_buffer is empty the size of the returned array is 0. +
+ +
+
+ Throws: +
+
+ Nothing. +
+
+
+
+ Complexity: +
+
+ Constant. +
+
+
+
+ Exception Safety: +
+
+ No-throw. +
+
+
+
+ Iterator Invalidation: +
+
+ Does not invalidate any iterator. +
+
+
+
+ Note: +
+
+ In the case the internal buffer is linear e.g. |a|b|c|d|e|f|g| | | | the "array one" is + represented by |a|b|c|d|e|f|g| and the "array two" does not exist (the array_two() method + returns an array with the size 0). +
+
+
+
+ See Also: +
+
+ array_two(), + linearize() +
+
+ + + + + array_range + array_two();
+
+ Get the second continuos array of the internal buffer. +

+ This method in combination with array_one() can be useful + when passing the stored data into the legacy C API as an array. +

+
+
+ Returns: +
+
+ The array range of the second continuos array of the internal buffer. In the case the internal buffer + is linear or the circular_buffer is empty the size of the returned array is + 0.
@@ -2389,26 +2592,11 @@ template <class T, class Alloc>
array_two(), - linearize(), - array_one() - const + "#classboost_1_1circular__buffer_1957cccdcb0c4ef7d80a34a990065818d">array_one()
- - - array_range - array_two();
-
- TODO doc.
-
- - const_array_range array_one() const;

- TODO doc.
-
+ Get the first continuos array of the internal buffer. +

+ This method in combination with array_two() const can be + useful when passing the stored data into the legacy C API as an array. +

+
+
+ Returns: +
+
+ The array range of the first continuos array of the internal buffer. In the case the + circular_buffer is empty the size of the returned array is 0. +
+
+
+
+ Throws: +
+
+ Nothing. +
+
+
+
+ Complexity: +
+
+ Constant. +
+
+
+
+ Exception Safety: +
+
+ No-throw. +
+
+
+
+ Iterator Invalidation: +
+
+ Does not invalidate any iterator. +
+
+
+
+ See Also: +
+
+ array_one() for more + details.how to pass data into the legacy C API. +
+
@@ -2427,8 +2670,63 @@ template <class T, class Alloc> "#classboost_1_1circular__buffer_11885d7f475b7e7a74c95b2448d243025">const_array_range array_two() const;

- TODO doc.
-
+ Get the second continuos array of the internal buffer. +

+ This method in combination with array_one() const can be + useful when passing the stored data into the legacy C API as an array. +

+
+
+ Returns: +
+
+ The array range of the second continuos array of the internal buffer. In the case the internal buffer + is linear or the circular_buffer is empty the size of the returned array is + 0. +
+
+
+
+ Throws: +
+
+ Nothing. +
+
+
+
+ Complexity: +
+
+ Constant. +
+
+
+
+ Exception Safety: +
+
+ No-throw. +
+
+
+
+ Iterator Invalidation: +
+
+ Does not invalidate any iterator. +
+
+
+
+ See Also: +
+
+ array_one() + const +
+
diff --git a/include/boost/circular_buffer/base.hpp b/include/boost/circular_buffer/base.hpp index df9295b..59729de 100644 --- a/include/boost/circular_buffer/base.hpp +++ b/include/boost/circular_buffer/base.hpp @@ -184,6 +184,7 @@ public: No-throw. \par Iterator Invalidation Does not invalidate any iterator. + \sa get_allocator() */ allocator_type get_allocator() const { return m_alloc; } @@ -199,6 +200,7 @@ public: Does not invalidate any iterator. \note This method was added in order to optimize obtaining of the allocator with a state, although use of stateful allocators in STL is discouraged. + \sa get_allocator() const */ allocator_type& get_allocator() { return m_alloc; } @@ -279,6 +281,7 @@ public: No-throw. \par Iterator Invalidation Does not invalidate any iterator. + \sa rend(), begin() */ reverse_iterator rbegin() { return reverse_iterator(end()); } @@ -294,6 +297,7 @@ public: No-throw. \par Iterator Invalidation Does not invalidate any iterator. + \sa rbegin() */ reverse_iterator rend() { return reverse_iterator(begin()); } @@ -309,6 +313,7 @@ public: No-throw. \par Iterator Invalidation Does not invalidate any iterator. + \sa rend() const */ const_reverse_iterator rbegin() const { return const_reverse_iterator(end()); } @@ -324,6 +329,7 @@ public: No-throw. \par Iterator Invalidation Does not invalidate any iterator. + \sa rbegin() const */ const_reverse_iterator rend() const { return const_reverse_iterator(begin()); } @@ -338,6 +344,7 @@ public: No-throw. \par Iterator Invalidation Does not invalidate any iterator. + \sa at(size_type) */ reference operator [] (size_type index) { BOOST_CB_ASSERT(index < size()); // check for invalid index @@ -355,6 +362,7 @@ public: Strong. \par Iterator Invalidation Does not invalidate any iterator. + \sa at(size_type) const */ return_value_type operator [] (size_type index) const { BOOST_CB_ASSERT(index < size()); // check for invalid index @@ -371,6 +379,7 @@ public: Strong. \par Iterator Invalidation Does not invalidate any iterator. + \sa operator[](size_type) */ reference at(size_type index) { check_position(index); @@ -387,6 +396,7 @@ public: Strong. \par Iterator Invalidation Does not invalidate any iterator. + \sa operator[](size_type) const */ return_value_type at(size_type index) const { check_position(index); @@ -404,6 +414,7 @@ public: No-throw. \par Iterator Invalidation Does not invalidate any iterator. + \sa back() */ reference front() { BOOST_CB_ASSERT(!empty()); // check for empty buffer (front element not available) @@ -421,6 +432,7 @@ public: No-throw. \par Iterator Invalidation Does not invalidate any iterator. + \sa front() */ reference back() { BOOST_CB_ASSERT(!empty()); // check for empty buffer (back element not available) @@ -438,6 +450,7 @@ public: No-throw. \par Iterator Invalidation Does not invalidate any iterator. + \sa back() const */ return_value_type front() const { BOOST_CB_ASSERT(!empty()); // check for empty buffer (front element not available) @@ -455,6 +468,7 @@ public: No-throw. \par Iterator Invalidation Does not invalidate any iterator. + \sa front() const */ return_value_type back() const { BOOST_CB_ASSERT(!empty()); // check for empty buffer (back element not available) @@ -473,7 +487,7 @@ public: |e|f|g| | | |a|b|c|d|
end ---^
begin -------^

- where |a|b|c|d| represents the 'array one', |e|f|g| represents the 'array two' and + where |a|b|c|d| represents the "array one", |e|f|g| represents the "array two" and | | | | is a free space.
Now consider a typical C style function for writting data into a file:

int write(int file_desc, char* buff, int num_bytes);

@@ -482,14 +496,15 @@ public: array_range ar = cbuff.array_one();
write(file_desc, ar.first, ar.second);
ar = cbuff.array_two();
- write(file_desc, ar.first, ar.second);

+ write(file_desc, ar.first, ar.second);

Or relying on the linearize() method:

write(file_desc, cbuff.linearize(), cbuff.size());

As the complexity of array_one() and array_two() methods is constant the first option - is suitable when calling the write method is 'cheap'. On the other hand the second option is more suitable when - calling the write method is more 'expensive' than calling the linearize() method whose complexity + is suitable when calling the write method is "cheap". On the other hand the second option is more suitable when + calling the write method is more "expensive" than calling the linearize() method whose complexity is linear. - \return The array range of the first continuos array of the internal buffer. + \return The array range of the first continuos array of the internal buffer. In the case the + circular_buffer is empty the size of the returned array is 0. \throws Nothing. \par Complexity Constant. @@ -497,23 +512,70 @@ public: No-throw. \par Iterator Invalidation Does not invalidate any iterator. - \sa array_two(), linearize(), array_one() const + \note In the case the internal buffer is linear e.g. |a|b|c|d|e|f|g| | | | the "array one" is + represented by |a|b|c|d|e|f|g| and the "array two" does not exist (the + array_two() method returns an array with the size 0). + \sa array_two(), linearize() */ array_range array_one() { return array_range(m_first, (m_last <= m_first && !empty() ? m_end : m_last) - m_first); } - //! TODO doc + //! Get the second continuos array of the internal buffer. + /*! + This method in combination with array_one() can be useful when passing the stored data into the + legacy C API as an array. + \return The array range of the second continuos array of the internal buffer. In the case the internal buffer + is linear or the circular_buffer is empty the size of the returned array is + 0. + \throws Nothing. + \par Complexity + Constant. + \par Exception Safety + No-throw. + \par Iterator Invalidation + Does not invalidate any iterator. + \sa array_one() + */ array_range array_two() { return array_range(m_buff, m_last <= m_first && !empty() ? m_last - m_buff : 0); } - //! TODO doc + //! Get the first continuos array of the internal buffer. + /*! + This method in combination with array_two() const can be useful when passing the stored data into + the legacy C API as an array. + \return The array range of the first continuos array of the internal buffer. In the case the + circular_buffer is empty the size of the returned array is 0. + \throws Nothing. + \par Complexity + Constant. + \par Exception Safety + No-throw. + \par Iterator Invalidation + Does not invalidate any iterator. + \sa array_one() for more details.how to pass data into the legacy C API. + */ const_array_range array_one() const { return const_array_range(m_first, (m_last <= m_first && !empty() ? m_end : m_last) - m_first); } - //! TODO doc + //! Get the second continuos array of the internal buffer. + /*! + This method in combination with array_one() const can be useful when passing the stored data into + the legacy C API as an array. + \return The array range of the second continuos array of the internal buffer. In the case the internal buffer + is linear or the circular_buffer is empty the size of the returned array is + 0. + \throws Nothing. + \par Complexity + Constant. + \par Exception Safety + No-throw. + \par Iterator Invalidation + Does not invalidate any iterator. + \sa array_one() const + */ const_array_range array_two() const { return const_array_range(m_buff, m_last <= m_first && !empty() ? m_last - m_buff : 0); }