| Home | Libraries | People | FAQ | More

## Class template circular_buffer_space_optimized

boost::circular_buffer_space_optimized — Space optimized circular buffer container adaptor. `T` must be a copyable class or must have an noexcept move constructor and move assignment operator.

## Synopsis

    // In header: <boost/circular_buffer/space_optimized.hpp>

    template<typename T, typename Alloc>
    class circular_buffer_space_optimized :
      private boost::circular_buffer< T, Alloc >
    {
    public:
      // types
      typedef circular_buffer< T, Alloc >::value_type             value_type;
      typedef circular_buffer< T, Alloc >::pointer                pointer;
      typedef circular_buffer< T, Alloc >::const_pointer          const_pointer;
      typedef circular_buffer< T, Alloc >::reference              reference;
      typedef circular_buffer< T, Alloc >::const_reference        const_reference;
      typedef circular_buffer< T, Alloc >::size_type              size_type;
      typedef circular_buffer< T, Alloc >::difference_type        difference_type;
      typedef circular_buffer< T, Alloc >::allocator_type         allocator_type;
      typedef circular_buffer< T, Alloc >::const_iterator         const_iterator;
      typedef circular_buffer< T, Alloc >::iterator               iterator;
      typedef circular_buffer< T, Alloc >::const_reverse_iterator const_reverse_iterator;
      typedef circular_buffer< T, Alloc >::reverse_iterator       reverse_iterator;
      typedef circular_buffer< T, Alloc >::array_range            array_range;
      typedef circular_buffer< T, Alloc >::const_array_range      const_array_range;
      typedef circular_buffer< T, Alloc >::param_value_type       param_value_type;
      typedef circular_buffer< T, Alloc >::rvalue_type            rvalue_type;
      typedef cb_details::capacity_control< size_type >           capacity_type;

      // construct/copy/destruct
      explicit circular_buffer_space_optimized(const allocator_type & = allocator_type());
      explicit circular_buffer_space_optimized(capacity_type,
                                               const allocator_type & = allocator_type());
      circular_buffer_space_optimized(capacity_type, param_value_type,
                                      const allocator_type & = allocator_type());
      circular_buffer_space_optimized(capacity_type, size_type, param_value_type,
                                      const allocator_type & = allocator_type());
      circular_buffer_space_optimized(const circular_buffer_space_optimized< T, Alloc > &);
      circular_buffer_space_optimized(circular_buffer_space_optimized< T, Alloc > &&);
      template<typename InputIterator>
        circular_buffer_space_optimized(InputIterator, InputIterator,
                                        const allocator_type & = allocator_type());
      template<typename InputIterator>
        circular_buffer_space_optimized(capacity_type, InputIterator,
                                        InputIterator,
                                        const allocator_type & = allocator_type());
      circular_buffer_space_optimized&
      operator=(const circular_buffer_space_optimized< T, Alloc > &);
      circular_buffer_space_optimized&
      operator=(circular_buffer_space_optimized< T, Alloc > &&);

      // public member functions
      bool full() const;
      size_type reserve() const;
      const capacity_type & capacity() const;
      void set_capacity(const capacity_type &);
      void resize(size_type, param_value_type = value_type());
      void rset_capacity(const capacity_type &);
      void rresize(size_type, param_value_type = value_type());
      void assign(size_type, param_value_type);
      void assign(capacity_type, size_type, param_value_type);
      template<typename InputIterator> void assign(InputIterator, InputIterator);
      template<typename InputIterator>
        void assign(capacity_type, InputIterator, InputIterator);
      void swap(circular_buffer_space_optimized< T, Alloc > &);
      void push_back(param_value_type);
      void push_back(rvalue_type);
      void push_back();
      void push_front(param_value_type);
      void push_front(rvalue_type);
      void push_front();
      void pop_back();
      void pop_front();
      iterator insert(iterator, param_value_type);
      iterator insert(iterator, rvalue_type);
      iterator insert(iterator);
      void insert(iterator, size_type, param_value_type);
      template<typename InputIterator>
        void insert(iterator, InputIterator, InputIterator);
      iterator rinsert(iterator, param_value_type);
      iterator rinsert(iterator, rvalue_type);
      iterator rinsert(iterator);
      void rinsert(iterator, size_type, param_value_type);
      template<typename InputIterator>
        void rinsert(iterator, InputIterator, InputIterator);
      iterator erase(iterator);
      iterator erase(iterator, iterator);
      iterator rerase(iterator);
      iterator rerase(iterator, iterator);
      void clear();

      // private member functions
      void adjust_min_capacity();
      size_type ensure_reserve(size_type, size_type) const;
      void check_low_capacity(size_type = 1);
      void check_high_capacity();
      void reduce_capacity(const true_type &);
      void reduce_capacity(const false_type &);
      template<typename IntegralType>
        void insert(const iterator &, IntegralType, IntegralType,
                    const true_type &);
      template<typename Iterator>
        void insert(const iterator &, Iterator, Iterator, const false_type &);
      template<typename IntegralType>
        void rinsert(const iterator &, IntegralType, IntegralType,
                     const true_type &);
      template<typename Iterator>
        void rinsert(const iterator &, Iterator, Iterator, const false_type &);

      // private static functions
      static size_type init_capacity(const capacity_type &, size_type);
      template<typename IntegralType>
        static size_type
        init_capacity(const capacity_type &, IntegralType, IntegralType,
                      const true_type &);
      template<typename Iterator>
        static size_type
        init_capacity(const capacity_type &, Iterator, Iterator,
                      const false_type &);
      template<typename InputIterator>
        static size_type
        init_capacity(const capacity_type &, InputIterator, InputIterator,
                      const std::input_iterator_tag &);
      template<typename ForwardIterator>
        static size_type
        init_capacity(const capacity_type &, ForwardIterator, ForwardIterator,
                      const std::forward_iterator_tag &);
    };

## Description

### `circular_buffer_space_optimized` public types

1. typedef cb_details::capacity_control< size_type > capacity_type;

   Capacity controller of the space optimized circular buffer. \see capacity_control in details.hpp.

   `class capacity_control
   {
   size_type m_capacity; // Available capacity.
   size_type m_min_capacity; // Minimum 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; }
   };
   `

   Always `capacity >= min_capacity`.

   The `capacity()` represents the capacity of the `circular_buffer_space_optimized` and the `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()` 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`.

### `circular_buffer_space_optimized` public construct/copy/destruct

1.     explicit circular_buffer_space_optimized(const allocator_type & alloc = allocator_type());

   Create an empty space optimized circular buffer with zero capacity.

   Complexity. Constant.

   | Warning
   Since Boost version 1.36 the behaviour of this constructor has changed. Now it creates a space optimized circular buffer with zero capacity.

   Parameters: |
   `alloc` | The allocator.
   Postconditions: | `capacity().capacity() == 0 && capacity().min_capacity() == 0 && size() == 0`
   Throws: | Nothing.

2.     explicit circular_buffer_space_optimized(capacity_type capacity_ctrl,
                                                const allocator_type & alloc = allocator_type());

   Create an empty space optimized circular buffer with the specified capacity.

   Complexity. Constant.

   Parameters: |
   `alloc` | The allocator.
   `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.
   Postconditions: | `capacity() == capacity_ctrl && size() == 0` The amount of allocated memory in the internal buffer is `capacity_ctrl.min_capacity()`.
   Throws: | An allocation error if memory is exhausted (`std::bad_alloc` if the standard allocator is used).

3.     circular_buffer_space_optimized(capacity_type capacity_ctrl,
                                       param_value_type item,
                                       const allocator_type & alloc = allocator_type());

   Create a full space optimized circular buffer with the specified capacity filled with `capacity_ctrl.capacity()` copies of `item`.

   Complexity. Linear (in the `capacity_ctrl.capacity()`).

   Parameters: |
   `alloc` | The allocator.
   `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.
   `item` | The element the created ``circular_buffer_space_optimized`` will be filled with.
   Postconditions: | `capacity() == capacity_ctrl && full() && (*this)[0] == item && (*this)[1] == item && ... && (*this) [capacity_ctrl.capacity() - 1] == item` The amount of allocated memory in the internal buffer is `capacity_ctrl.capacity()`.
   Throws: | An allocation error if memory is exhausted (`std::bad_alloc` if the standard allocator is used). `T::T(const T&)` throws.

4.     circular_buffer_space_optimized(capacity_type capacity_ctrl, size_type n,
                                       param_value_type item,
                                       const allocator_type & alloc = allocator_type());

   Create a space optimized circular buffer with the specified capacity filled with `n` copies of `item`.

   Complexity. Linear (in the `n`).

   Parameters: |
   `alloc` | The allocator.
   `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.
   `item` | The element the created ``circular_buffer_space_optimized`` will be filled with.
   `n` | The number of elements the created ``circular_buffer_space_optimized`` will be filled with.
   Requires: | `capacity_ctrl.capacity() >= n`
   Postconditions: | `capacity() == capacity_ctrl && size() == n && (*this)[0] == item && (*this)[1] == item && ... && (*this)[n - 1] == item` The amount of allocated memory in the internal buffer is `max[n, capacity_ctrl.min_capacity()]`.
   Throws: | An allocation error if memory is exhausted (`std::bad_alloc` if the standard allocator is used). Whatever `T::T(const T&)` throws.

5.     circular_buffer_space_optimized(const circular_buffer_space_optimized< T, Alloc > & cb);

   The copy constructor.

   Creates a copy of the specified ``circular_buffer_space_optimized``.

   Complexity. Linear (in the size of `cb`).

   Parameters: |
   `cb` | The ``circular_buffer_space_optimized`` to be copied.
   Postconditions: | `*this == cb` The amount of allocated memory in the internal buffer is `cb.size()`.
   Throws: | An allocation error if memory is exhausted (`std::bad_alloc` if the standard allocator is used). Whatever `T::T(const T&)` throws.

6.     circular_buffer_space_optimized(circular_buffer_space_optimized< T, Alloc > && cb);

   The move constructor.

   Move constructs a ``circular_buffer_space_optimized`` from `cb`, leaving `cb` empty.

   Constant.

   Parameters: |
   `cb` | ``circular_buffer`` to 'steal' value from.
   Requires: | C++ compiler with rvalue references support.
   Postconditions: | `cb.empty()`
   Throws: | Nothing.

7.     template<typename InputIterator>
         circular_buffer_space_optimized(InputIterator first, InputIterator last,
                                         const allocator_type & alloc = allocator_type());

   Create a full space optimized circular buffer filled with a copy of the range.

   Complexity. Linear (in the `std::distance(first, last)`).

   Parameters: |
   `alloc` | The allocator.
   `first` | The beginning of the range to be copied.
   `last` | The end of the range to be copied.
   Requires: | Valid range `[first, last)`. `first` and `last` have to meet the requirements of InputIterator.
   Postconditions: | `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)` The amount of allocated memory in the internal buffer is `std::distance(first, last)`.
   Throws: | An allocation error if memory is exhausted (`std::bad_alloc` if the standard allocator is used). Whatever `T::T(const T&)` throws or nothing if `T::T(T&&)` is noexcept and `InputIterator` is a move iterator.

8.     template<typename 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.

   Complexity. Linear (in `std::distance(first, last)`; in `min[capacity_ctrl.capacity(), std::distance(first, last)]` if the `InputIterator` is a RandomAccessIterator).

   Parameters: |
   `alloc` | The allocator.
   `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.
   Requires: | Valid range `[first, last)`. `first` and `last` have to meet the requirements of InputIterator.
   Postconditions: | `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)` 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. The amount of allocated memory in the internal buffer is `max[capacity_ctrl.min_capacity(), min[capacity_ctrl.capacity(), std::distance(first, last)]]`.
   Throws: | An allocation error if memory is exhausted (`std::bad_alloc` if the standard allocator is used). Whatever `T::T(const T&)` throws.

9.     circular_buffer_space_optimized&
       operator=(const circular_buffer_space_optimized< T, Alloc > & cb);

   The assign operator.

   Makes this ``circular_buffer_space_optimized`` to become a copy of the specified ``circular_buffer_space_optimized``.

   Exception Safety. Strong.

   Iterator Invalidation. Invalidates all iterators pointing to this ``circular_buffer_space_optimized`` (except iterators equal to `end()`).

   Complexity. Linear (in the size of `cb`).

   See Also:

   `assign(size_type, const_reference)`, `assign(capacity_type, size_type, const_reference)`, `assign(InputIterator, InputIterator)`, `assign(capacity_type, InputIterator, InputIterator)`

   Parameters: |
   `cb` | The ``circular_buffer_space_optimized`` to be copied.
   Postconditions: | `*this == cb` The amount of allocated memory in the internal buffer is `cb.size()`.
   Throws: | An allocation error if memory is exhausted (`std::bad_alloc` if the standard allocator is used). `T::T(const T&)` throws.

10.     circular_buffer_space_optimized&
        operator=(circular_buffer_space_optimized< T, Alloc > && cb);

    Move assigns content of `cb` to `*this`, leaving `cb` empty.

    Complexity. Constant.

    Parameters: |
    `cb` | ``circular_buffer`` to 'steal' value from.
    Requires: | C++ compiler with rvalue references support.
    Postconditions: | `cb.empty()`
    Throws: | Nothing.

### `circular_buffer_space_optimized` public member functions

1.     bool full() const;

   Is the ``circular_buffer_space_optimized`` full?

   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()`

   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.

2.     size_type reserve() const;

   Get the maximum number of elements which can be inserted into the ``circular_buffer_space_optimized`` without overwriting any of already stored elements.

   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()`

   Returns: | `capacity().capacity() - size()`
   Throws: | Nothing.

3.     const capacity_type & capacity() const;

   Get the capacity of the ``circular_buffer_space_optimized``.

   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(const capacity_type&)`

   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.

4.     void set_capacity(const capacity_type & capacity_ctrl);

   Change the capacity (and the minimal guaranteed amount of allocated memory) of the ``circular_buffer_space_optimized``.

   Exception Safety. Strong.

   Iterator Invalidation. Invalidates all iterators pointing to the ``circular_buffer_space_optimized`` (except iterators equal to `end()`).

   Complexity. Linear (in `min[size(), capacity_ctrl.capacity()]`).

   | Note
   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.

   See Also:

   `rset_capacity(const capacity_type&)`, `resize(size_type, const_reference)`

   Parameters: |
   `capacity_ctrl` | The new capacity controller.
   Postconditions: | `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 the new capacity then the amount of allocated memory in the internal buffer may be accommodated as necessary but it will never drop below `capacity_ctrl.min_capacity()`.
   Throws: | An allocation error if memory is exhausted, (`std::bad_alloc` if the standard allocator is used). Whatever `T::T(const T&)` throws or nothing if `T::T(T&&)` is noexcept.

5.     void resize(size_type new_size, param_value_type item = value_type());

   Change the size of the ``circular_buffer_space_optimized``.

   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(size_type, const_reference)`, `set_capacity(const capacity_type&)`

   Parameters: |
   `item` | The element the ``circular_buffer_space_optimized`` will be filled with in order to gain the requested size. (See the Effect.)
   `new_size` | The new size.
   Postconditions: | `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.) The amount of allocated memory in the internal buffer may be accommodated as necessary.
   Throws: | An allocation error if memory is exhausted (`std::bad_alloc` if the standard allocator is used). Whatever `T::T(const T&)` throws.

6.     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``.

   Exception Safety. Strong.

   Iterator Invalidation. Invalidates all iterators pointing to the ``circular_buffer_space_optimized`` (except iterators equal to `end()`).

   Complexity. Linear (in `min[size(), capacity_ctrl.capacity()]`).

   See Also:

   `set_capacity(const capacity_type&)`, `rresize(size_type, const_reference)`

   Parameters: |
   `capacity_ctrl` | The new capacity controller.
   Postconditions: | `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 the new capacity then the amount of allocated memory in the internal buffer may be accommodated as necessary but it will never drop below `capacity_ctrl.min_capacity()`.
   Throws: | An allocation error if memory is exhausted (`std::bad_alloc` if the standard allocator is used). Whatever `T::T(const T&)` throws or nothing if `T::T(T&&)` is noexcept.

7.     void rresize(size_type new_size, param_value_type item = value_type());

   Change the size of the ``circular_buffer_space_optimized``.

   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:

   `resize(size_type, const_reference)`, `rset_capacity(const capacity_type&)`

   Parameters: |
   `item` | The element the ``circular_buffer_space_optimized`` will be filled with in order to gain the requested size. (See the Effect.)
   `new_size` | The new size.
   Postconditions: | `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.) The amount of allocated memory in the internal buffer may be accommodated as necessary.
   Throws: | An allocation error if memory is exhausted (`std::bad_alloc` if the standard allocator is used). Whatever `T::T(const T&)` throws.

8.     void assign(size_type n, param_value_type item);

   Assign `n` items into the space optimized circular buffer.

   The content of the ``circular_buffer_space_optimized`` will be removed and replaced with `n` copies of the `item`.

   Exception Safety. Basic.

   Iterator Invalidation. Invalidates all iterators pointing to the ``circular_buffer_space_optimized`` (except iterators equal to `end()`).

   Complexity. Linear (in the `n`).

   See Also:

   `operator=`, `assign(capacity_type, size_type, const_reference)`, `assign(InputIterator, InputIterator)`, `assign(capacity_type, InputIterator, InputIterator)`

   Parameters: |
   `item` | The element the ``circular_buffer_space_optimized`` will be filled with.
   `n` | The number of elements the ``circular_buffer_space_optimized`` will be filled with.
   Postconditions: | `capacity().capacity() == n && capacity().min_capacity() == 0 && size() == n && (*this)[0] == item && (*this)[1] == item && ... && (*this) [n - 1] == item` The amount of allocated memory in the internal buffer is `n`.
   Throws: | An allocation error if memory is exhausted (`std::bad_alloc` if the standard allocator is used). Whatever `T::T(const T&)` throws.

9.     void assign(capacity_type capacity_ctrl, size_type n, param_value_type item);

   Assign `n` items into the space optimized circular buffer specifying the capacity.

   The capacity of the ``circular_buffer_space_optimized`` will be set to the specified value and the content of the ``circular_buffer_space_optimized`` will be removed and replaced with `n` copies of the `item`.

   Exception Safety. Basic.

   Iterator Invalidation. Invalidates all iterators pointing to the ``circular_buffer_space_optimized`` (except iterators equal to `end()`).

   Complexity. Linear (in the `n`).

   See Also:

   `operator=`, `assign(size_type, const_reference)`, `assign(InputIterator, InputIterator)`, `assign(capacity_type, InputIterator, InputIterator)`

   Parameters: |
   `capacity_ctrl` | The new capacity controller.
   `item` | The element the ``circular_buffer_space_optimized`` will be filled with.
   `n` | The number of elements the ``circular_buffer_space_optimized`` will be filled with.
   Requires: | `capacity_ctrl.capacity() >= n`
   Postconditions: | `capacity() == capacity_ctrl && size() == n && (*this)[0] == item && (*this)[1] == item && ... && (*this) [n - 1] == item` The amount of allocated memory will be `max[n, capacity_ctrl.min_capacity()]`.
   Throws: | An allocation error if memory is exhausted (`std::bad_alloc` if the standard allocator is used). Whatever `T::T(const T&)` throws.

10.     template<typename InputIterator>
          void assign(InputIterator first, InputIterator last);

    Assign a copy of the range into the space optimized circular buffer.

    The content of the ``circular_buffer_space_optimized`` will be removed and replaced with copies of elements from the specified range.

    Exception Safety. Basic.

    Iterator Invalidation. Invalidates all iterators pointing to the ``circular_buffer_space_optimized`` (except iterators equal to `end()`).

    Complexity. Linear (in the `std::distance(first, last)`).

    See Also:

    `operator=`, `assign(size_type, const_reference)`, `assign(capacity_type, size_type, const_reference)`, `assign(capacity_type, InputIterator, InputIterator)`

    Parameters: |
    `first` | The beginning of the range to be copied.
    `last` | The end of the range to be copied.
    Requires: | Valid range `[first, last)`. `first` and `last` have to meet the requirements of InputIterator.
    Postconditions: | `capacity().capacity() == std::distance(first, last) && capacity().min_capacity() == 0 && size() == std::distance(first, last) && (*this)[0]== *first && (*this)[1] == *(first + 1) && ... && (*this)[std::distance(first, last) - 1] == *(last - 1)` The amount of allocated memory in the internal buffer is `std::distance(first, last)`.
    Throws: | An allocation error if memory is exhausted (`std::bad_alloc` if the standard allocator is used). Whatever `T::T(const T&)` throws or nothing if `T::T(T&&)` is noexcept and `InputIterator` is a move iterator.

11.     template<typename InputIterator>
          void assign(capacity_type capacity_ctrl, InputIterator first,
                      InputIterator last);

    Assign a copy of the range into the space optimized circular buffer specifying the capacity.

    The capacity of the ``circular_buffer_space_optimized`` will be set to the specified value and the content of the ``circular_buffer_space_optimized`` will be removed and replaced with copies of elements from the specified range.

    Exception Safety. Basic.

    Iterator Invalidation. Invalidates all iterators pointing to the ``circular_buffer_space_optimized`` (except iterators equal to `end()`).

    Complexity. Linear (in `std::distance(first, last)`; in `min[capacity_ctrl.capacity(), std::distance(first, last)]` if the `InputIterator` is a RandomAccessIterator).

    See Also:

    `operator=`, `assign(size_type, const_reference)`, `assign(capacity_type, size_type, const_reference)`, `assign(InputIterator, InputIterator)`

    Parameters: |
    `capacity_ctrl` | The new capacity controller.
    `first` | The beginning of the range to be copied.
    `last` | The end of the range to be copied.
    Requires: | Valid range `[first, last)`. `first` and `last` have to meet the requirements of InputIterator.
    Postconditions: | `capacity() == capacity_ctrl && size() <= std::distance(first, last) && (*this)[0]== *(last - capacity) && (*this)[1] == *(last - capacity + 1) && ... && (*this)[capacity - 1] == *(last - 1)` If the number of items to be copied from the range `[first, last)` is greater than the specified `capacity` then only elements from the range `[last - capacity, last)` will be copied. The amount of allocated memory in the internal buffer is `max[std::distance(first, last), capacity_ctrl.min_capacity()]`.
    Throws: | An allocation error if memory is exhausted (`std::bad_alloc` if the standard allocator is used). Whatever `T::T(const T&)` throws or nothing if `T::T(T&&)` is noexcept and `InputIterator` is a move iterator.

12.     void swap(circular_buffer_space_optimized< T, Alloc > & cb);

    Swap the contents of two space-optimized circular-buffers.

    Exception Safety. No-throw.

    Iterator Invalidation. Invalidates all iterators of both ``circular_buffer_space_optimized`` containers. (On the other hand the iterators still point to the same elements but within another container. If you want to rely on this feature you have to turn the __debug_support off by defining macro BOOST_CB_DISABLE_DEBUG, otherwise an assertion will report an error if such invalidated iterator is used.)

    Complexity. Constant (in the size of the ``circular_buffer_space_optimized``).

    See Also:

    `swap(circular_buffer<T, Alloc>&, circular_buffer<T, Alloc>&)`, `swap(circular_buffer_space_optimized<T, Alloc>&, circular_buffer_space_optimized<T, Alloc>&)`

    Parameters: |
    `cb` | The ``circular_buffer_space_optimized`` whose content will be swapped.
    Postconditions: | `this` contains elements of `cb` and vice versa; the capacity and the amount of allocated memory in the internal buffer of `this` equal to the capacity and the amount of allocated memory of `cb` and vice versa.
    Throws: | Nothing.

13.     void push_back(param_value_type item);

    Insert a new element at the end of the space optimized circular buffer.

    Exception Safety. Basic.

    Iterator Invalidation. Invalidates all iterators pointing to the ``circular_buffer_space_optimized`` (except iterators equal to `end()`).

    Complexity. Linear (in the size of the ``circular_buffer_space_optimized``).

    See Also:

    `push_front(const_reference)`, `pop_back()`, `pop_front()`

    Parameters: |
    `item` | The element to be inserted.
    Postconditions: | if `capacity().capacity() > 0` then `back() == item` If the `circular_buffer_space_optimized` is full, the first element will be removed. If the capacity is `0`, nothing will be inserted. The amount of allocated memory in the internal buffer may be predictively increased.
    Throws: | An allocation error if memory is exhausted (`std::bad_alloc` if the standard allocator is used). Whatever `T::T(const T&)` throws.

14.     void push_back(rvalue_type item);

    Insert a new element at the end of the space optimized circular buffer.

    Exception Safety. Basic.

    Iterator Invalidation. Invalidates all iterators pointing to the ``circular_buffer_space_optimized`` (except iterators equal to `end()`).

    Complexity. Linear (in the size of the ``circular_buffer_space_optimized``).

    See Also:

    `push_front(const_reference)`, `pop_back()`, `pop_front()`

    Parameters: |
    `item` | The element to be inserted.
    Postconditions: | if `capacity().capacity() > 0` then `back() == item` If the `circular_buffer_space_optimized` is full, the first element will be removed. If the capacity is `0`, nothing will be inserted. The amount of allocated memory in the internal buffer may be predictively increased.
    Throws: | An allocation error if memory is exhausted (`std::bad_alloc` if the standard allocator is used).

15.     void push_back();

    Insert a new element at the end of the space optimized circular buffer.

    Exception Safety. Basic.

    Iterator Invalidation. Invalidates all iterators pointing to the ``circular_buffer_space_optimized`` (except iterators equal to `end()`).

    Complexity. Linear (in the size of the ``circular_buffer_space_optimized``).

    See Also:

    `push_front(const_reference)`, `pop_back()`, `pop_front()`

    Postconditions: | if `capacity().capacity() > 0` then `back() == item` If the `circular_buffer_space_optimized` is full, the first element will be removed. If the capacity is `0`, nothing will be inserted. The amount of allocated memory in the internal buffer may be predictively increased.
    Throws: | An allocation error if memory is exhausted (`std::bad_alloc` if the standard allocator is used). Whatever `T::T()` throws. Whatever `T::T(const T&)` throws or nothing if `T::T(T&&)` is noexcept.

16.     void push_front(param_value_type item);

    Insert a new element at the beginning of the space optimized circular buffer.

    Exception Safety. Basic.

    Iterator Invalidation. Invalidates all iterators pointing to the ``circular_buffer_space_optimized`` (except iterators equal to `end()`).

    Complexity. Linear (in the size of the ``circular_buffer_space_optimized``).

    See Also:

    `push_back(const_reference)`, `pop_back()`, `pop_front()`

    Parameters: |
    `item` | The element to be inserted.
    Postconditions: | if `capacity().capacity() > 0` then `front() == item` If the `circular_buffer_space_optimized` is full, the last element will be removed. If the capacity is `0`, nothing will be inserted. The amount of allocated memory in the internal buffer may be predictively increased.
    Throws: | An allocation error if memory is exhausted (`std::bad_alloc` if the standard allocator is used). Whatever `T::T(const T&)` throws.

17.     void push_front(rvalue_type item);

    Insert a new element at the beginning of the space optimized circular buffer.

    Exception Safety. Basic.

    Iterator Invalidation. Invalidates all iterators pointing to the ``circular_buffer_space_optimized`` (except iterators equal to `end()`).

    Complexity. Linear (in the size of the ``circular_buffer_space_optimized``).

    See Also:

    `push_back(const_reference)`, `pop_back()`, `pop_front()`

    Parameters: |
    `item` | The element to be inserted.
    Postconditions: | if `capacity().capacity() > 0` then `front() == item` If the `circular_buffer_space_optimized` is full, the last element will be removed. If the capacity is `0`, nothing will be inserted. The amount of allocated memory in the internal buffer may be predictively increased.
    Throws: | An allocation error if memory is exhausted (`std::bad_alloc` if the standard allocator is used). Whatever `T::T(const T&)` throws or nothing if `T::T(T&&)` is noexcept.

18.     void push_front();

    Insert a new element at the beginning of the space optimized circular buffer.

    Exception Safety. Basic.

    Iterator Invalidation. Invalidates all iterators pointing to the ``circular_buffer_space_optimized`` (except iterators equal to `end()`).

    Complexity. Linear (in the size of the ``circular_buffer_space_optimized``).

    See Also:

    `push_back(const_reference)`, `pop_back()`, `pop_front()`

    Postconditions: | if `capacity().capacity() > 0` then `front() == item` If the `circular_buffer_space_optimized` is full, the last element will be removed. If the capacity is `0`, nothing will be inserted. The amount of allocated memory in the internal buffer may be predictively increased.
    Throws: | An allocation error if memory is exhausted (`std::bad_alloc` if the standard allocator is used). Whatever `T::T()` throws. Whatever `T::T(const T&)` throws or nothing if `T::T(T&&)` is noexcept.

19.     void pop_back();

    Remove the last element from the space optimized circular buffer.

    Exception Safety. Basic.

    Iterator Invalidation. Invalidates all iterators pointing to the ``circular_buffer_space_optimized`` (except iterators equal to `end()`).

    Complexity. Linear (in the size of the ``circular_buffer_space_optimized``).

    See Also:

    `pop_front()`, `push_back(const_reference)`, `push_front(const_reference)`

    Requires: | `!empty()`
    Postconditions: | The last element is removed from the `circular_buffer_space_optimized`. The amount of allocated memory in the internal buffer may be predictively decreased.
    Throws: | An allocation error if memory is exhausted (`std::bad_alloc` if the standard allocator is used).

20.     void pop_front();

    Remove the first element from the space optimized circular buffer.

    Exception Safety. Basic.

    Iterator Invalidation. Invalidates all iterators pointing to the ``circular_buffer_space_optimized`` (except iterators equal to `end()`).

    Complexity. Linear (in the size of the ``circular_buffer_space_optimized``).

    See Also:

    `pop_back()`, `push_back(const_reference)`, `push_front(const_reference)`

    Requires: | `!empty()`
    Postconditions: | The first element is removed from the `circular_buffer_space_optimized`. The amount of allocated memory in the internal buffer may be predictively decreased.
    Throws: | An allocation error if memory is exhausted (`std::bad_alloc` if the standard allocator is used).

21.     iterator insert(iterator pos, param_value_type item);

    Insert an element at the specified position.

    Exception Safety. Basic.

    Iterator Invalidation. Invalidates all iterators pointing to the ``circular_buffer_space_optimized`` (except iterators equal to `end()`).

    Complexity. Linear (in the size of the ``circular_buffer_space_optimized``).

    See Also:

    `insert(iterator, size_type, value_type)`, `insert(iterator, InputIterator, InputIterator)`, `rinsert(iterator, value_type)`, `rinsert(iterator, size_type, value_type)`, `rinsert(iterator, InputIterator, InputIterator)`

    Parameters: |
    `item` | The element to be inserted.
    `pos` | An iterator specifying the position where the `item` will be inserted.
    Requires: | `pos` is a valid iterator pointing to the `circular_buffer_space_optimized` or its end.
    Postconditions: | The `item` will be inserted at the position `pos`. If the `circular_buffer_space_optimized` is full, the first element will be overwritten. If the `circular_buffer_space_optimized` is full and the `pos` points to `begin()`, then the `item` will not be inserted. If the capacity is `0`, nothing will be inserted. The amount of allocated memory in the internal buffer may be predictively increased.
    Returns: | Iterator to the inserted element or `begin()` if the `item` is not inserted. (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. Whatever `T::operator = (const T&)` throws.

22.     iterator insert(iterator pos, rvalue_type item);

    Insert an element at the specified position.

    Exception Safety. Basic.

    Iterator Invalidation. Invalidates all iterators pointing to the ``circular_buffer_space_optimized`` (except iterators equal to `end()`).

    Complexity. Linear (in the size of the ``circular_buffer_space_optimized``).

    See Also:

    `insert(iterator, size_type, value_type)`, `insert(iterator, InputIterator, InputIterator)`, `rinsert(iterator, value_type)`, `rinsert(iterator, size_type, value_type)`, `rinsert(iterator, InputIterator, InputIterator)`

    Parameters: |
    `item` | The element to be inserted.
    `pos` | An iterator specifying the position where the `item` will be inserted.
    Requires: | `pos` is a valid iterator pointing to the `circular_buffer_space_optimized` or its end.
    Postconditions: | The `item` will be inserted at the position `pos`. If the `circular_buffer_space_optimized` is full, the first element will be overwritten. If the `circular_buffer_space_optimized` is full and the `pos` points to `begin()`, then the `item` will not be inserted. If the capacity is `0`, nothing will be inserted. The amount of allocated memory in the internal buffer may be predictively increased.
    Returns: | Iterator to the inserted element or `begin()` if the `item` is not inserted. (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 or nothing if `T::T(T&&)` is noexcept.

23.     iterator insert(iterator pos);

    Insert an element at the specified position.

    Exception Safety. Basic.

    Iterator Invalidation. Invalidates all iterators pointing to the ``circular_buffer_space_optimized`` (except iterators equal to `end()`).

    Complexity. Linear (in the size of the ``circular_buffer_space_optimized``).

    See Also:

    `insert(iterator, size_type, value_type)`, `insert(iterator, InputIterator, InputIterator)`, `rinsert(iterator, value_type)`, `rinsert(iterator, size_type, value_type)`, `rinsert(iterator, InputIterator, InputIterator)`

    Parameters: |
    `pos` | An iterator specifying the position where the `item` will be inserted.
    Requires: | `pos` is a valid iterator pointing to the `circular_buffer_space_optimized` or its end.
    Postconditions: | The `item` will be inserted at the position `pos`. If the `circular_buffer_space_optimized` is full, the first element will be overwritten. If the `circular_buffer_space_optimized` is full and the `pos` points to `begin()`, then the `item` will not be inserted. If the capacity is `0`, nothing will be inserted. The amount of allocated memory in the internal buffer may be predictively increased.
    Returns: | Iterator to the inserted element or `begin()` if the `item` is not inserted. (See the Effect.)
    Throws: | An allocation error if memory is exhausted (`std::bad_alloc` if the standard allocator is used). Whatever `T::T()` throws. Whatever `T::T(const T&)` throws or nothing if `T::T(T&&)` is noexcept.

24.     void insert(iterator pos, size_type n, param_value_type item);

    Insert `n` copies of the `item` at the specified position.

    Exception Safety. Basic.

    Iterator Invalidation. Invalidates all iterators pointing to the ``circular_buffer_space_optimized`` (except iterators equal to `end()`).

    Complexity. Linear (in `min[capacity().capacity(), size() + n]`).

    Example. Consider a ``circular_buffer_space_optimized`` with the capacity of 6 and the size of 4. Its internal buffer may look like the one below.
    `|1|2|3|4| | |`
    `p ___^`
    After inserting 5 elements at the position `p`:
    `insert(p, (size_t)5, 0);`
    actually only 4 elements get inserted and elements `1` and `2` are overwritten. This is due to the fact the insert operation preserves the capacity. After insertion the internal buffer looks like this:
    `|0|0|0|0|3|4|`
    For comparison if the capacity would not be preserved the internal buffer would then result in `|1|2|0|0|0|0|0|3|4|`.

    See Also:

    `insert(iterator, value_type)`, `insert(iterator, InputIterator, InputIterator)`, `rinsert(iterator, value_type)`, `rinsert(iterator, size_type, value_type)`, `rinsert(iterator, InputIterator, InputIterator)`

    Parameters: |
    `item` | The element whose copies will be inserted.
    `n` | The number of `item`s the to be inserted.
    `pos` | An iterator specifying the position where the `item`s will be inserted.
    Requires: | `pos` is a valid iterator pointing to the `circular_buffer_space_optimized` or its end.
    Postconditions: | The number of `min[n, (pos - begin()) + reserve()]` elements will be inserted at the position `pos`. The number of `min[pos - begin(), max[0, n - reserve()]]` elements will be overwritten at the beginning of the `circular_buffer_space_optimized`. (See Example for the explanation.) The amount of allocated memory in the internal buffer may be predictively increased.
    Throws: | An allocation error if memory is exhausted (`std::bad_alloc` if the standard allocator is used). Whatever `T::T(const T&)` throws. Whatever `T::operator = (const T&)` throws.

25.     template<typename InputIterator>
          void insert(iterator pos, InputIterator first, InputIterator last);

    Insert the range `[first, last)` at the specified position.

    Exception Safety. Basic.

    Iterator Invalidation. Invalidates all iterators pointing to the ``circular_buffer_space_optimized`` (except iterators equal to `end()`).

    Complexity. Linear (in `[size() + std::distance(first, last)]`; in `min[capacity().capacity(), size() + std::distance(first, last)]` if the `InputIterator` is a RandomAccessIterator).

    Example. Consider a ``circular_buffer_space_optimized`` with the capacity of 6 and the size of 4. Its internal buffer may look like the one below.
    `|1|2|3|4| | |`
    `p ___^`
    After inserting a range of elements at the position `p`:
    `int array[] = { 5, 6, 7, 8, 9 };`
    `insert(p, array, array + 5);`
    actually only elements `6`, `7`, `8` and `9` from the specified range get inserted and elements `1` and `2` are overwritten. This is due to the fact the insert operation preserves the capacity. After insertion the internal buffer looks like this:
    `|6|7|8|9|3|4|`
    For comparison if the capacity would not be preserved the internal buffer would then result in `|1|2|5|6|7|8|9|3|4|`.

    See Also:

    `insert(iterator, value_type)`, `insert(iterator, size_type, value_type)`, `rinsert(iterator, value_type)`, `rinsert(iterator, size_type, value_type)`, `rinsert(iterator, InputIterator, InputIterator)`

    Parameters: |
    `first` | The beginning of the range to be inserted.
    `last` | The end of the range to be inserted.
    `pos` | An iterator specifying the position where the range will be inserted.
    Requires: | `pos` is a valid iterator pointing to the `circular_buffer_space_optimized` or its end. Valid range `[first, last)` where `first` and `last` meet the requirements of an InputIterator.
    Postconditions: | Elements from the range `[first + max[0, distance(first, last) - (pos - begin()) - reserve()], last)` will be inserted at the position `pos`. The number of `min[pos - begin(), max[0, distance(first, last) - reserve()]]` elements will be overwritten at the beginning of the `circular_buffer_space_optimized`. (See Example for the explanation.) The amount of allocated memory in the internal buffer may be predictively increased.
    Throws: | An allocation error if memory is exhausted (`std::bad_alloc` if the standard allocator is used). Whatever `T::T(const T&)` throws or nothing if `T::T(T&&)` is noexcept.

26.     iterator rinsert(iterator pos, param_value_type item);

    Insert an element before the specified position.

    Exception Safety. Basic.

    Iterator Invalidation. Invalidates all iterators pointing to the ``circular_buffer_space_optimized`` (except iterators equal to `end()`).

    Complexity. Linear (in the size of the ``circular_buffer_space_optimized``).

    See Also:

    `rinsert(iterator, size_type, value_type)`, `rinsert(iterator, InputIterator, InputIterator)`, `insert(iterator, value_type)`, `insert(iterator, size_type, value_type)`, `insert(iterator, InputIterator, InputIterator)`

    Parameters: |
    `item` | The element to be inserted.
    `pos` | An iterator specifying the position before which the `item` will be inserted.
    Requires: | `pos` is a valid iterator pointing to the `circular_buffer_space_optimized` or its end.
    Postconditions: | The `item` will be inserted before the position `pos`. If the `circular_buffer_space_optimized` is full, the last element will be overwritten. If the `circular_buffer_space_optimized` is full and the `pos` points to `end()`, then the `item` will not be inserted. If the capacity is `0`, nothing will be inserted. The amount of allocated memory in the internal buffer may be predictively increased.
    Returns: | Iterator to the inserted element or `end()` if the `item` is not inserted. (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. Whatever `T::operator = (const T&)` throws.

27.     iterator rinsert(iterator pos, rvalue_type item);

    Insert an element before the specified position.

    Exception Safety. Basic.

    Iterator Invalidation. Invalidates all iterators pointing to the ``circular_buffer_space_optimized`` (except iterators equal to `end()`).

    Complexity. Linear (in the size of the ``circular_buffer_space_optimized``).

    See Also:

    `rinsert(iterator, size_type, value_type)`, `rinsert(iterator, InputIterator, InputIterator)`, `insert(iterator, value_type)`, `insert(iterator, size_type, value_type)`, `insert(iterator, InputIterator, InputIterator)`

    Parameters: |
    `item` | The element to be inserted.
    `pos` | An iterator specifying the position before which the `item` will be inserted.
    Requires: | `pos` is a valid iterator pointing to the `circular_buffer_space_optimized` or its end.
    Postconditions: | The `item` will be inserted before the position `pos`. If the `circular_buffer_space_optimized` is full, the last element will be overwritten. If the `circular_buffer_space_optimized` is full and the `pos` points to `end()`, then the `item` will not be inserted. If the capacity is `0`, nothing will be inserted. The amount of allocated memory in the internal buffer may be predictively increased.
    Returns: | Iterator to the inserted element or `end()` if the `item` is not inserted. (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 or nothing if `T::T(T&&)` is noexcept.

28.     iterator rinsert(iterator pos);

    Insert an element before the specified position.

    Exception Safety. Basic.

    Iterator Invalidation. Invalidates all iterators pointing to the ``circular_buffer_space_optimized`` (except iterators equal to `end()`).

    Complexity. Linear (in the size of the ``circular_buffer_space_optimized``).

    See Also:

    `rinsert(iterator, size_type, value_type)`, `rinsert(iterator, InputIterator, InputIterator)`, `insert(iterator, value_type)`, `insert(iterator, size_type, value_type)`, `insert(iterator, InputIterator, InputIterator)`

    Parameters: |
    `pos` | An iterator specifying the position before which the `item` will be inserted.
    Requires: | `pos` is a valid iterator pointing to the `circular_buffer_space_optimized` or its end.
    Postconditions: | The `item` will be inserted before the position `pos`. If the `circular_buffer_space_optimized` is full, the last element will be overwritten. If the `circular_buffer_space_optimized` is full and the `pos` points to `end()`, then the `item` will not be inserted. If the capacity is `0`, nothing will be inserted. The amount of allocated memory in the internal buffer may be predictively increased.
    Returns: | Iterator to the inserted element or `end()` if the `item` is not inserted. (See the Effect.)
    Throws: | An allocation error if memory is exhausted (`std::bad_alloc` if the standard allocator is used). Whatever `T::T()` throws. Whatever `T::T(const T&)` throws or nothing if `T::T(T&&)` is noexcept.

29.     void rinsert(iterator pos, size_type n, param_value_type item);

    Insert `n` copies of the `item` before the specified position.

    Exception Safety. Basic.

    Iterator Invalidation. Invalidates all iterators pointing to the ``circular_buffer_space_optimized`` (except iterators equal to `end()`).

    Complexity. Linear (in `min[capacity().capacity(), size() + n]`).

    Example. Consider a ``circular_buffer_space_optimized`` with the capacity of 6 and the size of 4. Its internal buffer may look like the one below.
    `|1|2|3|4| | |`
    `p ___^`
    After inserting 5 elements before the position `p`:
    `rinsert(p, (size_t)5, 0);`
    actually only 4 elements get inserted and elements `3` and `4` are overwritten. This is due to the fact the rinsert operation preserves the capacity. After insertion the internal buffer looks like this:
    `|1|2|0|0|0|0|`
    For comparison if the capacity would not be preserved the internal buffer would then result in `|1|2|0|0|0|0|0|3|4|`.

    See Also:

    `rinsert(iterator, value_type)`, `rinsert(iterator, InputIterator, InputIterator)`, `insert(iterator, value_type)`, `insert(iterator, size_type, value_type)`, `insert(iterator, InputIterator, InputIterator)`

    Parameters: |
    `item` | The element whose copies will be inserted.
    `n` | The number of `item`s the to be inserted.
    `pos` | An iterator specifying the position where the `item`s will be inserted.
    Requires: | `pos` is a valid iterator pointing to the `circular_buffer_space_optimized` or its end.
    Postconditions: | The number of `min[n, (end() - pos) + reserve()]` elements will be inserted before the position `pos`. The number of `min[end() - pos, max[0, n - reserve()]]` elements will be overwritten at the end of the `circular_buffer_space_optimized`. (See Example for the explanation.) The amount of allocated memory in the internal buffer may be predictively increased.
    Throws: | An allocation error if memory is exhausted (`std::bad_alloc` if the standard allocator is used). Whatever `T::T(const T&)` throws. Whatever `T::operator = (const T&)` throws.

30.     template<typename InputIterator>
          void rinsert(iterator pos, InputIterator first, InputIterator last);

    Insert the range `[first, last)` before the specified position.

    Exception Safety. Basic.

    Iterator Invalidation. Invalidates all iterators pointing to the ``circular_buffer_space_optimized`` (except iterators equal to `end()`).

    Complexity. Linear (in `[size() + std::distance(first, last)]`; in `min[capacity().capacity(), size() + std::distance(first, last)]` if the `InputIterator` is a RandomAccessIterator).

    Example. Consider a ``circular_buffer_space_optimized`` with the capacity of 6 and the size of 4. Its internal buffer may look like the one below.
    `|1|2|3|4| | |`
    `p ___^`
    After inserting a range of elements before the position `p`:
    `int array[] = { 5, 6, 7, 8, 9 };`
    `insert(p, array, array + 5);`
    actually only elements `5`, `6`, `7` and `8` from the specified range get inserted and elements `3` and `4` are overwritten. This is due to the fact the rinsert operation preserves the capacity. After insertion the internal buffer looks like this:
    `|1|2|5|6|7|8|`
    For comparison if the capacity would not be preserved the internal buffer would then result in `|1|2|5|6|7|8|9|3|4|`.

    See Also:

    `rinsert(iterator, value_type)`, `rinsert(iterator, size_type, value_type)`, `insert(iterator, value_type)`, `insert(iterator, size_type, value_type)`, `insert(iterator, InputIterator, InputIterator)`

    Parameters: |
    `first` | The beginning of the range to be inserted.
    `last` | The end of the range to be inserted.
    `pos` | An iterator specifying the position where the range will be inserted.
    Requires: | `pos` is a valid iterator pointing to the `circular_buffer_space_optimized` or its end. Valid range `[first, last)` where `first` and `last` meet the requirements of an InputIterator.
    Postconditions: | Elements from the range `[first, last - max[0, distance(first, last) - (end() - pos) - reserve()])` will be inserted before the position `pos`. The number of `min[end() - pos, max[0, distance(first, last) - reserve()]]` elements will be overwritten at the end of the `circular_buffer`. (See Example for the explanation.) The amount of allocated memory in the internal buffer may be predictively increased.
    Throws: | An allocation error if memory is exhausted (`std::bad_alloc` if the standard allocator is used). Whatever `T::T(const T&)` throws. Whatever `T::operator = (const T&)` throws.

31.     iterator erase(iterator pos);

    Remove an element at the specified position.

    Exception Safety. Basic.

    Iterator Invalidation. Invalidates all iterators pointing to the ``circular_buffer_space_optimized`` (except iterators equal to `end()`).

    Complexity. Linear (in the size of the ``circular_buffer_space_optimized``).

    See Also:

    `erase(iterator, iterator)`, `rerase(iterator)`, `rerase(iterator, iterator)`, `clear()`

    Parameters: |
    `pos` | An iterator pointing at the element to be removed.
    Requires: | `pos` is a valid iterator pointing to the `circular_buffer_space_optimized` (but not an `end()`).
    Postconditions: | The element at the position `pos` is removed. The amount of allocated memory in the internal buffer may be predictively decreased.
    Returns: | Iterator to the first element remaining beyond the removed element or `end()` if no such element exists.
    Throws: | An allocation error if memory is exhausted (`std::bad_alloc` if the standard allocator is used). Whatever `T::operator = (const T&)` throws or nothing if `T::operator = (T&&)` is noexcept.

32.     iterator erase(iterator first, iterator last);

    Erase the range `[first, last)`.

    Exception Safety. Basic.

    Iterator Invalidation. Invalidates all iterators pointing to the ``circular_buffer_space_optimized`` (except iterators equal to `end()`).

    Complexity. Linear (in the size of the ``circular_buffer_space_optimized``).

    See Also:

    `erase(iterator)`, `rerase(iterator)`, `rerase(iterator, iterator)`, `clear()`

    Parameters: |
    `first` | The beginning of the range to be removed.
    `last` | The end of the range to be removed.
    Requires: | Valid range `[first, last)`.
    Postconditions: | The elements from the range `[first, last)` are removed. (If `first == last` nothing is removed.) The amount of allocated memory in the internal buffer may be predictively decreased.
    Returns: | Iterator to the first element remaining beyond the removed elements or `end()` if no such element exists.
    Throws: | An allocation error if memory is exhausted (`std::bad_alloc` if the standard allocator is used). Whatever `T::operator = (const T&)` throws or nothing if `T::operator = (T&&)` is noexcept.

33.     iterator rerase(iterator pos);

    Remove an element at the specified position.

    Exception Safety. Basic.

    Iterator Invalidation. Invalidates all iterators pointing to the ``circular_buffer_space_optimized`` (except iterators equal to `end()`).

    Complexity. Linear (in the size of the ``circular_buffer_space_optimized``).

    | Note
    Basically there is no difference between `erase(iterator)` and this method. It is implemented only for consistency with the base ``circular_buffer``.

    See Also:

    `erase(iterator)`, `erase(iterator, iterator)`, `rerase(iterator, iterator)`, `clear()`

    Parameters: |
    `pos` | An iterator pointing at the element to be removed.
    Requires: | `pos` is a valid iterator pointing to the `circular_buffer_space_optimized` (but not an `end()`). The amount of allocated memory in the internal buffer may be predictively decreased.
    Postconditions: | The element at the position `pos` is removed.
    Returns: | Iterator to the first element remaining in front of the removed element or `begin()` if no such element exists.
    Throws: | An allocation error if memory is exhausted (`std::bad_alloc` if the standard allocator is used). Whatever `T::operator = (const T&)` throws or nothing if `T::operator = (T&&)` is noexcept.

34.     iterator rerase(iterator first, iterator last);

    Erase the range `[first, last)`.

    Exception Safety. Basic.

    Iterator Invalidation. Invalidates all iterators pointing to the ``circular_buffer_space_optimized`` (except iterators equal to `end()`).

    Complexity. Linear (in the size of the ``circular_buffer_space_optimized``).

    | Note
    Basically there is no difference between `erase(iterator, iterator)` and this method. It is implemented only for consistency with the base `<`circular_buffer``.

    See Also:

    `erase(iterator)`, `erase(iterator, iterator)`, `rerase(iterator)`, `clear()`

    Parameters: |
    `first` | The beginning of the range to be removed.
    `last` | The end of the range to be removed.
    Requires: | Valid range `[first, last)`.
    Postconditions: | The elements from the range `[first, last)` are removed. (If `first == last` nothing is removed.) The amount of allocated memory in the internal buffer may be predictively decreased.
    Returns: | Iterator to the first element remaining in front of the removed elements or `begin()` if no such element exists.
    Throws: | An allocation error if memory is exhausted (`std::bad_alloc` if the standard allocator is used). Whatever `T::operator = (const T&)` throws or nothing if `T::operator = (T&&)` is noexcept.

35.     void clear();

    Remove all stored elements from the space optimized circular buffer.

    Exception Safety. Basic.

    Iterator Invalidation. Invalidates all iterators pointing to the ``circular_buffer_space_optimized`` (except iterators equal to `end()`).

    Complexity. Linear (in the size of the ``circular_buffer_space_optimized``).

    See Also:

    `~circular_buffer_space_optimized()`, `erase(iterator)`, `erase(iterator, iterator)`, `rerase(iterator)`, `rerase(iterator, iterator)`

    Postconditions: | `size() == 0` The amount of allocated memory in the internal buffer may be predictively decreased.
    Throws: | An allocation error if memory is exhausted (`std::bad_alloc` if the standard allocator is used).

### `circular_buffer_space_optimized` private member functions

1.     void adjust_min_capacity();

   Adjust the amount of allocated memory.

2.     size_type ensure_reserve(size_type new_capacity, size_type buffer_size) const;

   Ensure the reserve for possible growth up.

3.     void check_low_capacity(size_type n = 1);

   Check for low capacity.

4.     void check_high_capacity();

   Check for high capacity.

5.     void reduce_capacity(const true_type &);

   Specialized method for reducing the capacity.

6.     void reduce_capacity(const false_type &);

   Specialized method for reducing the capacity.

7.     template<typename IntegralType>
         void insert(const iterator & pos, IntegralType n, IntegralType item,
                     const true_type &);

   Specialized insert method.

8.     template<typename Iterator>
         void insert(const iterator & pos, Iterator first, Iterator last,
                     const false_type &);

   Specialized insert method.

9.     template<typename IntegralType>
         void rinsert(const iterator & pos, IntegralType n, IntegralType item,
                      const true_type &);

   Specialized rinsert method.

10.     template<typename Iterator>
          void rinsert(const iterator & pos, Iterator first, Iterator last,
                       const false_type &);

    Specialized rinsert method.

### `circular_buffer_space_optimized` private static functions

1.     static size_type
       init_capacity(const capacity_type & capacity_ctrl, size_type n);

   Determine the initial capacity.

2.     template<typename IntegralType>
         static size_type
         init_capacity(const capacity_type & capacity_ctrl, IntegralType n,
                       IntegralType, const true_type &);

   Specialized method for determining the initial capacity.

3.     template<typename Iterator>
         static size_type
         init_capacity(const capacity_type & capacity_ctrl, Iterator first,
                       Iterator last, const false_type &);

   Specialized method for determining the initial capacity.

4.     template<typename InputIterator>
         static size_type
         init_capacity(const capacity_type & capacity_ctrl, InputIterator,
                       InputIterator, const std::input_iterator_tag &);

   Specialized method for determining the initial capacity.

5.     template<typename ForwardIterator>
         static size_type
         init_capacity(const capacity_type & capacity_ctrl, ForwardIterator first,
                       ForwardIterator last, const std::forward_iterator_tag &);

   Specialized method for determining the initial capacity.