CircularBuffer< T, CAPACITY > Class Template Reference

`#include <circularBuffer.h>`

## Detailed Description

template<class T, std::size_t CAPACITY>
class sdi_toolBox::common::utils::CircularBuffer< T, CAPACITY >

Fixed-size circular buffer with compile-time capacity and no-overwrite behavior.

This template wraps a RingBuffer and prevents new elements from being written when the buffer is full. Existing data is never overwritten; push() simply fails and returns false when capacity is reached.

Template Parameters

  T | Element type stored in the buffer.
  CAPACITY | Compile-time buffer capacity. Must be > 0.

Note
  The class provides both optional-returning and out-parameter overloads for pop/front/back to suit different runtime constraints.

Warning
  Instantiating with CAPACITY == 0 is forbidden (static_assert).

CircularBuffer<int, 8> cb;
if (cb.push(42))
{
// element was inserted
}
else
{
// buffer was full, element was discarded
}
sdi_toolBox::common::utils::CircularBuffer
Fixed-size circular buffer with compile-time capacity and no-overwrite behavior.
Definition circularBuffer.h:49
sdi_toolBox::common::utils::CircularBuffer::push
bool push(const T &value)
Try to append a value to the buffer.
Definition circularBuffer.h:178

Definition at line 48 of file circularBuffer.h.

## Public Member Functions

Write operations
bool | push (const T &value)
| Try to append a value to the buffer.
Read operations
std::optional< T > | pop ()
| Remove and return the oldest element from the buffer.
bool | pop (T &value)
| Remove the oldest element and store it in the provided reference.
std::optional< T > | front () const
| Return (without removing) the oldest element.
bool | front (T &value) const
| Copy the oldest element into the provided reference without removing it.
std::optional< T > | back () const
| Return (without removing) the newest element.
bool | back (T &value) const
| Copy the newest element into the provided reference without removing it.
State queries
bool | empty () const
| Check whether the buffer is empty.
bool | full () const
| Check whether the buffer is full.
std::size_t | size () const
| Number of elements currently stored in the buffer.
constexpr std::size_t | capacity () const
| Compile-time capacity of the buffer.
Modifiers
void | clear ()
| Clear the buffer and reset internal indices.

## Member Function Documentation

## push()

template<class T , std::size_t CAPACITY>

bool push | ( | const T & | value | ) |

Try to append a value to the buffer.

If the buffer is full, the value is discarded and no overwrite occurs.

Parameters

  value | Value to append (copied).

Returns
  true if the value was inserted, false if the buffer was full.

Definition at line 178 of file circularBuffer.h.

## pop() [1/2]

template<class T , std::size_t CAPACITY>

std::optional< T > pop | ( |  | ) |

Remove and return the oldest element from the buffer.

Returns
  std::optional<T> The oldest element if present, std::nullopt if empty.

Definition at line 188 of file circularBuffer.h.

## pop() [2/2]

template<class T , std::size_t CAPACITY>

bool pop | ( | T & | value | ) |

Remove the oldest element and store it in the provided reference.

Parameters

  value | Output reference that receives the removed element.

Returns
  true if an element was removed, false if the buffer was empty.

Definition at line 196 of file circularBuffer.h.

## front() [1/2]

template<class T , std::size_t CAPACITY>

std::optional< T > front | ( |  | ) | const

Return (without removing) the oldest element.

Returns
  std::optional<T> The oldest element if present, std::nullopt if empty.

Definition at line 204 of file circularBuffer.h.

## front() [2/2]

template<class T , std::size_t CAPACITY>

bool front | ( | T & | value | ) | const

Copy the oldest element into the provided reference without removing it.

Parameters

  value | Output reference that receives the element.

Returns
  true if the element was copied, false if the buffer is empty.

Definition at line 212 of file circularBuffer.h.

## back() [1/2]

template<class T , std::size_t CAPACITY>

std::optional< T > back | ( |  | ) | const

Return (without removing) the newest element.

Returns
  std::optional<T> The newest element if present, std::nullopt if empty.

Definition at line 220 of file circularBuffer.h.

## back() [2/2]

template<class T , std::size_t CAPACITY>

bool back | ( | T & | value | ) | const

Copy the newest element into the provided reference without removing it.

Parameters

  value | Output reference that receives the element.

Returns
  true if the element was copied, false if the buffer is empty.

Definition at line 228 of file circularBuffer.h.

## empty()

template<class T , std::size_t CAPACITY>

bool empty | ( |  | ) | const

Check whether the buffer is empty.

Returns
  true if empty, false otherwise.

Definition at line 235 of file circularBuffer.h.

## full()

template<class T , std::size_t CAPACITY>

bool full | ( |  | ) | const

Check whether the buffer is full.

Returns
  true if full, false otherwise.

Definition at line 242 of file circularBuffer.h.

## size()

template<class T , std::size_t CAPACITY>

std::size_t size | ( |  | ) | const

Number of elements currently stored in the buffer.

Returns
  Current size (0 .. CAPACITY).

Definition at line 249 of file circularBuffer.h.

## capacity()

template<class T , std::size_t CAPACITY>

constexpr std::size_t capacity | ( |  | ) | const

constexpr

Compile-time capacity of the buffer.

Returns
  The maximum number of elements the buffer can hold.

Definition at line 256 of file circularBuffer.h.

## clear()

template<class T , std::size_t CAPACITY>

void clear | ( |  | ) |

Clear the buffer and reset internal indices.

After calling clear(), empty() returns true and size() returns 0.

Definition at line 263 of file circularBuffer.h.