25e2d6e8a3
* Adopt the Library Fundamentals TS make_array design for the sequence factories make_array, make_deque, make_vector, make_list, make_forward_list and make_indirect_vector now follow the Library Fundamentals TS std::experimental::make_array design: a defaulted leading template parameter selects the element type explicitly, falling back to the decayed common type of the arguments when it is not supplied. A shared trait (etl::private_make::element_type) performs the selection lazily, so common_type is not instantiated when the element type is explicit. This fixes the explicit-element-type calling style for the four common-type factories, where make_vector<char>(lvalue) never compiled: the explicit argument pinned the first pack parameter to char, making it a char&& that no lvalue can bind to. It also gives make_array and make_deque the deduced form (e.g. make_array(1, 2L) is array<long, 2>) for free. All arguments are converted with static_cast, as in the make_array const-lvalue fix, so const-qualified lvalues and narrowing initialisers work in both forms. Intentional behaviour change: an explicit element type now converts every argument instead of pinning only the first. make_vector<char>(0, 1, ...) previously produced vector<int> - the explicit char affected only the first argument and the element type was still the common type - and now produces vector<char>. test_make_vector documented the old behaviour and has been updated. The keyed set and map factories are unchanged: their key/mapped types are separate mandatory template parameters ahead of a fully-deduced pack, so the explicit-type style already works, and retrofitting deduction there would interact with the defaulted comparator/hash parameters. Adds explicit-element-type tests for the four common-type factories (const/non-const lvalues plus narrowing initialisers) and deduced-element-type tests for make_array and make_deque, and updates the four documented signatures. * Address review comments on the make_xxx factory design - Forward same-type arguments in the make_xxx factories instead of casting them. static_cast produced a prvalue that, before C++17, had to be materialised through the move constructor, rejecting copyable-but-non-movable element types. The new private_make::convert helper forwards arguments that already have the element type and static_casts the rest. - Drop ETL_NOEXCEPT from make_array: conversions can throw, and the other factories do not declare it. - Remove the redundant etl::decay in element_type<void, ...>; etl::common_type already decays its arguments. - Stop leaking the etl::private_make implementation namespace into the documented factory signatures. * Add a test for make_array with an explicit element type and no arguments etl::make_array<int>() produces an empty etl::array<int, 0> and now has a regression test. A call with neither an element type nor arguments remains ill-formed, matching the Library Fundamentals TS: there is nothing to deduce the element type from. The array documentation now states this explicitly. --------- Co-authored-by: John Wellbelove <jwellbelove@users.noreply.github.com> Co-authored-by: Roland Reichwein <Roland.Reichwein@bmw.de>
17 KiB
| title | weight |
|---|---|
| list | 1 |
{{< callout >}}
Header: list.h
Similar to: std::list
{{< /callout >}}
A fixed capacity bidirectional list.
etl::list<typename T, size_t SIZE>
etl::list_ext<typename T>
Inherits from etl::ilist<T>.
etl::ilist may be used as a size independent pointer or reference type for any etl::list instance.
{{< callout type="warning">}}
Does not support the member function swap.
{{< /callout >}}
Shared Pools
etl::list<typename T>
This template 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 have 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.
The pool must be declared with the list's pool_type.
Example
// The element type
struct Point { int x; int y; };
// The list type
using List = etl::list_ext<Point>;
// The shared pool
etl::pool<List::pool_type, 10> pool;
Template deduction guides
C++17 and above
template <typename... T>
etl::list(T...)
Example
etl::list data{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 };
Defines data as an list of int, of length 10, containing the supplied data.
Make template
C++11 and above
template <typename T = void, typename... TValues>
constexpr auto make_list(TValues&&... values) -> etl::list</*element-type*/, sizeof...(TValues)>
The element type is T when supplied, otherwise the decayed common type of
the arguments (the Library Fundamentals TS make_array design).
Example
// Deduced element type: etl::list<int, 10>.
auto data = etl::make_list(0, 1, 2, 3, 4, 5, 6, 7, 8, 9);
// Explicit element type: etl::list<char, 10>. Each argument is converted.
auto chars = etl::make_list<char>(0, 1, 2, 3, 4, 5, 6, 7, 8, 9);
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 Bi-directional iterator
const_iterator Constant bi-directional iterator
reverse_iterator ETL_OR_STD::reverse_iterator<iterator>
const_reverse_iterator ETL_OR_STD::reverse_iterator<const_iterator>
Constructors
etl::list<typename T, const size_t SIZE>()
etl::list<typename T, const size_t SIZE>(size_t initialSize, parameter_t value = T())
etl::list<typename T, const size_t SIZE>(const etl::list<typename T, const size_t SIZE>&)
etl::list<typename T, const size_t SIZE>(etl::list<typename T, const size_t SIZE>&&)
template <typename TIterator>
etl::list<typename T, const size_t SIZE>(TIterator begin, TIterator end)
Description
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)
Description
Emits an etl::list_iterator if the iterators are invalid. If asserts or exceptions are disabled then undefined behaviour occurs.
Copy constructor
Implicit pool
Uses the pool from other.
etl::list<typename T, const size_t SIZE>(etl::list<typename T, size_t SIZE>& other)
Explicit pool
etl::list<typename T, const size_t SIZE>(etl::list<typename T, size_t SIZE>& other, etl::pool& pool)
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.
The pool instance can be retrieved by call get_pool()
Element access
T& front()
const T& front() const
Description
Returns a reference or const reference to the first element.
Undefined behaviour if the list is empty.
T& back()
const T& back() const
Description
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
Description
Returns an iterator to the beginning of the list.
iterator end()
const_iterator end() const
const_iterator cend() const
Description
Returns an iterator to the end of the list.
reverse_iterator rbegin()
const_reverse_iterator rbegin() const
const_reverse_iterator crbegin() const
Description
Returns a reverse iterator to the beginning of the list.
reverse_iterator rend()
const_reverse_iterator rend() const
const_reverse_iterator crend() const
Description
Returns a reverse iterator to the end of the list.
Capacity
bool empty() const
Description
Returns true if the size of the list is zero, otherwise false.
bool full() const
Description
Returns true if the size of the list is SIZE, otherwise false.
size_t size() const
Description
Returns the size of the list.
size_t available() const
Description
Returns the remaining available capacity in the list.
size_t max_size() const
Description
Returns the maximum possible size of the list.
Modifiers
template <typename TIterator>
void assign(TIterator begin, TIterator end)
Description
Assigns from a range of values.
void assign(size_t n, parameter_t value)
Description
Fills the list with the values.
void push_front(const T& value)
void push_front(T&& value)
Description
Pushes a value to the front of the list.
If the list is full then emits an etl::list_full error.
emplace_front
C++03
template <typename T1>
void emplace_front(const T1& value1)
template <typename T1, typename T2>
void emplace_front(const T1& value1, const T2& value2)
template <typename T1, typename T2, typename T3>
void emplace_front(const T1& value1, const T2& value2,
const T3& value3)
template <typename T1, typename T2, typename T3, typename T4>
void emplace_front(const T1& value1, const T2& value2,
const T3& value3, const T4& value4)
Description
Emplaces a value at the front, constructed using the supplied arguments.
Before: 20.35.10
template <typename T1>
reference emplace_front(const T1& value1)
template <typename T1, typename T2>
reference emplace_front(const T1& value1, const T2& value2)
template <typename T1, typename T2, typename T3>
reference emplace_front(const T1& value1, const T2& value2,
const T3& value3)
template <typename T1, typename T2, typename T3, typename T4>
reference emplace_front(const T1& value1, const T2& value2,
const T3& value3, const T4& value4)
Description
Emplaces a value at the front, constructed using the supplied arguments.
Since: 20.35.10
C++11 and above
template <typename ... Args>
reference emplace_front(Args&& …args)
Description
Emplaces a value at the front, constructed using the supplied arguments.
void push_back(const T& value);
void push_back(T&& value);
Description
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.
emplace_back
Description
Emplaces a value at the back, constructed using the supplied arguments.
C++03
template <typename T1>
void emplace_back(const T1& value1)
template <typename T1, typename T2>
void emplace_back(const T1& value1, const T2& value2)
template <typename T1, typename T2, typename T3>
void emplace_back(const T1& value1, const T2& value2,
const T3& value3)
template <typename T1, typename T2, typename T3, typename T4>
void emplace_back(const T1& value1, const T2& value2,
const T3& value3, const T4& value4)
Before: 20.35.10
template <typename T1>
reference emplace_back(const T1& value1)
template <typename T1, typename T2>
reference emplace_back(const T1& value1, const T2& value2)
template <typename T1, typename T2, typename T3>
reference emplace_back(const T1& value1, const T2& value2,
const T3& value3)
template <typename T1, typename T2, typename T3, typename T4>
reference emplace_back(const T1& value1, const T2& value2,
const T3& value3, const T4& value4)
Since: 20.35.10
C++11 and above
template <typename ... Args>
reference emplace_back(Args&& ... args)
Description
Emplaces a value at the back, constructed using the supplied arguments.
From: 20.35.10
C++11 and above
template <typename ... Args>
reference emplace_back(Args&& ... args)
Description
Emplaces a value at the back, constructed using the supplied arguments.
From: 20.35.10
void pop_front()
Description
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()
Description
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)
Description
Before: 20.20.0
iterator insert(iterator position, parameter_t value);
void insert(iterator position, size_t n, parameter_t value)
template <typename TIterator>
iterator insert(const_iterator position, TIterator begin, TIterator end)
Description
Since 20.20.0
iterator insert(const_iterator position, parameter_t value)
iterator insert(const_iterator position, size_t n, parameter_t value)
Description
Inserts values in to the list. If the list is full then emits an etl::list_full error.
emplace
Description
Constructs an item at the insert point in the list 'in place'.
C++03
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)
Before: 20.20.0
iterator emplace(const_iterator position, const T1& value1)
iterator emplace(const_iterator position, const T1& value1, const T2& value2)
iterator emplace(const_iterator position, const T1& value1, const T2& value2, const T3& value3)
iterator emplace(const_iterator position, const T1& value1, const T2& value2, const T3& value3, const T4& value4)
Description
From: 20.20.0
C++11
void emplace(iterator position, Args&& ... args)
Description
Constructs an item at the insert point in the the list 'in place'.
Before: 20.20.0
void emplace(const_iterator position, Args&& ... args)
Description
Constructs an item at the insert point in the the list 'in place'.
From: 20.20.0
template <typename TIterator>
iterator erase(TIterator begin, TIterator end)
iterator erase(iterator position)
Description
Before: 20.20.0
iterator erase(iterator position)
iterator erase(const_iterator position)
Description
Erases values in the list.
Before: 20.21.0
void resize(size_t n);
void resize(size_t n, parameter_t value)
Description
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();
Description
Clears the list to a size of zero.
void splice(iterator to, etl::ilist& other)
void splice(iterator to, etl::ilist&& other)
Description
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)
void splice(iterator to, etl::ilist&& other, iterator from)
Description
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)
void splice(iterator to, etl::ilist&& other, iterator first, iterator last)
Description
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)
void merge(etl::ilist&& other)
Description
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)
template <typename TCompare>
void merge(etl::ilist&& other, TCompare compare)
Description
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)
Description
Removes from the container all the elements that compare equal to value.
template <typename TPredicate>
void remove_if(TPredicate predicate)
Description
Removes from the container all the elements that satisfy predicate.
void unique()
Description
Removes all but the first element from every group of consecutive elements.
template <typename TPredicate>
void unique(TPredicate predicate)
Description
Removes all but the first element from every group of consecutive elements that satisfy the binary predicate.
void sort()
Description
Sorts using the < operator.
template <typename TCompare>
void sort(TCompare compare)
Description
Sorts using the supplied compare function.
void reverse()
Description
Reverses the order of the list.
Non-member functions
operator ==
Description
true if the contents of the lists are equal, otherwise false.
operator !=
Description
true if the contents of the lists are not equal, otherwise false.
operator <
Description
true if the contents of the lhs are lexicographically less than the contents of the rhs, otherwise false.
operator <=
Description
true if the contents of the lhs are lexicographically less than or equal to the contents of the rhs, otherwise false.
operator >
Description
true if the contents of the lhs are lexicographically greater than the contents of the rhs, otherwise false.
operator >=
Description
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
using List = etl::list_ext<Point>;
// 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'