|
From: Jan G. <jan...@us...> - 2007-04-15 22:52:35
|
Update of /cvsroot/boost-sandbox/boost-sandbox/boost/circular_buffer In directory sc8-pr-cvs3.sourceforge.net:/tmp/cvs-serv4782/boost/circular_buffer Modified Files: base.hpp space_optimized.hpp Log Message: circular_buffer: updated srcdoc and test cases Index: space_optimized.hpp =================================================================== RCS file: /cvsroot/boost-sandbox/boost-sandbox/boost/circular_buffer/space_optimized.hpp,v retrieving revision 1.26 retrieving revision 1.27 diff -u -d -r1.26 -r1.27 --- space_optimized.hpp 9 Apr 2007 22:06:13 -0000 1.26 +++ space_optimized.hpp 15 Apr 2007 22:52:33 -0000 1.27 @@ -522,19 +522,87 @@ */ ~circular_buffer_space_optimized(); - //! TODO doc + //! The assign operator. + /*! + Makes this <code>circular_buffer_space_optimized</code> to become a copy of the specified + <code>circular_buffer_space_optimized</code>. + \post <code>*this == cb</code> + \param cb The <code>circular_buffer_space_optimized</code> to be copied. + \throws "An allocation error" if memory is exhausted (<code>std::bad_alloc</code> if the standard allocator is + used). + \throws Whatever <code>T::T(const T&)</code> throws. + \par Exception Safety + Strong. + \par Iterator Invalidation + Invalidates all iterators pointing to this <code>circular_buffer_space_optimized</code> (except iterators + equal to end()). + \par Complexity + Linear (in the size of <code>cb</code>). + \sa <code>\link assign(size_type, param_value_type) assign(size_type, const_reference)\endlink</code>, + <code>\link assign(capacity_type, size_type, param_value_type) + assign(capacity_type, size_type, const_reference)\endlink</code>, + <code>assign(InputIterator, InputIterator)</code>, + <code>assign(capacity_type, InputIterator, InputIterator)</code> + */ circular_buffer_space_optimized<T, Alloc>& operator = (const circular_buffer_space_optimized<T, Alloc>& cb); #endif // #if defined(BOOST_CB_NEVER_DEFINED) - //! See the circular_buffer source documentation. + //! Assign <code>n</code> items into the space optimized circular buffer. + /*! + The content of the <code>circular_buffer_space_optimized</code> will be removed and replaced with + <code>n</code> copies of the <code>item</code>. + \post <code>capacity().%capacity() == n \&\& capacity().min_capacity() == 0 \&\& size() == n \&\& (*this)[0] == + item \&\& (*this)[1] == item \&\& ... \&\& (*this) [n - 1] == item</code> + \param n The number of elements the <code>circular_buffer_space_optimized</code> will be filled with. + \param item The element the <code>circular_buffer_space_optimized</code> will be filled with. + \throws "An allocation error" if memory is exhausted (<code>std::bad_alloc</code> if the standard allocator is + used). + \throws Whatever <code>T::T(const T&)</code> throws. + \par Exception Safety + Basic. + \par Iterator Invalidation + Invalidates all iterators pointing to the <code>circular_buffer_space_optimized</code> (except iterators + equal to end()). + \par Complexity + Linear (in the <code>n</code>). + \sa <code>operator=</code>, <code>\link assign(capacity_type, size_type, param_value_type) + assign(capacity_type, size_type, const_reference)\endlink</code>, + <code>assign(InputIterator, InputIterator)</code>, + <code>assign(capacity_type, InputIterator, InputIterator)</code> + */ void assign(size_type n, param_value_type item) { circular_buffer<T, Alloc>::assign(n, item); m_capacity_ctrl.m_capacity = n; m_capacity_ctrl.m_min_capacity = 0; } - //! See the circular_buffer source documentation. + //! Assign <code>n</code> items into the space optimized circular buffer specifying the capacity. + /*! + The capacity of the <code>circular_buffer_space_optimized</code> will be set to the specified value and the + content of the <code>circular_buffer_space_optimized</code> will be removed and replaced with <code>n</code> + copies of the <code>item</code>. + \pre <code>capacity_ctrl.%capacity() >= n</code> + \post <code>capacity() == capacity_ctrl \&\& size() == n \&\& (*this)[0] == item \&\& (*this)[1] == item + \&\& ... \&\& (*this) [n - 1] == item </code><br><br> + The amount of allocated memory will be <code>max[n, capacity_ctrl.min_capacity()]</code>. + \param capacity_ctrl The new capacity controller. + \param n The number of elements the <code>circular_buffer_space_optimized</code> will be filled with. + \param item The element the <code>circular_buffer_space_optimized</code> will be filled with. + \throws "An allocation error" if memory is exhausted (<code>std::bad_alloc</code> if the standard allocator is + used). + \throws Whatever <code>T::T(const T&)</code> throws. + \par Exception Safety + Basic. + \par Iterator Invalidation + Invalidates all iterators pointing to the <code>circular_buffer_space_optimized</code> (except iterators + equal to end()). + \par Complexity + Linear (in the <code>n</code>). + \sa <code>operator=</code>, <code>\link assign(size_type, param_value_type) + assign(size_type, const_reference)\endlink</code>, <code>assign(InputIterator, InputIterator)</code>, + <code>assign(capacity_type, InputIterator, InputIterator)</code> + */ void assign(capacity_type capacity_ctrl, size_type n, param_value_type item) { BOOST_CB_ASSERT(capacity_ctrl.m_capacity >= n); // check for new capacity lower than n circular_buffer<T, Alloc>::assign(std::max(capacity_ctrl.m_min_capacity, n), n, item); Index: base.hpp =================================================================== RCS file: /cvsroot/boost-sandbox/boost-sandbox/boost/circular_buffer/base.hpp,v retrieving revision 1.84 retrieving revision 1.85 diff -u -d -r1.84 -r1.85 --- base.hpp 9 Apr 2007 22:06:13 -0000 1.84 +++ base.hpp 15 Apr 2007 22:52:33 -0000 1.85 @@ -608,9 +608,11 @@ Basic; no-throw if the operations in the <i>Throws</i> section do not throw anything. \par Iterator Invalidation Invalidates all iterators pointing to the <code>circular_buffer</code> (except iterators equal to end()); - does not invalidate any iterators if the postcondition is already met prior calling this method. + does not invalidate any iterators if the postcondition (the <i>Effect</i>) is already met prior calling + this method. \par Complexity - Linear (in the size of the <code>circular_buffer</code>); constant if the postcondition is already met. + Linear (in the size of the <code>circular_buffer</code>); constant if the postcondition (the + <i>Effect</i>) is already met. \warning In general invoking any method which modifies the internal state of the <code>circular_buffer</code> may delinearize the internal buffer and invalidate the returned pointer. \sa <code>array_one()</code> and <code>array_two()</code> for the other option how to pass data into a legacy @@ -1087,7 +1089,7 @@ \par Exception Safety Strong. \par Iterator Invalidation - Invalidates all iterators pointing to this <code>circular_buffer</code>. + Invalidates all iterators pointing to this <code>circular_buffer</code> (except iterators equal to end()). \par Complexity Linear (in the size of <code>cb</code>). \sa <code>\link assign(size_type, param_value_type) assign(size_type, const_reference)\endlink</code>, @@ -1115,7 +1117,7 @@ The content of the <code>circular_buffer</code> will be removed and replaced with <code>n</code> copies of the <code>item</code>. \post <code>capacity() == n \&\& size() == n \&\& (*this)[0] == item \&\& (*this)[1] == item \&\& ... \&\& - (*this) [n - 1] == item </code> + (*this) [n - 1] == item</code> \param n The number of elements the <code>circular_buffer</code> will be filled with. \param item The element the <code>circular_buffer</code> will be filled with. \throws "An allocation error" if memory is exhausted (<code>std::bad_alloc</code> if the standard allocator is @@ -1124,7 +1126,7 @@ \par Exception Safety Basic. \par Iterator Invalidation - Invalidates all iterators pointing to the <code>circular_buffer</code>. + Invalidates all iterators pointing to the <code>circular_buffer</code> (except iterators equal to end()). \par Complexity Linear (in the <code>n</code>). \sa <code>operator=</code>, <code>\link assign(capacity_type, size_type, param_value_type) @@ -1136,14 +1138,14 @@ assign_n(n, n, cb_details::assign_n<param_value_type, allocator_type>(n, item, m_alloc)); } - //! Assign <code>n</code> items into the <code>circular_buffer</code> with the specified capacity. + //! Assign <code>n</code> items into the <code>circular_buffer</code> specifying the capacity. /*! The capacity of the <code>circular_buffer</code> will be set to the specified value and the content of the <code>circular_buffer</code> will be removed and replaced with <code>n</code> copies of the <code>item</code>. \pre <code>capacity >= n</code> \post <code>capacity() == capacity \&\& size() == n \&\& (*this)[0] == item \&\& (*this)[1] == item \&\& ... \&\& (*this) [n - 1] == item </code> - \param capacity The new capacity of the <code>circular_buffer</code>. + \param capacity The new capacity. \param n The number of elements the <code>circular_buffer</code> will be filled with. \param item The element the <code>circular_buffer</code> will be filled with. \throws "An allocation error" if memory is exhausted (<code>std::bad_alloc</code> if the standard allocator is @@ -1152,7 +1154,7 @@ \par Exception Safety Basic. \par Iterator Invalidation - Invalidates all iterators pointing to the <code>circular_buffer</code>. + Invalidates all iterators pointing to the <code>circular_buffer</code> (except iterators equal to end()). \par Complexity Linear (in the <code>n</code>). \sa <code>operator=</code>, <code>\link assign(size_type, param_value_type) @@ -1196,7 +1198,7 @@ assign(first, last, is_integral<InputIterator>()); } - //! Assign a copy of the range into the <code>circular_buffer</code> with the specified capacity. + //! Assign a copy of the range into the <code>circular_buffer</code> specifying the capacity. /*! The capacity of the <code>circular_buffer</code> will be set to the specified value and the content of the <code>circular_buffer</code> will be removed and replaced with copies of elements from the specified range. @@ -1210,7 +1212,7 @@ If the number of items to be copied from the range <code>[first, last)</code> is greater than the specified <code>capacity</code> then only elements from the range <code>[last - capacity, last)</code> will be copied. - \param capacity The new capacity of the <code>circular_buffer</code>. + \param capacity The new capacity. \param first The beginning of the range to be copied. \param last The end of the range to be copied. \throws "An allocation error" if memory is exhausted (<code>std::bad_alloc</code> if the standard allocator is |