![]() |
Home | Libraries | People | FAQ | More |
boost::circular_buffer — Circular buffer - a STL compliant container.
// In header: <boost/circular_buffer/base.hpp> template<typename T, typename Alloc> class circular_buffer : private { public: // types typedef circular_buffer< ; // The type of thiscircular_buffer
. typedef ; // The type of elements stored in thecircular_buffer
. typedef ; // A pointer to an element. typedef ; // A const pointer to the element. typedef ; // A reference to an element. typedef ; // A const reference to an element. typedef ; typedef ; typedef ; // The type of an allocator used in thecircular_buffer
. typedef circular_buffer< ; // A const (random access) iterator used to iterate through thecircular_buffer
. typedef circular_buffer< ; // A (random access) iterator used to iterate through thecircular_buffer
. typedef ; // A const iterator used to iterate backwards through acircular_buffer
. typedef ; // An iterator used to iterate backwards through acircular_buffer
. typedef ; typedef ; typedef ; typedef ; // A type representing the "best" way to pass the value_type to a method. typedef ; // construct/copy/destruct ( = ) ; (, = ); (, , = ); (, , , = ); (circular_buffer< ); (circular_buffer< ) ; template<typename InputIterator> (, , = ); template<typename InputIterator> (, , , = ); circular_buffer< (circular_buffer< ); circular_buffer< (circular_buffer< ) ; ~(); // public member functions () ; () ; () ; () ; () ; () ; () ; () ; () ; () ; () ; () ; (); () ; (); () ; (); (); () ; () ; (); (); () ; () ; (); () ; (); () ; () ; () ; () ; () ; () ; (); (, = ); (); (, = ); (, ); (, , ); template<typename InputIterator> (, ); template<typename InputIterator> (, , ); (circular_buffer< ) ; (); (); (); (); (); (); (); (); (, ); (, ); (); (, , ); template<typename InputIterator> (, , ); (, ); (, ); (); (, , ); template<typename InputIterator> (, , ); (); (, ); (); (, ); (); (); () ; };
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.
Type Requirements Alloc. The Alloc
has to meet the allocator requirements imposed by STL.
Default Alloc. std::allocator<T>
For detailed documentation of the circular_buffer visit: http://www.boost.org/libs/circular_buffer/doc/circular_buffer.html
typename T
The type of the elements stored in the
. circular_buffer
typename Alloc
The allocator type used for all internal memory management.
circular_buffer
public
types(A signed integral type used to represent the distance between two iterators.)
(An unsigned integral type that can represent any non-negative value of the container's distance type.)
(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.)
(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.)
(Same as size_type
- defined for consistency with the __cbso class.
A type representing rvalue from param type. On compilers without rvalue references support this type is the Boost.Moves type used for emulation.
circular_buffer
public
construct/copy/destruct( alloc = ) ;Create an empty
circular_buffer
with zero capacity.
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 |
![]() |
Note |
---|---|
You can explicitly set the capacity by calling the |
See Also:
circular_buffer(capacity_type, const allocator_type& alloc)
, set_capacity(capacity_type)
Parameters: |
|
||
Postconditions: |
|
||
Throws: |
Nothing. |
( buffer_capacity, alloc = );Create an empty
circular_buffer
with the specified capacity.
Complexity. Constant.
Parameters: |
|
||||
Postconditions: |
|
||||
Throws: |
An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is used). |
( n, item, alloc = );Create a full
circular_buffer
with the specified capacity and filled with n
copies of item
.
Complexity. Linear (in the n
).
Parameters: |
|
||||||
Postconditions: |
|
||||||
Throws: |
An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is used). Whatever T::T(const T&) throws. |
( buffer_capacity, n, item, alloc = );Create a
circular_buffer
with the specified capacity and filled with n
copies of item
.
Complexity. Linear (in the n
).
Parameters: |
|
||||||||
Requires: |
|
||||||||
Postconditions: |
|
||||||||
Throws: |
An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is used). Whatever T::T(const T&) throws. |
(circular_buffer< cb);The copy constructor.
Creates a copy of the specified
.
circular_buffer
Complexity. Linear (in the size of cb
).
Parameters: |
|
||
Postconditions: |
|
||
Throws: |
An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is used). Whatever T::T(const T&) throws. |
(circular_buffer< cb) ;The move constructor.
Move constructs a
from circular_buffer
cb
, leaving cb
empty.
Constant.
Parameters: |
|
||
Requires: |
C++ compiler with rvalue references support. |
||
Postconditions: |
|
||
Throws: |
Nothing. |
template<typename InputIterator> ( first, last, alloc = );Create a full
circular_buffer
filled with a copy of the range.
Complexity. Linear (in the std::distance(first, last)
).
Parameters: |
|
||||||
Requires: |
Valid range |
||||||
Postconditions: |
|
||||||
Throws: |
An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is used). Whatever T::T(const T&) throws. |
template<typename InputIterator> ( buffer_capacity, first, last, alloc = );Create a
circular_buffer
with the specified capacity and filled with a copy of the range.
Complexity. Linear (in std::distance(first, last)
; in min[capacity, std::distance(first, last)]
if the InputIterator
is a RandomAccessIterator).
Parameters: |
|
||||||||
Requires: |
Valid range |
||||||||
Postconditions: |
|
||||||||
Throws: |
An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is used). Whatever T::T(const T&) throws. |
circular_buffer< (circular_buffer< cb);The assign operator.
Makes this
to become a copy of the specified circular_buffer
.
circular_buffer
Exception Safety. Strong.
Iterator Invalidation. Invalidates all iterators pointing to this
(except iterators equal to circular_buffer
end()
).
Complexity. Linear (in the size of cb
).
See Also:
assign(size_type, const_reference)
, assign(capacity_type, size_type, const_reference)
, assign(InputIterator, InputIterator)
, assign(capacity_type, InputIterator, InputIterator)
Parameters: |
|
||
Postconditions: |
|
||
Throws: |
An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is used). Whatever T::T(const T&) throws. |
circular_buffer< (circular_buffer< cb) ;Move assigns content of
cb
to *this
, leaving cb
empty.
Complexity. Constant.
Parameters: |
|
||
Requires: |
C++ compiler with rvalue references support. |
||
Postconditions: |
|
||
Throws: |
Nothing. |
~();The destructor.
Destroys the
.
circular_buffer
Iterator Invalidation. Invalidates all iterators pointing to the
(including iterators equal to circular_buffer
end()
).
Complexity. Constant (in the size of the
) for scalar types; linear for other types. circular_buffer
See Also:
clear()
Throws: |
Nothing. |
circular_buffer
public member functions() ;Get the allocator.
Exception Safety. No-throw.
Iterator Invalidation. Does not invalidate any iterators.
Complexity. Constant (in the size of the
). circular_buffer
See Also:
get_allocator()
for obtaining an allocator reference.
Returns: |
The allocator. |
Throws: |
Nothing. |
() ;Get the allocator reference.
Exception Safety. No-throw.
Iterator Invalidation. Does not invalidate any iterators.
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. |
See Also:
get_allocator() const
Returns: |
A reference to the allocator. |
Throws: |
Nothing. |
() ;Get the iterator pointing to the beginning of the
circular_buffer
.
Exception Safety. No-throw.
Iterator Invalidation. Does not invalidate any iterators.
Complexity. Constant (in the size of the
). circular_buffer
See Also:
end()
, rbegin()
, rend()
Returns: |
A random access iterator pointing to the first element of the |
Throws: |
Nothing. |
() ;Get the iterator pointing to the end of the
circular_buffer
.
Exception Safety. No-throw.
Iterator Invalidation. Does not invalidate any iterators.
Complexity. Constant (in the size of the
). circular_buffer
See Also:
begin()
, rbegin()
, rend()
Returns: |
A random access iterator pointing to the element "one behind" the last element of the |
Throws: |
Nothing. |
() ;Get the const iterator pointing to the beginning of the
circular_buffer
.
Exception Safety. No-throw.
Iterator Invalidation. Does not invalidate any iterators.
Complexity. Constant (in the size of the
). circular_buffer
See Also:
end() const
, rbegin() const
, rend() const
Returns: |
A const random access iterator pointing to the first element of the |
Throws: |
Nothing. |
() ;
() ;Get the const iterator pointing to the end of the
circular_buffer
.
Exception Safety. No-throw.
Iterator Invalidation. Does not invalidate any iterators.
Complexity. Constant (in the size of the
). circular_buffer
See Also:
begin() const
, rbegin() const
, rend() const
Returns: |
A const random access iterator pointing to the element "one behind" the last element of the |
Throws: |
Nothing. |
() ;
() ;Get the iterator pointing to the beginning of the "reversed"
circular_buffer
.
Exception Safety. No-throw.
Iterator Invalidation. Does not invalidate any iterators.
Complexity. Constant (in the size of the
). circular_buffer
See Also:
rend()
, begin()
, end()
Returns: |
A reverse random access iterator pointing to the last element of the |
Throws: |
Nothing. |
() ;Get the iterator pointing to the end of the "reversed"
circular_buffer
.
Exception Safety. No-throw.
Iterator Invalidation. Does not invalidate any iterators.
Complexity. Constant (in the size of the
). circular_buffer
See Also:
rbegin()
, begin()
, end()
Returns: |
A reverse random access iterator pointing to the element "one before" the first element of the |
Throws: |
Nothing. |
() ;Get the const iterator pointing to the beginning of the "reversed"
circular_buffer
.
Exception Safety. No-throw.
Iterator Invalidation. Does not invalidate any iterators.
Complexity. Constant (in the size of the
). circular_buffer
See Also:
rend() const
, begin() const
, end() const
Returns: |
A const reverse random access iterator pointing to the last element of the |
Throws: |
Nothing. |
() ;Get the const iterator pointing to the end of the "reversed"
circular_buffer
.
Exception Safety. No-throw.
Iterator Invalidation. Does not invalidate any iterators.
Complexity. Constant (in the size of the
). circular_buffer
See Also:
rbegin() const
, begin() const
, end() const
Returns: |
A const reverse random access iterator pointing to the element "one before" the first element of the |
Throws: |
Nothing. |
( index);Get the element at the
index
position.
Exception Safety. No-throw.
Iterator Invalidation. Does not invalidate any iterators.
Complexity. Constant (in the size of the
). circular_buffer
See Also:
at()
Parameters: |
|
||
Requires: |
|
||
Returns: |
A reference to the element at the |
||
Throws: |
Nothing. |
( index) ;Get the element at the
index
position.
Exception Safety. No-throw.
Iterator Invalidation. Does not invalidate any iterators.
Complexity. Constant (in the size of the
). circular_buffer
See Also:
at() const
Parameters: |
|
||
Requires: |
|
||
Returns: |
A const reference to the element at the |
||
Throws: |
Nothing. |
( index);Get the element at the
index
position.
Exception Safety. Strong.
Iterator Invalidation. Does not invalidate any iterators.
Complexity. Constant (in the size of the
). circular_buffer
See Also:
operator[]
Parameters: |
|
||
Returns: |
A reference to the element at the |
||
Throws: |
<code>std::out_of_range</code> when the index is invalid (when index >= size() ). |
( index) ;Get the element at the
index
position.
Exception Safety. Strong.
Iterator Invalidation. Does not invalidate any iterators.
Complexity. Constant (in the size of the
). circular_buffer
See Also:
operator[] const
Parameters: |
|
||
Returns: |
A const reference to the element at the |
||
Throws: |
<code>std::out_of_range</code> when the index is invalid (when index >= size() ). |
();Get the first element.
Exception Safety. No-throw.
Iterator Invalidation. Does not invalidate any iterators.
Complexity. Constant (in the size of the
). circular_buffer
See Also:
back()
Requires: |
|
Returns: |
A reference to the first element of the |
Throws: |
Nothing. |
();Get the last element.
Exception Safety. No-throw.
Iterator Invalidation. Does not invalidate any iterators.
Complexity. Constant (in the size of the
). circular_buffer
See Also:
front()
Requires: |
|
Returns: |
A reference to the last element of the |
Throws: |
Nothing. |
() ;Get the first element.
Exception Safety. No-throw.
Iterator Invalidation. Does not invalidate any iterators.
Complexity. Constant (in the size of the
). circular_buffer
See Also:
back() const
Requires: |
|
Returns: |
A const reference to the first element of the |
Throws: |
Nothing. |
() ;Get the last element.
Exception Safety. No-throw.
Iterator Invalidation. Does not invalidate any iterators.
Complexity. Constant (in the size of the
). circular_buffer
See Also:
front() const
Requires: |
|
Returns: |
A const reference to the last element of the |
Throws: |
Nothing. |
();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
of capacity 10, containing 7 characters circular_buffer
'a', 'b', ..., 'g'
where buff[0] == 'a'
, buff[1] == 'b'
, ... and buff[6] == 'g'
:
circular_buffer<char> 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
into a file. Either relying on circular_buffer
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.
Exception Safety. No-throw.
Iterator Invalidation. Does not invalidate any iterators.
Complexity. Constant (in the size of the
). circular_buffer
![]() |
Warning |
---|---|
In general invoking any method which modifies the internal state of the |
![]() |
Note |
---|---|
In the case the internal buffer is linear e.g. |
See Also:
array_two()
, linearize()
Returns: |
The array range of the first continuous array of the internal buffer. In the case the |
Throws: |
Nothing. |
();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.
Exception Safety. No-throw.
Iterator Invalidation. Does not invalidate any iterators.
Complexity. Constant (in the size of the
). circular_buffer
See Also:
array_one()
Returns: |
The array range of the second continuous array of the internal buffer. In the case the internal buffer is linear or the |
Throws: |
Nothing. |
() ;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.
Exception Safety. No-throw.
Iterator Invalidation. Does not invalidate any iterators.
Complexity. Constant (in the size of the
). circular_buffer
See Also:
array_two() const
; array_one()
for more details how to pass data into a legacy C API.
Returns: |
The array range of the first continuous array of the internal buffer. In the case the |
Throws: |
Nothing. |
() ;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.
Exception Safety. No-throw.
Iterator Invalidation. Does not invalidate any iterators.
Complexity. Constant (in the size of the
). circular_buffer
See Also:
array_one() const
Returns: |
The array range of the second continuous array of the internal buffer. In the case the internal buffer is linear or the |
Throws: |
Nothing. |
();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.
Exception Safety. Basic; no-throw if the operations in the Throws section do not throw anything.
Iterator Invalidation. Invalidates all iterators pointing to the
(except iterators equal to circular_buffer
end()
); does not invalidate any iterators if the postcondition (the Effect) is already met prior calling this method.
Complexity. Linear (in the size of the
); constant if the postcondition (the Effect) is already met. circular_buffer
![]() |
Warning |
---|---|
In general invoking any method which modifies the internal state of the |
See Also:
array_one()
and array_two()
for the other option how to pass data into a legacy C API; is_linearized()
, rotate(const_iterator)
Postconditions: |
|
Returns: |
A pointer to the beginning of the array or |
Throws: |
<a href="circular_buffer/implementation.html#circular_buffer.implementation.exceptions_of_move_if_noexcept_t">Exceptions of move_if_noexcept(T&). |
() ;Is the
circular_buffer
linearized?
Exception Safety. No-throw.
Iterator Invalidation. Does not invalidate any iterators.
Complexity. Constant (in the size of the
). circular_buffer
See Also:
linearize()
, array_one()
, array_two()
Returns: |
|
Throws: |
Nothing. |
( new_begin);Rotate elements in the
circular_buffer
. A more effective implementation of std::rotate
.
Exception Safety. Basic; no-throw if the
is full or circular_buffer
new_begin
points to begin()
or if the operations in the Throws section do not throw anything.
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
is full. circular_buffer
Complexity. Linear (in (std::min)(m, n)
); constant if the
is full. circular_buffer
See Also:
Parameters: |
|
||
Requires: |
|
||
Postconditions: |
Before calling the method suppose: |
||
Throws: |
See Exceptions of move_if_noexcept(T&). |
() ;Get the number of elements currently stored in the
circular_buffer
.
Exception Safety. No-throw.
Iterator Invalidation. Does not invalidate any iterators.
Complexity. Constant (in the size of the
). circular_buffer
See Also:
capacity()
, max_size()
, reserve()
, resize(size_type, const_reference)
Returns: |
The number of elements stored in the |
Throws: |
Nothing. |
() ;Get the largest possible size or capacity of the
circular_buffer
. (It depends on allocator's max_size()).
Exception Safety. No-throw.
Iterator Invalidation. Does not invalidate any iterators.
Complexity. Constant (in the size of the
). circular_buffer
See Also:
size()
, capacity()
, reserve()
Returns: |
The maximum size/capacity the |
Throws: |
Nothing. |
() ;Is the
circular_buffer
empty?
Exception Safety. No-throw.
Iterator Invalidation. Does not invalidate any iterators.
Complexity. Constant (in the size of the
). circular_buffer
See Also:
full()
Returns: |
|
Throws: |
Nothing. |
() ;Is the
circular_buffer
full?
Exception Safety. No-throw.
Iterator Invalidation. Does not invalidate any iterators.
Complexity. Constant (in the size of the
). circular_buffer
See Also:
empty()
Returns: |
|
Throws: |
Nothing. |
() ;Get the maximum number of elements which can be inserted into the
circular_buffer
without overwriting any of already stored elements.
Exception Safety. No-throw.
Iterator Invalidation. Does not invalidate any iterators.
Complexity. Constant (in the size of the
). circular_buffer
See Also:
capacity()
, size()
, max_size()
Returns: |
|
Throws: |
Nothing. |
() ;Get the capacity of the
circular_buffer
.
Exception Safety. No-throw.
Iterator Invalidation. Does not invalidate any iterators.
Complexity. Constant (in the size of the
). circular_buffer
See Also:
reserve()
, size()
, max_size()
, set_capacity(capacity_type)
Returns: |
The maximum number of elements which can be stored in the |
Throws: |
Nothing. |
( new_capacity);Change the capacity of the
circular_buffer
.
Exception Safety. Strong.
Iterator Invalidation. Invalidates all iterators pointing to the
(except iterators equal to circular_buffer
end()
) if the new capacity is different from the original.
Complexity. Linear (in min[size(), new_capacity]
).
See Also:
rset_capacity(capacity_type)
, resize(size_type, const_reference)
Parameters: |
|
||
Requires: |
If |
||
Postconditions: |
|
||
Throws: |
An allocation error if memory is exhausted, (std::bad_alloc if the standard allocator is used). Whatever T::T(const T&) throws or nothing if T::T(T&&) is noexcept. |
( new_size, item = );Change the size of the
circular_buffer
.
Exception Safety. Basic.
Iterator Invalidation. Invalidates all iterators pointing to the
(except iterators equal to circular_buffer
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.
Complexity. Linear (in the new size of the
). circular_buffer
See Also:
rresize(size_type, const_reference)
, set_capacity(capacity_type)
Parameters: |
|
||||
Postconditions: |
|
||||
Throws: |
An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is used). Whatever T::T(const T&) throws or nothing if T::T(T&&) is noexcept. |
( new_capacity);Change the capacity of the
circular_buffer
.
Exception Safety. Strong.
Iterator Invalidation. Invalidates all iterators pointing to the
(except iterators equal to circular_buffer
end()
) if the new capacity is different from the original.
Complexity. Linear (in min[size(), new_capacity]
).
See Also:
set_capacity(capacity_type)
, rresize(size_type, const_reference)
Parameters: |
|
||
Requires: |
If |
||
Postconditions: |
|
||
Throws: |
An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is used). Whatever T::T(const T&) throws or nothing if T::T(T&&) is noexcept. |
( new_size, item = );Change the size of the
circular_buffer
.
Exception Safety. Basic.
Iterator Invalidation. Invalidates all iterators pointing to the
(except iterators equal to circular_buffer
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.
Complexity. Linear (in the new size of the
). circular_buffer
See Also:
resize(size_type, const_reference)
, rset_capacity(capacity_type)
Parameters: |
|
||||
Postconditions: |
|
||||
Throws: |
An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is used). Whatever T::T(const T&) throws or nothing if T::T(T&&) is noexcept. |
( n, item);Assign
n
items into the circular_buffer
. The content of the
will be removed and replaced with circular_buffer
n
copies of the item
.
Exception Safety. Basic.
Iterator Invalidation. Invalidates all iterators pointing to the
(except iterators equal to circular_buffer
end()
).
Complexity. Linear (in the n
).
See Also:
operator=
, assign(capacity_type, size_type, const_reference)
, assign(InputIterator, InputIterator)
, assign(capacity_type, InputIterator, InputIterator)
Parameters: |
|
||||
Postconditions: |
|
||||
Throws: |
An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is used). Whatever T::T(const T&) throws. |
( buffer_capacity, n, item);Assign
n
items into the circular_buffer
specifying the capacity. The capacity of the
will be set to the specified value and the content of the circular_buffer
will be removed and replaced with circular_buffer
n
copies of the item
.
Exception Safety. Basic.
Iterator Invalidation. Invalidates all iterators pointing to the
(except iterators equal to circular_buffer
end()
).
Complexity. Linear (in the n
).
See Also:
operator=
, assign(size_type, const_reference)
, assign(InputIterator, InputIterator)
, assign(capacity_type, InputIterator, InputIterator)
Parameters: |
|
||||||
Requires: |
|
||||||
Postconditions: |
|
||||||
Throws: |
An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is used). Whatever T::T(const T&) throws. |
template<typename InputIterator> ( first, last);Assign a copy of the range into the
circular_buffer
. The content of the
will be removed and replaced with copies of elements from the specified range.
circular_buffer
Exception Safety. Basic.
Iterator Invalidation. Invalidates all iterators pointing to the
(except iterators equal to circular_buffer
end()
).
Complexity. Linear (in the std::distance(first, last)
).
See Also:
operator=
, assign(size_type, const_reference)
, assign(capacity_type, size_type, const_reference)
, assign(capacity_type, InputIterator, InputIterator)
Parameters: |
|
||||
Requires: |
Valid range |
||||
Postconditions: |
|
||||
Throws: |
An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is used). Whatever T::T(const T&) throws. |
template<typename InputIterator> ( buffer_capacity, first, last);Assign a copy of the range into the
circular_buffer
specifying the capacity. The capacity of the
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.
circular_buffer
Exception Safety. Basic.
Iterator Invalidation. Invalidates all iterators pointing to the
(except iterators equal to circular_buffer
end()
).
Complexity. Linear (in std::distance(first, last)
; in min[capacity, std::distance(first, last)]
if the InputIterator
is a RandomAccessIterator).
See Also:
operator=
, assign(size_type, const_reference)
, assign(capacity_type, size_type, const_reference)
, assign(InputIterator, InputIterator)
Parameters: |
|
||||||
Requires: |
Valid range |
||||||
Postconditions: |
|
||||||
Throws: |
An allocation error if memory is exhausted (std::bad_alloc if the standard allocator is used). Whatever T::T(const T&) throws. |
(circular_buffer< cb) ;Swap the contents of two
circular_buffer
s.
Exception Safety. No-throw.
Iterator Invalidation. Invalidates all iterators of both
s. (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.) circular_buffer
Complexity. Constant (in the size of the
). circular_buffer
See Also:
swap(circular_buffer<T, Alloc>&, circular_buffer<T, Alloc>&)
Parameters: |
|
||
Postconditions: |
|
||
Throws: |
Nothing. |
( item);Insert a new element at the end of the
circular_buffer
.
Exception Safety. Basic; no-throw if the operation in the Throws section does not throw anything.
Iterator Invalidation. Does not invalidate any iterators with the exception of iterators pointing to the overwritten element.
Complexity. Constant (in the size of the
). circular_buffer
See Also:
push_front(const_reference)
, pop_back()
, pop_front()
Parameters: |
|
||
Postconditions: |
if |
||
Throws: |
Whatever T::T(const T&) throws. Whatever T::operator = (const T&) throws. |
( item);Insert a new element at the end of the
circular_buffer
using rvalue references or rvalues references emulation.
Exception Safety. Basic; no-throw if the operation in the Throws section does not throw anything.
Iterator Invalidation. Does not invalidate any iterators with the exception of iterators pointing to the overwritten element.
Complexity. Constant (in the size of the
). circular_buffer
See Also:
push_front(const_reference)
, pop_back()
, pop_front()
Parameters: |
|
||
Postconditions: |
if |
||
Throws: |
Whatever T::T(T&&) throws. Whatever T::operator = (T&&) throws. |
();Insert a new default-constructed element at the end of the
circular_buffer
.
Exception Safety. Basic; no-throw if the operation in the Throws section does not throw anything.
Iterator Invalidation. Does not invalidate any iterators with the exception of iterators pointing to the overwritten element.
Complexity. Constant (in the size of the
). circular_buffer
See Also:
push_front(const_reference)
, pop_back()
, pop_front()
Postconditions: |
if |
Throws: |
Whatever T::T() throws. Whatever T::T(T&&) throws. Whatever T::operator = (T&&) throws. |
( item);Insert a new element at the beginning of the
circular_buffer
.
Exception Safety. Basic; no-throw if the operation in the Throws section does not throw anything.
Iterator Invalidation. Does not invalidate any iterators with the exception of iterators pointing to the overwritten element.
Complexity. Constant (in the size of the
). circular_buffer
See Also:
push_back(const_reference)
, pop_back()
, pop_front()
Parameters: |
|
||
Postconditions: |
if |
||
Throws: |
Whatever T::T(const T&) throws. Whatever T::operator = (const T&) throws. |
( item);Insert a new element at the beginning of the
circular_buffer
using rvalue references or rvalues references emulation.
Exception Safety. Basic; no-throw if the operation in the Throws section does not throw anything.
Iterator Invalidation. Does not invalidate any iterators with the exception of iterators pointing to the overwritten element.
Complexity. Constant (in the size of the
). circular_buffer
See Also:
push_back(const_reference)
, pop_back()
, pop_front()
Parameters: |
|
||
Postconditions: |
if |
||
Throws: |
Whatever T::T(T&&) throws. Whatever T::operator = (T&&) throws. |
();Insert a new default-constructed element at the beginning of the
circular_buffer
.
Exception Safety. Basic; no-throw if the operation in the Throws section does not throw anything.
Iterator Invalidation. Does not invalidate any iterators with the exception of iterators pointing to the overwritten element.
Complexity. Constant (in the size of the
). circular_buffer
See Also:
push_back(const_reference)
, pop_back()
, pop_front()
Postconditions: |
if |
Throws: |
Whatever T::T() throws. Whatever T::T(T&&) throws. Whatever T::operator = (T&&) throws. |
();Remove the last element from the
circular_buffer
.
Exception Safety. No-throw.
Iterator Invalidation. Invalidates only iterators pointing to the removed element.
Complexity. Constant (in the size of the
). circular_buffer
See Also:
pop_front()
, push_back(const_reference)
, push_front(const_reference)
Requires: |
|
Postconditions: |
The last element is removed from the |
Throws: |
Nothing. |
();Remove the first element from the
circular_buffer
.
Exception Safety. No-throw.
Iterator Invalidation. Invalidates only iterators pointing to the removed element.
Complexity. Constant (in the size of the
). circular_buffer
See Also:
pop_back()
, push_back(const_reference)
, push_front(const_reference)
Requires: |
|
Postconditions: |
The first element is removed from the |
Throws: |
Nothing. |
( pos, item);Insert an element at the specified position.
Exception Safety. Basic; no-throw if the operation in the Throws section does not throw anything.
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.
Complexity. Linear (in std::distance(pos, end())
).
See Also:
insert(iterator, size_type, value_type)
, insert(iterator, InputIterator, InputIterator)
, rinsert(iterator, value_type)
, rinsert(iterator, size_type, value_type)
, rinsert(iterator, InputIterator, InputIterator)
Parameters: |
|
||||
Requires: |
|
||||
Postconditions: |
The |
||||
Returns: |
Iterator to the inserted element or |
||||
Throws: |
Whatever T::T(const T&) throws. Whatever T::operator = (const T&) throws. Exceptions of move_if_noexcept(T&). |
( pos, item);Insert an element at the specified position.
Exception Safety. Basic; no-throw if the operation in the Throws section does not throw anything.
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.
Complexity. Linear (in std::distance(pos, end())
).
See Also:
insert(iterator, size_type, value_type)
, insert(iterator, InputIterator, InputIterator)
, rinsert(iterator, value_type)
, rinsert(iterator, size_type, value_type)
, rinsert(iterator, InputIterator, InputIterator)
Parameters: |
|
||||
Requires: |
|
||||
Postconditions: |
The |
||||
Returns: |
Iterator to the inserted element or |
||||
Throws: |
Whatever T::T(T&&) throws. Whatever T::operator = (T&&) throws. Exceptions of move_if_noexcept(T&). |
( pos);Insert a default-constructed element at the specified position.
Exception Safety. Basic; no-throw if the operation in the Throws section does not throw anything.
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.
Complexity. Linear (in std::distance(pos, end())
).
See Also:
insert(iterator, size_type, value_type)
, insert(iterator, InputIterator, InputIterator)
, rinsert(iterator, value_type)
, rinsert(iterator, size_type, value_type)
, rinsert(iterator, InputIterator, InputIterator)
Parameters: |
|
||
Requires: |
|
||
Postconditions: |
The |
||
Returns: |
Iterator to the inserted element or |
||
Throws: |
Whatever T::T() throws. Whatever T::T(T&&) throws. Whatever T::operator = (T&&) throws. Exceptions of move_if_noexcept(T&). |
( pos, n, item);Insert
n
copies of the item
at the specified position.
Exception Safety. Basic; no-throw if the operations in the Throws section do not throw anything.
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.
Complexity. Linear (in min[capacity(), std::distance(pos, end()) + n]
).
Example. Consider a
with the capacity of 6 and the size of 4. Its internal buffer may look like the one below.circular_buffer
|1|2|3|4| | |
p ___^
After inserting 5 elements at the position p
:
insert(p, (size_t)5, 0);
actually only 4 elements get inserted and elements 1
and 2
are overwritten. This is due to the fact the insert operation preserves the capacity. After insertion the internal buffer looks like this:
|0|0|0|0|3|4|
For comparison if the capacity would not be preserved the internal buffer would then result in |1|2|0|0|0|0|0|3|4|
.
See Also:
insert(iterator, value_type)
, insert(iterator, InputIterator, InputIterator)
, rinsert(iterator, value_type)
, rinsert(iterator, size_type, value_type)
, rinsert(iterator, InputIterator, InputIterator)
Parameters: |
|
||||||
Requires: |
|
||||||
Postconditions: |
The number of |
||||||
Throws: |
Whatever T::T(const T&) throws. Whatever T::operator = (const T&) throws. Exceptions of move_if_noexcept(T&). |
template<typename InputIterator> ( pos, first, last);Insert the range
[first, last)
at the specified position.
Exception Safety. Basic; no-throw if the operations in the Throws section do not throw anything.
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.
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).
Example. Consider a
with the capacity of 6 and the size of 4. Its internal buffer may look like the one below.circular_buffer
|1|2|3|4| | |
p ___^
After inserting a range of elements at the position p
:
int array[] = { 5, 6, 7, 8, 9 };
insert(p, array, array + 5);
actually only elements 6
, 7
, 8
and 9
from the specified range get inserted and elements 1
and 2
are overwritten. This is due to the fact the insert operation preserves the capacity. After insertion the internal buffer looks like this:
|6|7|8|9|3|4|
For comparison if the capacity would not be preserved the internal buffer would then result in |1|2|5|6|7|8|9|3|4|
.
See Also:
insert(iterator, value_type)
, insert(iterator, size_type, value_type)
, rinsert(iterator, value_type)
, rinsert(iterator, size_type, value_type)
, rinsert(iterator, InputIterator, InputIterator)
Parameters: |
|
||||||
Requires: |
|
||||||
Postconditions: |
Elements from the range |
||||||
Throws: |
Whatever T::T(const T&) throws if the InputIterator is not a move iterator. Whatever T::operator = (const T&) throws if the InputIterator is not a move iterator. Whatever T::T(T&&) throws if the InputIterator is a move iterator. Whatever T::operator = (T&&) throws if the InputIterator is a move iterator. |
( pos, item);Insert an element before the specified position.
Exception Safety. Basic; no-throw if the operations in the Throws section do not throw anything.
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.
Complexity. Linear (in std::distance(begin(), pos)
).
See Also:
rinsert(iterator, size_type, value_type)
, rinsert(iterator, InputIterator, InputIterator)
, insert(iterator, value_type)
, insert(iterator, size_type, value_type)
, insert(iterator, InputIterator, InputIterator)
Parameters: |
|
||||
Requires: |
|
||||
Postconditions: |
The |
||||
Returns: |
Iterator to the inserted element or |
||||
Throws: |
Whatever T::T(const T&) throws. Whatever T::operator = (const T&) throws. Exceptions of move_if_noexcept(T&). |
( pos, item);Insert an element before the specified position.
Exception Safety. Basic; no-throw if the operations in the Throws section do not throw anything.
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.
Complexity. Linear (in std::distance(begin(), pos)
).
See Also:
rinsert(iterator, size_type, value_type)
, rinsert(iterator, InputIterator, InputIterator)
, insert(iterator, value_type)
, insert(iterator, size_type, value_type)
, insert(iterator, InputIterator, InputIterator)
Parameters: |
|
||||
Requires: |
|
||||
Postconditions: |
The |
||||
Returns: |
Iterator to the inserted element or |
||||
Throws: |
Whatever T::T(T&&) throws. Whatever T::operator = (T&&) throws. Exceptions of move_if_noexcept(T&). |
( pos);Insert an element before the specified position.
Exception Safety. Basic; no-throw if the operations in the Throws section do not throw anything.
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.
Complexity. Linear (in std::distance(begin(), pos)
).
See Also:
rinsert(iterator, size_type, value_type)
, rinsert(iterator, InputIterator, InputIterator)
, insert(iterator, value_type)
, insert(iterator, size_type, value_type)
, insert(iterator, InputIterator, InputIterator)
Parameters: |
|
||
Requires: |
|
||
Postconditions: |
The |
||
Returns: |
Iterator to the inserted element or |
||
Throws: |
Whatever T::T() throws. Whatever T::T(T&&) throws. Whatever T::operator = (T&&) throws. Exceptions of move_if_noexcept(T&). |
( pos, n, item);Insert
n
copies of the item
before the specified position.
Exception Safety. Basic; no-throw if the operations in the Throws section do not throw anything.
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.
Complexity. Linear (in min[capacity(), std::distance(begin(), pos) + n]
).
Example. Consider a
with the capacity of 6 and the size of 4. Its internal buffer may look like the one below.circular_buffer
|1|2|3|4| | |
p ___^
After inserting 5 elements before the position p
:
rinsert(p, (size_t)5, 0);
actually only 4 elements get inserted and elements 3
and 4
are overwritten. This is due to the fact the rinsert operation preserves the capacity. After insertion the internal buffer looks like this:
|1|2|0|0|0|0|
For comparison if the capacity would not be preserved the internal buffer would then result in |1|2|0|0|0|0|0|3|4|
.
See Also:
rinsert(iterator, value_type)
, rinsert(iterator, InputIterator, InputIterator)
, insert(iterator, value_type)
, insert(iterator, size_type, value_type)
, insert(iterator, InputIterator, InputIterator)
Parameters: |
|
||||||
Requires: |
|
||||||
Postconditions: |
The number of |
||||||
Throws: |
Whatever T::T(const T&) throws. Whatever T::operator = (const T&) throws. Exceptions of move_if_noexcept(T&). |
template<typename InputIterator> ( pos, first, last);Insert the range
[first, last)
before the specified position.
Exception Safety. Basic; no-throw if the operations in the Throws section do not throw anything.
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.
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).
Example. Consider a
with the capacity of 6 and the size of 4. Its internal buffer may look like the one below.circular_buffer
|1|2|3|4| | |
p ___^
After inserting a range of elements before the position p
:
int array[] = { 5, 6, 7, 8, 9 };
insert(p, array, array + 5);
actually only elements 5
, 6
, 7
and 8
from the specified range get inserted and elements 3
and 4
are overwritten. This is due to the fact the rinsert operation preserves the capacity. After insertion the internal buffer looks like this:
|1|2|5|6|7|8|
For comparison if the capacity would not be preserved the internal buffer would then result in |1|2|5|6|7|8|9|3|4|
.
See Also:
rinsert(iterator, value_type)
, rinsert(iterator, size_type, value_type)
, insert(iterator, value_type)
, insert(iterator, size_type, value_type)
, insert(iterator, InputIterator, InputIterator)
Parameters: |
|
||||||
Requires: |
|
||||||
Postconditions: |
Elements from the range |
||||||
Throws: |
Whatever T::T(const T&) throws if the InputIterator is not a move iterator. Whatever T::operator = (const T&) throws if the InputIterator is not a move iterator. Whatever T::T(T&&) throws if the InputIterator is a move iterator. Whatever T::operator = (T&&) throws if the InputIterator is a move iterator. |
( pos);Remove an element at the specified position.
Exception Safety. Basic; no-throw if the operation in the Throws section does not throw anything.
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()
).
Complexity. Linear (in std::distance(pos, end())
).
See Also:
erase(iterator, iterator)
, rerase(iterator)
, rerase(iterator, iterator)
, erase_begin(size_type)
, erase_end(size_type)
, clear()
Parameters: |
|
||
Requires: |
|
||
Postconditions: |
The element at the position |
||
Returns: |
Iterator to the first element remaining beyond the removed element or |
||
Throws: |
<a href="circular_buffer/implementation.html#circular_buffer.implementation.exceptions_of_move_if_noexcept_t">Exceptions of move_if_noexcept(T&). |
( first, last);Erase the range
[first, last)
.
Exception Safety. Basic; no-throw if the operation in the Throws section does not throw anything.
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()
).
Complexity. Linear (in std::distance(first, end())
).
See Also:
erase(iterator)
, rerase(iterator)
, rerase(iterator, iterator)
, erase_begin(size_type)
, erase_end(size_type)
, clear()
Parameters: |
|
||||
Requires: |
Valid range |
||||
Postconditions: |
The elements from the range |
||||
Returns: |
Iterator to the first element remaining beyond the removed elements or |
||||
Throws: |
<a href="circular_buffer/implementation.html#circular_buffer.implementation.exceptions_of_move_if_noexcept_t">Exceptions of move_if_noexcept(T&). |
( pos);Remove an element at the specified position.
Exception Safety. Basic; no-throw if the operation in the Throws section does not throw anything.
Iterator Invalidation. Invalidates iterators pointing to the erased element and iterators pointing to the elements in front of the erased element (towards the beginning).
Complexity. Linear (in std::distance(begin(), pos)
).
![]() |
Note |
---|---|
This method is symmetric to the |
See Also:
erase(iterator)
, erase(iterator, iterator)
, rerase(iterator, iterator)
, erase_begin(size_type)
, erase_end(size_type)
, clear()
Parameters: |
|
||
Requires: |
|
||
Postconditions: |
The element at the position |
||
Returns: |
Iterator to the first element remaining in front of the removed element or |
||
Throws: |
<a href="circular_buffer/implementation.html#circular_buffer.implementation.exceptions_of_move_if_noexcept_t">Exceptions of move_if_noexcept(T&). |
( first, last);Erase the range
[first, last)
.
Exception Safety. Basic; no-throw if the operation in the Throws section does not throw anything.
Iterator Invalidation. Invalidates iterators pointing to the erased elements and iterators pointing to the elements in front of the erased range (towards the beginning).
Complexity. Linear (in std::distance(begin(), last)
).
![]() |
Note |
---|---|
This method is symmetric to the |
See Also:
erase(iterator)
, erase(iterator, iterator)
, rerase(iterator)
, erase_begin(size_type)
, erase_end(size_type)
, clear()
Parameters: |
|
||||
Requires: |
Valid range |
||||
Postconditions: |
The elements from the range |
||||
Returns: |
Iterator to the first element remaining in front of the removed elements or |
||||
Throws: |
<a href="circular_buffer/implementation.html#circular_buffer.implementation.exceptions_of_move_if_noexcept_t">Exceptions of move_if_noexcept(T&). |
( n);Remove first
n
elements (with constant complexity for scalar types).
Exception Safety. Basic; no-throw if the operation in the Throws section does not throw anything. (I.e. no throw in case of scalars.)
Iterator Invalidation. Invalidates iterators pointing to the first n
erased elements.
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 |
See Also:
erase(iterator)
, erase(iterator, iterator)
, rerase(iterator)
, rerase(iterator, iterator)
, erase_end(size_type)
, clear()
Parameters: |
|
||
Requires: |
|
||
Postconditions: |
The |
||
Throws: |
<a href="circular_buffer/implementation.html#circular_buffer.implementation.exceptions_of_move_if_noexcept_t">Exceptions of move_if_noexcept(T&). |
( n);Remove last
n
elements (with constant complexity for scalar types).
Exception Safety. Basic; no-throw if the operation in the Throws section does not throw anything. (I.e. no throw in case of scalars.)
Iterator Invalidation. Invalidates iterators pointing to the last n
erased elements.
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 |
See Also:
erase(iterator)
, erase(iterator, iterator)
, rerase(iterator)
, rerase(iterator, iterator)
, erase_begin(size_type)
, clear()
Parameters: |
|
||
Requires: |
|
||
Postconditions: |
The |
||
Throws: |
<a href="circular_buffer/implementation.html#circular_buffer.implementation.exceptions_of_move_if_noexcept_t">Exceptions of move_if_noexcept(T&). |
() ;Remove all stored elements from the
circular_buffer
.
Exception Safety. No-throw.
Iterator Invalidation. Invalidates all iterators pointing to the
(except iterators equal to circular_buffer
end()
).
Complexity. Constant (in the size of the
) for scalar types; linear for other types. circular_buffer
See Also:
~circular_buffer()
, erase(iterator)
, erase(iterator, iterator)
, rerase(iterator)
, rerase(iterator, iterator)
, erase_begin(size_type)
, erase_end(size_type)
Postconditions: |
|
Throws: |
Nothing. |