A C++ template library for embedded applications
Designed and maintained by
Aster Consulting Ltd
Join the ETL community

list


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

etl::list<typename T, const size_t SIZE>

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

Note: Does not support the member function swap
____________________________________________________________________________________________________

Shared Pools


If the list is given a size of zero then it may share pools with another etl::list of the same type.
The list is initialised with the pool either at construction time or a call to set_pool(etl::ipool& pool)
When pools are shared there are a few side effects that must be noted.

size() and empty() will be O(N) complexity. For a normal etl::list they are O(1)

Destruction of the container will always be O(N) regardless of whether the type store is trivially destructible or not.

max_size() will return the potential maximum size of the list. The actual maximum size will dependent of how many
elements the other lists sharing the pool have allocated.

Pool must be declared with the list's pool_type.
i.e.
// The element type
struct Point { int x; int y; };

// The list type
typedef etl::list<Point, 0> List;

// The shared pool
etl::pool<List::pool_type, 10> pool;
____________________________________________________________________________________________________

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*
iterator                Bi-directional iterator
const_iterator          Constant bi-directional iterator
reverse_iterator        std::reverse_iterator<iterator>
const_reverse_iterator  std::reverse_iterator<const_iterator>

____________________________________________________________________________________________________

Constructor


etl::list<typename T, const size_t SIZE>();
etl::list<typename T, const size_t SIZE>(size_t initialSize, parameter_t value = T());

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

Emits an etl::list_iterator if the iterators are invalid. If asserts or exceptions are disabled then undefined behaviour
occurs.
____________________________________________________________________________________________________

For shared pool lists

etl::list<typename T, const size_t SIZE>(etl::pool& pool);
etl::list<typename T, const size_t SIZE>(size_t initialSize, parameter_t value, etl::pool& pool);
template <typename TIterator>
etl::list<typename T, const size_t SIZE>(TIterator begin, TIterator end, etl::pool& pool);

Emits an etl::list_iterator if the iterators are invalid. If asserts or exceptions are disabled then undefined behaviour
occurs.
____________________________________________________________________________________________________

Initialisation


if the list is sharing pools then a set_pool(etl::pool&) is available.
If a pool has already been set then the list is first cleared before updating to the new pool.
____________________________________________________________________________________________________

Element access


T& front()
const T& front() const

Returns a reference or const reference to the first element.
Undefined behaviour if the list is empty.
____________________________________________________________________________________________________

T& back()
const T& back() const

Returns a reference or const reference to the last element.
Undefined behaviour if the list is empty.
____________________________________________________________________________________________________

Iterators


iterator begin()
const_iterator begin() const
const_iterator cbegin() const

Returns an iterator to the beginning of the list.
____________________________________________________________________________________________________

iterator end()
const_iterator end() const
const_iterator cend() const

Returns an iterator to the end of the list.
____________________________________________________________________________________________________

reverse_iterator rbegin()
const_reverse_iterator rbegin() const
const_reverse_iterator crbegin() const

Returns a reverse iterator to the beginning of the list.
____________________________________________________________________________________________________

reverse_iterator rend()
const_reverse_iterator rend() const
const_reverse_iterator crend() const

Returns a reverse iterator to the end of the list.
____________________________________________________________________________________________________

Capacity


bool empty() const

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

bool full() const

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

size_t size() const

Returns the size of the list.
____________________________________________________________________________________________________

size_t available() const

Returns the remaining available capacity in the list.
____________________________________________________________________________________________________

size_t max_size() const

Returns the maximum possible size of the list .
____________________________________________________________________________________________________

Modifiers


template <typename TIterator>
void assign(TIterator begin, TIterator end);

void assign(size_t n, parameter_t value);

Fills the list with the values.
____________________________________________________________________________________________________

void push_front(parameter_t value);
void push_front();

Pushes a value to the front of the list. The first pushes a value, the second allocates the new element but does not
initialise it. If the list is full then emits an etl::list_full error.
____________________________________________________________________________________________________

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

Constructs an item at the front of the the list 'in place'.
Supports up to four constructor parameters.
____________________________________________________________________________________________________

void push_back(parameter_t value);

Pushes a value to the back of the list.
If the list is full and ETL_CHECK_PUSH_POP is defined then emits an etl::list_full error, otherwise undefined
behaviour occurs.
____________________________________________________________________________________________________

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

Constructs an item at the back of the the list 'in place'.
Supports up to four constructor parameters.
If the list is full and ETL_CHECK_PUSH_POP is defined then emits an etl::list_full error, otherwise undefined
behaviour occurs.
____________________________________________________________________________________________________

void pop_front();

Pop a value from the front of the list.
If the list is empty and ETL_CHECK_PUSH_POP is defined then emits an etl::list_empty error, otherwise undefined
behaviour occurs.
____________________________________________________________________________________________________

void pop_back();

Pop a value from the back of the list.
If the list is empty and ETL_CHECK_PUSH_POP is defined then emits an etl::list_empty error, otherwise undefined
behaviour occurs.
____________________________________________________________________________________________________

template <typename TIterator>
void insert(iterator position, TIterator begin, TIterator end);

iterator insert(iterator position, parameter_t value);
void insert(iterator position, size_t n, parameter_t value);

Inserts values in to the list. If the list is full then emits an etl::list_full error.
____________________________________________________________________________________________________

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

Constructs an item at the insert point in the the list 'in place'.
Supports up to four constructor parameters.
____________________________________________________________________________________________________

template <typename TIterator>
iterator erase(TIterator begin, TIterator end);

iterator erase(iterator position);

Erases values in the list.
____________________________________________________________________________________________________

void resize(size_t n);
void resize(size_t n, parameter_t value);

Resizes the list. If the new size is larger then the first assigns default constructed values, the second assigns the
supplied value.
If n is larger than the capacity then emits an etl::list_full error, if asserts or exceptions are not enabled then
undefined behaviour occurs.
____________________________________________________________________________________________________

void clear();

Clears the list to a size of zero.
____________________________________________________________________________________________________

void splice(iterator to, etl::ilist& other);

Moves the elements in list other to before the position to.
The operation performs copies between the different lists.
____________________________________________________________________________________________________

void splice(iterator to, etl::ilist& other, iterator from);

Moves the element at position from in list other to before the position to.
The operation is fast when spicing within the same list, otherwise performs copies between different lists.
If from is not valid then undefined behaviour occurs.
____________________________________________________________________________________________________

void splice(iterator to, etl::ilist& other, iterator first, iterator last);

Moves the elements in the range first to one before last in list other to before the position to.
The operation is fast when spicing within the same list, otherwise performs copies between different lists.
____________________________________________________________________________________________________

void merge(etl::ilist& other);

Merges the elements in list other to this list.
The lists must be sorted. If a debug compile and asserts or exceptions are enabled than an etl::list_unsorted is
emitted if either list is unsorted, otherwise undefined behaviour occurs.
____________________________________________________________________________________________________

template <typename TCompare>
void merge(etl::ilist& other, TCompare compare);

Merges the elements in list other to this list using the supplied comparison function to determine order.
The lists must already be sorted according to the compare function.
If a debug compile and asserts or exceptions are enabled than an etl::list_unsorted is emitted if either list is
unsorted, otherwise undefined behaviour occurs.
____________________________________________________________________________________________________

Operations


void remove(const T& value);

Removes from the container all the elements that compare equal to value.
____________________________________________________________________________________________________

template <typename TPredicate>
void remove_if(TPredicate predicate);

Removes from the container all the elements that satisfy predicate.
____________________________________________________________________________________________________

void unique();

template <typename TPredicate>
void unique(TPredicate predicate);

The first version removes all but the first element from every group of consecutive elements.
The second removes all but the first element from every group of consecutive elements that satisfy the binary
predicate.
____________________________________________________________________________________________________

void sort();

template <typename TCompare>
void sort(TCompare compare);

The first version sorts using the < operator.
The second uses the supplied compare function.
____________________________________________________________________________________________________

void reverse();
Reverses the order of the list.
____________________________________________________________________________________________________

Non-member functions


==  true if the contents of the lists are equal, otherwise false.
!=  true if the contents of the lists 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.

____________________________________________________________________________________________________

Shared pool example


// The element type.
struct Point { int x; int y; };

// The list type
typedef etl::list<Point, 0> List;

// The shared pool. Maximum of 10 items.
etl::pool<List::pool_type, 10> pool;

// The vector of lists with shared pools.
etl::vector<List, 3> vector_of_lists(3, List(pool));

// Make some data.
Point point = { 1, 2 };

// Push one to each list.
vector_of_lists[0].push_back(point);
vector_of_lists[1].push_back(point);
vector_of_lists[2].push_back(point);

size_t available = 0;

available = vector_of_lists[0].available(); // Reports '7'
available = vector_of_lists[1].available(); // Reports '7'
available = vector_of_lists[2].available(); // Reports '7'

list.h