A C++ template library for embedded applications
MIT licensed
Designed and
maintained by
John Wellbelove
Support the development
of the ETL
vector

A fixed capacity vector.
STL equivalent: std::vector

etl::vector<typename T, size_t SIZE>
etl::vector_ext<typename T>

Inherits from etl::ivector<T>
etl::ivector may be used as a size independent pointer or reference type for any etl::vector instance.

There is a specialisation for pointers that means that just one instantiation of code for all pointer types.
The one caveat is that etl::vector cannot directly store pointers to functions. They must be wrapped in either a
custom struct, one of the etl::function templates, or std::function.

Has the ability to be copied by low level functions such as memcpy by use of a repair() function.
See the function reference for an example of use.

The size of the instance will be (SIZE * sizeof(T)) + (2 * sizeof(size_t)) + sizeof(T*)
For a 32 bit environment the overhead (compared to an array) will usually be 12 bytes.
____________________________________________________________________________________________________
External buffer

etl::vector_ext<typename T>
With this template the constructor expects pointer and size parameters to the externally provided buffer. This buffer
must not be shared concurrently with any other vector.
When a vector with an external buffer is moved, the data is moved, not the pointer to the buffer.
____________________________________________________________________________________________________
Template deduction guides
C++17 and above

template <typename T, typename... Ts>
etl::vector(T, Ts...)
  ->etl::vector<etl::enable_if_t<(etl::is_same_v<T, Ts> && ...), T>, 1U + sizeof...(Ts)>;

template <typename T, typename... Ts>
etl::vector(T*, Ts*...)
  ->etl::vector<etl::enable_if_t<(etl::is_same_v<T, Ts> && ...), T*>, 1U + sizeof...(Ts)>;

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

Defines data as an 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&
rvalue_reference        value_type&&
pointer                 value_type*
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>
____________________________________________________________________________________________________
Constructor

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

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

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

External buffer
etl::vector<typename T, const size_t SIZE>(void* buffer, size_t max_size);
etl::vector<typename T, const size_t SIZE>(size_t initialSize, void* buffer, size_t max_size);
etl::vector<typename T, const size_t SIZE>(size_t initialSize, const T& value, void* buffer, size_t
max_size);

template <typename TIterator>
etl::vector<typename T, const size_t SIZE>(TIterator begin, TIterator end, void* buffer, size_t
max_size);

etl::vector<typename T, const size_t SIZE>(const etl::vector<typename T, const size_t SIZE>&, void*
buffer, size_t max_size);

etl::vector<typename T, const size_t SIZE>(etl::vector<typename T, const size_t SIZE>&&, void* buffer,
size_t max_size);
If the vector is full then emits an etl::vector_full. If asserts or exceptions are not enabled then undefined
behaviour occurs.
____________________________________________________________________________________________________
Element access

T& at(size_t i)
const T& 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.
____________________________________________________________________________________________________
T& operator[](size_t i)
const T& 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.
____________________________________________________________________________________________________
T& front()
const T& front() const
Returns a reference or const reference to the first element.
Undefined behaviour if the vector is empty.
____________________________________________________________________________________________________
T& back()
const T& back() const
Returns a reference or const reference to the last element.
Undefined behaviour if the vector is empty.
____________________________________________________________________________________________________
T* data()
const T* data() const
Returns a pointer or const pointer to the internal buffer.
____________________________________________________________________________________________________
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.
____________________________________________________________________________________________________
void uninitialized_resize(size_t new_size)
20.4.0
Resizes the vector, up to the maximum capacity, without initialising the new elements.
____________________________________________________________________________________________________
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(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
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.
____________________________________________________________________________________________________
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.
____________________________________________________________________________________________________
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);

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);

iterator erase(iterator position);
Erases values in the vector.
Iterators are not checked.
____________________________________________________________________________________________________
void clear()
Clears the vector to a size of zero.
____________________________________________________________________________________________________
void repair()
This function must be called if the vector has been copied via a low level method such as memcpy.
This can only be called from an etl::vector instance, unless ETL_IVECTOR_REPAIR_ENABLE is defined. Be aware that
doing so introduces a virtual function to the class.

Has no effect if the object has not been copied in this way.

NOTE:
The contained type must be trivially copyable.
Compilers that satisfy the C++11 type traits support check in platform.h will generate an assert if the type is
incompatible.

Example:
typedef etl::vector<int, 10> Data;

Data data(8, 1);

char buffer[sizeof(Data)];

memcpy(&buffer, &data, sizeof(Data));

Data& rdata(*reinterpret_cast<Data*>(buffer));

// Do not access the copied object in any way until you have called this.
rdata.repair();
____________________________________________________________________________________________________
Non-member functions
____________________________________________________________________________________________________
erase
template <typename T, typename U>
typename etl::ivector<T>::difference_type erase(etl::ivector<T>& v, const U& value)
Erases all elements that compare equal to value from the vector.

template <typename T, typename TPredicate>
typename etl::ivector<T>::difference_type erase_if(etl::ivector<T>& v, TPredicate predicate)
Erases all elements that satisfy the predicate from the vector.
____________________________________________________________________________________________________

Operators

==  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.

vector.h