Template Class CircularArray

Defined in File circular_array.hpp

Class Documentation

template<typename T, std::size_t N, CircularArrayFeatureFlags F = CircularArrayFeatureFlags::kNone> class CircularArray

An implementation of generic, non-threadsafe circular array.

Modelled after std::array. Its maximum size is fixed at compile-time. Most operations are O(1) but for a few that exhibit worse case O(N) (not considering the complexity of move-construction and move-assignment of array elements of type T). Additionally, it features optional indexing reversal (making it a LIFO rather than a FIFO data structure), optional back value extrapolation for constant read accesses, and optional rollover on write accesses (i.e. overwriting the oldest value when pushing to an array instance that is full).

Template Parameters:

T – Element type. It must be default constructible, move constructible, and move assignable.
N – Maximum size. It must be a positive integer.
F – Array feature flags, to enable optional functionality. It defaults to none.

Public Types

using value_type = T : Value type of the array.

using size_type = std::size_t: Size type of the array.

using difference_type = std::ptrdiff_t: Size difference type of the array.

using reference = value_type&: Value reference type of the array.

using const_reference = const value_type&: Constant value reference type of the array.

using pointer = value_type*: Value pointer type of the array.

using const_pointer = const value_type*: Constant value pointer type of the arra.y.

using allocator_type = void: Allocator type of the array (required in range-v3 10.0).

using iterator = IndexingIterator<CircularArray<T, N, F>>: Iterator type of the array.

using const_iterator = IndexingIterator<const CircularArray<T, N, F>>: Constant iterator type of the array.

using reverse_iterator = std::reverse_iterator<iterator>: Reverse iterator type of the array.

using const_reverse_iterator = std::reverse_iterator<const_iterator>: Constant reverse iterator type of the array.

Public Functions

CircularArray() = default

Default constructor.

Array will be functionally empty but storage will be default initialized.

template<typename Iterator, typename Sentinel, typename = std::enable_if_t<std::is_same_v<T, typename std::iterator_traits<Iterator>::value_type>>> inline CircularArray(Iterator first, Sentinel last)

Constructs array from a pair of iterators.

Functionally equivalent to repeated push_back() operations or push_front() operations in reverse if the layout reversal feature is enabled. That is, both range and array layouts match.

Parameters:

first – Iterator to the beginning of a range.
last – Sentinel for the end of a range.

Throws:

std::length_error – If the range does not fit in the array (and the rollover on write feature is not enabled).

template<std::size_t M> inline explicit CircularArray(T (&&data)[M])

Constructs array from an aggregate.

Functionally equivalent to repeated push_back() operations or push_front() operations in reverse if the layout reversal feature is enabled. That is, both aggregate and array layouts match.

Parameters:: data – Aggregate data to initialize the array with. Its size must be in the [1, N] interval.

inline constexpr iterator begin() noexcept: Returns an iterator pointing to the front of the array.

inline constexpr const_iterator begin() const noexcept: Returns a constant iterator pointing to the front of the array.

inline constexpr const_iterator cbegin() const noexcept: Returns a constant iterator pointing to the front of the array.

inline constexpr iterator end() noexcept: Returns an iterator pointing past the back of the array.

inline constexpr const_iterator end() const noexcept: Returns a constant iterator pointing past the back of the array.

inline constexpr const_iterator cend() const noexcept: Returns a constant iterator pointing past the back of the array.

inline constexpr reverse_iterator rbegin() noexcept: Returns a reverse iterator pointing to the back of the array.

inline constexpr const_reverse_iterator rbegin() const noexcept: Returns a constant reverse iterator pointing to the back of the array.

inline constexpr const_reverse_iterator crbegin() const noexcept: Returns a constant reverse iterator pointing to the back of the array.

inline constexpr reverse_iterator rend() noexcept: Returns a reverse iterator pointing past the front of the array.

inline constexpr const_reverse_iterator rend() const noexcept: Returns a constant reverse iterator pointing past the front of the array.

inline constexpr const_reverse_iterator crend() const noexcept: Returns a constant reverse iterator pointing past the front of the array.

template<bool Enabled = !(F & CircularArrayFeatureFlags::kLayoutReversal)> inline std::enable_if_t<Enabled> push_back(value_type value)

Pushes a value to the back of the array.

Only available when the layout reversal feature is not enabled.

Throws:: std::length_error – If the array is full and the rollover on write feature is not enabled.

template<bool Enabled = (F & CircularArrayFeatureFlags::kLayoutReversal)> inline std::enable_if_t<Enabled> push_front(value_type value)

Pushes a value at the front of the array.

Only available when the layout reversal feature is enabled.

Throws:: std::length_error – If the array is full and the rollover on write feature is not enabled.

template<bool Enabled = (F & CircularArrayFeatureFlags::kLayoutReversal)> inline std::enable_if_t<Enabled> pop_back() noexcept

Pops a value from the back of the array.

Only available when the layout reversal feature is enabled. Behavior is undefined when popping from the back of an empty array. No destructors are invoked on the value popped.

template<bool Enabled = !(F & CircularArrayFeatureFlags::kLayoutReversal)> inline std::enable_if_t<Enabled> pop_front() noexcept

Pops a value from the front of the array.

Only available when the layout reversal feature is not enabled. Behavior is undefined when popping from the front of an empty array. No destructors are invoked on the value popped.

inline constexpr reference back() noexcept

Returns a reference to the value at the back of the array.

Behavior is undefined when accessing the back of an empty array.

inline constexpr const_reference back() const noexcept

Returns a constant reference to the value at the back of the array.

Behavior is undefined when accessing the back of an empty array.

inline constexpr reference front() noexcept

Returns a reference to the value at the front of the array.

Behavior is undefined when accessing the front of an empty array.

inline constexpr const_reference front() const noexcept

Returns a constant reference to the value at the front of the array.

Behavior is undefined when accessing the front of an empty array.

inline constexpr reference at(size_type index)

Returns a reference to the array value at the given index.

Throws:: std::out_of_range – If index is past the array’s effective size.

inline constexpr const_reference at(size_type index) const

Returns a constant reference to the array value at the given index.

Throws:: std::out_of_range – If index is past the array effective size.

inline constexpr reference operator[](size_type index) noexcept

Returns a reference to the array value at the given index.

Behavior is undefined when index is greater than or equal to the array size.

inline constexpr const_reference operator[](size_type index) const noexcept

Returns a constant reference to the array value at the given index.

Behavior is undefined when index is greater than or equal to the array effective size.

inline void fill(const T &value)

Fills array to its maximum size with a given value.

Functionally equivalent to repeated push_back() operations or push_front() operations if the layout reversal feature is enabled until the array reaches its maximum size. Existing values are kept. Filling an array that is full is a no-op.

inline void clear() noexcept

Clears array.

No value destructors are invoked.

template<CircularArrayFeatureFlags G> inline void swap(CircularArray<T, N, G> &other) noexcept(std::is_nothrow_swappable_v<T>)

Swaps array with another.

Arrays being swapped may not necessarily have the same features enabled. This is most relevant when arrays differ in layout direction, as swapping two such arrays effectively reverses their elements.

inline constexpr T *data() noexcept

Returns a pointer to the underlying array data.

Note that a circular array does not feature a contiguous layout in memory. Indices and distances between them for the array do not map to its data.

inline constexpr const T *data() const noexcept

Returns a constant pointer to the underlying array data.

Note that a circular array does not feature a contiguous layout in memory. Indices and distances between them for the array do not map to its data.

inline constexpr bool full() const noexcept: Returns true if the array is full, false otherwise.

inline constexpr bool empty() const noexcept: Returns true if the array is empty, false otherwise.

inline constexpr size_type size() const noexcept: Returns the current array size.

inline constexpr size_type max_size() const noexcept: Returns the maximum array size.

inline constexpr size_type effective_size() const noexcept

Returns the effective array size.

Nominally, the effective array size is equal to the array size. If the last value extrapolation feature is enabled, however, the effective array size can only be 0 or N, when the array is empty and when the array is non-empty respectively.

Friends

friend class CircularArray