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>
12 KiB
| title | weight |
|---|---|
| forward_list | 3 |
{{< callout >}}
Header: forward_list.h
Similar to: std::forward_list
{{< /callout >}}
A fixed capacity forward list.
etl::forward_list<typename T, size_t SIZE>
etl::forward_list_ext<typename T>
Inherits from etl::iforward_list<T>.
etl::iforward_list may be used as a size independent pointer or reference type for any etl::forward_list instance.
Note: Does not support the member function swap.
Shared Pools
etl::forward_list_ext<typename T>
This template may share pools with another etl::forward_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::forward_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.
Example
// The element type
struct Point { int x; int y; };
// The list type
using List = etl::forward_list_ext<Point>;
// The shared pool
etl::pool<List::pool_type, 10> pool;
Template deduction guides
C++17 and above
template <typename T...>
etl::forward_list(T...)
Example
etl::forward_list data{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 };
Defines data as an forward_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_forward_list(TValues&&... values) -> etl::forward_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::forward_list<int, 10>.
auto data = etl::make_forward_list(0, 1, 2, 3, 4, 5, 6, 7, 8, 9);
// Explicit element type: etl::forward_list<char, 10>. Each argument is converted.
auto chars = etl::make_forward_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&
pointer value_type*
const_pointer const value_type*
iterator Forward iterator
const_iterator Constant forward iterator
Constructors
etl::forward_list<typename T, const size_t SIZE>()
etl::forward_list<typename T, const size_t SIZE>(size_t initialSize, parameter_t value = T())
template <typename TIterator>
etl::forward_list<typename T, const size_t SIZE>(TIterator begin, TIterator end)
Raises an etl::forward_list_iterator if the iterators are invalid. Raises an etl::forward_list_full if the list becomes full.
If asserts or exceptions are disabled then undefined behaviour occurs.
For shared pool lists
etl::forward_list<typename T, const size_t SIZE>(etl::pool& pool)
etl::forward_list<typename T, const size_t SIZE>(size_t initialSize, parameter_t value, etl::pool& pool)
template <typename TIterator>
etl::forward_list<typename T, const size_t SIZE>(TIterator begin, TIterator end, etl::pool& pool)
Raises an etl::forward_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::forward_list<typename T, const size_t SIZE>(etl::forward_list<typename T, const size_t SIZE>& other)
Explicit pool
etl::forward_list<typename T, const size_t SIZE>(etl::forward_list<typename T, const size_t SIZE>& other, etl::pool& 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.
Iterators
iterator begin()
const_iterator begin() const
const_iterator cbegin() const
Description
Returns an iterator to the beginning of the forward list.
Returns end() if the list is empty.
iterator end()
const_iterator end() const
const_iterator cend() const
Description
Returns an iterator to the end of the forward list.
iterator before_begin()
const_iterator before_begin() const
const_iterator cbefore_begin() const
Description
Returns an iterator to before the beginning of the forward list.
Capacity
bool empty() const
Description
Returns true if the size of the forward list is zero, otherwise false.
bool full() const
Description
Returns true if the size of the forward list is SIZE, otherwise false.
size_t size() const
Description
Returns the size of the forward list.
size_t available() const
Description
Returns the remaining available capacity in the forward list.
size_t max_size() const
Description
Returns the maximum possible size of the forward list .
Modifiers
template <typename TIterator>
void assign(TIterator begin, TIterator end)
void assign(size_t n, parameter_t value)
Description
Fills the forward list with the values.
Raises an etl::forward_list_iterator if the iterators are invalid.
Raises an etl::forward_list_full if the list becomes full.
If asserts or exceptions are disabled then undefined behaviour occurs.
void push_front(parameter_t value)
Description
Pushes a value to the front of the forward list. If the forward list is full and ETL_CHECK_PUSH_POP is defined then raises an etl::forward_list_full error, otherwise undefined behaviour occurs.
emplace_front
Description
Constructs an item at the front of the the list 'in place'.
If the forward list is full and ETL_CHECK_PUSH_POP is defined then raises an etl::forward_list_full error, otherwise undefined behaviour occurs.
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)
Before: 20.35.0
C++11 and above
template <typename ... Args>
void emplace_front(Args&& ... args)
Description
Constructs an item at the front of the the list 'in place'.
If the forward list is full and ETL_CHECK_PUSH_POP is defined then raises an etl::forward_list_full error, otherwise undefined behaviour occurs.
C++03
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)
From 20.35.10
C++11 and above
template <typename ... Args>
reference emplace_front(Args&& …args)
void pop_front()
Description
Pop a value from the front of the forward list.
If the forward list is empty and ETL_CHECK_PUSH_POP is defined then raises an etl::forward_list_empty error, otherwise undefined behaviour occurs.
template <typename TIterator>
void insert_after(iterator position, TIterator begin, TIterator end)
Description
Inserts the range [begin, end) into the forward list after the specified position.
Before: 20.20.0
iterator insert_after(iterator position, parameter_t value)
void insert_after(iterator position, size_t n, parameter_t value)
Description
Inserts value in to the forward list after the specified position.
template <typename TIterator>
iterator insert_after(const_iterator position, TIterator begin, TIterator end)
Description
Inserts the range [begin, end) into the forward list after the specified position.
Since: 20.20.0
iterator insert_after(const_iterator position, parameter_t value)
Description
Inserts value in to the forward list after the specified position.
iterator insert_after(const_iterator position, size_t n, parameter_t value)
Inserts values in to the forward list after the specified position.
If the forward list is full then raises an etl::forward_list_full error.
If asserts or exceptions are disabled then undefined behaviour occurs.
iterator erase_after(iterator position)
Erases elements after the specified position.
Before: 20.20.0
iterator erase_after(iterator position, const_iterator end)
Description
Erases the range (position, end)
Before: 20.20.0
iterator erase_after(const_iterator position)
Description
Erases elements after the specified position.
Since: 20.20.0
iterator erase_after(const_iterator position, const_iterator end)
Description
Erases the range (position, end)
Since: 20.20.0
void resize(size_t n)
Description
Resizes the forward list.
If the new size is larger then the first assigns default constructed values.
If n is larger than the capacity then raises an etl::forward_list_full error, if asserts or exceptions are not enabled then undefined behaviour occurs.
void resize(size_t n, parameter_t value)
Description
Resizes the forward list.
If the new size is larger then the first assigns the supplied value.
If n is larger than the capacity then raises an etl::forward_list_full error, if asserts or exceptions are not enabled then undefined behaviour occurs.
void clear()
Description
Clears the forward list to a size of zero.
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 container.
Non-member functions
operator ==
Return
true if the contents of the lists are equal, otherwise false.
operator !=
Return
true if the contents of the lists are not equal, otherwise false.
operator <
Return
true if the contents of the lhs are lexicographically less than the contents of the rhs, otherwise false.
operator <=
Return
true if the contents of the lhs are lexicographically less than or equal to the contents of the rhs, otherwise false.
operator >
Return
true if the contents of the lhs are lexicographically greater than the contents of the rhs, otherwise false.
operator >=
Return
true if the contents of the lhs are lexicographically greater than or equal to the contents of the rhs, otherwise false.