diff --git a/doc/circular_buffer.html b/doc/circular_buffer.html index 4c5c660..47bef6b 100644 --- a/doc/circular_buffer.html +++ b/doc/circular_buffer.html @@ -998,6 +998,16 @@ template <class T, class Alloc> allocator_type());

Create an empty circular_buffer with the specified capacity. +
+
+ Effect: +
+
+ capacity() == + capacity && size() == 0 +
+
Parameter(s): @@ -1023,16 +1033,6 @@ template <class T, class Alloc>
-
-
- Effect: -
-
- capacity() == - capacity && size() == 0 -
-
Throws: @@ -1069,9 +1069,9 @@ template <class T, class Alloc>
capacity() == n - && size() == n - && (*this)[0] == item && (*this)[1] == item && ... && (*this) [n - 1] - == item + && full() + && (*this)[0] == item && (*this)[1] == item && ... && (*this)[n - 1] == + item
@@ -1294,7 +1294,7 @@ template <class T, class Alloc> "#classboost_1_1circular__buffer_14e07c6ddfe89debe384e59bed06e7cb7">allocator_type& alloc = allocator_type());

- Create a circular_buffer filled with a copy of the range. + Create a full circular_buffer filled with a copy of the range.
Precondition: @@ -1312,9 +1312,9 @@ template <class T, class Alloc>
capacity() == std::distance(first, last) && size() == std::distance(first, - last) && (*this)[0]== *first && (*this)[1] == *(first + 1) && ... && - (*this)[std::distance(first, last) - 1] == *(last - 1) + "#classboost_1_1circular__buffer_1fd0eef8ba91210d1575404b7e3e8207a">full() && (*this)[0]== + *first && (*this)[1] == *(first + 1) && ... && (*this)[std::distance(first, + last) - 1] == *(last - 1)
@@ -3670,7 +3670,7 @@ template <class T, class Alloc>
The element the circular_buffer will be filled with in order to gain the requested - size. (See the postcondition.) + size. (See the Effect.)
@@ -6781,7 +6781,7 @@ template <class T, class Alloc>

Use, modification, and distribution is subject to the Boost Software License, Version 1.0.
(See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt.) + "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt)

diff --git a/doc/circular_buffer_space_optimized.html b/doc/circular_buffer_space_optimized.html index 12c9a70..9347863 100644 --- a/doc/circular_buffer_space_optimized.html +++ b/doc/circular_buffer_space_optimized.html @@ -190,11 +190,11 @@ public: const capacity_type& capacity() const; void set_capacity(const capacity_type& new_capacity); +"#classboost_1_1circular__buffer__space__optimized_149f28bc5b33d2062b9f6a33b48264e3f">set_capacity(const capacity_type& capacity_ctrl); void resize(size_type new_size, const_reference item = value_type()); void rset_capacity(size_type new_capacity); +"#classboost_1_1circular__buffer__space__optimized_10f096c108ebde69ae83a9de41b3bea56">rset_capacity(const capacity_type& capacity_ctrl); void rresize(size_type new_size, const_reference item = value_type()); circular_buffer_space_optimized<T, Alloc>& Capacity controller of the space optimized circular buffer. 
-    struct capacity_control {
-       capacity_control(size_type capacity, size_type min_capacity = 0) m_capacity(capacity), m_min_capacity(min_capacity) {};
-       size_type m_capacity;
-       size_type m_min_capacity;
-    };
-        
+class capacity_control {
+   size_type m_capacity;
+   size_type m_min_capacity;
+public:
+   capacity_control(size_type capacity, size_type min_capacity = 0) : m_capacity(capacity), m_min_capacity(min_capacity) {};
+   size_type capacity() const { return m_capacity; }
+   size_type min_capacity() const { return m_min_capacity; }
+   operator size_type() const { return m_capacity; }
+};
@@ -337,11 +340,15 @@ template <class T, class Alloc>
capacity >= min_capacity
-
The m_capacity denotes the capacity of the circular_buffer_space_optimized - and the m_min_capacity determines the minimal allocated size of its internal buffer. The - converting constructor of the capacity_control allows implicit conversion from - size_type like types which ensures compatibility of creating an instance of the - circular_buffer_space_optimized with other STL containers. +
The m_capacity represents the capacity of the + circular_buffer_space_optimized and the m_min_capacity determines the minimal + allocated size of its internal buffer. The converting constructor of the capacity_control + allows implicit conversion from size_type-like types which ensures compatibility of creating + an instance of the circular_buffer_space_optimized with other STL containers. On the other + hand the operator size_type() (returning m_capacity) provides implicit conversion + to the size_type which allows to treat the capacity of the + circular_buffer_space_optimized the same way as in the circular_buffer. @@ -363,9 +370,55 @@ template <class T, class Alloc> alloc = allocator_type());

Create an empty space optimized circular buffer with a maximum capacity. -

- TODO - doc -

+
+
+ Effect: +
+
+ capacity().capacity() + == max_size() + && capacity().min_capacity() + == 0 && size() == + 0
+
+ There is no memory allocated in the internal buffer after execution of this constructor. +
+
+
+
+ Parameter(s): +
+
+
+
+ alloc +
+
+ The allocator. +
+
+
+
+
+
+ Throws: +
+
+ Nothing. +
+
+
+
+ Complexity: +
+
+ Constant. +
+
@@ -373,12 +426,24 @@ template <class T, class Alloc> explicit circular_buffer_space_optimized(capacity_type + "#classboost_1_1circular__buffer__space__optimized_1e805212e7de49dcb60f2cad1ef304bb3">capacity_type capacity_ctrl, const allocator_type& alloc = allocator_type());

Create an empty space optimized circular buffer with the specified capacity. +
+
+ Effect: +
+
+ capacity() == + capacity_ctrl && size() == + 0 +
+
Parameter(s): @@ -389,8 +454,8 @@ template <class T, class Alloc> capacity_ctrl
- The capacity of the buffer. (param min_capacity The minimal guaranteed amount of allocated memory.) - (The metrics of the min_capacity is number of items.) + The capacity controller representing the maximum number of elements which can be stored in the + circular_buffer_space_optimized and the minimal allocated size of the internal buffer.
@@ -405,25 +470,6 @@ template <class T, class Alloc> -
-
- Precondition: -
-
- capacity >= min_capacity -
-
-
-
- Effect: -
-
- (*this).capacity() == - capacity && (*this).size == 0
- Allocates memory specified by the min_capacity parameter. -
-
Throws: @@ -435,11 +481,10 @@ template <class T, class Alloc>
- Note: + Complexity:
- It is considered as a bug if the precondition is not met (i.e. if capacity < - min_capacity) and an assertion will be invoked in the debug mode. + Constant.
@@ -447,14 +492,28 @@ template <class T, class Alloc> circular_buffer_space_optimized(capacity_type + "classboost_1_1circular__buffer__space__optimized_1f8c9fa872f9a84d454d7e245cc2eadbd">circular_buffer_space_optimized(capacity_type capacity_ctrl, const_reference item, const allocator_type& alloc = allocator_type());

- Create a full space optimized circular buffer filled with copies of item. + Create a full space optimized circular buffer with the specified capacity (and the minimal guaranteed + amount of allocated memory) filled with capacity_ctrl.capacity() copies of item. +
+
+ Effect: +
+
+ capacity() == + capacity_ctrl && full() + && (*this)[0] == item && (*this)[1] == item && ... && (*this) + [capacity_ctrl.capacity() - 1] == item +
+
Parameter(s): @@ -465,8 +524,8 @@ template <class T, class Alloc> capacity_ctrl
- The capacity of the buffer. (param min_capacity The minimal guaranteed amount of allocated memory.) - (The metrics of the min_capacity is number of items.) + The capacity controller representing the maximum number of elements which can be stored in the + circular_buffer_space_optimized and the minimal allocated size of the internal buffer.
@@ -476,7 +535,7 @@ template <class T, class Alloc> item
- The item to be filled with. + The element the created circular_buffer_space_optimized will be filled with.
@@ -491,12 +550,48 @@ template <class T, class Alloc> +
+
+ Throws: +
+
+ An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is + used). +
+
+ Whatever T::T(const T&) throws. +
+
+
+
+ Complexity: +
+
+ Linear (in the capacity_ctrl.capacity()). +
+
+ + + + + circular_buffer_space_optimized(capacity_type + capacity_ctrl, size_type n, + const_reference + item, const allocator_type& + alloc = allocator_type());
+
+ Create a space optimized circular buffer with the specified capacity (and the minimal guaranteed amount of + allocated memory) filled with n copies of item.
Precondition:
- capacity >= min_capacity + capacity_ctrl.capacity() >= n
@@ -504,11 +599,61 @@ template <class T, class Alloc> Effect:
- (*this).size() == - capacity && (*this)[0] == (*this)[1] == ... == (*this).back() == - item + capacity() == + capacity_ctrl && size() == n + && (*this)[0] == item && (*this)[1] == item && ... && (*this)[n - 1] == + item
+
+ Allocates at least as much memory as specified by the capacity_ctrl.min_capacity(). +
+
+
+
+ Parameter(s): +
+
+
+
+ capacity_ctrl +
+
+ The capacity controller representing the maximum number of elements which can be stored in the + circular_buffer_space_optimized and the minimal allocated size of the internal buffer. +
+
+
+
+
+
+ n +
+
+ The number of elements the created circular_buffer_space_optimized will be filled + with. +
+
+
+
+
+
+ item +
+
+ The element the created circular_buffer_space_optimized will be filled with. +
+
+
+
+
+
+ alloc +
+
+ The allocator. +
+
@@ -520,44 +665,74 @@ template <class T, class Alloc> used).
- Whatever T::T(const T&) throws. + Whatever T::T(const T&) throws.
- Note: + Complexity:
- It is considered as a bug if the precondition is not met (i.e. if capacity < - min_capacity) and an assertion will be invoked in the debug mode. + Linear (in the n).
- - - circular_buffer_space_optimized(capacity_type - capacity_ctrl, size_type n, - const_reference - item, const allocator_type& - alloc = allocator_type());
-
- TODO doc.
-
- - circular_buffer_space_optimized(const circular_buffer_space_optimized<T,Alloc>& cb);

- TODO doc.
-
+ The copy constructor. +

+ Creates a copy of the specified circular_buffer_space_optimized. +

+
+
+ Effect: +
+
+ *this == cb
+
+ Allocates the exact amount of memory to store the content of cb. +
+
+
+
+ Parameter(s): +
+
+
+
+ cb +
+
+ The circular_buffer_space_optimized to be copied. +
+
+
+
+
+
+ Throws: +
+
+ An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is + used). +
+
+ Whatever T::T(const T&) throws. +
+
+
+
+ Complexity: +
+
+ Linear (in the size of cb). +
+
@@ -569,44 +744,43 @@ template <class T, class Alloc> "circular_buffer.html#classboost_1_1circular__buffer_14e07c6ddfe89debe384e59bed06e7cb7">allocator_type& alloc = allocator_type());

- TODO doc.
-
- - - - - template - <class InputIterator>
- circular_buffer_space_optimized(capacity_type - capacity_ctrl, InputIterator first, InputIterator last, const allocator_type& - alloc = allocator_type());
-
- Create a space optimized circular buffer with a copy of a range. + Create a full space optimized circular buffer filled with a copy of the range. +
+
+ Precondition: +
+
+ Valid range [first, last).
+ first and last have to meet the requirements of InputIterator. +
+
+
+
+ Effect: +
+
+ capacity().capacity() + == std::distance(first, last) && capacity().min_capacity() + == 0 && full() + && (*this)[0]== *first && (*this)[1] == *(first + 1) && ... && + (*this)[std::distance(first, last) - 1] == *(last - 1) +
+
Parameter(s):
-
-
-
- capacity_ctrl -
-
- The capacity of the buffer. (param min_capacity The minimal guaranteed amount of allocated memory.) - (The metrics of the min_capacity is number of items.) -
-
-
first
- The beginning of the range. + The beginning of the range to be copied.
@@ -616,7 +790,7 @@ template <class T, class Alloc> last
- The end of the range. + The end of the range to be copied.
@@ -631,12 +805,49 @@ template <class T, class Alloc> +
+
+ Throws: +
+
+ An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is + used). +
+
+ Whatever T::T(const T&) throws. +
+
+
+
+ Complexity: +
+
+ Linear (in the std::distance(first, last)). +
+
+ + + + + template + <class InputIterator>
+ circular_buffer_space_optimized(capacity_type + capacity_ctrl, InputIterator first, InputIterator last, const allocator_type& + alloc = allocator_type());
+
+ Create a space optimized circular buffer with the specified capacity (and the minimal guaranteed amount of + allocated memory) filled with a copy of the range.
Precondition:
- capacity >= min_capacity and valid range [first, last). + Valid range [first, last).
+ first and last have to meet the requirements of InputIterator.
@@ -644,14 +855,65 @@ template <class T, class Alloc> Effect:
- (*this).capacity() == - capacity
- Allocates at least as much memory as specified by the - TODO change min_capacity - parameter.
- If the number of items to copy from the range [first, last) is greater than the specified - capacity then only elements from the range [last - capacity, last) will be - copied. + capacity_ctrl && size() + <= std::distance(first, last) && (*this)[0]== (last - capacity_ctrl.capacity()) && + (*this)[1] == *(last - capacity_ctrl.capacity() + 1) && ... && + (*this)[capacity_ctrl.capacity() - 1] == *(last - 1)
+
+ Allocates at least as much memory as specified by the capacity_ctrl.min_capacity().
+
+ If the number of items to be copied from the range [first, last) is greater than the + specified capacity_ctrl.capacity() then only elements from the range [last - + capacity_ctrl.capacity(), last) will be copied. +
+
+
+
+ Parameter(s): +
+
+
+
+ capacity_ctrl +
+
+ The capacity controller representing the maximum number of elements which can be stored in the + circular_buffer_space_optimized and the minimal allocated size of the internal buffer. +
+
+
+
+
+
+ first +
+
+ The beginning of the range to be copied. +
+
+
+
+
+
+ last +
+
+ The end of the range to be copied. +
+
+
+
+
+
+ alloc +
+
+ The allocator. +
+
@@ -663,16 +925,15 @@ template <class T, class Alloc> used).
- Whatever T::T(const T&) throws. + Whatever T::T(const T&) throws.
- Note: + Complexity:
- It is considered as a bug if the precondition is not met (i.e. if capacity < - min_capacity) and an assertion will be invoked in the debug mode. + Linear (in the capacity_ctrl.capacity()/std::distance(first, last)).
@@ -683,8 +944,45 @@ template <class T, class Alloc> "classboost_1_1circular__buffer__space__optimized_16839c3ea656ff0f800e38096748fe8ac">~circular_buffer_space_optimized();

- TODO doc.
-
+ The destructor. +

+ Destroys the circular_buffer_space_optimized. +

+
+
+ Throws: +
+
+ Nothing. +
+
+
+
+ Iterator Invalidation: +
+
+ Invalidates all iterators pointing to the circular_buffer_space_optimized (including + iterators equal to end()). +
+
+
+
+ Complexity: +
+
+ Linear (in the size of the circular_buffer_space_optimized). +
+
+
+
+ See Also: +
+
+ clear() +
+
@@ -700,9 +998,57 @@ template <class T, class Alloc> "classboost_1_1circular__buffer__space__optimized_142f4a13c50904a4ac0bf746c88451954">bool full() const;

- See the circular_buffer source - documentation.
-
+ Is the circular_buffer_space_optimized full? +
+
+ Returns: +
+
+ true if the number of elements stored in the circular_buffer_space_optimized + equals the capacity of the circular_buffer_space_optimized; false otherwise. +
+
+
+
+ Throws: +
+
+ Nothing. +
+
+
+
+ Exception Safety: +
+
+ No-throw. +
+
+
+
+ Iterator Invalidation: +
+
+ Does not invalidate any iterators. +
+
+
+
+ Complexity: +
+
+ Constant (in the size of the circular_buffer_space_optimized). +
+
+
+
+ See Also: +
+
+ empty() +
+
@@ -712,9 +1058,64 @@ template <class T, class Alloc> "circular_buffer.html#classboost_1_1circular__buffer_19ba12c0142a21a7d960877c22fa3ea00">size_type reserve() const;

- See the circular_buffer source - documentation.
-
+ Get the maximum number of elements which can be inserted into the + circular_buffer_space_optimized without overwriting any of already stored elements. +
+
+ Returns: +
+
+ capacity() - + size() +
+
+
+
+ Throws: +
+
+ Nothing. +
+
+
+
+ Exception Safety: +
+
+ No-throw. +
+
+
+
+ Iterator Invalidation: +
+
+ Does not invalidate any iterators. +
+
+
+
+ Complexity: +
+
+ Constant (in the size of the circular_buffer_space_optimized). +
+
+
+
+ See Also: +
+
+ capacity(), + size(), + max_size() +
+
@@ -722,40 +1123,151 @@ template <class T, class Alloc> const capacity_type& + "#classboost_1_1circular__buffer__space__optimized_1e805212e7de49dcb60f2cad1ef304bb3">capacity_type& capacity() const;

- See the circular_buffer source - documentation.
-
+ Get the capacity of the circular_buffer_space_optimized. +
+
+ Returns: +
+
+ The capacity controller representing the maximum number of elements which can be stored in the + circular_buffer_space_optimized and the minimal allocated size of the internal buffer. +
+
+
+
+ Throws: +
+
+ Nothing. +
+
+
+
+ Exception Safety: +
+
+ No-throw. +
+
+
+
+ Iterator Invalidation: +
+
+ Does not invalidate any iterators. +
+
+
+
+ Complexity: +
+
+ Constant (in the size of the circular_buffer_space_optimized). +
+
+
+
+ See Also: +
+
+ reserve(), + size(), + max_size(), + set_capacity() +
+
- void + void set_capacity(const capacity_type& - new_capacity);
+ "#classboost_1_1circular__buffer__space__optimized_1e805212e7de49dcb60f2cad1ef304bb3">capacity_type& + capacity_ctrl);

- TODO Change the minimal guaranteed amount of allocated memory. -
-
- Precondition: -
-
- (*this).capacity() - >= new_min_capacity -
-
+ Change the capacity (and the minimal guaranteed amount of allocated memory) of the + circular_buffer_space_optimized.
Effect:
- (*this).min_capacity() == new_min_capacity Allocates memory specified by the - new_min_capacity parameter. + capacity() == + capacity_ctrl && size() + <= capacity_ctrl.capacity()
+
+ If the current number of elements stored in the circular_buffer_space_optimized is greater + than the desired new capacity then number of [size() - + capacity_ctrl.capacity()] last elements will be removed and the new size will be equal to + capacity_ctrl.capacity().
+
+ If the current number of elements stored in the circular_buffer_space_optimized is lower + than than the new capacity the allocated memory (in the internal buffer) may be accommodated as + necessary but it will never drop below capacity_ctrl.min_capacity(). +
+
+
+
+ Parameter(s): +
+
+
+
+ capacity_ctrl +
+
+ The new capacity controller. +
+
+
+
+
+
+ Throws: +
+
+ An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is + used). +
+
+ Whatever T::T(const T&) throws. +
+
+
+
+ Exception Safety: +
+
+ Strong. +
+
+
+
+ Iterator Invalidation: +
+
+ Invalidates all iterators pointing to the circular_buffer_space_optimized (except + iterators equal to end()). +
+
+
+
+ Complexity: +
+
+ Linear (in the size/new capacity of the circular_buffer_space_optimized).
@@ -763,27 +1275,25 @@ template <class T, class Alloc> Note:
- It is considered as a bug if the precondition is not met (i.e. if new_min_capacity > - (*this).capacity()) - and an assertion will be invoked in the debug mode. + To explicitly clear the extra allocated memory use the shrink-to-fit technique:
+
+ boost::circular_buffer_space_optimized<int> cb(1000);
+ ...
+ boost::circular_buffer_space_optimized<int>(cb).swap(cb);
+
+ For more information about the shrink-to-fit technique in STL see http://www.gotw.ca/gotw/054.htm.
- Precondition: + See Also:
- min_capacity() <= new_capacity -
-
-
-
- Note: -
-
- It is considered as a bug if the precondition is not met (i.e. if new_capacity > - min_capacity()) and an assertion will be invoked in the debug mode. + rset_capacity(), + resize()
@@ -798,36 +1308,200 @@ template <class T, class Alloc> "circular_buffer.html#classboost_1_1circular__buffer_1a8397191092f5bacee991b623ca4b910">const_reference item = value_type());

- See the circular_buffer source - documentation.
-
- - - - - void - rset_capacity(size_type - new_capacity);
-
- See the circular_buffer source - documentation. + Change the size of the circular_buffer_space_optimized.
- Precondition: + Effect:
- min_capacity() <= new_capacity + size() == + new_size && capacity().capacity() + >= new_size
+
+ If the new size is greater than the current size, copies of item will be inserted at the + back of the of the circular_buffer_space_optimized in order to achieve the desired + size. In the case the resulting size exceeds the current capacity the capacity will be set to + new_size.
+
+ If the current number of elements stored in the circular_buffer_space_optimized is greater + than the desired new size then number of [size() - + new_size] last elements will be removed. (The capacity will remain unchanged.)
- Note: + Parameter(s):
- It is considered as a bug if the precondition is not met (i.e. if new_capacity > - min_capacity()) and an assertion will be invoked in the debug mode. +
+
+ new_size +
+
+ The new size. +
+
+
+
+
+
+ item +
+
+ The element the circular_buffer_space_optimized will be filled with in order to gain + the requested size. (See the Effect.) +
+
+
+
+
+
+ Throws: +
+
+ An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is + used). +
+
+ Whatever T::T(const T&) throws. +
+
+
+
+ Exception Safety: +
+
+ Basic. +
+
+
+
+ Iterator Invalidation: +
+
+ Invalidates all iterators pointing to the circular_buffer_space_optimized (except + iterators equal to end()). +
+
+
+
+ Complexity: +
+
+ Linear (in the new size of the circular_buffer_space_optimized). +
+
+
+
+ See Also: +
+
+ rresize(), + set_capacity() +
+
+ + + + + void + rset_capacity(const capacity_type& + capacity_ctrl);
+
+ Change the capacity (and the minimal guaranteed amount of allocated memory) of the + circular_buffer_space_optimized. +
+
+ Effect: +
+
+ capacity() == + capacity_ctrl && size() + <= capacity_ctrl
+
+ If the current number of elements stored in the circular_buffer_space_optimized is greater + than the desired new capacity then number of [size() - + capacity_ctrl.capacity()] first elements will be removed and the new size will be equal + to capacity_ctrl.capacity().
+
+ If the current number of elements stored in the circular_buffer_space_optimized is lower + than than the new capacity the allocated memory (in the internal buffer) may be accommodated as + necessary but it will never drop below capacity_ctrl.min_capacity(). +
+
+
+
+ Parameter(s): +
+
+
+
+ capacity_ctrl +
+
+ The new capacity controller. +
+
+
+
+
+
+ Throws: +
+
+ An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is + used). +
+
+ Whatever T::T(const T&) throws. +
+
+
+
+ Exception Safety: +
+
+ Strong. +
+
+
+
+ Iterator Invalidation: +
+
+ Invalidates all iterators pointing to the circular_buffer_space_optimized (except + iterators equal to end()). +
+
+
+
+ Complexity: +
+
+ Linear (in the size/new capacity of the circular_buffer_space_optimized). +
+
+
+
+ See Also: +
+
+ set_capacity(), + rresize()
@@ -842,9 +1516,104 @@ template <class T, class Alloc> "circular_buffer.html#classboost_1_1circular__buffer_1a8397191092f5bacee991b623ca4b910">const_reference item = value_type());

- See the circular_buffer source - documentation.
-
+ Change the size of the circular_buffer_space_optimized. +
+
+ Effect: +
+
+ size() == + new_size && capacity().capacity() + >= new_size
+
+ If the new size is greater than the current size, copies of item will be inserted at the + front of the of the circular_buffer_space_optimized in order to achieve the desired + size. In the case the resulting size exceeds the current capacity the capacity will be set to + new_size.
+
+ If the current number of elements stored in the circular_buffer_space_optimized is greater + than the desired new size then number of [size() - + new_size] first elements will be removed. (The capacity will remain unchanged.) +
+
+
+
+ Parameter(s): +
+
+
+
+ new_size +
+
+ The new size. +
+
+
+
+
+
+ item +
+
+ The element the circular_buffer_space_optimized will be filled with in order to gain + the requested size. (See the Effect.) +
+
+
+
+
+
+ Throws: +
+
+ An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is + used). +
+
+ Whatever T::T(const T&) throws. +
+
+
+
+ Exception Safety: +
+
+ Basic. +
+
+
+
+ Iterator Invalidation: +
+
+ Invalidates all iterators pointing to the circular_buffer_space_optimized (except + iterators equal to end()). +
+
+
+
+ Complexity: +
+
+ Linear (in the new size of the circular_buffer_space_optimized). +
+
+
+
+ See Also: +
+
+ rresize(), + set_capacity() +
+
@@ -877,7 +1646,7 @@ template <class T, class Alloc> void assign(capacity_type + "#classboost_1_1circular__buffer__space__optimized_1e805212e7de49dcb60f2cad1ef304bb3">capacity_type capacity_ctrl, size_type n, template <class InputIterator>
void assign(capacity_type + "#classboost_1_1circular__buffer__space__optimized_1e805212e7de49dcb60f2cad1ef304bb3">capacity_type capacity_ctrl, InputIterator first, InputIterator last);

See the circular_buffer source diff --git a/doc/circular_buffer_space_optimized.xslt b/doc/circular_buffer_space_optimized.xslt index 1de5db4..511bad2 100644 --- a/doc/circular_buffer_space_optimized.xslt +++ b/doc/circular_buffer_space_optimized.xslt @@ -23,7 +23,7 @@ http://www.boost.org/LICENSE_1_0.txt) - + @@ -71,30 +71,6 @@ http://www.boost.org/LICENSE_1_0.txt) - diff --git a/include/boost/circular_buffer/base.hpp b/include/boost/circular_buffer/base.hpp index f934d42..f7b050d 100644 --- a/include/boost/circular_buffer/base.hpp +++ b/include/boost/circular_buffer/base.hpp @@ -52,9 +52,6 @@ namespace boost { The Alloc has to meet the allocator requirements imposed by STL. \par Default Alloc std::allocator - \author Jan Gaspar - \version 3.7 - \date 2007 For detailed documentation of the circular_buffer visit: http://www.boost.org/libs/circular_buffer/doc/circular_buffer.html @@ -64,7 +61,7 @@ class circular_buffer /*! \cond */ #if BOOST_CB_ENABLE_DEBUG : public cb_details::debug_iterator_registry -#endif // #if BOOST_CB_ENABLE_DEBUG +#endif /*! \endcond */ { @@ -800,7 +797,7 @@ public: capacity will remain unchanged.) \param new_size The new size. \param item The element the circular_buffer will be filled with in order to gain the requested - size. (See the postcondition.) + size. (See the Effect.) \throws "An allocation error" if memory is exhausted (std::bad_alloc if the standard allocator is used). \throws Whatever T::T(const T&) throws. @@ -912,9 +909,9 @@ public: //! Create an empty circular_buffer with the specified capacity. /*! + \post capacity() == capacity \&\& size() == 0 \param capacity The maximum number of elements which can be stored in the circular_buffer. \param alloc The allocator. - \post capacity() == capacity \&\& size() == 0 \throws "An allocation error" if memory is exhausted (std::bad_alloc if the standard allocator is used). \par Complexity @@ -927,8 +924,8 @@ public: /*! \brief Create a full circular_buffer with the specified capacity and filled with n copies of item. - \post capacity() == n \&\& size() == n \&\& (*this)[0] == item \&\& (*this)[1] == item \&\& ... \&\& - (*this) [n - 1] == item + \post capacity() == n \&\& full() \&\& (*this)[0] == item \&\& (*this)[1] == item \&\& ... \&\& + (*this)[n - 1] == item \param n The number of elements the created circular_buffer will be filled with. \param item The element the created circular_buffer will be filled with. \param alloc The allocator. @@ -988,7 +985,7 @@ public: BOOST_CATCH_END } -#if BOOST_WORKAROUND(BOOST_MSVC, <= 1200) +#if BOOST_WORKAROUND(BOOST_MSVC, < 1300) /*! \cond */ template @@ -1006,14 +1003,13 @@ public: #else - //! Create a circular_buffer filled with a copy of the range. + //! Create a full circular_buffer filled with a copy of the range. /*! \pre Valid range [first, last).
first and last have to meet the requirements of InputIterator. - \post capacity() == std::distance(first, last) \&\& size() == std::distance(first, last) \&\& - (*this)[0]== *first \&\& (*this)[1] == *(first + 1) \&\& ... \&\& (*this)[std::distance(first, last) - 1] - == *(last - 1) + \post capacity() == std::distance(first, last) \&\& full() \&\& (*this)[0]== *first \&\& + (*this)[1] == *(first + 1) \&\& ... \&\& (*this)[std::distance(first, last) - 1] == *(last - 1) \param first The beginning of the range to be copied. \param last The end of the range to be copied. \param alloc The allocator. @@ -1057,7 +1053,7 @@ public: initialize(capacity, first, last, is_integral()); } -#endif // #if BOOST_WORKAROUND(BOOST_MSVC, <= 1200) +#endif // #if BOOST_WORKAROUND(BOOST_MSVC, < 1300) //! The destructor. /*! @@ -2149,7 +2145,7 @@ private: clear(); insert(begin(), first, last); } else { -#if BOOST_WORKAROUND(BOOST_MSVC, <= 1200) +#if BOOST_WORKAROUND(BOOST_MSVC, < 1300) circular_buffer tmp(new_capacity, m_alloc); tmp.insert(begin(), first, last); #else diff --git a/include/boost/circular_buffer/details.hpp b/include/boost/circular_buffer/details.hpp index 8baa966..ded07d7 100644 --- a/include/boost/circular_buffer/details.hpp +++ b/include/boost/circular_buffer/details.hpp @@ -166,10 +166,10 @@ public: // Default assign operator. - // Get the capacity of the space optimized circular buffer. + //! Get the capacity of the space optimized circular buffer. Size capacity() const { return m_capacity; } - // Get the minimal capacity of the space optimized circular buffer. + //! Get the minimal capacity of the space optimized circular buffer. Size min_capacity() const { return m_min_capacity; } //! Size operator - returns the capacity of the space optimized circular buffer. diff --git a/include/boost/circular_buffer/space_optimized.hpp b/include/boost/circular_buffer/space_optimized.hpp index 7f42292..6478814 100644 --- a/include/boost/circular_buffer/space_optimized.hpp +++ b/include/boost/circular_buffer/space_optimized.hpp @@ -18,27 +18,18 @@ namespace boost { /*! \class circular_buffer_space_optimized \brief Space optimized circular buffer container adaptor. - \param T The type of the elements stored in the space optimized circular buffer. - \par Type Requirements T - The T has to be - SGIAssignable (SGI STL defined combination of - Assignable and CopyConstructible). - Moreover T has to be - DefaultConstructible if supplied as a default parameter when invoking some of the methods. - \param Alloc The allocator type used for all internal memory management. - \par Type Requirements Alloc - The Alloc has to meet the allocator requirements imposed by STL. - \par Default Alloc - std::allocator - \author Jan Gaspar - \version 1.4 - \date 2007 For detailed documentation of the space_optimized_circular_buffer visit: - http://www.boost.org/libs/circular_buffer/doc/circular_buffer_adaptor.html + http://www.boost.org/libs/circular_buffer/doc/circular_buffer_space_optimized.html */ template -class circular_buffer_space_optimized : private circular_buffer { +class circular_buffer_space_optimized : +/*! \cond */ +#if BOOST_CB_ENABLE_DEBUG +public +#endif +/*! \endcond */ +circular_buffer { public: // Typedefs @@ -63,27 +54,31 @@ public: //! Capacity controller of the space optimized circular buffer. /*! 

-    struct capacity_control {
-       capacity_control(size_type capacity, size_type min_capacity = 0) m_capacity(capacity), m_min_capacity(min_capacity) {};
-       size_type m_capacity;
-       size_type m_min_capacity;
-    };
-

+class capacity_control { + size_type m_capacity; + size_type m_min_capacity; +public: + capacity_control(size_type capacity, size_type min_capacity = 0) : m_capacity(capacity), m_min_capacity(min_capacity) {}; + size_type %capacity() const { return m_capacity; } + size_type min_capacity() const { return m_min_capacity; } + operator size_type() const { return m_capacity; } +};

\pre capacity >= min_capacity -

The m_capacity denotes the capacity of the - circular_buffer_space_optimized and the m_min_capacity - determines the minimal allocated size of its internal buffer.

-

The converting constructor of the capacity_control - allows implicit conversion from size_type like types - which ensures compatibility of creating an instance of the - circular_buffer_space_optimized with other STL containers.

+

The m_capacity represents the capacity of the circular_buffer_space_optimized and + the m_min_capacity determines the minimal allocated size of its internal buffer.

+

The converting constructor of the capacity_control allows implicit conversion from + size_type-like types which ensures compatibility of creating an instance of the + circular_buffer_space_optimized with other STL containers. On the other hand the operator + %size_type() (returning m_capacity) provides implicit conversion to the + size_type which allows to treat the capacity of the circular_buffer_space_optimized + the same way as in the circular_buffer.

*/ typedef cb_details::capacity_control capacity_type; #else /*! \cond */ typedef cb_details::capacity_control capacity_type; /*! \endcond */ -#endif +#endif // #if defined(BOOST_NO_MEMBER_TEMPLATE_FRIENDS) // Inherited @@ -118,13 +113,48 @@ private: public: // Overridden - //! See the circular_buffer source documentation. - bool full() const { return capacity() == size(); } + //! Is the circular_buffer_space_optimized full? + /*! + \return true if the number of elements stored in the circular_buffer_space_optimized + equals the capacity of the circular_buffer_space_optimized; false otherwise. + \throws Nothing. + \par Exception Safety + No-throw. + \par Iterator Invalidation + Does not invalidate any iterators. + \par Complexity + Constant (in the size of the circular_buffer_space_optimized). + \sa empty() + */ + bool full() const { return m_capacity_ctrl.capacity() == size(); } - //! See the circular_buffer source documentation. - size_type reserve() const { return capacity() - size(); } + /*! \brief Get the maximum number of elements which can be inserted into the + circular_buffer_space_optimized without overwriting any of already stored elements. + \return capacity() - size() + \throws Nothing. + \par Exception Safety + No-throw. + \par Iterator Invalidation + Does not invalidate any iterators. + \par Complexity + Constant (in the size of the circular_buffer_space_optimized). + \sa capacity(), size(), max_size() + */ + size_type reserve() const { return m_capacity_ctrl.capacity() - size(); } - //! See the circular_buffer source documentation. + //! Get the capacity of the circular_buffer_space_optimized. + /*! + \return The capacity controller representing the maximum number of elements which can be stored in the + circular_buffer_space_optimized and the minimal allocated size of the internal buffer. + \throws Nothing. + \par Exception Safety + No-throw. + \par Iterator Invalidation + Does not invalidate any iterators. + \par Complexity + Constant (in the size of the circular_buffer_space_optimized). + \sa reserve(), size(), max_size(), set_capacity() + */ const capacity_type& capacity() const { return m_capacity_ctrl; } #if defined(BOOST_CB_TEST) @@ -138,28 +168,69 @@ public: #endif // #if defined(BOOST_CB_TEST) - //! TODO Change the minimal guaranteed amount of allocated memory. - /*! - \pre (*this).capacity() >= new_min_capacity - \post (*this).min_capacity() == new_min_capacity - Allocates memory specified by the new_min_capacity parameter. - \note It is considered as a bug if the precondition is not met (i.e. if - new_min_capacity > (*this).capacity()) and an assertion - will be invoked in the debug mode. - - \pre min_capacity() <= new_capacity - \note It is considered as a bug if the precondition is not met (i.e. if - new_capacity > min_capacity()) and an assertion - will be invoked in the debug mode. + /*! \brief Change the capacity (and the minimal guaranteed amount of allocated memory) of the + circular_buffer_space_optimized. + \post capacity() == capacity_ctrl \&\& size() \<= capacity_ctrl.capacity()

+ If the current number of elements stored in the circular_buffer_space_optimized is greater + than the desired new capacity then number of [size() - capacity_ctrl.capacity()] last + elements will be removed and the new size will be equal to capacity_ctrl.capacity().

+ If the current number of elements stored in the circular_buffer_space_optimized is lower + than than the new capacity the allocated memory (in the internal buffer) may be accommodated as necessary + but it will never drop below capacity_ctrl.min_capacity(). + \param capacity_ctrl The new capacity controller. + \throws "An allocation error" if memory is exhausted (std::bad_alloc if the standard allocator is + used). + \throws Whatever T::T(const T&) throws. + \par Exception Safety + Strong. + \par Iterator Invalidation + Invalidates all iterators pointing to the circular_buffer_space_optimized (except iterators + equal to end()). + \par Complexity + Linear (in the size/new capacity of the circular_buffer_space_optimized). + \note To explicitly clear the extra allocated memory use the shrink-to-fit technique:

+ boost::%circular_buffer_space_optimized\ cb(1000);
+ ...
+ boost::%circular_buffer_space_optimized\(cb).swap(cb);

+ For more information about the shrink-to-fit technique in STL see + http://www.gotw.ca/gotw/054.htm. + \sa rset_capacity(), resize() */ - void set_capacity(const capacity_type& new_capacity) { - m_capacity_ctrl = new_capacity; - if (new_capacity.capacity() < circular_buffer::capacity()) - circular_buffer::set_capacity(new_capacity.capacity()); - set_min_capacity(new_capacity.min_capacity()); + void set_capacity(const capacity_type& capacity_ctrl) { + m_capacity_ctrl = capacity_ctrl; + if (capacity_ctrl.capacity() < circular_buffer::capacity()) + circular_buffer::set_capacity(capacity_ctrl.capacity()); + set_min_capacity(capacity_ctrl.min_capacity()); +#if BOOST_CB_ENABLE_DEBUG + invalidate_iterators_except(end()); +#endif } - //! See the circular_buffer source documentation. + //! Change the size of the circular_buffer_space_optimized. + /*! + \post size() == new_size \&\& capacity().%capacity() >= new_size

+ If the new size is greater than the current size, copies of item will be inserted at the + back of the of the circular_buffer_space_optimized in order to achieve the desired + size. In the case the resulting size exceeds the current capacity the capacity will be set to + new_size.

+ If the current number of elements stored in the circular_buffer_space_optimized is greater + than the desired new size then number of [size() - new_size] last elements will be + removed. (The capacity will remain unchanged.) + \param new_size The new size. + \param item The element the circular_buffer_space_optimized will be filled with in order to gain + the requested size. (See the Effect.) + \throws "An allocation error" if memory is exhausted (std::bad_alloc if the standard allocator is + used). + \throws Whatever T::T(const T&) throws. + \par Exception Safety + Basic. + \par Iterator Invalidation + Invalidates all iterators pointing to the circular_buffer_space_optimized (except iterators + equal to end()). + \par Complexity + Linear (in the new size of the circular_buffer_space_optimized). + \sa rresize(), set_capacity() + */ void resize(size_type new_size, param_value_type item = value_type()) { if (new_size > size()) { if (new_size > capacity()) @@ -168,36 +239,90 @@ public: } else { erase(end() - (size() - new_size), end()); } +#if BOOST_CB_ENABLE_DEBUG + invalidate_iterators_except(end()); +#endif } - //! See the circular_buffer source documentation. - /*! - \pre min_capacity() <= new_capacity - \note It is considered as a bug if the precondition is not met (i.e. if - new_capacity > min_capacity()) and an assertion - will be invoked in the debug mode. + /*! \brief Change the capacity (and the minimal guaranteed amount of allocated memory) of the + circular_buffer_space_optimized. + \post capacity() == capacity_ctrl \&\& size() \<= capacity_ctrl

+ If the current number of elements stored in the circular_buffer_space_optimized is greater + than the desired new capacity then number of [size() - capacity_ctrl.capacity()] + first elements will be removed and the new size will be equal to + capacity_ctrl.capacity().

+ If the current number of elements stored in the circular_buffer_space_optimized is lower + than than the new capacity the allocated memory (in the internal buffer) may be accommodated as necessary + but it will never drop below capacity_ctrl.min_capacity(). + \param capacity_ctrl The new capacity controller. + \throws "An allocation error" if memory is exhausted (std::bad_alloc if the standard allocator is + used). + \throws Whatever T::T(const T&) throws. + \par Exception Safety + Strong. + \par Iterator Invalidation + Invalidates all iterators pointing to the circular_buffer_space_optimized (except iterators + equal to end()). + \par Complexity + Linear (in the size/new capacity of the circular_buffer_space_optimized). + \sa set_capacity(), rresize() */ - void rset_capacity(const capacity_type& new_capacity) { - m_capacity_ctrl = new_capacity; - if (new_capacity.capacity() < circular_buffer::capacity()) - circular_buffer::rset_capacity(new_capacity.capacity()); - set_min_capacity(new_capacity.min_capacity()); + void rset_capacity(const capacity_type& capacity_ctrl) { + m_capacity_ctrl = capacity_ctrl; + if (capacity_ctrl.capacity() < circular_buffer::capacity()) + circular_buffer::rset_capacity(capacity_ctrl.capacity()); + set_min_capacity(capacity_ctrl.min_capacity()); +#if BOOST_CB_ENABLE_DEBUG + invalidate_iterators_except(end()); +#endif } - //! See the circular_buffer source documentation. + //! Change the size of the circular_buffer_space_optimized. + /*! + \post size() == new_size \&\& capacity().%capacity() >= new_size

+ If the new size is greater than the current size, copies of item will be inserted at the + front of the of the circular_buffer_space_optimized in order to achieve the desired + size. In the case the resulting size exceeds the current capacity the capacity will be set to + new_size.

+ If the current number of elements stored in the circular_buffer_space_optimized is greater + than the desired new size then number of [size() - new_size] first elements will be + removed. (The capacity will remain unchanged.) + \param new_size The new size. + \param item The element the circular_buffer_space_optimized will be filled with in order to gain + the requested size. (See the Effect.) + \throws "An allocation error" if memory is exhausted (std::bad_alloc if the standard allocator is + used). + \throws Whatever T::T(const T&) throws. + \par Exception Safety + Basic. + \par Iterator Invalidation + Invalidates all iterators pointing to the circular_buffer_space_optimized (except iterators + equal to end()). + \par Complexity + Linear (in the new size of the circular_buffer_space_optimized). + \sa rresize(), set_capacity() + */ void rresize(size_type new_size, param_value_type item = value_type()) { if (new_size > size()) { if (new_size > capacity()) m_capacity_ctrl.m_capacity = new_size; - insert(begin(), new_size - size(), item); + rinsert(begin(), new_size - size(), item); } else { - erase(begin(), end() - new_size); + rerase(begin(), end() - new_size); } +#if BOOST_CB_ENABLE_DEBUG + invalidate_iterators_except(end()); +#endif } //! Create an empty space optimized circular buffer with a maximum capacity. /*! - TODO - doc + \post capacity().%capacity() == max_size() \&\& capacity().min_capacity() == 0 \&\& size() == 0 +

There is no memory allocated in the internal buffer after execution of this constructor. + \param alloc The allocator. + \throws Nothing. + \par Complexity + Constant. */ explicit circular_buffer_space_optimized( const allocator_type& alloc = allocator_type()) @@ -206,17 +331,15 @@ public: //! Create an empty space optimized circular buffer with the specified capacity. /*! - \param capacity_ctrl The capacity of the buffer. - (param min_capacity The minimal guaranteed amount of allocated memory.) - (The metrics of the min_capacity is number of items.) + \post capacity() == capacity_ctrl \&\& size() == 0 + \param capacity_ctrl The capacity controller representing the maximum number of elements which can be stored in + the circular_buffer_space_optimized and the minimal allocated size of the + internal buffer. \param alloc The allocator. - \pre capacity >= min_capacity - \post (*this).capacity() == capacity \&\& (*this).size == 0
- Allocates memory specified by the min_capacity parameter. - \throws "An allocation error" if memory is exhausted (std::bad_alloc if the standard allocator is used). - \note It is considered as a bug if the precondition is not met (i.e. if - capacity < min_capacity) and an assertion will be invoked - in the debug mode. + \throws "An allocation error" if memory is exhausted (std::bad_alloc if the standard allocator is + used). + \par Complexity + Constant. */ explicit circular_buffer_space_optimized( capacity_type capacity_ctrl, @@ -224,20 +347,21 @@ public: : circular_buffer(capacity_ctrl.m_min_capacity, alloc) , m_capacity_ctrl(capacity_ctrl) {} - //! Create a full space optimized circular buffer filled with copies of item. - /*! - \param capacity_ctrl The capacity of the buffer. - (param min_capacity The minimal guaranteed amount of allocated memory.) - (The metrics of the min_capacity is number of items.) - \param item The item to be filled with. + /*! \brief Create a full space optimized circular buffer with the specified capacity (and the minimal guaranteed + amount of allocated memory) filled with capacity_ctrl.%capacity() copies of + item. + \post capacity() == capacity_ctrl \&\& full() \&\& (*this)[0] == item \&\& (*this)[1] == item \&\& ... + \&\& (*this) [capacity_ctrl.%capacity() - 1] == item + \param capacity_ctrl The capacity controller representing the maximum number of elements which can be stored in + the circular_buffer_space_optimized and the minimal allocated size of the + internal buffer. + \param item The element the created circular_buffer_space_optimized will be filled with. \param alloc The allocator. - \pre capacity >= min_capacity - \post (*this).size() == capacity \&\& (*this)[0] == (*this)[1] == ... == (*this).back() == item - \throws "An allocation error" if memory is exhausted (std::bad_alloc if the standard allocator is used). - \throws Whatever T::T(const T&) throws. - \note It is considered as a bug if the precondition is not met (i.e. if - capacity < min_capacity) and an assertion will be invoked - in the debug mode. + \throws "An allocation error" if memory is exhausted (std::bad_alloc if the standard allocator is + used). + \throws Whatever T::T(const T&) throws. + \par Complexity + Linear (in the capacity_ctrl.%capacity()). */ circular_buffer_space_optimized( capacity_type capacity_ctrl, @@ -246,7 +370,24 @@ public: : circular_buffer(capacity_ctrl.m_capacity, item, alloc) , m_capacity_ctrl(capacity_ctrl) {} - //! TODO doc + /*! \brief Create a space optimized circular buffer with the specified capacity (and the minimal guaranteed amount + of allocated memory) filled with n copies of item. + \pre capacity_ctrl.%capacity() >= n + \post capacity() == capacity_ctrl \&\& size() == n \&\& (*this)[0] == item \&\& (*this)[1] == item + \&\& ... \&\& (*this)[n - 1] == item

+ Allocates at least as much memory as specified by the capacity_ctrl.min_capacity(). + \param capacity_ctrl The capacity controller representing the maximum number of elements which can be stored in + the circular_buffer_space_optimized and the minimal allocated size of the + internal buffer. + \param n The number of elements the created circular_buffer_space_optimized will be filled with. + \param item The element the created circular_buffer_space_optimized will be filled with. + \param alloc The allocator. + \throws "An allocation error" if memory is exhausted (std::bad_alloc if the standard allocator is + used). + \throws Whatever T::T(const T&) throws. + \par Complexity + Linear (in the n). + */ circular_buffer_space_optimized( capacity_type capacity_ctrl, size_type n, @@ -255,21 +396,13 @@ public: : circular_buffer(init_capacity(capacity_ctrl, n), n, item, alloc) , m_capacity_ctrl(capacity_ctrl) {} -#if defined(BOOST_CB_NEVER_DEFINED) +#if BOOST_WORKAROUND(BOOST_MSVC, < 1300) - // Default copy constructor - declared only for documentation purpose. - /* - \note This section will never be compiled. The default copy constructor - will be generated instead. - */ - //! TODO doc - circular_buffer_space_optimized(const circular_buffer_space_optimized& cb); + /*! \cond */ + circular_buffer_space_optimized(const circular_buffer_space_optimized& cb) + : circular_buffer(cb.begin(), cb.end()) + , m_capacity_ctrl(cb.m_capacity_ctrl) {} -#endif // #if defined(BOOST_CB_NEVER_DEFINED) - -#if BOOST_WORKAROUND(BOOST_MSVC, <= 1200) - - // TODO describe workaround template circular_buffer_space_optimized( InputIterator first, @@ -277,7 +410,6 @@ public: : circular_buffer(first, last) , m_capacity_ctrl(circular_buffer::capacity()) {} - // TODO describe workaround template circular_buffer_space_optimized( capacity_type capacity_ctrl, @@ -289,10 +421,43 @@ public: , m_capacity_ctrl(capacity_ctrl) { check_high_capacity(is_integral()); } + /*! \endcond */ #else - //! TODO doc + //! The copy constructor. + /*! + Creates a copy of the specified circular_buffer_space_optimized. + \post *this == cb

+ Allocates the exact amount of memory to store the content of cb. + \param cb The circular_buffer_space_optimized to be copied. + \throws "An allocation error" if memory is exhausted (std::bad_alloc if the standard allocator is + used). + \throws Whatever T::T(const T&) throws. + \par Complexity + Linear (in the size of cb). + */ + circular_buffer_space_optimized(const circular_buffer_space_optimized& cb) + : circular_buffer(cb.begin(), cb.end(), cb.get_allocator()) + , m_capacity_ctrl(cb.m_capacity_ctrl) {} + + //! Create a full space optimized circular buffer filled with a copy of the range. + /*! + \pre Valid range [first, last).
+ first and last have to meet the requirements of + InputIterator. + \post capacity().%capacity() == std::distance(first, last) \&\& capacity().min_capacity() == 0 \&\& + full() \&\& (*this)[0]== *first \&\& (*this)[1] == *(first + 1) \&\& ... \&\& + (*this)[std::distance(first, last) - 1] == *(last - 1) + \param first The beginning of the range to be copied. + \param last The end of the range to be copied. + \param alloc The allocator. + \throws "An allocation error" if memory is exhausted (std::bad_alloc if the standard allocator is + used). + \throws Whatever T::T(const T&) throws. + \par Complexity + Linear (in the std::distance(first, last)). + */ template circular_buffer_space_optimized( InputIterator first, @@ -301,28 +466,29 @@ public: : circular_buffer(first, last, alloc) , m_capacity_ctrl(circular_buffer::capacity()) {} - - //! Create a space optimized circular buffer with a copy of a range. - /*! - \param capacity_ctrl The capacity of the buffer. - (param min_capacity The minimal guaranteed amount of allocated memory.) - (The metrics of the min_capacity is number of items.) - \param first The beginning of the range. - \param last The end of the range. + /*! \brief Create a space optimized circular buffer with the specified capacity (and the minimal guaranteed amount + of allocated memory) filled with a copy of the range. + \pre Valid range [first, last).
+ first and last have to meet the requirements of + InputIterator. + \post capacity() == capacity_ctrl \&\& size() \<= std::distance(first, last) \&\& (*this)[0]== + *(last - capacity_ctrl.%capacity()) \&\& (*this)[1] == *(last - capacity_ctrl.%capacity() + 1) \&\& ... + \&\& (*this)[capacity_ctrl.%capacity() - 1] == *(last - 1)

+ Allocates at least as much memory as specified by the capacity_ctrl.min_capacity().

+ If the number of items to be copied from the range [first, last) is greater than the + specified capacity_ctrl.%capacity() then only elements from the range + [last - capacity_ctrl.%capacity(), last) will be copied. + \param capacity_ctrl The capacity controller representing the maximum number of elements which can be stored in + the circular_buffer_space_optimized and the minimal allocated size of the + internal buffer. + \param first The beginning of the range to be copied. + \param last The end of the range to be copied. \param alloc The allocator. - \pre capacity >= min_capacity and valid range [first, last). - \post (*this).capacity() == capacity
- Allocates at least as much memory as specified by the - TODO change - min_capacity parameter.
- If the number of items to copy from the range - [first, last) is greater than the specified - capacity then only elements from the range - [last - capacity, last) will be copied. - \throws "An allocation error" if memory is exhausted (std::bad_alloc if the standard allocator is used). - \throws Whatever T::T(const T&) throws. - \note It is considered as a bug if the precondition is not met (i.e. if - capacity < min_capacity) and an assertion will be invoked - in the debug mode. + \throws "An allocation error" if memory is exhausted (std::bad_alloc if the standard allocator is + used). + \throws Whatever T::T(const T&) throws. + \par Complexity + Linear (in the capacity_ctrl.%capacity()/std::distance(first, last)). */ template circular_buffer_space_optimized( @@ -337,20 +503,25 @@ public: check_high_capacity(is_integral()); } -#endif // #if BOOST_WORKAROUND(BOOST_MSVC, <= 1200) +#endif // #if BOOST_WORKAROUND(BOOST_MSVC, < 1300) #if defined(BOOST_CB_NEVER_DEFINED) +// This section will never be compiled - the default destructor and assignment operator will be generated instead. +// Declared only for documentation purpose. - // Default destructor - //! TODO doc + //! The destructor. + /*! + Destroys the circular_buffer_space_optimized. + \throws Nothing. + \par Iterator Invalidation + Invalidates all iterators pointing to the circular_buffer_space_optimized (including + iterators equal to end()). + \par Complexity + Linear (in the size of the circular_buffer_space_optimized). + \sa clear() + */ ~circular_buffer_space_optimized(); - - // Assignment operator - declared only for documentation purpose. - /* - \note This section will never be compiled. The default assignment - operator will be generated instead. - */ //! TODO doc circular_buffer_space_optimized& operator = (const circular_buffer_space_optimized& cb); @@ -614,15 +785,15 @@ private: ensure_reserve(new_capacity, size())); } - //! TODO doc + //! Specialized method for checking of the high capacity. void check_high_capacity(const true_type&) {} - //! TODO doc + //! Specialized method for checking of the high capacity. void check_high_capacity(const false_type&) { check_high_capacity(); } - //! TODO doc + //! Determine the initial capacity. static size_type init_capacity(const capacity_type& capacity_ctrl, size_type n) { BOOST_CB_ASSERT(capacity_ctrl.m_capacity >= n); // check for capacity lower than n return std::max(capacity_ctrl.m_min_capacity, n); diff --git a/test/space_optimized_test.cpp b/test/space_optimized_test.cpp index 18d5f8c..3477d73 100644 --- a/test/space_optimized_test.cpp +++ b/test/space_optimized_test.cpp @@ -58,6 +58,104 @@ void min_capacity_test() { BOOST_CHECK(cb3.capacity().min_capacity() <= cb3.internal_capacity()); } +void some_constructor_tests() { + + cb_space_optimized cb1; + BOOST_CHECK(cb1.capacity() == cb1.max_size()); + BOOST_CHECK(cb1.capacity().min_capacity() == 0); + BOOST_CHECK(cb1.internal_capacity() == 0); + BOOST_CHECK(cb1.size() == 0); + + cb1.push_back(1); + cb1.push_back(2); + cb1.push_back(3); + + BOOST_CHECK(cb1.size() == 3); + BOOST_CHECK(cb1.capacity() == cb1.max_size()); + + cb_space_optimized cb2(cb1.begin(), cb1.end()); + + BOOST_CHECK(cb2.capacity() == 3); + BOOST_CHECK(cb2.capacity().min_capacity() == 0); + BOOST_CHECK(cb2.size() == 3); +} + +void shrink_to_fit() { + + cb_space_optimized cb(1000); + cb.push_back(1); + cb.push_back(2); + cb.push_back(3); + + BOOST_CHECK(cb.size() == 3); + BOOST_CHECK(cb.capacity() == 1000); + + size_t internal_capacity = cb.internal_capacity(); + cb_space_optimized(cb).swap(cb); + + BOOST_CHECK(cb.size() == 3); + BOOST_CHECK(cb.capacity() == 1000); + BOOST_CHECK(internal_capacity >= cb.internal_capacity()); +} + +void iterator_invalidation_test() { + +#if !defined(NDEBUG) && !defined(BOOST_CB_DISABLE_DEBUG) + + cb_space_optimized cb1(10, 1); + cb1.push_back(2); + cb1.push_back(3); + cb1.push_back(4); + cb_space_optimized::iterator it1 = cb1.end(); + cb_space_optimized::const_iterator it2 = cb1.begin(); + cb_space_optimized::iterator it3 = cb1.begin() + 6; + + cb1.set_capacity(10); + BOOST_CHECK(it1.is_valid(&cb1)); + BOOST_CHECK(!it2.is_valid(&cb1)); + BOOST_CHECK(!it3.is_valid(&cb1)); + + it1 = cb1.end(); + it2 = cb1.begin(); + it3 = cb1.begin() + 6; + cb1.rset_capacity(10); + BOOST_CHECK(it1.is_valid(&cb1)); + BOOST_CHECK(!it2.is_valid(&cb1)); + BOOST_CHECK(!it3.is_valid(&cb1)); + + it1 = cb1.end(); + it2 = cb1.begin(); + it3 = cb1.begin() + 6; + cb1.resize(10); + BOOST_CHECK(it1.is_valid(&cb1)); + BOOST_CHECK(!it2.is_valid(&cb1)); + BOOST_CHECK(!it3.is_valid(&cb1)); + + it1 = cb1.end(); + it2 = cb1.begin(); + it3 = cb1.begin() + 6; + cb1.rresize(10); + BOOST_CHECK(it1.is_valid(&cb1)); + BOOST_CHECK(!it2.is_valid(&cb1)); + BOOST_CHECK(!it3.is_valid(&cb1)); + + { + cb_space_optimized cb2(10, 1); + cb2.push_back(2); + cb2.push_back(3); + cb2.push_back(4); + it1 = cb2.end(); + it2 = cb2.begin(); + it3 = cb2.begin() + 6; + } + BOOST_CHECK(!it1.is_valid(&cb1)); + BOOST_CHECK(!it2.is_valid(&cb1)); + BOOST_CHECK(!it3.is_valid(&cb1)); + + +#endif // #if !defined(NDEBUG) && !defined(BOOST_CB_DISABLE_DEBUG) +} + // test main test_suite* init_unit_test_suite(int /*argc*/, char* /*argv*/[]) { @@ -65,6 +163,9 @@ test_suite* init_unit_test_suite(int /*argc*/, char* /*argv*/[]) { add_common_tests(tests); tests->add(BOOST_TEST_CASE(&min_capacity_test)); + tests->add(BOOST_TEST_CASE(&some_constructor_tests)); + tests->add(BOOST_TEST_CASE(&shrink_to_fit)); + tests->add(BOOST_TEST_CASE(&iterator_invalidation_test)); return tests; }