etl/docs/containers/queues & stacks/circular-buffer.md

title
circular_buffer

{{< callout >}} Header: circular_buffer.h
{{< /callout >}}

A fixed capacity circular buffer.

etl::circular_buffer<typename T, size_t SIZE>
etl::circular_buffer_ext<typename T>

Inherits from etl::icircular_buffer<T>
etl::icircular_buffer may be used as a size independent pointer or reference type for any etl::circular_buffer instance.

External buffer

etl::circular_buffer_ext<typename T>

For this template the constructor expects pointer and size parameters to the externally provided buffer. This buffer must not be shared concurrently with any other container.
When a circular_buffer with an external buffer is moved, the data is moved, not the pointer to the buffer.
The external buffer MUST be declared one item larger that the intended capacity of the circular buffer.

A swap on a circular_buffer with an external buffer is fast as it will swap buffer pointers rather than copying items.

Template deduction guides

template <typename T, typename... Ts>
etl::circular_buffer(T, Ts...)
  -> etl::circular_buffer<T, 1U + sizeof...(Ts)>;

C++17 and above.
Only enabled if Ts... is the same type as T.

Example

etl::circular_buffer data{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 };

Defines data as a circular_buffer of int, of length 10, containing the supplied data.

Member types

value_type              T
size_type               std::size_t
difference_type         std::ptrdiff_t
reference               value_type&
const_reference         const value_type&
rvalue_reference        value_type&&
pointer                 value_type*
const_pointer           const value_type*
iterator                Random access iterator
const_iterator          Constant random access iterator
reverse_iterator        reverse_iterator<iterator>
const_reverse_iterator  reverse_iterator<const_iterator>

Static Constants

MAX_SIZE The maximum size of the circular_buffer.

Constructors

circular_buffer<typename T, size_t SIZE>();

circular_buffer<typename T, size_t SIZE>(size_t initial_size);

circular_buffer<typename T, size_t SIZE>(size_t initial_size, const_reference value);

circular_buffer<typename T, size_t SIZE>(const etl::circular_buffer<typename T, size_t SIZE>& other);

circular_buffer<typename T, size_t SIZE>(etl::circular_buffer<typename T, size_t SIZE>&& other);

The initial_size constructor fills the buffer with default-constructed values.
The initial_size and value constructor fills the buffer with copies of value.
If initial_size exceeds SIZE, the buffer is filled to its capacity.

---

circular_buffer_ext(void* buffer, size_t max_size)

circular_buffer_ext(size_t max_size) 20.32.1

circular_buffer_ext(size_t initial_size, void* buffer, size_t max_size)

circular_buffer_ext(size_t initial_size, const_reference value, void* buffer, size_t max_size)

template <typename TIterator>
circular_buffer_ext(TIterator first, const TIterator& last, void* buffer, size_t max_size)

circular_buffer_ext(std::initializer_list<T> init, void* buffer, size_t max_size)

circular_buffer_ext(const circular_buffer_ext& other, void* buffer, size_t max_size)

The initial_size constructor fills the buffer with default-constructed values.
The initial_size and value constructor fills the buffer with copies of value.
If initial_size exceeds max_size, the buffer is filled to its capacity. The external storage must contain at least max_size + 1 elements.

Status

bool is_valid() const

Description
Returns true if the buffer has been set through the constructor or set_buffer.
For circular_buffer_ext only.
From: 20.32.1

Element access

reference operator[](size_t i)
const_reference operator[](size_t i) const

Description
Returns a reference or const reference to the indexed element. Emits an etl::circular_buffer_out_of_bounds if ETL_CHECK_INDEX_OPERATOR is defined and the index is out of range of the circular buffer. Undefined behaviour if asserts or exceptions are not enabled.

---

reference front()
const_reference front() const

Description
Returns a reference or const reference to the first element.

---

reference back()
const_reference back() const

Description
Returns a reference or const reference to the last element.

---

void fill(value_type value)

Description
Fill the current size of the buffer with value. From: 20.24.0

Iterators

iterator begin()
const_iterator begin() const
const_iterator cbegin() const

Description
Returns an iterator to the beginning of the circular_buffer.

---

iterator end()
const_iterator end() const
const_iterator cend() const

Description
Returns an iterator to the end of the circular_buffer.

---

iterator rbegin()
const_reverse_iterator rbegin() const
const_reverse_iterator crbegin() const

Description
Returns a reverse iterator to the beginning of the circular_buffer.

---

iterator rend()
const_reverse_iterator rend() const
const_reverse_iterator crend() const

Description
Returns a reverse iterator to the end of the circular_buffer.

Capacity

bool empty() const

Description
Returns true if the size of the circular_buffer is zero, otherwise false.

---

bool full() const

Description
Returns true if the size of the circular_buffer is SIZE, otherwise false.

---

size_t size() const

Description
Returns the size of the circular_buffer.

---

size_t max_size() const

Description
Returns the maximum possible size of the circular_buffer.

---

size_t capacity() const

Description
Returns the maximum possible size of the circular_buffer.

---

size_t available() const

Description
Returns the remaining available capacity in the circular_buffer.

Modifiers

void assign(iterator first, const iterator& last)
void assign(const_iterator first, const const_iterator& last)

template <typename TIterator>
void assign(TIterator first, const TIterator& last)

Description
Replaces the contents of the circular buffer with the elements in the range [first, last). If the range exceeds the capacity, only the last capacity() elements are retained. The range may refer to the circular buffer being assigned.

---

void assign(size_type n, const_reference value)

Description
Replaces the contents of the circular buffer with n copies of value. If n exceeds the capacity, the buffer is filled to its capacity. value may refer to an element in the circular buffer being assigned.

---

void set_buffer(void* buffer)

Description
Sets the associated buffer.
For circular_buffer_ext only.
From: 20.32.1

---

void push(const_reference value)
void push(rvalue_reference value)

Description
Pushes a value to the back of the circular_buffer.

---

template <typename TIterator>
void push(TIterator first, const TIterator& last)

Description
Pushes values to the back of the circular_buffer.

---

void pop()

Description
Pop a value from the front of the circular_buffer.

---

void clear()

Description
Clears the circular_buffer to a size of zero.

---

void swap(circular_buffer<T, SIZE>& other)

Description
Swaps the circular_buffer with other.

---

void swap(circular_buffer_ext<T> other)

Description
Swaps the circular_buffer_ext with other.
The internal pointers to the external buffers are swapped.

Non-member functions

operator ==

Description
true if the contents of the lists are equal, otherwise false.

---

operator !=

Description
true if the contents of the lists are not equal, otherwise false.

---

swap Swaps two circular buffers. A circular buffer with internal storage copies items, while one with an external buffer will swap pointers.