ringBuffer.h
Go to the documentation of this file.
/*
Copyright (c) 2026 - SD-Innovation S.A.S. - FRANCE
*/
/*
ver: 2.x.x - build: 2026-04-28
*/
/*
The zlib License Copyright (c) 2026 SD-Innovation S.A.S. This software is provided ‘as-is’, without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software. Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions: 1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required. 2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software. 3. This notice may not be removed or altered from any source distribution.
*/
#pragma once
#include <array>
#include <cstddef>
#include <optional>
namespace sdi_toolBox::common::utils
{
//--------------------------------------------------------------
template<class T, std::size_t CAPACITY>
class RingBuffer
{
static_assert(CAPACITY > 0, "CAPACITY must be > 0");
public:
bool push(const T &value);
std::optional<T> pop();
bool pop(T &value);
[[nodiscard]] std::optional<T> front() const;
[[nodiscard]] bool front(T &value) const;
[[nodiscard]] std::optional<T> back() const;
[[nodiscard]] bool back(T &value) const;
[[nodiscard]] bool empty() const;
[[nodiscard]] bool full() const;
[[nodiscard]] std::size_t size() const;
[[nodiscard]] constexpr std::size_t capacity() const;
void clear();
private:
[[nodiscard]] std::size_t next(std::size_t index) const;
std::array<T, CAPACITY> m_data{};
std::size_t m_head{ 0 };
std::size_t m_tail{ 0 };
bool m_full{ false };
};
//--------------------------------------------------------------
//--------------------------------------------------------------
/* Append a value to the buffer. If the buffer is full, the
* oldest value will be overwritten. Return true if the value
* was added without overwriting, false if an overwrite occurred. */
template<class T, std::size_t CAPACITY>
bool RingBuffer<T, CAPACITY>::push(const T &value)
{
m_data[m_head] = value;
m_head = next(m_head);
if (m_full)
{
m_tail = m_head; // overwrite the oldest value
return false; // indicate that an overwrite occurred
}
else
{
m_full = (m_head == m_tail);
return true; // indicate that the value was added without overwriting
}
}
//--------------------------------------------------------------
/* Remove and return the oldest value from the buffer. If the
* buffer is empty, return std::nullopt */
template<class T, std::size_t CAPACITY>
std::optional<T> RingBuffer<T, CAPACITY>::pop()
{
if (empty())
return std::nullopt;
const std::optional<T> result = m_data[m_tail];
m_tail = next(m_tail);
m_full = false;
return result;
}
//--------------------------------------------------------------
/* Remove the oldest value from the buffer and store it in
* 'value'. Return true if successful, false if the buffer is empty */
template<class T, std::size_t CAPACITY>
bool RingBuffer<T, CAPACITY>::pop(T &value)
{
if (empty())
return false;
value = m_data[m_tail];
m_tail = next(m_tail);
m_full = false;
return true;
}
//--------------------------------------------------------------
/* Return the oldest value without removing it. If the buffer is
* empty, return std::nullopt */
template<class T, std::size_t CAPACITY>
std::optional<T> RingBuffer<T, CAPACITY>::front() const
{
if (empty())
return std::nullopt;
return m_data[m_tail];
}
//--------------------------------------------------------------
/* Return the oldest value without removing it and store it in
* 'value'. Return true if successful, false if the buffer is empty */
template<class T, std::size_t CAPACITY>
bool RingBuffer<T, CAPACITY>::front(T &value) const
{
if (empty())
return false;
value = m_data[m_tail];
return true;
}
//--------------------------------------------------------------
/* Return the newest value without removing it. If the buffer is
* empty, return std::nullopt */
template<class T, std::size_t CAPACITY>
std::optional<T> RingBuffer<T, CAPACITY>::back() const
{
if (empty())
return std::nullopt;
return m_data[(m_head == 0) ? CAPACITY - 1 : m_head - 1];
}
//--------------------------------------------------------------
/* Return the newest value without removing it and store it in
* 'value'. Return true if successful, false if the buffer is empty */
template<class T, std::size_t CAPACITY>
bool RingBuffer<T, CAPACITY>::back(T &value) const
{
if (empty())
return false;
std::size_t backIndex = (m_head == 0) ? CAPACITY - 1 : m_head - 1;
value = m_data[backIndex];
return true;
}
//--------------------------------------------------------------
/* Check if the buffer is empty */
template<class T, std::size_t CAPACITY>
bool RingBuffer<T, CAPACITY>::empty() const
{
return !m_full && (m_head == m_tail);
}
//--------------------------------------------------------------
/* Check if the buffer is full */
template<class T, std::size_t CAPACITY>
bool RingBuffer<T, CAPACITY>::full() const
{
return m_full;
}
//--------------------------------------------------------------
/* Get the number of elements currently in the buffer */
template<class T, std::size_t CAPACITY>
std::size_t RingBuffer<T, CAPACITY>::size() const
{
if (m_full)
return CAPACITY;
if (m_head >= m_tail)
return m_head - m_tail;
return CAPACITY - (m_tail - m_head);
}
//--------------------------------------------------------------
/* Get the maximum capacity of the buffer */
template<class T, std::size_t CAPACITY>
[[nodiscard]] constexpr std::size_t RingBuffer<T, CAPACITY>::capacity() const
{
return CAPACITY;
}
//--------------------------------------------------------------
/* Clear the buffer, resetting it to an empty state */
template<class T, std::size_t CAPACITY>
void RingBuffer<T, CAPACITY>::clear()
{
m_head = 0;
m_tail = 0;
m_full = false;
}
//--------------------------------------------------------------
/* Helper function to calculate the next index in a circular manner */
template<class T, std::size_t CAPACITY>
std::size_t RingBuffer<T, CAPACITY>::next(const std::size_t index) const
{
// Calculate the next index in a circular manner without using
// modulus operator for better performance
const auto nextIndex = index + 1;
if (nextIndex == CAPACITY)
return 0;
return nextIndex;
}
//--------------------------------------------------------------
} // namespace sdi_toolBox::common::utils
sdi_toolBox::common::utils::RingBuffer
Fixed-size ring (circular) buffer with compile-time capacity and overwrite-on-full behavior.
Definition ringBuffer.h:50
sdi_toolBox::common::utils::RingBuffer::front
std::optional< T > front() const
Return (without removing) the oldest element.
Definition ringBuffer.h:243
sdi_toolBox::common::utils::RingBuffer::push
bool push(const T &value)
Append a value to the buffer.
Definition ringBuffer.h:196
sdi_toolBox::common::utils::RingBuffer::pop
std::optional< T > pop()
Remove and return the oldest element from the buffer.
Definition ringBuffer.h:216
sdi_toolBox::common::utils::RingBuffer::empty
bool empty() const
Check whether the buffer is empty.
Definition ringBuffer.h:285
sdi_toolBox::common::utils::RingBuffer::full
bool full() const
Check whether the buffer is full.
Definition ringBuffer.h:292
sdi_toolBox::common::utils::RingBuffer::back
std::optional< T > back() const
Return (without removing) the newest element.
Definition ringBuffer.h:264
sdi_toolBox::common::utils::RingBuffer::clear
void clear()
Clear the buffer and reset internal indices.
Definition ringBuffer.h:317
sdi_toolBox::common::utils::RingBuffer::size
std::size_t size() const
Number of elements currently stored in the buffer.
Definition ringBuffer.h:299
sdi_toolBox::common::utils::RingBuffer::capacity
constexpr std::size_t capacity() const
Compile-time capacity of the buffer.
Definition ringBuffer.h:310
sdi_toolBox::common::utils
General-purpose utility functions shared across all sdi_toolBox modules.
Definition circularBuffer.h:18