indirect_vector

A fixed capacity vector that uses indirection to access the elements.

Can be more efficient for vectors of large objects, especially when inserting, erasing or sorting.

Supplies function adaptors to allow efficient application of external algorithms.

STL equivalent: None

etl::indirect_vector<typename T, size_t SIZE>

etl::indirect_vector_ext<typename T>

Inherits from etl::iindirect_vector<T>

etl::iindirect_vector may be used as a size independent pointer or reference type for any etl::indirect_vector

instance.

____________________________________________________________________________________________________

External buffer

etl::indirect_vector_ext<typename T>

With this template, the constructor expects pointer and size parameters to the externally provided indirection lookup

vector and pool.

____________________________________________________________________________________________________

Template deduction guides

C++17 and above

template <typename... T>

etl::indirect_vector(T...)

Example

etl::indirect_vector data{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 };

Defines data as an indirect_vector of int, of length 10, containing the supplied data.

____________________________________________________________________________________________________

Member types

value_type T

size_type std::size_t

difference_type std::ptrdiff_t

reference value_type&

const_reference const value_type&

pointer value_type*

const_pointer const value_type*

indirect_iterator Iterator to the internal lookup vector

indirect_const_iterator Constant iterator to the internal lookup vector

const_pointer const value_type*

iterator Random access iterator

const_iterator Constant random access iterator

reverse_iterator std::reverse_iterator<iterator>

const_reverse_iterator std::reverse_iterator<const_iterator>

____________________________________________________________________________________________________

Iterators

Both iterator and const_iterator define indirection() member functions that return an indirect_iterator or

indirect_const_iterator to the internal lookup vector.

Access to these iterators allows an external algorithm to manipulate the indirect_vector without moving the objects

themselves, thereby vastly increasing the efficiency for vectors of large objects.

____________________________________________________________________________________________________

Function Object Adaptors

Unary and binary function object wrappers are defined to allow algorithms to manipulate the contents

of an indirect_vector using a standard function object with indirect iterators.

template <typename TUnaryFunction, typename TReturnType = void>

class unary_function_adaptor

template <typename TBinaryFunction, typename TReturnType = void>

class binary_function_adaptor

Example

Sorting without moving or copying large objects.

// The large data that we are storing in the vector.

struct Data

{

std::array<int, 1000> values;

};

// How to compare Data objects.

bool operator <(const Data& lhs, const Data& rhs)

{

return std::lexicographical_compare(lhs.begin(), lhs.end(), rhs.begin(), rhs.end());

}

// The vector of data.

using Vector = etl::indirect_vector<Data, 10>;

Vector v;

// std::less wrapped in a binary_function_adaptor.

using LessThan = typename Vector::binary_function_adaptor<std::less<Data>, bool>;

// Sort the vector without moving or copying actual Data objects.

std::sort(v.begin().indirection(),

v.end().indirection(),

LessThan());

Warning: This technique is not suitable for algorithms that may leave the container with multiple copies of an object,

such as std::remove_if. This is because the algorithm may create multiple copies of the indirection iterator, but only

one copy of the object that they point to.

____________________________________________________________________________________________________

Constructor

Internal buffer

etl::indirect_vector<typename T, const size_t SIZE>();

etl::indirect_vector<typename T, const size_t SIZE>(size_t initialSize);

etl::indirect_vector<typename T, const size_t SIZE>(size_t initialSize, const T& value);

template <typename TIterator>

etl::indirect_vector<typename T, const size_t SIZE>(TIterator begin, TIterator end);

etl::indirect_vector<typename T, const size_t SIZE>(const etl::indirect_vector<typename T, const size_t

SIZE>&);

etl::indirect_vector<typename T, const size_t SIZE>(etl::indirect_vector<typename T, const size_t

SIZE>&&);

____________________________________________________________________________________________________

External buffer

etl::indirect_vector<typename T, const size_t SIZE>(etl::ivector<T*>& lookup, etl::ipool& storage);

etl::indirect_vector<typename T, const size_t SIZE>(size_t initialSize, etl::ivector<T*>& lookup,

etl::ipool& storage);

etl::indirect_vector<typename T, const size_t SIZE>(size_t initialSize, const T& value,

etl::ivector<T*>& lookup, etl::ipool& storage);

template <typename TIterator>

etl::indirect_vector<typename T, const size_t SIZE>(TIterator begin, TIterator end, etl::ivector<T*>&

lookup, etl::ipool& storage);

etl::indirect_vector<typename T, const size_t SIZE>(const etl::indirect_vector<typename T, const size_t

SIZE>&, etl::ivector<T*>& lookup, etl::ipool& storage);

etl::indirect_vector<typename T, const size_t SIZE>(etl::indirect_vector<typename T, const size_t

SIZE>&&, etl::ivector<T*>& lookup, etl::ipool& storage);

If the vector is full then emits an etl::vector_full. If asserts or exceptions are not enabled then undefined

behaviour occurs.

____________________________________________________________________________________________________

Element access

reference at(size_t i)

const_reference at(size_t i) const

Returns a reference or const reference to the indexed element. Emits an etl::vector_out_of_range if the index is

out of range of the array. If asserts or exceptions are not enabled then undefined behaviour occurs.

____________________________________________________________________________________________________

reference operator[](size_t i)

const_reference operator[](size_t i) const

Returns a reference or const reference to the indexed element.

if the index is out of range of the array then undefined behaviour occurs.

____________________________________________________________________________________________________

reference front()

const_reference front() const

Returns a reference or const reference to the first element.

Undefined behaviour if the vector is empty.

____________________________________________________________________________________________________

reference back()

const_reference back() const

Returns a reference or const reference to the last element.

Undefined behaviour if the vector is empty.

____________________________________________________________________________________________________

Iterators

iterator begin()

const_iterator begin() const

const_iterator cbegin() const

Returns an iterator to the beginning of the vector.

____________________________________________________________________________________________________

iterator end()

const_iterator end() const

const_iterator cend() const

Returns an iterator to the end of the vector.

____________________________________________________________________________________________________

iterator rbegin()

const_reverse_iterator rbegin() const

const_reverse_iterator crbegin() const

Returns a reverse iterator to the beginning of the vector.

____________________________________________________________________________________________________

iterator rend()

const_reverse_iterator rend() const

const_reverse_iterator crend() const

Returns a reverse iterator to the end of the vector.

____________________________________________________________________________________________________

Capacity

bool empty() const

Returns true if the size of the vector is zero, otherwise false.

____________________________________________________________________________________________________

bool full() const

Returns true if the size of the vector is SIZE, otherwise false.

____________________________________________________________________________________________________

size_t size() const

Returns the size of the vector.

____________________________________________________________________________________________________

void resize(size_t new_size, T value = T())

Resizes the vector, up to the maximum capacity. Emits an etl::vector_full if the vector does not have the capacity.

____________________________________________________________________________________________________

size_t max_size() const

Returns the maximum possible size of the vector.

____________________________________________________________________________________________________

size_t capacity() const

Returns the maximum possible size of the vector.

____________________________________________________________________________________________________

size_t available() const

Returns the remaining available capacity in the vector.

____________________________________________________________________________________________________

Modifiers

template <typename TIterator>

void assign(TIterator begin, TIterator end);

void assign(size_t n, const T& value);

Fills the vector with the values. Emits etl::vector_iterator if the distance between begin and end is illegal.

(debug mode only). If asserts or exceptions are not enabled undefined behaviour occurs.

____________________________________________________________________________________________________

void push_back(const T& value);

void push_back(T&& value);

Pushes a value to the back of the vector.

If the vector is full then emits an etl::vector_full. If asserts or exceptions are not enabled undefined behaviour

occurs.

____________________________________________________________________________________________________

C++03

void emplace(); 20.38.0

void emplace(const T1& value1);

void emplace(const T1& value1, const T2& value2);

void emplace(const T1& value1, const T2& value2, const T3& value3);

void emplace(const T1& value1, const T2& value2, const T3& value3, const T4& value4);

C++11

template <typename… Args>

void emplace(Args&&… args);

Constructs an item at the back of the the vector 'in place'.

Supports up to four constructor parameters.

Pushes a value to the back of the vector. The first pushes a value, the second allocates the new element but does not

initialise it.

If the vector is full then emits an etl::vector_full. If asserts or exceptions are not enabled undefined behaviour

occurs.

____________________________________________________________________________________________________

<=20.35.9

void emplace_back(const T1& value1);

void emplace_back(const T1& value1, const T2& value2);

void emplace_back(const T1& value1, const T2& value2, const T3& value3);

void emplace_back(const T1& value1, const T2& value2, const T3& value3, const T4& value4);

>=20.35.10

reference emplace_back(); 20.38.0

reference emplace_back(const T1& value1);

reference emplace_back(const T1& value1, const T2& value2);

reference emplace_back(const T1& value1, const T2& value2, const T3& value3);

reference emplace_back(const T1& value1, const T2& value2, const T3& value3, const T4& value4);

C++11

<=20.35.9

template <typename Args...>

void emplace_back(Args&&... args);

>=20.35.10

template <typename Args...>

reference emplace_back(Args&&... args);

Constructs an item at the back of the the vector 'in place'.

Supports up to four constructor parameters.

If the vector is full then emits an etl::vector_full. If asserts or exceptions are not enabled undefined behaviour

occurs.

____________________________________________________________________________________________________

void pop_back();

Pop a value from the back of the vector.

If the vector is empty and ETL_CHECK_PUSH_POP is defined then emits an etl::vector_empty. If asserts or exceptions

are not enabled undefined behaviour occurs.

____________________________________________________________________________________________________

<=20.19.0

template <typename TIterator>

void insert(iterator position, TIterator begin, TIterator end);

iterator insert(iterator position, const T& value);

iterator insert(iterator position, T&& value);

void insert(iterator position, size_t n, const T& value);

>=20.20.0

template <typename TIterator>

void insert(const_iterator position, TIterator begin, TIterator end);

iterator insert(const_iterator position, const T& value);

iterator insert(const_iterator position, T&& value);

iterator insert(const_iterator position, size_t n, const T& value);

Inserts values in to the vector.

If the vector is full then emits an etl::vector_full exception. If asserts or exceptions are not enabled undefined

behaviour occurs.

____________________________________________________________________________________________________

template <typename TIterator>

iterator erase(TIterator begin, TIterator end);

<=20.19.0

iterator erase(iterator position);

>=20.20.0

iterator erase(iterator position);

iterator erase(const_iterator position);

Erases values in the vector.

Iterators are not checked.

____________________________________________________________________________________________________

void clear()

Clears the vector to a size of zero.

____________________________________________________________________________________________________

void sort()

Sorts the elements using the 'less than' operator.

template <typename TCompare>

void sort(TCompare compare)

Sorts the elements using the supplied compare.

void sort(iterator first, iterator last)

Sorts a range of elements using the supplied 'less than' operator.

template <typename TCompare>

void sort(iterator first, iterator last, TCompare compare)

Sorts a range of elements using the supplied compare.

____________________________________________________________________________________________________

void stable_sort()

Stable sorts the elements using the 'less than' operator.

template <typename TCompare>

void stable_sort(TCompare compare)

Stable sorts the elements using the supplied compare.

void stable_sort(iterator first, iterator last)

Stable sorts a range of elements using the supplied 'less than' operator.

template <typename TCompare>

void stable_sort(iterator first, iterator last, TCompare compare)

Stable sorts a range of elements using the supplied compare.

____________________________________________________________________________________________________

Non-member functions

== true if the contents of the vectors are equal, otherwise false.

!= true if the contents of the vectors are not equal, otherwise false.

< true if the contents of the lhs are lexicographically less than the contents of the rhs, otherwise false.

<= true if the contents of the lhs are lexicographically less than or equal to the contents of the rhs, otherwise false.

> true if the contents of the lhs are lexicographically greater than the contents of the rhs, otherwise false.

>= true if the contents of the lhs are lexicographically greater than or equal to the contents of the rhs, otherwise

false.

indirect_vector.h