// Implementation of the base circular buffer. // Copyright (c) 2003-2008 Jan Gaspar // 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) #if !defined(BOOST_CIRCULAR_BUFFER_BASE_HPP) #define BOOST_CIRCULAR_BUFFER_BASE_HPP #if defined(_MSC_VER) && _MSC_VER >= 1200 #pragma once #endif #include #include #include #include #include #include #include #include #include #include #include #if !defined(BOOST_NO_EXCEPTIONS) #include #endif #if BOOST_CB_ENABLE_DEBUG #include #endif #if BOOST_WORKAROUND(__MWERKS__, BOOST_TESTED_AT(0x3205)) #include #endif #if defined(BOOST_NO_STDC_NAMESPACE) namespace std { using ::memset; } #endif namespace boost { /*! \class circular_buffer \brief Circular buffer - a STL compliant container. \param T The type of the elements stored in the 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 circular_buffer's methods e.g. insert(iterator pos, const value_type& item = %value_type()). And EqualityComparable and/or LessThanComparable if the circular_buffer will be compared with another container. \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 For detailed documentation of the circular_buffer visit: http://www.boost.org/libs/circular_buffer/doc/circular_buffer.html */ template class circular_buffer /*! \cond */ #if BOOST_CB_ENABLE_DEBUG : public cb_details::debug_iterator_registry #endif /*! \endcond */ { // Requirements BOOST_CLASS_REQUIRE(T, boost, SGIAssignableConcept); public: // Basic types //! The type of elements stored in the circular_buffer. typedef typename Alloc::value_type value_type; //! A pointer to an element. typedef typename Alloc::pointer pointer; //! A const pointer to the element. typedef typename Alloc::const_pointer const_pointer; //! A reference to an element. typedef typename Alloc::reference reference; //! A const reference to an element. typedef typename Alloc::const_reference const_reference; //! The distance type. /*! (A signed integral type used to represent the distance between two iterators.) */ typedef typename Alloc::difference_type difference_type; //! The size type. /*! (An unsigned integral type that can represent any non-negative value of the container's distance type.) */ typedef typename Alloc::size_type size_type; //! The type of an allocator used in the circular_buffer. typedef Alloc allocator_type; // Iterators //! A const (random access) iterator used to iterate through the circular_buffer. typedef cb_details::iterator< circular_buffer, cb_details::const_traits > const_iterator; //! A (random access) iterator used to iterate through the circular_buffer. typedef cb_details::iterator< circular_buffer, cb_details::nonconst_traits > iterator; //! A const iterator used to iterate backwards through a circular_buffer. typedef boost::reverse_iterator const_reverse_iterator; //! An iterator used to iterate backwards through a circular_buffer. typedef boost::reverse_iterator reverse_iterator; // Container specific types //! An array range. /*! (A typedef for the std::pair where its first element is a pointer to a beginning of an array and its second element represents a size of the array.) */ typedef std::pair array_range; //! A range of a const array. /*! (A typedef for the std::pair where its first element is a pointer to a beginning of a const array and its second element represents a size of the const array.) */ typedef std::pair const_array_range; //! The capacity type. /*! (Same as size_type - defined for consistency with the circular_buffer_space_optimized.) */ typedef size_type capacity_type; // Helper types // A type representing the "best" way to pass the value_type to a method. typedef typename call_traits::param_type param_value_type; // A type representing the "best" way to return the value_type from a const method. typedef typename call_traits::param_type return_value_type; private: // Member variables //! The internal buffer used for storing elements in the circular buffer. pointer m_buff; //! The internal buffer's end (end of the storage space). pointer m_end; //! The virtual beginning of the circular buffer. pointer m_first; //! The virtual end of the circular buffer (one behind the last element). pointer m_last; //! The number of items currently stored in the circular buffer. size_type m_size; //! The allocator. allocator_type m_alloc; // Friends #if defined(BOOST_NO_MEMBER_TEMPLATE_FRIENDS) friend iterator; friend const_iterator; #else template friend struct cb_details::iterator; #endif public: // Allocator //! Get the allocator. /*! \return The allocator. \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). \sa get_allocator() for obtaining an allocator %reference. */ allocator_type get_allocator() const { return m_alloc; } //! Get the allocator reference. /*! \return A reference to the allocator. \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). \note This method was added in order to optimize obtaining of the allocator with a state, although use of stateful allocators in STL is discouraged. \sa get_allocator() const */ allocator_type& get_allocator() { return m_alloc; } // Element access //! Get the iterator pointing to the beginning of the circular_buffer. /*! \return A random access iterator pointing to the first element of the circular_buffer. If the circular_buffer is empty it returns an iterator equal to the one returned by end(). \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). \sa end(), rbegin(), rend() */ iterator begin() { return iterator(this, empty() ? 0 : m_first); } //! Get the iterator pointing to the end of the circular_buffer. /*! \return A random access iterator pointing to the element "one behind" the last element of the circular_buffer. If the circular_buffer is empty it returns an iterator equal to the one returned by begin(). \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). \sa begin(), rbegin(), rend() */ iterator end() { return iterator(this, 0); } //! Get the const iterator pointing to the beginning of the circular_buffer. /*! \return A const random access iterator pointing to the first element of the circular_buffer. If the circular_buffer is empty it returns an iterator equal to the one returned by end() const. \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). \sa end() const, rbegin() const, rend() const */ const_iterator begin() const { return const_iterator(this, empty() ? 0 : m_first); } //! Get the const iterator pointing to the end of the circular_buffer. /*! \return A const random access iterator pointing to the element "one behind" the last element of the circular_buffer. If the circular_buffer is empty it returns an iterator equal to the one returned by begin() const const. \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). \sa begin() const, rbegin() const, rend() const */ const_iterator end() const { return const_iterator(this, 0); } //! Get the iterator pointing to the beginning of the "reversed" circular_buffer. /*! \return A reverse random access iterator pointing to the last element of the circular_buffer. If the circular_buffer is empty it returns an iterator equal to the one returned by rend(). \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). \sa rend(), begin(), end() */ reverse_iterator rbegin() { return reverse_iterator(end()); } //! Get the iterator pointing to the end of the "reversed" circular_buffer. /*! \return A reverse random access iterator pointing to the element "one before" the first element of the circular_buffer. If the circular_buffer is empty it returns an iterator equal to the one returned by rbegin(). \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). \sa rbegin(), begin(), end() */ reverse_iterator rend() { return reverse_iterator(begin()); } //! Get the const iterator pointing to the beginning of the "reversed" circular_buffer. /*! \return A const reverse random access iterator pointing to the last element of the circular_buffer. If the circular_buffer is empty it returns an iterator equal to the one returned by rend() const. \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). \sa rend() const, begin() const, end() const */ const_reverse_iterator rbegin() const { return const_reverse_iterator(end()); } //! Get the const iterator pointing to the end of the "reversed" circular_buffer. /*! \return A const reverse random access iterator pointing to the element "one before" the first element of the circular_buffer. If the circular_buffer is empty it returns an iterator equal to the one returned by rbegin() const. \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). \sa rbegin() const, begin() const, end() const */ const_reverse_iterator rend() const { return const_reverse_iterator(begin()); } //! Get the element at the index position. /*! \pre 0 \<= index \&\& index \< size() \param index The position of the element. \return A reference to the element at the index position. \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). \sa at() */ reference operator [] (size_type index) { BOOST_CB_ASSERT(index < size()); // check for invalid index return *add(m_first, index); } //! Get the element at the index position. /*! \pre 0 \<= index \&\& index \< size() \param index The position of the element. \return A const reference to the element at the index position. \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). \sa \link at(size_type)const at() const \endlink */ return_value_type operator [] (size_type index) const { BOOST_CB_ASSERT(index < size()); // check for invalid index return *add(m_first, index); } //! Get the element at the index position. /*! \param index The position of the element. \return A reference to the element at the index position. \throws std::out_of_range when the index is invalid (when index >= size()). \par Exception Safety Strong. \par Iterator Invalidation Does not invalidate any iterators. \par Complexity Constant (in the size of the circular_buffer). \sa \link operator[](size_type) operator[] \endlink */ reference at(size_type index) { check_position(index); return (*this)[index]; } //! Get the element at the index position. /*! \param index The position of the element. \return A const reference to the element at the index position. \throws std::out_of_range when the index is invalid (when index >= size()). \par Exception Safety Strong. \par Iterator Invalidation Does not invalidate any iterators. \par Complexity Constant (in the size of the circular_buffer). \sa \link operator[](size_type)const operator[] const \endlink */ return_value_type at(size_type index) const { check_position(index); return (*this)[index]; } //! Get the first element. /*! \pre !empty() \return A reference to the first element of the circular_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). \sa back() */ reference front() { BOOST_CB_ASSERT(!empty()); // check for empty buffer (front element not available) return *m_first; } //! Get the last element. /*! \pre !empty() \return A reference to the last element of the circular_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). \sa front() */ reference back() { BOOST_CB_ASSERT(!empty()); // check for empty buffer (back element not available) return *((m_last == m_buff ? m_end : m_last) - 1); } //! Get the first element. /*! \pre !empty() \return A const reference to the first element of the circular_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). \sa back() const */ return_value_type front() const { BOOST_CB_ASSERT(!empty()); // check for empty buffer (front element not available) return *m_first; } //! Get the last element. /*! \pre !empty() \return A const reference to the last element of the circular_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). \sa front() const */ return_value_type back() const { BOOST_CB_ASSERT(!empty()); // check for empty buffer (back element not available) return *((m_last == m_buff ? m_end : m_last) - 1); } //! Get the first continuous array of the internal buffer. /*! This method in combination with array_two() can be useful when passing the stored data into a legacy C API as an array. Suppose there is a circular_buffer of capacity 10, containing 7 characters 'a', 'b', ..., 'g' where buff[0] == 'a', buff[1] == 'b', ... and buff[6] == 'g':

circular_buffer buff(10);

The internal representation is often not linear and the state of the internal buffer may look like this:

|e|f|g| | | |a|b|c|d|
end ---^
begin -------^

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

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

There are two ways how to write the content of the circular_buffer into a file. Either relying on array_one() and array_two() methods and calling the write function twice:

array_range ar = buff.array_one();
write(file_desc, ar.first, ar.second);
ar = buff.array_two();
write(file_desc, ar.first, ar.second);

Or relying on the linearize() method:

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

Since the complexity of array_one() and array_two() methods is constant the first option is suitable when calling the write method is "cheap". On the other hand the second option is more suitable when calling the write method is more "expensive" than calling the linearize() method whose complexity is linear. \return The array range of the first continuous array of the internal buffer. In the case the circular_buffer is empty the size of the returned array is 0. \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). \warning In general invoking any method which modifies the internal state of the circular_buffer may delinearize the internal buffer and invalidate the array ranges returned by array_one() and array_two() (and their const versions). \note In the case the internal buffer is linear e.g. |a|b|c|d|e|f|g| | | | the "array one" is represented by |a|b|c|d|e|f|g| and the "array two" does not exist (the array_two() method returns an array with the size 0). \sa array_two(), linearize() */ array_range array_one() { return array_range(m_first, (m_last <= m_first && !empty() ? m_end : m_last) - m_first); } //! Get the second continuous array of the internal buffer. /*! This method in combination with array_one() can be useful when passing the stored data into a legacy C API as an array. \return The array range of the second continuous array of the internal buffer. In the case the internal buffer is linear or the circular_buffer is empty the size of the returned array is 0. \throws Nothing. \par Exception Safety No-throw. \par Iterator Invalidation Does not invalidate any iterators. \par Complexity Constant (in the size of the circular_buffer). \sa array_one() */ array_range array_two() { return array_range(m_buff, m_last <= m_first && !empty() ? m_last - m_buff : 0); } //! Get the first continuous array of the internal buffer. /*! This method in combination with array_two() const can be useful when passing the stored data into a legacy C API as an array. \return The array range of the first continuous array of the internal buffer. In the case the circular_buffer is empty the size of the returned array is 0. \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). \sa array_two() const; array_one() for more details how to pass data into a legacy C API. */ const_array_range array_one() const { return const_array_range(m_first, (m_last <= m_first && !empty() ? m_end : m_last) - m_first); } //! Get the second continuous array of the internal buffer. /*! This method in combination with array_one() const can be useful when passing the stored data into a legacy C API as an array. \return The array range of the second continuous array of the internal buffer. In the case the internal buffer is linear or the circular_buffer is empty the size of the returned array is 0. \throws Nothing. \par Exception Safety No-throw. \par Iterator Invalidation Does not invalidate any iterators. \par Complexity Constant (in the size of the circular_buffer). \sa array_one() const */ const_array_range array_two() const { return const_array_range(m_buff, m_last <= m_first && !empty() ? m_last - m_buff : 0); } //! Linearize the internal buffer into a continuous array. /*! This method can be useful when passing the stored data into a legacy C API as an array. \post \&(*this)[0] \< \&(*this)[1] \< ... \< \&(*this)[size() - 1] \return A pointer to the beginning of the array or 0 if empty. \throws Whatever T::T(const T&) throws. \throws Whatever T::operator = (const T&) throws. \par Exception Safety Basic; no-throw if the operations in the Throws section do not throw anything. \par Iterator Invalidation Invalidates all iterators pointing to the circular_buffer (except iterators equal to end()); does not invalidate any iterators if the postcondition (the Effect) is already met prior calling this method. \par Complexity Linear (in the size of the circular_buffer); constant if the postcondition (the Effect) is already met. \warning In general invoking any method which modifies the internal state of the circular_buffer may delinearize the internal buffer and invalidate the returned pointer. \sa array_one() and array_two() for the other option how to pass data into a legacy C API; is_linearized(), rotate(const_iterator) */ pointer linearize() { if (empty()) return 0; if (m_first < m_last || m_last == m_buff) return m_first; pointer src = m_first; pointer dest = m_buff; size_type moved = 0; size_type constructed = 0; BOOST_TRY { for (pointer first = m_first; dest < src; src = first) { for (size_type ii = 0; src < m_end; ++src, ++dest, ++moved, ++ii) { if (moved == size()) { first = dest; break; } if (dest == first) { first += ii; break; } if (is_uninitialized(dest)) { m_alloc.construct(dest, *src); ++constructed; } else { value_type tmp = *src; replace(src, *dest); replace(dest, tmp); } } } } BOOST_CATCH(...) { m_last += constructed; m_size += constructed; BOOST_RETHROW } BOOST_CATCH_END for (src = m_end - constructed; src < m_end; ++src) destroy_item(src); m_first = m_buff; m_last = add(m_buff, size()); #if BOOST_CB_ENABLE_DEBUG invalidate_iterators_except(end()); #endif return m_buff; } //! Is the circular_buffer linearized? /*! \return true if the internal buffer is linearized into a continuous array (i.e. the circular_buffer meets a condition \&(*this)[0] \< \&(*this)[1] \< ... \< \&(*this)[size() - 1]); 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). \sa linearize(), array_one(), array_two() */ bool is_linearized() const { return m_first < m_last || m_last == m_buff; } //! Rotate elements in the circular_buffer. /*! A more effective implementation of std::rotate. \pre new_begin is a valid iterator pointing to the circular_buffer except its end. \post Before calling the method suppose:

m == std::distance(new_begin, end())
n == std::distance(begin(), new_begin)
val_0 == *new_begin, val_1 == *(new_begin + 1), ... val_m == *(new_begin + m)
val_r1 == *(new_begin - 1), val_r2 == *(new_begin - 2), ... val_rn == *(new_begin - n)

then after call to the method:

val_0 == (*this)[0] \&\& val_1 == (*this)[1] \&\& ... \&\& val_m == (*this)[m - 1] \&\& val_r1 == (*this)[m + n - 1] \&\& val_r2 == (*this)[m + n - 2] \&\& ... \&\& val_rn == (*this)[m] \param new_begin The new beginning. \throws Whatever T::T(const T&) throws. \throws Whatever T::operator = (const T&) throws. \par Exception Safety Basic; no-throw if the circular_buffer is full or new_begin points to begin() or if the operations in the Throws section do not throw anything. \par Iterator Invalidation If m \< n invalidates iterators pointing to the last m elements (including new_begin, but not iterators equal to end()) else invalidates iterators pointing to the first n elements; does not invalidate any iterators if the circular_buffer is full. \par Complexity Linear (in (std::min)(m, n)); constant if the circular_buffer is full. \sa std::rotate */ void rotate(const_iterator new_begin) { BOOST_CB_ASSERT(new_begin.is_valid(this)); // check for uninitialized or invalidated iterator BOOST_CB_ASSERT(new_begin.m_it != 0); // check for iterator pointing to end() if (full()) { m_first = m_last = const_cast(new_begin.m_it); } else { difference_type m = end() - new_begin; difference_type n = new_begin - begin(); if (m < n) { for (; m > 0; --m) { push_front(back()); pop_back(); } } else { for (; n > 0; --n) { push_back(front()); pop_front(); } } } } // Size and capacity //! Get the number of elements currently stored in the circular_buffer. /*! \return The number of elements stored in the circular_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). \sa capacity(), max_size(), reserve(), \link resize() resize(size_type, const_reference)\endlink */ size_type size() const { return m_size; } /*! \brief Get the largest possible size or capacity of the circular_buffer. (It depends on allocator's %max_size()). \return The maximum size/capacity the circular_buffer can be set to. \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). \sa size(), capacity(), reserve() */ size_type max_size() const { return (std::min)(m_alloc.max_size(), (std::numeric_limits::max)()); } //! Is the circular_buffer empty? /*! \return true if there are no elements stored in the circular_buffer; 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). \sa full() */ bool empty() const { return size() == 0; } //! Is the circular_buffer full? /*! \return true if the number of elements stored in the circular_buffer equals the capacity of the circular_buffer; 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). \sa empty() */ bool full() const { return capacity() == size(); } /*! \brief Get the maximum number of elements which can be inserted into the circular_buffer 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). \sa capacity(), size(), max_size() */ size_type reserve() const { return capacity() - size(); } //! Get the capacity of the circular_buffer. /*! \return The maximum number of elements which can be stored in the circular_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). \sa reserve(), size(), max_size(), set_capacity(capacity_type) */ capacity_type capacity() const { return m_end - m_buff; } //! Change the capacity of the circular_buffer. /*! \post capacity() == new_capacity \&\& size() \<= new_capacity

If the current number of elements stored in the circular_buffer is greater than the desired new capacity then number of [size() - new_capacity] last elements will be removed and the new size will be equal to new_capacity. \param new_capacity The new capacity. \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 (except iterators equal to end()) if the new capacity is different from the original. \par Complexity Linear (in min[size(), new_capacity]). \sa rset_capacity(capacity_type), \link resize() resize(size_type, const_reference)\endlink */ void set_capacity(capacity_type new_capacity) { if (new_capacity == capacity()) return; pointer buff = allocate(new_capacity); iterator b = begin(); BOOST_TRY { reset(buff, cb_details::uninitialized_copy_with_alloc(b, b + (std::min)(new_capacity, size()), buff, m_alloc), new_capacity); } BOOST_CATCH(...) { deallocate(buff, new_capacity); BOOST_RETHROW } BOOST_CATCH_END } //! Change the size of the circular_buffer. /*! \post size() == new_size \&\& 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 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 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 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 (except iterators equal to end()) if the new size is greater than the current capacity. Invalidates iterators pointing to the removed elements if the new size is lower that the original size. Otherwise it does not invalidate any iterator. \par Complexity Linear (in the new size of the circular_buffer). \sa \link rresize() rresize(size_type, const_reference)\endlink, set_capacity(capacity_type) */ void resize(size_type new_size, param_value_type item = value_type()) { if (new_size > size()) { if (new_size > capacity()) set_capacity(new_size); insert(end(), new_size - size(), item); } else { iterator e = end(); erase(e - (size() - new_size), e); } } //! Change the capacity of the circular_buffer. /*! \post capacity() == new_capacity \&\& size() \<= new_capacity

If the current number of elements stored in the circular_buffer is greater than the desired new capacity then number of [size() - new_capacity] first elements will be removed and the new size will be equal to new_capacity. \param new_capacity The new capacity. \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 (except iterators equal to end()) if the new capacity is different from the original. \par Complexity Linear (in min[size(), new_capacity]). \sa set_capacity(capacity_type), \link rresize() rresize(size_type, const_reference)\endlink */ void rset_capacity(capacity_type new_capacity) { if (new_capacity == capacity()) return; pointer buff = allocate(new_capacity); iterator e = end(); BOOST_TRY { reset(buff, cb_details::uninitialized_copy_with_alloc(e - (std::min)(new_capacity, size()), e, buff, m_alloc), new_capacity); } BOOST_CATCH(...) { deallocate(buff, new_capacity); BOOST_RETHROW } BOOST_CATCH_END } //! Change the size of the circular_buffer. /*! \post size() == new_size \&\& 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 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 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 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 (except iterators equal to end()) if the new size is greater than the current capacity. Invalidates iterators pointing to the removed elements if the new size is lower that the original size. Otherwise it does not invalidate any iterator. \par Complexity Linear (in the new size of the circular_buffer). \sa \link resize() resize(size_type, const_reference)\endlink, rset_capacity(capacity_type) */ void rresize(size_type new_size, param_value_type item = value_type()) { if (new_size > size()) { if (new_size > capacity()) set_capacity(new_size); rinsert(begin(), new_size - size(), item); } else { rerase(begin(), end() - new_size); } } // Construction/Destruction //! Create an empty circular_buffer with zero capacity. /*! \post capacity() == 0 \&\& size() == 0 \param alloc The allocator. \throws "An allocation error" if memory is exhausted (std::bad_alloc if the standard allocator is used). \par Complexity Constant. \warning Since Boost version 1.36 the behaviour of this constructor has changed. Now the constructor does not allocate any memory and both capacity and size are set to zero. Also note when inserting an element into a circular_buffer with zero capacity (e.g. by \link push_back() push_back(const_reference)\endlink or \link insert(iterator, param_value_type) insert(iterator, value_type)\endlink) nothing will be inserted and the size (as well as capacity) remains zero. \note You can explicitly set the capacity by calling the set_capacity(capacity_type) method or you can use the other constructor with the capacity specified. \sa circular_buffer(capacity_type, const allocator_type& alloc), set_capacity(capacity_type) */ explicit circular_buffer(const allocator_type& alloc = allocator_type()) : m_buff(0), m_end(0), m_first(0), m_last(0), m_size(0), m_alloc(alloc) {} //! Create an empty circular_buffer with the specified capacity. /*! \post capacity() == buffer_capacity \&\& size() == 0 \param buffer_capacity The maximum number of elements which can be stored in the circular_buffer. \param alloc The allocator. \throws "An allocation error" if memory is exhausted (std::bad_alloc if the standard allocator is used). \par Complexity Constant. */ explicit circular_buffer(capacity_type buffer_capacity, const allocator_type& alloc = allocator_type()) : m_size(0), m_alloc(alloc) { initialize_buffer(buffer_capacity); m_first = m_last = m_buff; } /*! \brief Create a full circular_buffer with the specified capacity and filled with n copies of 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. \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(size_type n, param_value_type item, const allocator_type& alloc = allocator_type()) : m_size(n), m_alloc(alloc) { initialize_buffer(n, item); m_first = m_last = m_buff; } /*! \brief Create a circular_buffer with the specified capacity and filled with n copies of item. \pre buffer_capacity >= n \post capacity() == buffer_capacity \&\& size() == n \&\& (*this)[0] == item \&\& (*this)[1] == item \&\& ... \&\& (*this)[n - 1] == item \param buffer_capacity The capacity of the created circular_buffer. \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. \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(capacity_type buffer_capacity, size_type n, param_value_type item, const allocator_type& alloc = allocator_type()) : m_size(n), m_alloc(alloc) { BOOST_CB_ASSERT(buffer_capacity >= size()); // check for capacity lower than size initialize_buffer(buffer_capacity, item); m_first = m_buff; m_last = buffer_capacity == n ? m_buff : m_buff + n; } //! The copy constructor. /*! Creates a copy of the specified circular_buffer. \post *this == cb \param cb The circular_buffer 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(const circular_buffer& cb) : #if BOOST_CB_ENABLE_DEBUG debug_iterator_registry(), #endif m_size(cb.size()), m_alloc(cb.get_allocator()) { initialize_buffer(cb.capacity()); m_first = m_buff; BOOST_TRY { m_last = cb_details::uninitialized_copy_with_alloc(cb.begin(), cb.end(), m_buff, m_alloc); } BOOST_CATCH(...) { deallocate(m_buff, cb.capacity()); BOOST_RETHROW } BOOST_CATCH_END if (m_last == m_end) m_last = m_buff; } #if BOOST_WORKAROUND(BOOST_MSVC, < 1300) /*! \cond */ template circular_buffer(InputIterator first, InputIterator last) : m_alloc(allocator_type()) { initialize(first, last, is_integral()); } template circular_buffer(capacity_type capacity, InputIterator first, InputIterator last) : m_alloc(allocator_type()) { initialize(capacity, first, last, is_integral()); } /*! \endcond */ #else //! 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) \&\& 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(InputIterator first, InputIterator last, const allocator_type& alloc = allocator_type()) : m_alloc(alloc) { initialize(first, last, is_integral()); } //! Create a circular_buffer with the specified capacity and filled with a copy of the range. /*! \pre Valid range [first, last).
first and last have to meet the requirements of InputIterator. \post capacity() == buffer_capacity \&\& size() \<= std::distance(first, last) \&\& (*this)[0]== *(last - buffer_capacity) \&\& (*this)[1] == *(last - buffer_capacity + 1) \&\& ... \&\& (*this)[buffer_capacity - 1] == *(last - 1)

If the number of items to be copied from the range [first, last) is greater than the specified buffer_capacity then only elements from the range [last - buffer_capacity, last) will be copied. \param buffer_capacity The capacity of the created circular_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. \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 std::distance(first, last); in min[capacity, std::distance(first, last)] if the InputIterator is a RandomAccessIterator). */ template circular_buffer(capacity_type buffer_capacity, InputIterator first, InputIterator last, const allocator_type& alloc = allocator_type()) : m_alloc(alloc) { initialize(buffer_capacity, first, last, is_integral()); } #endif // #if BOOST_WORKAROUND(BOOST_MSVC, < 1300) //! The destructor. /*! Destroys the circular_buffer. \throws Nothing. \par Iterator Invalidation Invalidates all iterators pointing to the circular_buffer (including iterators equal to end()). \par Complexity Constant (in the size of the circular_buffer) for scalar types; linear for other types. \sa clear() */ ~circular_buffer() { destroy(); #if BOOST_CB_ENABLE_DEBUG invalidate_all_iterators(); #endif } public: // Assign methods //! The assign operator. /*! Makes this circular_buffer to become a copy of the specified circular_buffer. \post *this == cb \param cb The circular_buffer 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 Exception Safety Strong. \par Iterator Invalidation Invalidates all iterators pointing to this circular_buffer (except iterators equal to end()). \par Complexity Linear (in the size of cb). \sa \link assign(size_type, param_value_type) assign(size_type, const_reference)\endlink, \link assign(capacity_type, size_type, param_value_type) assign(capacity_type, size_type, const_reference)\endlink, assign(InputIterator, InputIterator), assign(capacity_type, InputIterator, InputIterator) */ circular_buffer& operator = (const circular_buffer& cb) { if (this == &cb) return *this; pointer buff = allocate(cb.capacity()); BOOST_TRY { reset(buff, cb_details::uninitialized_copy_with_alloc(cb.begin(), cb.end(), buff, m_alloc), cb.capacity()); } BOOST_CATCH(...) { deallocate(buff, cb.capacity()); BOOST_RETHROW } BOOST_CATCH_END return *this; } //! Assign n items into the circular_buffer. /*! The content of the circular_buffer will be removed and replaced with n copies of the item. \post capacity() == n \&\& size() == n \&\& (*this)[0] == item \&\& (*this)[1] == item \&\& ... \&\& (*this) [n - 1] == item \param n The number of elements the circular_buffer will be filled with. \param item The element the circular_buffer will be filled with. \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 (except iterators equal to end()). \par Complexity Linear (in the n). \sa \link operator=(const circular_buffer&) operator=\endlink, \link assign(capacity_type, size_type, param_value_type) assign(capacity_type, size_type, const_reference)\endlink, assign(InputIterator, InputIterator), assign(capacity_type, InputIterator, InputIterator) */ void assign(size_type n, param_value_type item) { assign_n(n, n, cb_details::assign_n(n, item, m_alloc)); } //! Assign n items into the circular_buffer specifying the capacity. /*! The capacity of the circular_buffer will be set to the specified value and the content of the circular_buffer will be removed and replaced with n copies of the item. \pre capacity >= n \post capacity() == buffer_capacity \&\& size() == n \&\& (*this)[0] == item \&\& (*this)[1] == item \&\& ... \&\& (*this) [n - 1] == item \param buffer_capacity The new capacity. \param n The number of elements the circular_buffer will be filled with. \param item The element the circular_buffer will be filled with. \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 (except iterators equal to end()). \par Complexity Linear (in the n). \sa \link operator=(const circular_buffer&) operator=\endlink, \link assign(size_type, param_value_type) assign(size_type, const_reference)\endlink, assign(InputIterator, InputIterator), assign(capacity_type, InputIterator, InputIterator) */ void assign(capacity_type buffer_capacity, size_type n, param_value_type item) { BOOST_CB_ASSERT(buffer_capacity >= n); // check for new capacity lower than n assign_n(buffer_capacity, n, cb_details::assign_n(n, item, m_alloc)); } //! Assign a copy of the range into the circular_buffer. /*! The content of the circular_buffer will be removed and replaced with copies of elements from the specified 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) \param first The beginning of the range to be copied. \param last The end of the range to be copied. \throws "An allocation error" if memory is exhausted (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 (except iterators equal to end()). \par Complexity Linear (in the std::distance(first, last)). \sa \link operator=(const circular_buffer&) operator=\endlink, \link assign(size_type, param_value_type) assign(size_type, const_reference)\endlink, \link assign(capacity_type, size_type, param_value_type) assign(capacity_type, size_type, const_reference)\endlink, assign(capacity_type, InputIterator, InputIterator) */ template void assign(InputIterator first, InputIterator last) { assign(first, last, is_integral()); } //! Assign a copy of the range into the circular_buffer specifying the capacity. /*! The capacity of the circular_buffer will be set to the specified value and the content of the circular_buffer will be removed and replaced with copies of elements from the specified range. \pre Valid range [first, last).
first and last have to meet the requirements of InputIterator. \post capacity() == buffer_capacity \&\& size() \<= std::distance(first, last) \&\& (*this)[0]== *(last - buffer_capacity) \&\& (*this)[1] == *(last - buffer_capacity + 1) \&\& ... \&\& (*this)[buffer_capacity - 1] == *(last - 1)

If the number of items to be copied from the range [first, last) is greater than the specified buffer_capacity then only elements from the range [last - buffer_capacity, last) will be copied. \param buffer_capacity The new capacity. \param first The beginning of the range to be copied. \param last The end of the range to be copied. \throws "An allocation error" if memory is exhausted (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 (except iterators equal to end()). \par Complexity Linear (in std::distance(first, last); in min[capacity, std::distance(first, last)] if the InputIterator is a RandomAccessIterator). \sa \link operator=(const circular_buffer&) operator=\endlink, \link assign(size_type, param_value_type) assign(size_type, const_reference)\endlink, \link assign(capacity_type, size_type, param_value_type) assign(capacity_type, size_type, const_reference)\endlink, assign(InputIterator, InputIterator) */ template void assign(capacity_type buffer_capacity, InputIterator first, InputIterator last) { assign(buffer_capacity, first, last, is_integral()); } //! Swap the contents of two circular_buffers. /*! \post this contains elements of cb and vice versa; the capacity of this equals to the capacity of cb and vice versa. \param cb The circular_buffer whose content will be swapped. \throws Nothing. \par Exception Safety No-throw. \par Iterator Invalidation Invalidates all iterators of both circular_buffers. (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 otherwise an assertion will report an error if such invalidated iterator is used.) \par Complexity Constant (in the size of the circular_buffer). \sa swap(circular_buffer&, circular_buffer&) */ void swap(circular_buffer& cb) { swap_allocator(cb, is_stateless()); std::swap(m_buff, cb.m_buff); std::swap(m_end, cb.m_end); std::swap(m_first, cb.m_first); std::swap(m_last, cb.m_last); std::swap(m_size, cb.m_size); #if BOOST_CB_ENABLE_DEBUG invalidate_all_iterators(); cb.invalidate_all_iterators(); #endif } // push and pop //! Insert a new element at the end of the circular_buffer. /*! \post if capacity() > 0 then back() == item
If the circular_buffer is full, the first element will be removed. If the capacity is 0, nothing will be inserted. \param item The element to be inserted. \throws Whatever T::T(const T&) throws. \throws Whatever T::operator = (const T&) throws. \par Exception Safety Basic; no-throw if the operation in the Throws section does not throw anything. \par Iterator Invalidation Does not invalidate any iterators with the exception of iterators pointing to the overwritten element. \par Complexity Constant (in the size of the circular_buffer). \sa \link push_front() push_front(const_reference)\endlink, pop_back(), pop_front() */ void push_back(param_value_type item = value_type()) { if (full()) { if (empty()) return; replace(m_last, item); increment(m_last); m_first = m_last; } else { m_alloc.construct(m_last, item); increment(m_last); ++m_size; } } //! Insert a new element at the beginning of the circular_buffer. /*! \post if capacity() > 0 then front() == item
If the circular_buffer is full, the last element will be removed. If the capacity is 0, nothing will be inserted. \param item The element to be inserted. \throws Whatever T::T(const T&) throws. \throws Whatever T::operator = (const T&) throws. \par Exception Safety Basic; no-throw if the operation in the Throws section does not throw anything. \par Iterator Invalidation Does not invalidate any iterators with the exception of iterators pointing to the overwritten element. \par Complexity Constant (in the size of the circular_buffer). \sa \link push_back() push_back(const_reference)\endlink, pop_back(), pop_front() */ void push_front(param_value_type item = value_type()) { BOOST_TRY { if (full()) { if (empty()) return; decrement(m_first); replace(m_first, item); m_last = m_first; } else { decrement(m_first); m_alloc.construct(m_first, item); ++m_size; } } BOOST_CATCH(...) { increment(m_first); BOOST_RETHROW } BOOST_CATCH_END } //! Remove the last element from the circular_buffer. /*! \pre !empty() \post The last element is removed from the circular_buffer. \throws Nothing. \par Exception Safety No-throw. \par Iterator Invalidation Invalidates only iterators pointing to the removed element. \par Complexity Constant (in the size of the circular_buffer). \sa pop_front(), \link push_back() push_back(const_reference)\endlink, \link push_front() push_front(const_reference)\endlink */ void pop_back() { BOOST_CB_ASSERT(!empty()); // check for empty buffer (back element not available) decrement(m_last); destroy_item(m_last); --m_size; } //! Remove the first element from the circular_buffer. /*! \pre !empty() \post The first element is removed from the circular_buffer. \throws Nothing. \par Exception Safety No-throw. \par Iterator Invalidation Invalidates only iterators pointing to the removed element. \par Complexity Constant (in the size of the circular_buffer). \sa pop_back(), \link push_back() push_back(const_reference)\endlink, \link push_front() push_front(const_reference)\endlink */ void pop_front() { BOOST_CB_ASSERT(!empty()); // check for empty buffer (front element not available) destroy_item(m_first); increment(m_first); --m_size; } public: // Insert //! Insert an element at the specified position. /*! \pre pos is a valid iterator pointing to the circular_buffer or its end. \post The item will be inserted at the position pos.
If the circular_buffer is full, the first element will be overwritten. If the circular_buffer is full and the pos points to begin(), then the item will not be inserted. If the capacity is 0, nothing will be inserted. \param pos An iterator specifying the position where the item will be inserted. \param item The element to be inserted. \return Iterator to the inserted element or begin() if the item is not inserted. (See the Effect.) \throws Whatever T::T(const T&) throws. \throws Whatever T::operator = (const T&) throws. \par Exception Safety Basic; no-throw if the operation in the Throws section does not throw anything. \par Iterator Invalidation Invalidates iterators pointing to the elements at the insertion point (including pos) and iterators behind the insertion point (towards the end; except iterators equal to end()). It also invalidates iterators pointing to the overwritten element. \par Complexity Linear (in std::distance(pos, end())). \sa \link insert(iterator, size_type, param_value_type) insert(iterator, size_type, value_type)\endlink, insert(iterator, InputIterator, InputIterator), \link rinsert(iterator, param_value_type) rinsert(iterator, value_type)\endlink, \link rinsert(iterator, size_type, param_value_type) rinsert(iterator, size_type, value_type)\endlink, rinsert(iterator, InputIterator, InputIterator) */ iterator insert(iterator pos, param_value_type item = value_type()) { BOOST_CB_ASSERT(pos.is_valid(this)); // check for uninitialized or invalidated iterator iterator b = begin(); if (full() && pos == b) return b; return insert_item(pos, item); } //! Insert n copies of the item at the specified position. /*! \pre pos is a valid iterator pointing to the circular_buffer or its end. \post 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.
(See Example for the explanation.) \param pos An iterator specifying the position where the items will be inserted. \param n The number of items the to be inserted. \param item The element whose copies will be inserted. \throws Whatever T::T(const T&) throws. \throws Whatever T::operator = (const T&) throws. \par Exception Safety Basic; no-throw if the operations in the Throws section do not throw anything. \par Iterator Invalidation Invalidates iterators pointing to the elements at the insertion point (including pos) and iterators behind the insertion point (towards the end; except iterators equal to end()). It also invalidates iterators pointing to the overwritten elements. \par Complexity Linear (in min[capacity(), std::distance(pos, end()) + n]). \par Example Consider a circular_buffer 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|. \sa \link insert(iterator, param_value_type) insert(iterator, value_type)\endlink, insert(iterator, InputIterator, InputIterator), \link rinsert(iterator, param_value_type) rinsert(iterator, value_type)\endlink, \link rinsert(iterator, size_type, param_value_type) rinsert(iterator, size_type, value_type)\endlink, rinsert(iterator, InputIterator, InputIterator) */ void insert(iterator pos, size_type n, param_value_type item) { BOOST_CB_ASSERT(pos.is_valid(this)); // check for uninitialized or invalidated iterator if (n == 0) return; size_type copy = capacity() - (end() - pos); if (copy == 0) return; if (n > copy) n = copy; insert_n(pos, n, cb_details::item_wrapper(item)); } //! Insert the range [first, last) at the specified position. /*! \pre pos is a valid iterator pointing to the circular_buffer or its end.
Valid range [first, last) where first and last meet the requirements of an InputIterator. \post 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.
(See Example for the explanation.) \param pos An iterator specifying the position where the range will be inserted. \param first The beginning of the range to be inserted. \param last The end of the range to be inserted. \throws Whatever T::T(const T&) throws. \throws Whatever T::operator = (const T&) throws. \par Exception Safety Basic; no-throw if the operations in the Throws section do not throw anything. \par Iterator Invalidation Invalidates iterators pointing to the elements at the insertion point (including pos) and iterators behind the insertion point (towards the end; except iterators equal to end()). It also invalidates iterators pointing to the overwritten elements. \par Complexity Linear (in [std::distance(pos, end()) + std::distance(first, last)]; in min[capacity(), std::distance(pos, end()) + std::distance(first, last)] if the InputIterator is a RandomAccessIterator). \par Example Consider a circular_buffer 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|. \sa \link insert(iterator, param_value_type) insert(iterator, value_type)\endlink, \link insert(iterator, size_type, param_value_type) insert(iterator, size_type, value_type)\endlink, \link rinsert(iterator, param_value_type) rinsert(iterator, value_type)\endlink, \link rinsert(iterator, size_type, param_value_type) rinsert(iterator, size_type, value_type)\endlink, rinsert(iterator, InputIterator, InputIterator) */ template void insert(iterator pos, InputIterator first, InputIterator last) { BOOST_CB_ASSERT(pos.is_valid(this)); // check for uninitialized or invalidated iterator insert(pos, first, last, is_integral()); } //! Insert an element before the specified position. /*! \pre pos is a valid iterator pointing to the circular_buffer or its end. \post The item will be inserted before the position pos.
If the circular_buffer is full, the last element will be overwritten. If the circular_buffer is full and the pos points to end(), then the item will not be inserted. If the capacity is 0, nothing will be inserted. \param pos An iterator specifying the position before which the item will be inserted. \param item The element to be inserted. \return Iterator to the inserted element or end() if the item is not inserted. (See the Effect.) \throws Whatever T::T(const T&) throws. \throws Whatever T::operator = (const T&) throws. \par Exception Safety Basic; no-throw if the operations in the Throws section do not throw anything. \par Iterator Invalidation Invalidates iterators pointing to the elements before the insertion point (towards the beginning and excluding pos). It also invalidates iterators pointing to the overwritten element. \par Complexity Linear (in std::distance(begin(), pos)). \sa \link rinsert(iterator, size_type, param_value_type) rinsert(iterator, size_type, value_type)\endlink, rinsert(iterator, InputIterator, InputIterator), \link insert(iterator, param_value_type) insert(iterator, value_type)\endlink, \link insert(iterator, size_type, param_value_type) insert(iterator, size_type, value_type)\endlink, insert(iterator, InputIterator, InputIterator) */ iterator rinsert(iterator pos, param_value_type item = value_type()) { BOOST_CB_ASSERT(pos.is_valid(this)); // check for uninitialized or invalidated iterator if (full() && pos.m_it == 0) return end(); if (pos == begin()) { BOOST_TRY { decrement(m_first); construct_or_replace(!full(), m_first, item); } BOOST_CATCH(...) { increment(m_first); BOOST_RETHROW } BOOST_CATCH_END pos.m_it = m_first; } else { pointer src = m_first; pointer dest = m_first; decrement(dest); pos.m_it = map_pointer(pos.m_it); bool construct = !full(); BOOST_TRY { while (src != pos.m_it) { construct_or_replace(construct, dest, *src); increment(src); increment(dest); construct = false; } decrement(pos.m_it); replace(pos.m_it, item); } BOOST_CATCH(...) { if (!construct && !full()) { decrement(m_first); ++m_size; } BOOST_RETHROW } BOOST_CATCH_END decrement(m_first); } if (full()) m_last = m_first; else ++m_size; return iterator(this, pos.m_it); } //! Insert n copies of the item before the specified position. /*! \pre pos is a valid iterator pointing to the circular_buffer or its end. \post 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.
(See Example for the explanation.) \param pos An iterator specifying the position where the items will be inserted. \param n The number of items the to be inserted. \param item The element whose copies will be inserted. \throws Whatever T::T(const T&) throws. \throws Whatever T::operator = (const T&) throws. \par Exception Safety Basic; no-throw if the operations in the Throws section do not throw anything. \par Iterator Invalidation Invalidates iterators pointing to the elements before the insertion point (towards the beginning and excluding pos). It also invalidates iterators pointing to the overwritten elements. \par Complexity Linear (in min[capacity(), std::distance(begin(), pos) + n]). \par Example Consider a circular_buffer 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|. \sa \link rinsert(iterator, param_value_type) rinsert(iterator, value_type)\endlink, rinsert(iterator, InputIterator, InputIterator), \link insert(iterator, param_value_type) insert(iterator, value_type)\endlink, \link insert(iterator, size_type, param_value_type) insert(iterator, size_type, value_type)\endlink, insert(iterator, InputIterator, InputIterator) */ void rinsert(iterator pos, size_type n, param_value_type item) { BOOST_CB_ASSERT(pos.is_valid(this)); // check for uninitialized or invalidated iterator rinsert_n(pos, n, cb_details::item_wrapper(item)); } //! Insert the range [first, last) before the specified position. /*! \pre pos is a valid iterator pointing to the circular_buffer or its end.
Valid range [first, last) where first and last meet the requirements of an InputIterator. \post 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.) \param pos An iterator specifying the position where the range will be inserted. \param first The beginning of the range to be inserted. \param last The end of the range to be inserted. \throws Whatever T::T(const T&) throws. \throws Whatever T::operator = (const T&) throws. \par Exception Safety Basic; no-throw if the operations in the Throws section do not throw anything. \par Iterator Invalidation Invalidates iterators pointing to the elements before the insertion point (towards the beginning and excluding pos). It also invalidates iterators pointing to the overwritten elements. \par Complexity Linear (in [std::distance(begin(), pos) + std::distance(first, last)]; in min[capacity(), std::distance(begin(), pos) + std::distance(first, last)] if the InputIterator is a RandomAccessIterator). \par Example Consider a circular_buffer 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|. \sa \link rinsert(iterator, param_value_type) rinsert(iterator, value_type)\endlink, \link rinsert(iterator, size_type, param_value_type) rinsert(iterator, size_type, value_type)\endlink, \link insert(iterator, param_value_type) insert(iterator, value_type)\endlink, \link insert(iterator, size_type, param_value_type) insert(iterator, size_type, value_type)\endlink, insert(iterator, InputIterator, InputIterator) */ template void rinsert(iterator pos, InputIterator first, InputIterator last) { BOOST_CB_ASSERT(pos.is_valid(this)); // check for uninitialized or invalidated iterator rinsert(pos, first, last, is_integral()); } // Erase //! Remove an element at the specified position. /*! \pre pos is a valid iterator pointing to the circular_buffer (but not an end()). \post The element at the position pos is removed. \param pos An iterator pointing at the element to be removed. \return Iterator to the first element remaining beyond the removed element or end() if no such element exists. \throws Whatever T::operator = (const T&) throws. \par Exception Safety Basic; no-throw if the operation in the Throws section does not throw anything. \par Iterator Invalidation Invalidates iterators pointing to the erased element and iterators pointing to the elements behind the erased element (towards the end; except iterators equal to end()). \par Complexity Linear (in std::distance(pos, end())). \sa erase(iterator, iterator), rerase(iterator), rerase(iterator, iterator), erase_begin(size_type), erase_end(size_type), clear() */ iterator erase(iterator pos) { BOOST_CB_ASSERT(pos.is_valid(this)); // check for uninitialized or invalidated iterator BOOST_CB_ASSERT(pos.m_it != 0); // check for iterator pointing to end() pointer next = pos.m_it; increment(next); for (pointer p = pos.m_it; next != m_last; p = next, increment(next)) replace(p, *next); decrement(m_last); destroy_item(m_last); --m_size; #if BOOST_CB_ENABLE_DEBUG return m_last == pos.m_it ? end() : iterator(this, pos.m_it); #else return m_last == pos.m_it ? end() : pos; #endif } //! Erase the range [first, last). /*! \pre Valid range [first, last). \post The elements from the range [first, last) are removed. (If first == last nothing is removed.) \param first The beginning of the range to be removed. \param last The end of the range to be removed. \return Iterator to the first element remaining beyond the removed elements or end() if no such element exists. \throws Whatever T::operator = (const T&) throws. \par Exception Safety Basic; no-throw if the operation in the Throws section does not throw anything. \par Iterator Invalidation Invalidates iterators pointing to the erased elements and iterators pointing to the elements behind the erased range (towards the end; except iterators equal to end()). \par Complexity Linear (in std::distance(first, end())). \sa erase(iterator), rerase(iterator), rerase(iterator, iterator), erase_begin(size_type), erase_end(size_type), clear() */ iterator erase(iterator first, iterator last) { BOOST_CB_ASSERT(first.is_valid(this)); // check for uninitialized or invalidated iterator BOOST_CB_ASSERT(last.is_valid(this)); // check for uninitialized or invalidated iterator BOOST_CB_ASSERT(first <= last); // check for wrong range if (first == last) return first; pointer p = first.m_it; while (last.m_it != 0) replace((first++).m_it, *last++); do { decrement(m_last); destroy_item(m_last); --m_size; } while(m_last != first.m_it); return m_last == p ? end() : iterator(this, p); } //! Remove an element at the specified position. /*! \pre pos is a valid iterator pointing to the circular_buffer (but not an end()). \post The element at the position pos is removed. \param pos An iterator pointing at the element to be removed. \return Iterator to the first element remaining in front of the removed element or begin() if no such element exists. \throws Whatever T::operator = (const T&) throws. \par Exception Safety Basic; no-throw if the operation in the Throws section does not throw anything. \par Iterator Invalidation Invalidates iterators pointing to the erased element and iterators pointing to the elements in front of the erased element (towards the beginning). \par Complexity Linear (in std::distance(begin(), pos)). \note This method is symetric to the erase(iterator) method and is more effective than erase(iterator) if the iterator pos is close to the beginning of the circular_buffer. (See the Complexity.) \sa erase(iterator), erase(iterator, iterator), rerase(iterator, iterator), erase_begin(size_type), erase_end(size_type), clear() */ iterator rerase(iterator pos) { BOOST_CB_ASSERT(pos.is_valid(this)); // check for uninitialized or invalidated iterator BOOST_CB_ASSERT(pos.m_it != 0); // check for iterator pointing to end() pointer prev = pos.m_it; pointer p = prev; for (decrement(prev); p != m_first; p = prev, decrement(prev)) replace(p, *prev); destroy_item(m_first); increment(m_first); --m_size; #if BOOST_CB_ENABLE_DEBUG return p == pos.m_it ? begin() : iterator(this, pos.m_it); #else return p == pos.m_it ? begin() : pos; #endif } //! Erase the range [first, last). /*! \pre Valid range [first, last). \post The elements from the range [first, last) are removed. (If first == last nothing is removed.) \param first The beginning of the range to be removed. \param last The end of the range to be removed. \return Iterator to the first element remaining in front of the removed elements or begin() if no such element exists. \throws Whatever T::operator = (const T&) throws. \par Exception Safety Basic; no-throw if the operation in the Throws section does not throw anything. \par Iterator Invalidation Invalidates iterators pointing to the erased elements and iterators pointing to the elements in front of the erased range (towards the beginning). \par Complexity Linear (in std::distance(begin(), last)). \note This method is symetric to the erase(iterator, iterator) method and is more effective than erase(iterator, iterator) if std::distance(begin(), first) is lower that std::distance(last, end()). \sa erase(iterator), erase(iterator, iterator), rerase(iterator), erase_begin(size_type), erase_end(size_type), clear() */ iterator rerase(iterator first, iterator last) { BOOST_CB_ASSERT(first.is_valid(this)); // check for uninitialized or invalidated iterator BOOST_CB_ASSERT(last.is_valid(this)); // check for uninitialized or invalidated iterator BOOST_CB_ASSERT(first <= last); // check for wrong range if (first == last) return first; pointer p = map_pointer(last.m_it); last.m_it = p; while (first.m_it != m_first) { decrement(first.m_it); decrement(p); replace(p, *first.m_it); } do { destroy_item(m_first); increment(m_first); --m_size; } while(m_first != p); if (m_first == last.m_it) return begin(); decrement(last.m_it); return iterator(this, last.m_it); } //! Remove first n elements (with constant complexity for scalar types). /*! \pre n \<= size() \post The n elements at the beginning of the circular_buffer will be removed. \param n The number of elements to be removed. \throws Whatever T::operator = (const T&) throws. (Does not throw anything in case of scalars.) \par Exception Safety Basic; no-throw if the operation in the Throws section does not throw anything. (I.e. no throw in case of scalars.) \par Iterator Invalidation Invalidates iterators pointing to the first n erased elements. \par Complexity Constant (in n) for scalar types; linear for other types. \note This method has been specially designed for types which do not require an explicit destructruction (e.g. integer, float or a pointer). For these scalar types a call to a destructor is not required which makes it possible to implement the "erase from beginning" operation with a constant complexity. For non-sacalar types the complexity is linear (hence the explicit destruction is needed) and the implementation is actually equivalent to \link circular_buffer::rerase(iterator, iterator) rerase(begin(), begin() + n)\endlink. \sa erase(iterator), erase(iterator, iterator), rerase(iterator), rerase(iterator, iterator), erase_end(size_type), clear() */ void erase_begin(size_type n) { BOOST_CB_ASSERT(n <= size()); // check for n greater than size #if BOOST_CB_ENABLE_DEBUG erase_begin(n, false_type()); #else erase_begin(n, is_scalar()); #endif } //! Remove last n elements (with constant complexity for scalar types). /*! \pre n \<= size() \post The n elements at the end of the circular_buffer will be removed. \param n The number of elements to be removed. \throws Whatever T::operator = (const T&) throws. (Does not throw anything in case of scalars.) \par Exception Safety Basic; no-throw if the operation in the Throws section does not throw anything. (I.e. no throw in case of scalars.) \par Iterator Invalidation Invalidates iterators pointing to the last n erased elements. \par Complexity Constant (in n) for scalar types; linear for other types. \note This method has been specially designed for types which do not require an explicit destructruction (e.g. integer, float or a pointer). For these scalar types a call to a destructor is not required which makes it possible to implement the "erase from end" operation with a constant complexity. For non-sacalar types the complexity is linear (hence the explicit destruction is needed) and the implementation is actually equivalent to \link circular_buffer::erase(iterator, iterator) erase(end() - n, end())\endlink. \sa erase(iterator), erase(iterator, iterator), rerase(iterator), rerase(iterator, iterator), erase_begin(size_type), clear() */ void erase_end(size_type n) { BOOST_CB_ASSERT(n <= size()); // check for n greater than size #if BOOST_CB_ENABLE_DEBUG erase_end(n, false_type()); #else erase_end(n, is_scalar()); #endif } //! Remove all stored elements from the circular_buffer. /*! \post size() == 0 \throws Nothing. \par Exception Safety No-throw. \par Iterator Invalidation Invalidates all iterators pointing to the circular_buffer (except iterators equal to end()). \par Complexity Constant (in the size of the circular_buffer) for scalar types; linear for other types. \sa ~circular_buffer(), erase(iterator), erase(iterator, iterator), rerase(iterator), rerase(iterator, iterator), erase_begin(size_type), erase_end(size_type) */ void clear() { destroy_content(); m_size = 0; } private: // Helper methods //! Check if the index is valid. void check_position(size_type index) const { if (index >= size()) throw_exception(std::out_of_range("circular_buffer")); } //! Increment the pointer. template void increment(Pointer& p) const { if (++p == m_end) p = m_buff; } //! Decrement the pointer. template void decrement(Pointer& p) const { if (p == m_buff) p = m_end; --p; } //! Add n to the pointer. template Pointer add(Pointer p, difference_type n) const { return p + (n < (m_end - p) ? n : n - capacity()); } //! Subtract n from the pointer. template Pointer sub(Pointer p, difference_type n) const { return p - (n > (p - m_buff) ? n - capacity() : n); } //! Map the null pointer to virtual end of circular buffer. pointer map_pointer(pointer p) const { return p == 0 ? m_last : p; } //! Allocate memory. pointer allocate(size_type n) { if (n > max_size()) throw_exception(std::length_error("circular_buffer")); #if BOOST_CB_ENABLE_DEBUG pointer p = (n == 0) ? 0 : m_alloc.allocate(n, 0); std::memset(p, cb_details::UNINITIALIZED, sizeof(value_type) * n); return p; #else return (n == 0) ? 0 : m_alloc.allocate(n, 0); #endif } //! Deallocate memory. void deallocate(pointer p, size_type n) { if (p != 0) m_alloc.deallocate(p, n); } //! Does the pointer point to the uninitialized memory? bool is_uninitialized(const_pointer p) const { return p >= m_last && (m_first < m_last || p < m_first); } //! Replace an element. void replace(pointer pos, param_value_type item) { *pos = item; #if BOOST_CB_ENABLE_DEBUG invalidate_iterators(iterator(this, pos)); #endif } //! Construct or replace an element. /*! construct has to be set to true if and only if pos points to an uninitialized memory. */ void construct_or_replace(bool construct, pointer pos, param_value_type item) { if (construct) m_alloc.construct(pos, item); else replace(pos, item); } //! Destroy an item. void destroy_item(pointer p) { m_alloc.destroy(p); #if BOOST_CB_ENABLE_DEBUG invalidate_iterators(iterator(this, p)); std::memset(p, cb_details::UNINITIALIZED, sizeof(value_type)); #endif } //! Destroy an item only if it has been constructed. void destroy_if_constructed(pointer pos) { if (is_uninitialized(pos)) destroy_item(pos); } //! Destroy the whole content of the circular buffer. void destroy_content() { #if BOOST_CB_ENABLE_DEBUG destroy_content(false_type()); #else destroy_content(is_scalar()); #endif } //! Specialized destroy_content method. void destroy_content(const true_type&) { m_first = add(m_first, size()); } //! Specialized destroy_content method. void destroy_content(const false_type&) { for (size_type ii = 0; ii < size(); ++ii, increment(m_first)) destroy_item(m_first); } //! Destroy content and free allocated memory. void destroy() { destroy_content(); deallocate(m_buff, capacity()); #if BOOST_CB_ENABLE_DEBUG m_buff = 0; m_first = 0; m_last = 0; m_end = 0; #endif } //! Initialize the internal buffer. void initialize_buffer(capacity_type buffer_capacity) { m_buff = allocate(buffer_capacity); m_end = m_buff + buffer_capacity; } //! Initialize the internal buffer. void initialize_buffer(capacity_type buffer_capacity, param_value_type item) { initialize_buffer(buffer_capacity); BOOST_TRY { cb_details::uninitialized_fill_n_with_alloc(m_buff, size(), item, m_alloc); } BOOST_CATCH(...) { deallocate(m_buff, size()); BOOST_RETHROW } BOOST_CATCH_END } //! Specialized initialize method. template void initialize(IntegralType n, IntegralType item, const true_type&) { m_size = static_cast(n); initialize_buffer(size(), item); m_first = m_last = m_buff; } //! Specialized initialize method. template void initialize(Iterator first, Iterator last, const false_type&) { BOOST_CB_IS_CONVERTIBLE(Iterator, value_type); // check for invalid iterator type #if BOOST_WORKAROUND(__BORLANDC__, BOOST_TESTED_AT(0x581)) initialize(first, last, BOOST_ITERATOR_CATEGORY::type()); #else initialize(first, last, BOOST_DEDUCED_TYPENAME BOOST_ITERATOR_CATEGORY::type()); #endif } //! Specialized initialize method. template void initialize(InputIterator first, InputIterator last, const std::input_iterator_tag&) { BOOST_CB_ASSERT_TEMPLATED_ITERATOR_CONSTRUCTORS // check if the STL provides templated iterator constructors // for containers std::deque tmp(first, last, m_alloc); size_type distance = tmp.size(); initialize(distance, tmp.begin(), tmp.end(), distance); } //! Specialized initialize method. template void initialize(ForwardIterator first, ForwardIterator last, const std::forward_iterator_tag&) { BOOST_CB_ASSERT(std::distance(first, last) >= 0); // check for wrong range size_type distance = std::distance(first, last); initialize(distance, first, last, distance); } //! Specialized initialize method. template void initialize(capacity_type buffer_capacity, IntegralType n, IntegralType item, const true_type&) { BOOST_CB_ASSERT(buffer_capacity >= static_cast(n)); // check for capacity lower than n m_size = static_cast(n); initialize_buffer(buffer_capacity, item); m_first = m_buff; m_last = buffer_capacity == size() ? m_buff : m_buff + size(); } //! Specialized initialize method. template void initialize(capacity_type buffer_capacity, Iterator first, Iterator last, const false_type&) { BOOST_CB_IS_CONVERTIBLE(Iterator, value_type); // check for invalid iterator type #if BOOST_WORKAROUND(__BORLANDC__, BOOST_TESTED_AT(0x581)) initialize(buffer_capacity, first, last, BOOST_ITERATOR_CATEGORY::type()); #else initialize(buffer_capacity, first, last, BOOST_DEDUCED_TYPENAME BOOST_ITERATOR_CATEGORY::type()); #endif } //! Specialized initialize method. template void initialize(capacity_type buffer_capacity, InputIterator first, InputIterator last, const std::input_iterator_tag&) { initialize_buffer(buffer_capacity); m_first = m_last = m_buff; m_size = 0; if (buffer_capacity == 0) return; while (first != last && !full()) { m_alloc.construct(m_last, *first++); increment(m_last); ++m_size; } while (first != last) { replace(m_last, *first++); increment(m_last); m_first = m_last; } } //! Specialized initialize method. template void initialize(capacity_type buffer_capacity, ForwardIterator first, ForwardIterator last, const std::forward_iterator_tag&) { BOOST_CB_ASSERT(std::distance(first, last) >= 0); // check for wrong range initialize(buffer_capacity, first, last, std::distance(first, last)); } //! Initialize the circular buffer. template void initialize(capacity_type buffer_capacity, ForwardIterator first, ForwardIterator last, size_type distance) { initialize_buffer(buffer_capacity); m_first = m_buff; if (distance > buffer_capacity) { std::advance(first, distance - buffer_capacity); m_size = buffer_capacity; } else { m_size = distance; } BOOST_TRY { m_last = cb_details::uninitialized_copy_with_alloc(first, last, m_buff, m_alloc); } BOOST_CATCH(...) { deallocate(m_buff, buffer_capacity); BOOST_RETHROW } BOOST_CATCH_END if (m_last == m_end) m_last = m_buff; } //! Reset the circular buffer. void reset(pointer buff, pointer last, capacity_type new_capacity) { destroy(); m_size = last - buff; m_first = m_buff = buff; m_end = m_buff + new_capacity; m_last = last == m_end ? m_buff : last; } //! Specialized method for swapping the allocator. void swap_allocator(circular_buffer&, const true_type&) { // Swap is not needed because allocators have no state. } //! Specialized method for swapping the allocator. void swap_allocator(circular_buffer& cb, const false_type&) { std::swap(m_alloc, cb.m_alloc); } //! Specialized assign method. template void assign(IntegralType n, IntegralType item, const true_type&) { assign(static_cast(n), static_cast(item)); } //! Specialized assign method. template void assign(Iterator first, Iterator last, const false_type&) { BOOST_CB_IS_CONVERTIBLE(Iterator, value_type); // check for invalid iterator type #if BOOST_WORKAROUND(__BORLANDC__, BOOST_TESTED_AT(0x581)) assign(first, last, BOOST_ITERATOR_CATEGORY::type()); #else assign(first, last, BOOST_DEDUCED_TYPENAME BOOST_ITERATOR_CATEGORY::type()); #endif } //! Specialized assign method. template void assign(InputIterator first, InputIterator last, const std::input_iterator_tag&) { BOOST_CB_ASSERT_TEMPLATED_ITERATOR_CONSTRUCTORS // check if the STL provides templated iterator constructors // for containers std::deque tmp(first, last, m_alloc); size_type distance = tmp.size(); assign_n(distance, distance, cb_details::assign_range::iterator, allocator_type>(tmp.begin(), tmp.end(), m_alloc)); } //! Specialized assign method. template void assign(ForwardIterator first, ForwardIterator last, const std::forward_iterator_tag&) { BOOST_CB_ASSERT(std::distance(first, last) >= 0); // check for wrong range size_type distance = std::distance(first, last); assign_n(distance, distance, cb_details::assign_range(first, last, m_alloc)); } //! Specialized assign method. template void assign(capacity_type new_capacity, IntegralType n, IntegralType item, const true_type&) { assign(new_capacity, static_cast(n), static_cast(item)); } //! Specialized assign method. template void assign(capacity_type new_capacity, Iterator first, Iterator last, const false_type&) { BOOST_CB_IS_CONVERTIBLE(Iterator, value_type); // check for invalid iterator type #if BOOST_WORKAROUND(__BORLANDC__, BOOST_TESTED_AT(0x581)) assign(new_capacity, first, last, BOOST_ITERATOR_CATEGORY::type()); #else assign(new_capacity, first, last, BOOST_DEDUCED_TYPENAME BOOST_ITERATOR_CATEGORY::type()); #endif } //! Specialized assign method. template void assign(capacity_type new_capacity, InputIterator first, InputIterator last, const std::input_iterator_tag&) { if (new_capacity == capacity()) { clear(); insert(begin(), first, last); } else { #if BOOST_WORKAROUND(BOOST_MSVC, < 1300) circular_buffer tmp(new_capacity, m_alloc); tmp.insert(begin(), first, last); #else circular_buffer tmp(new_capacity, first, last, m_alloc); #endif tmp.swap(*this); } } //! Specialized assign method. template void assign(capacity_type new_capacity, ForwardIterator first, ForwardIterator last, const std::forward_iterator_tag&) { BOOST_CB_ASSERT(std::distance(first, last) >= 0); // check for wrong range size_type distance = std::distance(first, last); if (distance > new_capacity) { std::advance(first, distance - new_capacity); distance = new_capacity; } assign_n(new_capacity, distance, cb_details::assign_range(first, last, m_alloc)); } //! Helper assign method. template void assign_n(capacity_type new_capacity, size_type n, const Functor& fnc) { if (new_capacity == capacity()) { destroy_content(); BOOST_TRY { fnc(m_buff); } BOOST_CATCH(...) { m_size = 0; BOOST_RETHROW } BOOST_CATCH_END } else { pointer buff = allocate(new_capacity); BOOST_TRY { fnc(buff); } BOOST_CATCH(...) { deallocate(buff, new_capacity); BOOST_RETHROW } BOOST_CATCH_END destroy(); m_buff = buff; m_end = m_buff + new_capacity; } m_size = n; m_first = m_buff; m_last = add(m_buff, size()); } //! Helper insert method. iterator insert_item(const iterator& pos, param_value_type item) { pointer p = pos.m_it; if (p == 0) { construct_or_replace(!full(), m_last, item); p = m_last; } else { pointer src = m_last; pointer dest = m_last; bool construct = !full(); BOOST_TRY { while (src != p) { decrement(src); construct_or_replace(construct, dest, *src); decrement(dest); construct = false; } replace(p, item); } BOOST_CATCH(...) { if (!construct && !full()) { increment(m_last); ++m_size; } BOOST_RETHROW } BOOST_CATCH_END } increment(m_last); if (full()) m_first = m_last; else ++m_size; return iterator(this, p); } //! Specialized insert method. template void insert(const iterator& pos, IntegralType n, IntegralType item, const true_type&) { insert(pos, static_cast(n), static_cast(item)); } //! Specialized insert method. template void insert(const iterator& pos, Iterator first, Iterator last, const false_type&) { BOOST_CB_IS_CONVERTIBLE(Iterator, value_type); // check for invalid iterator type #if BOOST_WORKAROUND(__BORLANDC__, BOOST_TESTED_AT(0x581)) insert(pos, first, last, BOOST_ITERATOR_CATEGORY::type()); #else insert(pos, first, last, BOOST_DEDUCED_TYPENAME BOOST_ITERATOR_CATEGORY::type()); #endif } //! Specialized insert method. template void insert(iterator pos, InputIterator first, InputIterator last, const std::input_iterator_tag&) { if (!full() || pos != begin()) { for (;first != last; ++pos) pos = insert_item(pos, *first++); } } //! Specialized insert method. template void insert(const iterator& pos, ForwardIterator first, ForwardIterator last, const std::forward_iterator_tag&) { BOOST_CB_ASSERT(std::distance(first, last) >= 0); // check for wrong range size_type n = std::distance(first, last); if (n == 0) return; size_type copy = capacity() - (end() - pos); if (copy == 0) return; if (n > copy) { std::advance(first, n - copy); n = copy; } insert_n(pos, n, cb_details::iterator_wrapper(first)); } //! Helper insert method. template void insert_n(const iterator& pos, size_type n, const Wrapper& wrapper) { size_type construct = reserve(); if (construct > n) construct = n; if (pos.m_it == 0) { size_type ii = 0; pointer p = m_last; BOOST_TRY { for (; ii < construct; ++ii, increment(p)) m_alloc.construct(p, *wrapper()); for (;ii < n; ++ii, increment(p)) replace(p, *wrapper()); } BOOST_CATCH(...) { size_type constructed = (std::min)(ii, construct); m_last = add(m_last, constructed); m_size += constructed; BOOST_RETHROW } BOOST_CATCH_END } else { pointer src = m_last; pointer dest = add(m_last, n - 1); pointer p = pos.m_it; size_type ii = 0; BOOST_TRY { while (src != pos.m_it) { decrement(src); construct_or_replace(is_uninitialized(dest), dest, *src); decrement(dest); } for (; ii < n; ++ii, increment(p)) construct_or_replace(is_uninitialized(p), p, *wrapper()); } BOOST_CATCH(...) { for (p = add(m_last, n - 1); p != dest; decrement(p)) destroy_if_constructed(p); for (n = 0, p = pos.m_it; n < ii; ++n, increment(p)) destroy_if_constructed(p); BOOST_RETHROW } BOOST_CATCH_END } m_last = add(m_last, n); m_first = add(m_first, n - construct); m_size += construct; } //! Specialized rinsert method. template void rinsert(const iterator& pos, IntegralType n, IntegralType item, const true_type&) { rinsert(pos, static_cast(n), static_cast(item)); } //! Specialized rinsert method. template void rinsert(const iterator& pos, Iterator first, Iterator last, const false_type&) { BOOST_CB_IS_CONVERTIBLE(Iterator, value_type); // check for invalid iterator type #if BOOST_WORKAROUND(__BORLANDC__, BOOST_TESTED_AT(0x581)) rinsert(pos, first, last, BOOST_ITERATOR_CATEGORY::type()); #else rinsert(pos, first, last, BOOST_DEDUCED_TYPENAME BOOST_ITERATOR_CATEGORY::type()); #endif } //! Specialized insert method. template void rinsert(iterator pos, InputIterator first, InputIterator last, const std::input_iterator_tag&) { if (!full() || pos.m_it != 0) { for (;first != last; ++pos) { pos = rinsert(pos, *first++); if (pos.m_it == 0) break; } } } //! Specialized rinsert method. template void rinsert(const iterator& pos, ForwardIterator first, ForwardIterator last, const std::forward_iterator_tag&) { BOOST_CB_ASSERT(std::distance(first, last) >= 0); // check for wrong range rinsert_n(pos, std::distance(first, last), cb_details::iterator_wrapper(first)); } //! Helper rinsert method. template void rinsert_n(const iterator& pos, size_type n, const Wrapper& wrapper) { if (n == 0) return; iterator b = begin(); size_type copy = capacity() - (pos - b); if (copy == 0) return; if (n > copy) n = copy; size_type construct = reserve(); if (construct > n) construct = n; if (pos == b) { pointer p = sub(m_first, n); size_type ii = n; BOOST_TRY { for (;ii > construct; --ii, increment(p)) replace(p, *wrapper()); for (; ii > 0; --ii, increment(p)) m_alloc.construct(p, *wrapper()); } BOOST_CATCH(...) { size_type constructed = ii < construct ? construct - ii : 0; m_last = add(m_last, constructed); m_size += constructed; BOOST_RETHROW } BOOST_CATCH_END } else { pointer src = m_first; pointer dest = sub(m_first, n); pointer p = map_pointer(pos.m_it); BOOST_TRY { while (src != p) { construct_or_replace(is_uninitialized(dest), dest, *src); increment(src); increment(dest); } for (size_type ii = 0; ii < n; ++ii, increment(dest)) construct_or_replace(is_uninitialized(dest), dest, *wrapper()); } BOOST_CATCH(...) { for (src = sub(m_first, n); src != dest; increment(src)) destroy_if_constructed(src); BOOST_RETHROW } BOOST_CATCH_END } m_first = sub(m_first, n); m_last = sub(m_last, n - construct); m_size += construct; } //! Specialized erase_begin method. void erase_begin(size_type n, const true_type&) { m_first = add(m_first, n); m_size -= n; } //! Specialized erase_begin method. void erase_begin(size_type n, const false_type&) { iterator b = begin(); rerase(b, b + n); } //! Specialized erase_end method. void erase_end(size_type n, const true_type&) { m_last = sub(m_last, n); m_size -= n; } //! Specialized erase_end method. void erase_end(size_type n, const false_type&) { iterator e = end(); erase(e - n, e); } }; // Non-member functions //! Compare two circular_buffers element-by-element to determine if they are equal. /*! \param lhs The circular_buffer to compare. \param rhs The circular_buffer to compare. \return lhs.\link circular_buffer::size() size()\endlink == rhs.\link circular_buffer::size() size()\endlink && std::equal(lhs.\link circular_buffer::begin() begin()\endlink, lhs.\link circular_buffer::end() end()\endlink, rhs.\link circular_buffer::begin() begin()\endlink) \throws Nothing. \par Complexity Linear (in the size of the circular_buffers). \par Iterator Invalidation Does not invalidate any iterators. */ template inline bool operator == (const circular_buffer& lhs, const circular_buffer& rhs) { return lhs.size() == rhs.size() && std::equal(lhs.begin(), lhs.end(), rhs.begin()); } /*! \brief Compare two circular_buffers element-by-element to determine if the left one is lesser than the right one. \param lhs The circular_buffer to compare. \param rhs The circular_buffer to compare. \return std::lexicographical_compare(lhs.\link circular_buffer::begin() begin()\endlink, lhs.\link circular_buffer::end() end()\endlink, rhs.\link circular_buffer::begin() begin()\endlink, rhs.\link circular_buffer::end() end()\endlink) \throws Nothing. \par Complexity Linear (in the size of the circular_buffers). \par Iterator Invalidation Does not invalidate any iterators. */ template inline bool operator < (const circular_buffer& lhs, const circular_buffer& rhs) { return std::lexicographical_compare(lhs.begin(), lhs.end(), rhs.begin(), rhs.end()); } #if !defined(BOOST_NO_FUNCTION_TEMPLATE_ORDERING) || defined(BOOST_MSVC) //! Compare two circular_buffers element-by-element to determine if they are non-equal. /*! \param lhs The circular_buffer to compare. \param rhs The circular_buffer to compare. \return !(lhs == rhs) \throws Nothing. \par Complexity Linear (in the size of the circular_buffers). \par Iterator Invalidation Does not invalidate any iterators. \sa operator==(const circular_buffer&, const circular_buffer&) */ template inline bool operator != (const circular_buffer& lhs, const circular_buffer& rhs) { return !(lhs == rhs); } /*! \brief Compare two circular_buffers element-by-element to determine if the left one is greater than the right one. \param lhs The circular_buffer to compare. \param rhs The circular_buffer to compare. \return rhs \< lhs \throws Nothing. \par Complexity Linear (in the size of the circular_buffers). \par Iterator Invalidation Does not invalidate any iterators. \sa operator<(const circular_buffer&, const circular_buffer&) */ template inline bool operator > (const circular_buffer& lhs, const circular_buffer& rhs) { return rhs < lhs; } /*! \brief Compare two circular_buffers element-by-element to determine if the left one is lesser or equal to the right one. \param lhs The circular_buffer to compare. \param rhs The circular_buffer to compare. \return !(rhs \< lhs) \throws Nothing. \par Complexity Linear (in the size of the circular_buffers). \par Iterator Invalidation Does not invalidate any iterators. \sa operator<(const circular_buffer&, const circular_buffer&) */ template inline bool operator <= (const circular_buffer& lhs, const circular_buffer& rhs) { return !(rhs < lhs); } /*! \brief Compare two circular_buffers element-by-element to determine if the left one is greater or equal to the right one. \param lhs The circular_buffer to compare. \param rhs The circular_buffer to compare. \return !(lhs < rhs) \throws Nothing. \par Complexity Linear (in the size of the circular_buffers). \par Iterator Invalidation Does not invalidate any iterators. \sa operator<(const circular_buffer&, const circular_buffer&) */ template inline bool operator >= (const circular_buffer& lhs, const circular_buffer& rhs) { return !(lhs < rhs); } //! Swap the contents of two circular_buffers. /*! \post lhs contains elements of rhs and vice versa. \param lhs The circular_buffer whose content will be swapped with rhs. \param rhs The circular_buffer whose content will be swapped with lhs. \throws Nothing. \par Complexity Constant (in the size of the circular_buffers). \par Iterator Invalidation Invalidates all iterators of both circular_buffers. (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 otherwise an assertion will report an error if such invalidated iterator is used.) \sa \link circular_buffer::swap(circular_buffer&) swap(circular_buffer&)\endlink */ template inline void swap(circular_buffer& lhs, circular_buffer& rhs) { lhs.swap(rhs); } #endif // #if !defined(BOOST_NO_FUNCTION_TEMPLATE_ORDERING) || defined(BOOST_MSVC) } // namespace boost #endif // #if !defined(BOOST_CIRCULAR_BUFFER_BASE_HPP)