cxx-ring-buffer/README.md

# cxx-ring-buffer

a small header-only implementation of a C++ ring-buffer container wrapper and
STL-style iterators.

## Overview

This project provides the following types:

- the template `basic_ring_buffer<ContainerType>`, defined in `<ring-buffer.h>`  
  augments an existing container to be used as a ring buffer
- the alias template `ring_buffer<ValueType, Size>`, defined in `<ring-buffer.h>`  
  an alias for `basic_ring_buffer<std::array<ValueType, Size>>`
- the template `ring_buffer_iterator<ContainerType>`, defined in `<ring-buffer-iterator.h>`  
  a random access iterator over a `basic_ring_buffer` with the same container type
- the template `ring_buffer_const_iterator<ContainerType>`, defined in `<ring-buffer-iterator.h>`  
  a random access iterator over a `basic_ring_buffer` with the same container type,
  giving `const` access to the elements

This project can be configured via CMake options or preprocessor defines

## CMake options

- `RING_BUFFER_DEFAULT_CXXFLAGS` (default OFF)  
  set the C++ compiler flags to `-Wall -Wextra`, and try to detect the newest supported C++ standard.
- `RING_BUFFER_BUILD_TESTS` (default OFF)  
  build the test programs from the `test/` subdirectory
- `RING_BUFFER_FEATURE_DETECT` (default ON)  
  try to detect the values for the following feature options automatically
- `RING_BUFFER_NOEXCEPT` (default OFF)  
  enable use of the `noexcept(bool-expr)` conditional noexcept operator (needs C++11)
- `RING_BUFFER_CONSTEXPR` (default OFF)  
  make all member functions of `basic_ring_buffer` and its iterators `constexpr` (needs C++14)
- `RING_BUFFER_CONSTEXPR_DESTRUCTORS` (default OFF)  
  make the destructors of `basic_ring_buffer` and its iterators explicitly `constexpr` (needs C++20)

The last 3 options set preprocessor defines with the same name when enabled,
and may be automatically enabled when `RING_BUFFER_FEATURE_DETECT` is enabled.

## Preprocessor defines

- `RING_BUFFER_NOEXCEPT`  
  enable use of the `noexcept(bool-expr)` conditional noexcept operator (needs C++11)
- `RING_BUFFER_CONSTEXPR`  
  make all member functions of `basic_ring_buffer` and its iterators `constexpr` (needs C++14)
- `RING_BUFFER_CONSTEXPR_DESTRUCTORS`  
  make the destructors of `basic_ring_buffer` and its iterators explicitly `constexpr` (needs C++20)

## Documentation

All member functions and constructors of the following types are `constexpr` if
the `RING_BUFFER_CONSTEXPR` feature is enabled.

All member functions and constructors of the following types are `noexcept` or
conditionally `noexcept` if the `RING_BUFFER_NOEXCEPT` feature is enabled.

Destructors of the following types are explicitly marked as `constexpr` if the
`RING_BUFFER_CONSTEXPR_DESTRUCTORS` feature is enabled.

### `class ring_buffer<T, N>`
(defined in `<ring-buffer.h>`)

`ring_buffer` is an alias template resolving to
`basic_ring_buffer<std::array<T, N>>`.

### `class basic_ring_buffer<Container>`
(defined in `<ring-buffer.h>`)

`basic_ring_buffer` is a template class wrapping a container, providing a
`push_back(value)` method that treats the container as a ring buffer, and an
STL-style iterator interface to iterate over the wrapped container.

Use of the `push_back(value)` method replaces the oldest element in the
underlying container, and moves the logical first element one further. (i.e.,
the logical first element is always the oldest element in the underlying
container).

The iterators returned by `begin()`, `end()`, `begin() const`, `end() const`,
`cbegin() const`, and `cend() const` start at the logical first element and end
after the logical last element. (i.e., they wrap around if they reach the end of
the underlying container)

`basic_ring_buffer` fulfills its own template parameter requirements.

#### Template parameter requirements

The parameter `Container` needs to have member types `value_type` and
`size_type`, and methods `size_type size() const`, `iterator begin()`,
`iterator end()`, `const_iterator cbegin() const`, and `const_iterator cend()
const`, as well as an overloaded `value_type& operator[](size_type)` and `const
value_type& operator[](size_type) const)`.

The iterators returned by the container need to be random access iterators.

#### Member Types

- `value_type`:  
    the `value_type` of the underlying container, as well as the `value_type` of
    the provided iterators.
- `size_type`:  
    the `size_type` of the underlying container.
- `iterator`:  
    the type of iterators returned by `begin()` and `end()`:
    `ring_buffer_iterator<Container>`.
- `const_iterator`:  
    the type of iterators returned by `begin() const`, `end() const`, `cbegin()
    const`, and `cend() const`: `ring_buffer_const_iterator<Container>`.

#### Constructors

- `basic_ring_buffer()`:  
    default constructs the wrapped container and value-initializes the internal
    `front_index` variable of `size_type`.
- `basic_ring_buffer(const Container&)`:  
    copy-constructs the container and value-initializes the internal
    `front_index` variable of `size_type`.
- `basic_ring_buffer(Container&&)`:  
    move-constructs the container and value-initializes the internal
    `front_index` variable of `size_type`.
- `basic_ring_buffer(const basic_ring_buffer&)`:  
    copy-constructs a `basic_ring_buffer` from another instance with the same
    container type.
- `basic_ring_buffer(const basic_ring_buffer&&)`:  
    move-constructs a `basic_ring_buffer` from another instance with the same
    container type.

#### Operators

- `basic_ring_buffer& operator=(const basic_ring_buffer&)`:  
    copy-assigns a `basic_ring_buffer` with the same container type to this
    instance.
- `basic_ring_buffer& operator=(const basic_ring_buffer&&)`:  
    move-assigns a `basic_ring_buffer` with the same container type to this
    instance.

#### Methods

- `Container& buffer()`:  
    returns a reference to the underlying buffer
- `const Container& buffer() const`:  
    returns a const reference to the underlying buffer
- `void push_back(const value_type& value)`:  
    inserts a new element into the buffer, replacing the least-recently inserted
    element. This operation will appear to remove the first element and insert
    a new element in the back when using a `ring_buffer_iterator`.  
    e.g., if the container has length 6, with elements 'a', 'b', 'c', 'd', 'e',
    'f', and `push_back('g')` is called, the elements will be 'g', 'b', 'c',
    'd', e', 'f', and a future call to `begin()` will return an iterator to 'b'.
- `iterator begin()`:  
    returns a `ring_buffer_iterator` to the logical first element of the
    container.  
    e.g., if the container has length 6, with elements 'a', 'b', 'c', 'd', 'e',
    'f', and `push_back('g')` was called, the elements will be 'g', 'b', 'c',
    'd', e', 'f', and a call to `begin()` will return an iterator to 'b'.
- `iterator end()`:  
    returns a `ring_buffer_iterator` to the logical one-after-last element of
    the container so that itertion stops after the logical last element of the
    container.
- `const_iterator begin() const`:  
    returns a `ring_buffer_const_iterator` to the logical first element of the
    container.
- `const_iterator end() const`:  
    returns a `ring_buffer_const_iterator` to the logical one-after-last element
    of the container.
- `const_iterator cbegin() const`:  
    returns a `ring_buffer_const_iterator` to the logical first element of the
    container.
- `const_iterator cend() const`:  
    returns a `ring_buffer_const_iterator` to the logical one-after-last element
    of the container.

### `class ring_buffer_iterator<Container>`
(defined in `<ring-buffer-iterator.h>`)

`ring_buffer_iterator` is a template class providing an iterator usable for
iterating over a container in a ring-buffer-like fashion, i.e., start at an
index other than 0, and wrap around when the end of the container is reached.

`ring_buffer_iterator` is a random access iterator and fulfills the
requirements of the C++ named requirement
[LegacyRandomAccessIterator][lra-iter].

#### Template parameter requirements

The parameter `Container` needs to fulfill the same requirements as for
`basic_ring_buffer`.

### `class ring_buffer_const_iterator<Container>`
(defined in `<ring-buffer-iterator.h>`)

`ring_buffer_const_iterator` is a template class providing an iterator usable
for iterating over a container in a ring-buffer-like fashion, i.e., start at an
index other than 0, and wrap around when the end of the container is reached.

`ring_buffer_const_iterator` is a random access iterator and fulfills the
requirements of the C++ named requirement
[LegacyRandomAccessIterator][lra-iter].

#### Template parameter requirements

The parameter `Container` needs to fulfill the same requirements as for
`basic_ring_buffer`.

[lra-iter]: https://en.cppreference.com/w/cpp/named_req/RandomAccessIterator