baudvine::RingBuf
STL-like ring buffer in C++11
baudvine::RingBuf< Elem, Capacity, Allocator > Class Template Reference

An STL-like ring buffer with dynamic allocation and compile-time capacity limits. More...

#include <baudvine/ringbuf.h>

Public Types

using allocator_type = Allocator
 
using alloc_traits = std::allocator_traits< allocator_type >
 
using value_type = Elem
 
using pointer = typename alloc_traits::pointer
 
using const_pointer = typename alloc_traits::const_pointer
 
using reference = decltype(*pointer{})
 
using const_reference = decltype(*const_pointer{})
 
using iterator = detail::ringbuf::Iterator< pointer, alloc_traits, Capacity >
 
using const_iterator = detail::ringbuf::Iterator< const_pointer, alloc_traits, Capacity >
 
using reverse_iterator = std::reverse_iterator< iterator >
 
using const_reverse_iterator = std::reverse_iterator< const_iterator >
 
using difference_type = typename alloc_traits::difference_type
 
using size_type = typename alloc_traits::size_type
 
using unsigned_difference = typename std::make_unsigned< difference_type >::type
 
using self = RingBuf< Elem, Capacity >
 

Public Member Functions

 RingBuf ()
 Construct a new ring buffer object with a default-constructed allocator, and allocate the required memory. More...
 
 RingBuf (const allocator_type &allocator)
 Construct a new ring buffer object with the provided allocator, and allocate the required memory. More...
 
 ~RingBuf ()
 Destroy the ring buffer object. More...
 
 RingBuf (const RingBuf &other)
 Construct a new RingBuf object out of another, using elementwise copy assignment. More...
 
 RingBuf (const RingBuf &other, const allocator_type &allocator)
 Allocator-extended copy constructor. More...
 
 RingBuf (RingBuf &&other) noexcept
 Construct a new RingBuf object out of another, using bulk move assignment. More...
 
 RingBuf (RingBuf &&other, const allocator_type &allocator)
 Allocator-extended move constructor. More...
 
RingBufoperator= (const RingBuf &other)
 Copy a RingBuf into this one. More...
 
RingBufoperator= (RingBuf &&other) noexcept(alloc_traits::propagate_on_container_move_assignment::value||std::is_nothrow_move_constructible< value_type >::value)
 Move a RingBuf into this one. More...
 
allocator_type get_allocator () const
 Get a copy of the allocator used by this RingBuf.
 
reference front ()
 Returns the first element in the ring buffer. More...
 
const_reference front () const
 Returns the first element in the ring buffer. More...
 
reference back ()
 Returns he last element in the ring buffer. More...
 
const_reference back () const
 Returns he last element in the ring buffer. More...
 
const_reference operator[] (const size_type index) const
 Retrieve an element from the ring buffer without range checking. More...
 
reference operator[] (const size_type index)
 Retrieve an element from the ring buffer without range checking. More...
 
const_reference at (const size_type index) const
 Retrieve an element from the ring buffer with range checking. More...
 
reference at (const size_type index)
 Retrieve an element from the ring buffer with range checking. More...
 
iterator begin () noexcept
 Get an iterator pointing to the first element.
 
iterator end () noexcept
 Get an iterator pointing to one past the last element.
 
const_iterator begin () const noexcept
 Get a const iterator pointing to the first element.
 
const_iterator end () const noexcept
 Get a const iterator pointing to one past the last element.
 
const_iterator cbegin () const noexcept
 Get a const iterator pointing to the first element.
 
const_iterator cend () const noexcept
 Get a const iterator pointing to one past the last element.
 
reverse_iterator rbegin () noexcept
 Get a reverse iterator pointing to the last element.
 
reverse_iterator rend () noexcept
 Get a reverse iterator pointing to one before the first element.
 
const_reverse_iterator rbegin () const noexcept
 Get a const reverse iterator pointing to the last element.
 
const_reverse_iterator rend () const noexcept
 Get a const reverse iterator pointing to one before the first element.
 
const_reverse_iterator crbegin () const noexcept
 Get a const reverse iterator pointing to the last element.
 
const_reverse_iterator crend () const noexcept
 Get a const reverse iterator pointing to one before the first element.
 
bool empty () const noexcept
 Get whether the ring buffer is empty (size() == 0)
 
size_type size () const noexcept
 Get the number of elements in the ring buffer.
 
constexpr size_type max_size () const noexcept
 Get the maximum number of elements in this ring buffer (Capacity).
 
void push_front (const_reference value)
 Push a new element at the front of the ring buffer, popping the back if necessary. More...
 
void push_front (value_type &&value)
 Push a new element at the front of the ring buffer, popping the back if necessary. More...
 
template<typename... Args>
reference emplace_front (Args &&... args)
 Construct a new element in-place before the front of the ring buffer, popping the back if necessary. More...
 
void push_back (const_reference value)
 Push a new element into the ring buffer, popping the front if necessary. More...
 
void push_back (value_type &&value)
 Push a new element into the ring buffer, popping the front if necessary. More...
 
template<typename... Args>
reference emplace_back (Args &&... args)
 Construct a new element in-place at the end of the ring buffer, popping the front if necessary. More...
 
void pop_front () noexcept
 Pop an element off the front, destroying the first element in the ring buffer.
 
void pop_back () noexcept
 Pop an element off the back, destroying the last element in the ring buffer.
 
void clear () noexcept(noexcept(pop_front()))
 Remove all elements from the ring buffer, destroying each one starting at the front. More...
 
iterator erase (const_iterator from, const_iterator to) noexcept(noexcept(pop_front()) &&std::is_nothrow_move_assignable< Elem >::value)
 Erase elements in the range [first, last). More...
 
iterator erase (const_iterator pos) noexcept(noexcept(erase(pos, pos+1)))
 Erase an element. More...
 
void swap (RingBuf &other) noexcept
 Swap this ring buffer with another using std::swap. More...
 

Friends

bool operator< (const RingBuf &lhs, const RingBuf &rhs)
 Elementwise lexicographical comparison of two ring buffers. More...
 
bool operator> (const RingBuf &lhs, const RingBuf &rhs)
 Elementwise lexicographical comparison of two ring buffers. More...
 
bool operator== (const RingBuf &lhs, const RingBuf &rhs)
 Elementwise comparison of two ring buffers. More...
 
bool operator>= (const RingBuf &lhs, const RingBuf &rhs)
 Elementwise comparison of two ring buffers. More...
 
bool operator<= (const RingBuf &lhs, const RingBuf &rhs)
 Elementwise comparison of two ring buffers. More...
 
bool operator!= (const RingBuf &lhs, const RingBuf &rhs)
 Elementwise comparison of two ring buffers. More...
 

Detailed Description

template<typename Elem, std::size_t Capacity, typename Allocator = std::allocator<Elem>>
class baudvine::RingBuf< Elem, Capacity, Allocator >

An STL-like ring buffer with dynamic allocation and compile-time capacity limits.

Template Parameters
ElemThe type of elements contained by the ring buffer.
CapacityThe maximum size of the ring buffer, and the fixed size of the backing array.
AllocatorThe allocator type to use for storage and element construction.

Definition at line 337 of file ringbuf.h.

Constructor & Destructor Documentation

◆ RingBuf() [1/6]

template<typename Elem , std::size_t Capacity, typename Allocator = std::allocator<Elem>>
baudvine::RingBuf< Elem, Capacity, Allocator >::RingBuf ( )
inline

Construct a new ring buffer object with a default-constructed allocator, and allocate the required memory.

Allocates Capacity + 1 to allow for strong exception guarantees in emplace_front/back.

Definition at line 436 of file ringbuf.h.

◆ RingBuf() [2/6]

template<typename Elem , std::size_t Capacity, typename Allocator = std::allocator<Elem>>
baudvine::RingBuf< Elem, Capacity, Allocator >::RingBuf ( const allocator_type &  allocator)
inlineexplicit

Construct a new ring buffer object with the provided allocator, and allocate the required memory.

Allocates Capacity + 1 to allow for strong exception guarantees in emplace_front/back.

Parameters
allocatorThe allocator to use for storage and element construction.

Definition at line 446 of file ringbuf.h.

◆ ~RingBuf()

template<typename Elem , std::size_t Capacity, typename Allocator = std::allocator<Elem>>
baudvine::RingBuf< Elem, Capacity, Allocator >::~RingBuf ( )
inline

Destroy the ring buffer object.

Destroys the active elements via clear() and deallocates the backing array.

Definition at line 455 of file ringbuf.h.

◆ RingBuf() [3/6]

template<typename Elem , std::size_t Capacity, typename Allocator = std::allocator<Elem>>
baudvine::RingBuf< Elem, Capacity, Allocator >::RingBuf ( const RingBuf< Elem, Capacity, Allocator > &  other)
inline

Construct a new RingBuf object out of another, using elementwise copy assignment.

Parameters
otherThe RingBuf to copy values from.
Todo:
maybe allow other (smaller) sizes as input?

Definition at line 466 of file ringbuf.h.

◆ RingBuf() [4/6]

template<typename Elem , std::size_t Capacity, typename Allocator = std::allocator<Elem>>
baudvine::RingBuf< Elem, Capacity, Allocator >::RingBuf ( const RingBuf< Elem, Capacity, Allocator > &  other,
const allocator_type &  allocator 
)
inline

Allocator-extended copy constructor.

Parameters
otherThe RingBuf to copy values from.
allocatorThe allocator to use for storage and element construction.
Todo:

maybe allow other (smaller) sizes as input?

Use memcpy/stdcopy if Elem is POD

Definition at line 479 of file ringbuf.h.

◆ RingBuf() [5/6]

template<typename Elem , std::size_t Capacity, typename Allocator = std::allocator<Elem>>
baudvine::RingBuf< Elem, Capacity, Allocator >::RingBuf ( RingBuf< Elem, Capacity, Allocator > &&  other)
inlinenoexcept

Construct a new RingBuf object out of another, using bulk move assignment.

Parameters
otherThe RingBuf to move the data out of.

Definition at line 492 of file ringbuf.h.

◆ RingBuf() [6/6]

template<typename Elem , std::size_t Capacity, typename Allocator = std::allocator<Elem>>
baudvine::RingBuf< Elem, Capacity, Allocator >::RingBuf ( RingBuf< Elem, Capacity, Allocator > &&  other,
const allocator_type &  allocator 
)
inline

Allocator-extended move constructor.

May move elementwise if the provided allocator and other's allocator are not the same.

Parameters
otherThe RingBuf to move the data out of.
allocatorThe allocator to use for storage and element construction.

Definition at line 504 of file ringbuf.h.

Member Function Documentation

◆ at() [1/2]

template<typename Elem , std::size_t Capacity, typename Allocator = std::allocator<Elem>>
reference baudvine::RingBuf< Elem, Capacity, Allocator >::at ( const size_type  index)
inline

Retrieve an element from the ring buffer with range checking.

Parameters
indexThe logical index into the ring buffer. Must be in range [0, size()).
Returns
A reference to the element.
Exceptions
std::out_of_rangeThe index is out of range.

Definition at line 632 of file ringbuf.h.

◆ at() [2/2]

template<typename Elem , std::size_t Capacity, typename Allocator = std::allocator<Elem>>
const_reference baudvine::RingBuf< Elem, Capacity, Allocator >::at ( const size_type  index) const
inline

Retrieve an element from the ring buffer with range checking.

Parameters
indexThe logical index into the ring buffer. Must be in range [0, size()).
Returns
A const reference to the element.
Exceptions
std::out_of_rangeThe index is out of range.

Definition at line 618 of file ringbuf.h.

◆ back() [1/2]

template<typename Elem , std::size_t Capacity, typename Allocator = std::allocator<Elem>>
reference baudvine::RingBuf< Elem, Capacity, Allocator >::back ( )
inline

Returns he last element in the ring buffer.

Exceptions
std::out_of_rangeThe buffer is empty.

Definition at line 581 of file ringbuf.h.

◆ back() [2/2]

template<typename Elem , std::size_t Capacity, typename Allocator = std::allocator<Elem>>
const_reference baudvine::RingBuf< Elem, Capacity, Allocator >::back ( ) const
inline

Returns he last element in the ring buffer.

Exceptions
std::out_of_rangeThe buffer is empty.

Definition at line 586 of file ringbuf.h.

◆ clear()

template<typename Elem , std::size_t Capacity, typename Allocator = std::allocator<Elem>>
void baudvine::RingBuf< Elem, Capacity, Allocator >::clear ( )
inlinenoexcept

Remove all elements from the ring buffer, destroying each one starting at the front.

After clear(), size() == 0.

Definition at line 822 of file ringbuf.h.

◆ emplace_back()

template<typename Elem , std::size_t Capacity, typename Allocator = std::allocator<Elem>>
template<typename... Args>
reference baudvine::RingBuf< Elem, Capacity, Allocator >::emplace_back ( Args &&...  args)
inline

Construct a new element in-place at the end of the ring buffer, popping the front if necessary.

Template Parameters
ArgsArguments to the element constructor.
Parameters
argsArguments to the element constructor.

Definition at line 776 of file ringbuf.h.

◆ emplace_front()

template<typename Elem , std::size_t Capacity, typename Allocator = std::allocator<Elem>>
template<typename... Args>
reference baudvine::RingBuf< Elem, Capacity, Allocator >::emplace_front ( Args &&...  args)
inline

Construct a new element in-place before the front of the ring buffer, popping the back if necessary.

Template Parameters
ArgsArguments to the element constructor.
Parameters
argsArguments to the element constructor.

Definition at line 739 of file ringbuf.h.

◆ erase() [1/2]

template<typename Elem , std::size_t Capacity, typename Allocator = std::allocator<Elem>>
iterator baudvine::RingBuf< Elem, Capacity, Allocator >::erase ( const_iterator  from,
const_iterator  to 
)
inlinenoexcept

Erase elements in the range [first, last).

Parameters
fromThe first element to erase.
toOne past the last element to erase.
Returns
Iterator pointing to the element after to.

Definition at line 836 of file ringbuf.h.

◆ erase() [2/2]

template<typename Elem , std::size_t Capacity, typename Allocator = std::allocator<Elem>>
iterator baudvine::RingBuf< Elem, Capacity, Allocator >::erase ( const_iterator  pos)
inlinenoexcept

Erase an element.

Parameters
posAn iterator pointing to the element to erase.
Returns
Iterator pointing to the element after pos.

Definition at line 876 of file ringbuf.h.

◆ front() [1/2]

template<typename Elem , std::size_t Capacity, typename Allocator = std::allocator<Elem>>
reference baudvine::RingBuf< Elem, Capacity, Allocator >::front ( )
inline

Returns the first element in the ring buffer.

Exceptions
std::out_of_rangeThe buffer is empty.

Definition at line 571 of file ringbuf.h.

◆ front() [2/2]

template<typename Elem , std::size_t Capacity, typename Allocator = std::allocator<Elem>>
const_reference baudvine::RingBuf< Elem, Capacity, Allocator >::front ( ) const
inline

Returns the first element in the ring buffer.

Exceptions
std::out_of_rangeThe buffer is empty.

Definition at line 576 of file ringbuf.h.

◆ operator=() [1/2]

template<typename Elem , std::size_t Capacity, typename Allocator = std::allocator<Elem>>
RingBuf& baudvine::RingBuf< Elem, Capacity, Allocator >::operator= ( const RingBuf< Elem, Capacity, Allocator > &  other)
inline

Copy a RingBuf into this one.

First clear()s this RingBuf, and then copies other element by element.

Parameters
otherThe RingBuf to copy from.
Returns
This RingBuf.

Definition at line 523 of file ringbuf.h.

◆ operator=() [2/2]

template<typename Elem , std::size_t Capacity, typename Allocator = std::allocator<Elem>>
RingBuf& baudvine::RingBuf< Elem, Capacity, Allocator >::operator= ( RingBuf< Elem, Capacity, Allocator > &&  other)
inlinenoexcept

Move a RingBuf into this one.

If the allocator is the same or can be moved as well, no elementwise moves are performed.

Parameters
otherThe RingBuf to copy from.
Returns
This RingBuf.

Definition at line 542 of file ringbuf.h.

◆ operator[]() [1/2]

template<typename Elem , std::size_t Capacity, typename Allocator = std::allocator<Elem>>
reference baudvine::RingBuf< Elem, Capacity, Allocator >::operator[] ( const size_type  index)
inline

Retrieve an element from the ring buffer without range checking.

The behaviour is undefined when index is outside [0, size()).

Parameters
indexThe logical index into the ring buffer.
Returns
A reference to the element.

Definition at line 607 of file ringbuf.h.

◆ operator[]() [2/2]

template<typename Elem , std::size_t Capacity, typename Allocator = std::allocator<Elem>>
const_reference baudvine::RingBuf< Elem, Capacity, Allocator >::operator[] ( const size_type  index) const
inline

Retrieve an element from the ring buffer without range checking.

The behaviour is undefined when index is outside [0, size()).

Parameters
indexThe logical index into the ring buffer.
Returns
A const reference to the element.

Definition at line 596 of file ringbuf.h.

◆ push_back() [1/2]

template<typename Elem , std::size_t Capacity, typename Allocator = std::allocator<Elem>>
void baudvine::RingBuf< Elem, Capacity, Allocator >::push_back ( const_reference  value)
inline

Push a new element into the ring buffer, popping the front if necessary.

Parameters
valueThe value to copy into the ring buffer.

Definition at line 761 of file ringbuf.h.

◆ push_back() [2/2]

template<typename Elem , std::size_t Capacity, typename Allocator = std::allocator<Elem>>
void baudvine::RingBuf< Elem, Capacity, Allocator >::push_back ( value_type &&  value)
inline

Push a new element into the ring buffer, popping the front if necessary.

Parameters
valueThe value to move into the ring buffer.

Definition at line 767 of file ringbuf.h.

◆ push_front() [1/2]

template<typename Elem , std::size_t Capacity, typename Allocator = std::allocator<Elem>>
void baudvine::RingBuf< Elem, Capacity, Allocator >::push_front ( const_reference  value)
inline

Push a new element at the front of the ring buffer, popping the back if necessary.

Parameters
valueThe value to copy into the ring buffer.

Definition at line 723 of file ringbuf.h.

◆ push_front() [2/2]

template<typename Elem , std::size_t Capacity, typename Allocator = std::allocator<Elem>>
void baudvine::RingBuf< Elem, Capacity, Allocator >::push_front ( value_type &&  value)
inline

Push a new element at the front of the ring buffer, popping the back if necessary.

Parameters
valueThe value to move into the ring buffer.

Definition at line 730 of file ringbuf.h.

◆ swap()

template<typename Elem , std::size_t Capacity, typename Allocator = std::allocator<Elem>>
void baudvine::RingBuf< Elem, Capacity, Allocator >::swap ( RingBuf< Elem, Capacity, Allocator > &  other)
inlinenoexcept

Swap this ring buffer with another using std::swap.

Parameters
otherThe RingBuf to swap with.

Definition at line 885 of file ringbuf.h.

Friends And Related Function Documentation

◆ operator!=

template<typename Elem , std::size_t Capacity, typename Allocator = std::allocator<Elem>>
bool operator!= ( const RingBuf< Elem, Capacity, Allocator > &  lhs,
const RingBuf< Elem, Capacity, Allocator > &  rhs 
)
friend

Elementwise comparison of two ring buffers.

Returns
True if lhs is not equal to rhs.

Definition at line 940 of file ringbuf.h.

◆ operator<

template<typename Elem , std::size_t Capacity, typename Allocator = std::allocator<Elem>>
bool operator< ( const RingBuf< Elem, Capacity, Allocator > &  lhs,
const RingBuf< Elem, Capacity, Allocator > &  rhs 
)
friend

Elementwise lexicographical comparison of two ring buffers.

Returns
True if the left-hand side compares as less than the right.

Definition at line 895 of file ringbuf.h.

◆ operator<=

template<typename Elem , std::size_t Capacity, typename Allocator = std::allocator<Elem>>
bool operator<= ( const RingBuf< Elem, Capacity, Allocator > &  lhs,
const RingBuf< Elem, Capacity, Allocator > &  rhs 
)
friend

Elementwise comparison of two ring buffers.

Returns
True if lhs is less than or equal to rhs.

Definition at line 932 of file ringbuf.h.

◆ operator==

template<typename Elem , std::size_t Capacity, typename Allocator = std::allocator<Elem>>
bool operator== ( const RingBuf< Elem, Capacity, Allocator > &  lhs,
const RingBuf< Elem, Capacity, Allocator > &  rhs 
)
friend

Elementwise comparison of two ring buffers.

Returns
True if lhs is equal to rhs.

Definition at line 912 of file ringbuf.h.

◆ operator>

template<typename Elem , std::size_t Capacity, typename Allocator = std::allocator<Elem>>
bool operator> ( const RingBuf< Elem, Capacity, Allocator > &  lhs,
const RingBuf< Elem, Capacity, Allocator > &  rhs 
)
friend

Elementwise lexicographical comparison of two ring buffers.

Returns
True if the left-hand side compares as more than the right.

Definition at line 904 of file ringbuf.h.

◆ operator>=

template<typename Elem , std::size_t Capacity, typename Allocator = std::allocator<Elem>>
bool operator>= ( const RingBuf< Elem, Capacity, Allocator > &  lhs,
const RingBuf< Elem, Capacity, Allocator > &  rhs 
)
friend

Elementwise comparison of two ring buffers.

Returns
True if lhs is greater than or equal to rhs.

Definition at line 924 of file ringbuf.h.


The documentation for this class was generated from the following file: