Containers

Bounded Vector

The bounded vector is a container structure that tries to combine the advantages of arrays and vectors. It can be used if the maximum size is known at compile time. It combines the efficiency of arrays (e.g. locality) with the syntax of vectors (e.g. push_back).

Quaternion Cache

This container can be used to store direction-dependent data. To store the data efficiently, the directions are discretized. Hector_math implements three modes: Spherical, Largest dim and Spherical Fibonacci. The level of discretization, how many bins there, are can selected as well as the discretization mode. The modes have different advantages and disadvantages:

Discretization Mode Comparison
Mode	Speed	Evenly Discretization
Spherical	🟡	❌
Largest Dimension	✅	🟡
Spherical Fibonacci	❌	✅

It is impossible to achieve perfect evenly discretization for arbitrary many bins. The spherical fibonacci mode achieves the best discretization. The spherical mode is differently distributed near the poles and the equator while the largest dim mode doesn’t have a reduced resolution at the poles but at the cost of overlapping regions with increased bin resolution.

For more details, see Quaternion Binning.

Ring Buffer

The Ring Buffer is a container with a limited size which is controlled with the template argument MaxSize. If the Ring Buffer is full, adding new elements will overwrite the oldest elements! It can be used as a FIFO data structure. The oldest element can be easily retrieved while adding new elements will append them to the container. The container keeps track of which element is the oldest and the newest without ever moving any elements. Additionally, the container support any algorithm that work with forward iterators, like std::for_each() and of course range loops.

API

Bounded Vector

template<typename T, int MaxSize> class BoundedVector

Public Types

using iterator = typename std::array<T, MaxSize>::iterator

using const_iterator = typename std::array<T, MaxSize>::const_iterator

Public Functions

inline std::size_t size() const

inline void push_back(T val)

template<typename ...Args> inline void emplace_back(Args... args)

inline void pop_back()

inline void erase(const_iterator position)

inline void erase(const_iterator first, const_iterator last)

inline void clear()

inline T &front()

inline const T &front() const

inline T &back()

inline const T &back() const

inline iterator begin()

inline const_iterator begin() const

inline iterator end()

inline const_iterator end() const

inline T &operator[](std::size_t index)

inline const T &operator[](std::size_t index) const

inline T *data()

inline const T *data() const

inline void reserve(std::size_t size)

Private Members

std::array<T, MaxSize> items_

std::size_t size_ = 0

Quaternion Cache

template<typename Scalar, typename T, QuaternionBinningMode MODE = quaternion_binning_modes::LargestDim, int AXIS_BINS = 128, int ANGLE_COUNT = 512> class QuaternionCache

Public Types

using iterator = typename std::unordered_map<BinType, T>::iterator

using const_iterator = typename std::unordered_map<BinType, T>::const_iterator

Public Functions

inline std::pair<iterator, bool> insert(const Eigen::Quaternion<Scalar> &q, const T &val) noexcept

inline iterator find(const Eigen::Quaternion<Scalar> &q) noexcept

inline const_iterator find(const Eigen::Quaternion<Scalar> &q) const noexcept

inline iterator begin() noexcept

inline const_iterator begin() const noexcept

inline const_iterator cbegin() const noexcept

inline iterator end() noexcept

inline const_iterator end() const noexcept

inline const_iterator cend() const noexcept

inline void clear() noexcept

Public Static Functions

static inline BinType computeBin(const Eigen::Quaternion<Scalar> &q) noexcept

Private Types

using BinType = typename detail::QuaternionBinType<AXIS_BINS, ANGLE_COUNT>::BinType

Private Members

std::unordered_map<BinType, T> cache_

Ring Buffer

template<typename T, std::size_t N> class RingBuffer

A RingBuffer is a limited size storage container that once full will overwrite the oldest elements when a new element is added.

Template Parameters:

T – The type of the elements stored in this RingBuffer.
Nm – The maximum number of elements stored in the RingBuffer at any time.

Public Types

using value_type = T 

using pointer = value_type*

using const_pointer = const value_type*

using reference = value_type&

using const_reference = const value_type&

using size_type = std::size_t

using difference_type = std::ptrdiff_t

using iterator = ring_iterator<pointer>

using const_iterator = ring_iterator<const_pointer>

Public Functions

inline constexpr bool empty() const

Returns:: true if the container is empty, false otherwise

inline bool full() const

Returns:: true if the container is full, false otherwise. Appending to a full container will overwrite old elements.

inline constexpr std::size_t size() const

Returns:: the number of elements

inline constexpr std::size_t capacity() const

Returns:: the maximum number of elements which is equal to the template parameter TSize.

inline constexpr std::size_t max_size() const

Returns:: the maximum number of elements which is equal to the template parameter TSize.

inline void push_back(const_reference value)

Adds an element to the end of the RingBuffer. If the RingBuffer is full the oldest element will be overwritten.

Parameters:: value – element to be appended.

inline void pop_front(): Deletes the oldest element in the RingBuffer.

inline value_type read_and_pop_front()

Reads and deletes the oldest element of the RingBuffer.

Returns:: the oldest not yet overwritten element from The RingBuffer.

template<typename ...Args> inline void emplace_back(Args&&... args)

Constructs an element and appends it to the RingBuffer. If the RingBuffer is already full, the oldest element is overwritten.

Parameters:: args – The arguments that are passed to the constructor of the element.

inline iterator begin() noexcept

Returns:: an iterator pointing to the oldest element in the ringbuffer.

inline iterator end() noexcept

Returns:: an iterator pointing to the position after the newest element in the ringbuffer.

inline const_iterator cbegin() noexcept

Returns:: a const iterator pointing to the oldest element in the ringbuffer.

inline const_iterator cend() noexcept

Returns:: a const iterator pointing to the position after the newest element in the ringbuffer.

inline reference front()

Returns:: a reference to the oldest element in the buffer.

inline const_reference front() const

Returns:: a const reference to the oldest element in the buffer.

inline reference back()

Returns:: a reference to the newest element in the buffer.

inline const_reference back() const

Returns:: a const reference to the newest element in the buffer.

inline void clear(): Clears the contents of the RingBuffer.

inline const_reference operator[](std::size_t index) const

inline reference operator[](std::size_t index)

Public Static Attributes

static constexpr std::size_t Size = N 

Private Functions

inline std::size_t get_normalised_index(std::size_t index) const

inline void added_element_tail_adapt_indices()

inline void removed_element_at_head_adapt_indices()

inline std::size_t get_head_index() const: The index of the oldest element.

inline std::size_t get_last_index() const

Private Members

std::array<value_type, Size> items_

std::size_t size_ = 0

std::size_t tail_index_ = 0

template<typename Iterator> struct ring_iterator

Public Types

using iterator_type = Iterator 

using iterator_category = std::random_access_iterator_tag

using value_type = typename _traits::value_type

using difference_type = typename _traits::difference_type

using reference = typename _traits::reference

using pointer = typename _traits::pointer

Public Functions

inline ring_iterator(RingBuffer<T, N> *buffer, int offset, int index = 0) noexcept

inline reference operator*() const noexcept

inline pointer operator->() const noexcept

inline ring_iterator<Iterator> &operator++() noexcept

inline ring_iterator<Iterator> operator++(int) & noexcept

inline ring_iterator<Iterator> &operator+=(int nums) noexcept

inline ring_iterator<Iterator> &operator--() noexcept

inline ring_iterator<Iterator> operator--(int) & noexcept

inline ring_iterator<Iterator> &operator-=(int nums) noexcept

inline difference_type operator-(const ring_iterator<Iterator> &other) const noexcept

inline ring_iterator<Iterator> operator+(difference_type nums) const noexcept

inline ring_iterator<Iterator> operator-(difference_type nums) const noexcept

inline operator RingBuffer<T, N>::const_iterator() const noexcept

template<typename IteratorR> inline bool operator==(const ring_iterator<IteratorR> &other) const noexcept

template<typename IteratorR> inline bool operator!=(const ring_iterator<IteratorR> &other) const noexcept

Private Types

using _traits = std::iterator_traits<Iterator>

Private Members

RingBuffer<T, N> *buffer_

int offset_

int iterator_index_

int buffer_index_