diff --git a/docs/_index.md b/docs/_index.md index efc0a7d6..7dca7869 100644 --- a/docs/_index.md +++ b/docs/_index.md @@ -4,10 +4,6 @@ weight: 998 type: hextra-home --- -{{< callout type="warning">}} -**This documentation is still under development, and very much incomplete.** -{{< /callout >}} -
diff --git a/docs/containers/Views/array-view.md b/docs/containers/Views/array-view.md index 094e36cc..079c3f46 100644 --- a/docs/containers/Views/array-view.md +++ b/docs/containers/Views/array-view.md @@ -301,36 +301,52 @@ Returns the maximum possible size of the view. ## Non-member functions **Lexicographically comparisons** - -`operator ==` -**Returns** -Returns `true` if the contents of the array views are equal, otherwise `false`. +```cpp +operator == +``` +**Description** +`true` if the contents of the lists are equal, otherwise `false`. --- -`operator !=` -**Returns** -`true` if the contents of the array views are not equal, otherwise `false`. +```cpp +operator != +``` +**Description** +`true` if the contents of the lists are not equal, otherwise `false`. -`operator <` -**Returns** -`true` if the contents of the lhs are lexicographically less than the -contents of the rhs, otherwise `false`. +--- -`operator <=` -**Returns** -`true` if the contents of the lhs are lexicographically less than or equal to the -contents of the rhs, otherwise `false`. +```cpp +operator < +``` +**Description** +`true` if the contents of the lhs are lexicographically less than the contents of the rhs, otherwise `false`. -`operator >` -**Returns** -`true` if the contents of the lhs are lexicographically greater than the -contents of the rhs, otherwise `false`. +--- + +```cpp +operator <= +``` +**Description** +`true` if the contents of the lhs are lexicographically less than or equal to the contents of the rhs, otherwise `false`. + +--- + +```cpp +operator > +``` +**Description** +`true` if the contents of the lhs are lexicographically greater than the contents of the rhs, otherwise `false`. + +--- + +```cpp +operator >= +``` +**Description** +`true` if the contents of the lhs are lexicographically greater than or equal to the contents of the rhs, otherwise `false`. -`operator >=` -**Returns** -`true` if the contents of the lhs are lexicographically greater than or equal to the -contents of the rhs, otherwise `false`. ## Hash There are specialisations of `etl::hash` for `array_view`. diff --git a/docs/containers/arrays/array.md b/docs/containers/arrays/array.md index 3fd23a7a..e2cda55d 100644 --- a/docs/containers/arrays/array.md +++ b/docs/containers/arrays/array.md @@ -269,31 +269,48 @@ first/last are not checked for valid range. ## Non-member functions **Lexicographically comparisons** +```cpp +operator == +``` +**Description** +`true` if the contents of the lists are equal, otherwise `false`. -`operator ==` -**Returns** -`true` if the contents of the arrays are equal, otherwise `false`. +--- -`operator !=` -**Returns** -`true` if the contents of the arrays are not equal, otherwise `false`. +```cpp +operator != +``` +**Description** +`true` if the contents of the lists are not equal, otherwise `false`. -`operator <` -**Returns** -`true` if the contents of the lhs are lexicographically less than the -contents of the rhs, otherwise `false`. +--- -`operator <=` -**Returns** -`true` if the contents of the lhs are lexicographically less than or equal to the -contents of the rhs, otherwise `false`. +```cpp +operator < +``` +**Description** +`true` if the contents of the lhs are lexicographically less than the contents of the rhs, otherwise `false`. -`operator >` -**Returns** -`true` if the contents of the lhs are lexicographically greater than the -contents of the rhs, otherwise `false`. +--- -`operator >=` -**Returns** -`true` if the contents of the lhs are lexicographically greater than or equal to the -contents of the rhs, otherwise `false`. +```cpp +operator <= +``` +**Description** +`true` if the contents of the lhs are lexicographically less than or equal to the contents of the rhs, otherwise `false`. + +--- + +```cpp +operator > +``` +**Description** +`true` if the contents of the lhs are lexicographically greater than the contents of the rhs, otherwise `false`. + +--- + +```cpp +operator >= +``` +**Description** +`true` if the contents of the lhs are lexicographically greater than or equal to the contents of the rhs, otherwise `false`. diff --git a/docs/containers/deque.md b/docs/containers/deque.md index 9d42a3b7..a4960607 100644 --- a/docs/containers/deque.md +++ b/docs/containers/deque.md @@ -556,17 +556,48 @@ etl::deque& ## 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`. +```cpp +operator == +``` +**Description** +`true` if the contents of the lists are equal, otherwise `false`. + +--- + +```cpp +operator != +``` +**Description** +`true` if the contents of the lists are not equal, otherwise `false`. + +--- + +```cpp +operator < +``` +**Description** +`true` if the contents of the lhs are lexicographically less than the contents of the rhs, otherwise `false`. + +--- + +```cpp +operator <= +``` +**Description** +`true` if the contents of the lhs are lexicographically less than or equal to the contents of the rhs, otherwise `false`. + +--- + +```cpp +operator > +``` +**Description** +`true` if the contents of the lhs are lexicographically greater than the contents of the rhs, otherwise `false`. + +--- + +```cpp +operator >= +``` +**Description** +`true` if the contents of the lhs are lexicographically greater than or equal to the contents of the rhs, otherwise `false`. diff --git a/docs/containers/forward-list.md b/docs/containers/forward-list.md index 7f42e078..133f4297 100644 --- a/docs/containers/forward-list.md +++ b/docs/containers/forward-list.md @@ -106,7 +106,7 @@ template etl::forward_list(TIterator begin, TIterator end) ``` -Emits an `etl::forward_list_iterator` if the iterators are invalid. Emits an `etl::forward_list_full` if the list becomes full. +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 @@ -127,18 +127,18 @@ template etl::forward_list(TIterator begin, TIterator end, etl::pool& pool) ``` -Emits an `etl::forward_list_iterator` if the iterators are invalid. If asserts or exceptions are disabled then undefined behaviour occurs. +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. ```cpp -etl::forward_list(etl::forward_list& other); +etl::forward_list(etl::forward_list& other) ``` **Explicit pool** ```cpp -etl::forward_list(etl::forward_list& other, etl::pool& pool); +etl::forward_list(etl::forward_list& other, etl::pool& pool) ``` ## Element access @@ -164,224 +164,299 @@ Returns end() if the list is empty. --- +```cpp iterator end() const_iterator end() const const_iterator cend() const +``` **Description** Returns an iterator to the end of the forward list. --- +```cpp 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 +```cpp bool empty() const +``` **Description** -Returns true if the size of the forward list is zero, otherwise false. +Returns `true` if the size of the forward list is zero, otherwise `false`. --- +```cpp bool full() const +``` **Description** -Returns true if the size of the forward list is SIZE, otherwise false. +Returns `true` if the size of the forward list is SIZE, otherwise `false`. --- +```cpp size_t size() const +``` **Description** Returns the size of the forward list. --- +```cpp size_t available() const +``` **Description** Returns the remaining available capacity in the forward list. --- +```cpp size_t max_size() const +``` **Description** Returns the maximum possible size of the forward list . ## Modifiers +```cpp template -void assign(TIterator begin, TIterator end); -void assign(size_t n, parameter_t value); +void assign(TIterator begin, TIterator end) + +void assign(size_t n, parameter_t value) +``` **Description** Fills the forward list with the values. -Emits an etl::forward_list_iterator if the iterators are invalid. Emits an etl::forward_list_full if the list becomes full. If asserts or exceptions are disabled then undefined behaviour occurs. +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); +```cpp +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 emits an etl::forward_list_full error, otherwise undefined behaviour occurs. +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. --- -<=20.35.9 -C++03 +```cpp +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 +```cpp template void emplace_front(const T1& value1) ---- - template void emplace_front(const T1& value1, const T2& value2) ---- - template void emplace_front(const T1& value1, const T2& value2, const T3& value3) ---- - template void emplace_front(const T1& value1, const T2& value2, const T3& value3, const T4& value4) +``` +Before: `20.35.0` ---- +## C++11 and above -C++11 and above +```cpp template void emplace_front(Args&& ... args) -Constructs an item at the front of the the list 'in place'. -Supports up to four constructor parameters. -If the forward list is full and ETL_CHECK_PUSH_POP is defined then emits an etl::forward_list_full error, otherwise undefined behaviour occurs. +``` +**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. ---- - ->=20.35.10 -C++03 +### C++03 +```cpp template reference emplace_front(const T1& value1) ---- - template reference emplace_front(const T1& value1, const T2& value2) ---- - template reference emplace_front(const T1& value1, const T2& value2, const T3& value3) ---- - template reference emplace_front(const T1& value1, const T2& value2, const T3& value3, const T4& value4) - +``` +From 20.35.10 --- -C++11 and above +### C++11 and above +```cpp template reference emplace_front(Args&& …args) -Constructs an item at the front of the the list 'in place'. -Supports up to four constructor parameters. -If the forward list is full and ETL_CHECK_PUSH_POP is defined then emits an etl::forward_list_full error, otherwise undefined behaviour occurs. +``` --- -void pop_front(); -Pop a value from the front of the forward list. -If the forward list is empty and ETL_CHECK_PUSH_POP is defined then emits an etl::forward_list_empty error, otherwise undefined behaviour occurs. +```cpp +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. --- -<=20.19.0 +```cpp template -void insert_after(iterator position, TIterator begin, TIterator end); +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); +```cpp +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. --- ->=20.20.0 +```cpp template -iterator insert_after(const_iterator position, TIterator begin, TIterator end); +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); +```cpp +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); +```cpp +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 emits an etl::forward_list_full error. If asserts or exceptions are disabled then undefined behaviour occurs. +If the forward list is full then raises an `etl::forward_list_full error`. +If asserts or exceptions are disabled then undefined behaviour occurs. --- -<=20.19.0 -iterator erase_after(iterator position); - ---- - -iterator erase_after(iterator position, const_iterator end); - ---- - ->=20.20.0 -iterator erase_after(iterator position); - ---- - -iterator erase_after(const_iterator position); - ---- - -iterator erase_after(const_iterator position, const_iterator end); +```cpp +iterator erase_after(iterator position) +``` Erases elements after the specified position. -The second version erases up to, but not including end. +Before: `20.20.0` --- -void resize(size_t n); +```cpp +iterator erase_after(iterator position, const_iterator end) +``` +**Description** +Erases the range (`position`, `end`) +Before: `20.20.0` --- -void resize(size_t n, parameter_t value); -Resizes the forward 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::forward_list_full error, if asserts or exceptions are not enabled then undefined behaviour occurs. +```cpp +iterator erase_after(const_iterator position) +``` +**Description** +Erases elements after the specified position. +Since: `20.20.0` --- -void clear(); +```cpp +iterator erase_after(const_iterator position, const_iterator end) +``` +**Description** +Erases the range (`position`, `end`) +Since: `20.20.0` + +--- + +```cpp +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. + +--- + +```cpp +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. + +--- + +```cpp +void clear() +``` +**Description** Clears the forward list to a size of zero. ## Operations -void remove(const T& value); +```cpp +void remove(const T& value) +``` +**Description** Removes from the container all the elements that compare equal to value. --- +```cpp template -void remove_if(TPredicate predicate); +void remove_if(TPredicate predicate) +``` +**Description** Removes from the container all the elements that satisfy predicate. --- -void unique(); +```cpp +void unique() +``` +**Description** +Removes all but the first element from every group of consecutive elements. --- +```cpp template -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 unique(TPredicate predicate) +``` +**Description** +Removes all but the first element from every group of consecutive elements that satisfy the binary predicate. --- diff --git a/docs/containers/intrusive-forward-list.md b/docs/containers/intrusive-forward-list.md new file mode 100644 index 00000000..cf79d69a --- /dev/null +++ b/docs/containers/intrusive-forward-list.md @@ -0,0 +1,340 @@ +--- +title: "intrusive_forward_list" +--- + +{{< callout type="info">}} + Header: `intrusive_forward_list.h` + Similar to: `std::forward_list` +{{< /callout >}} + +An intrusive forward list. + +```cpp +template +etl::intrusive_forward_list +``` + +`TValue` is the type that contains the actual values. It is derived from `Tlink`. `Tlink` is the link type for this list. +See Intrusive links. + +Before `20.37.0` the default link type was `etl::forward_link<0>`. + +## Member types + +```cpp +link_type TLink +value_type TValue +pointer value_type* +const_pointer const value_type* +reference value_type& +const_reference const value_type& +size_type size_t +``` + +## Constructors + +```pcc +etl::intrusive_forward_list(); +``` +**Description** +Default constructor. + +--- + +```cpp +template +etl::intrusive_forward_list(TIterator begin, TIterator end); +``` +**Description** +Creates the list from the range [`begin`, `end`) of node links. + +--- + +```cpp +template +intrusive_forward_list(TLink& first, TLinks&... links); +```cpp +**Description** +Creates the list from node link references. + +## Element access + +```cpp +TValue& front() +const T& front() const +``` +**Description** +Returns a reference or const reference to the first element. + +--- + +```cpp +TValue& back() +const T& back() const +``` +**Description** +Returns a reference or const reference to the last element. + +## Iterators + +```cpp +iterator begin() +const_iterator begin() const +const_iterator cbegin() const +``` +**Description** +Returns an iterator to the beginning of the list. + +--- + +```cpp +iterator end() +const_iterator end() const +const_iterator cend() const +``` +**Description** +Returns an iterator to the end of the list. + +--- + +```cpp +iterator rbegin() +const_iterator rbegin() const +const_iterator crbegin() const +``` +**Description** +Returns a reverse iterator to the beginning of the list. + +--- + +```cpp +iterator rend() +const_iterator rend() const +const_iterator crend() const +``` +**Description** +Returns a reverse iterator to the end of the list. + +## Capacity + +```cpp +bool empty() const +``` +**Description** +Returns true if the size of the list is zero, otherwise false. + +--- + +```cpp +size_t size() const +``` +**Description** +Returns the size of the list. + +## Modifiers + +```cpp +template +void assign(TIterator begin, TIterator end); +``` +**Description** +Fills the list with the values. + +--- + +```cpp +void push_front(value_type& value); +``` +**Description** +Pushes a value to the front of the list. + +--- + +```cpp +void pop_front(); +``` +**Description** +Pop a value from the front of the list. +Emits an `etl::intrusive_forward_list_empty` if the list is empty. +If asserts or exceptions are disabled then undefined behaviour occurs. + +--- + +```cpp +template +void insert_after(iterator position, TIterator begin, TIterator end); +``` +**Description** + +--- + +```cpp +iterator insert_after(iterator position, value_type& value); +``` +**Description** +Inserts values in to the list. +position is not checked for validity. + +--- + +```cpp +template +iterator erase_after(TIterator begin, TIterator end); +``` +**Description** +Erases values in the range [`begin`, `end`). +Iterators are not checked for validity. + +--- + +```cpp +iterator erase_after(iterator position); +``` +**Description** +Erases values in the list. +Iterators are not checked for validity. + +--- + +```cpp +void clear() +``` +**Description** +Clears the list to a size of zero. No elements are destructed. + +--- + +```cpp +void splice_after(iterator position, list_type& list); +void splice_after(iterator position, list_type& list, iterator isource); +void splice_after(iterator position, list_type& list, iterator begin_, iterator end_); +``` +**Description** +Splices elements from a list into this list. +Iterators are not checked for validity. + +--- + +```cpp +void merge(list_type& list); +``` +**Description** +Merges the sorted elements of 'list' into this list. Merges are stable. +If a debug compile and asserts or exceptions are enabled than an etl::intrusive_list_unsorted is emitted if either list is unsorted, otherwise undefined behaviour occurs. + +--- + +```cpp +template +void merge(list_type& list, Tcompare compare) +``` +**Description** +Merges the sorted elements of list into this list. Comparison functor is supplied in compare. Merges are stable. +If a debug compile and asserts or exceptions are enabled than an etl::intrusive_list_unsorted is emitted if either list is unsorted, otherwise undefined behaviour occurs. + +## Operations + +```cpp +void remove(const T& value); +``` +**Description** +Removes from the container all the elements that compare equal to value. + +--- + +```cpp +template +void remove_if(TPredicate predicate); +``` +**Description** +Removes from the container all the elements that satisfy predicate. + +--- + +```cpp +void unique(); +``` +**Description** +Removes all but the first element from every group of consecutive elements. + +--- + +```cpp +template +void unique(TPredicate predicate); +``` +**Description** +Removes all but the first element from every group of consecutive elements that satisfy the binary `predicate`. + +--- + +```cpp +void sort(); +``` +**Description** +Sorts using the < operator. + +--- + +```cpp +template +void sort(TCompare compare); +``` +**Description** +Sorts using the supplied `compare` function. + +--- + +```cpp +void reverse(); +``` +**Description** +Reverses the order of the list. + +## Non-member functions + +```cpp +operator == +``` +**Description** +`true` if the contents of the lists are equal, otherwise `false`. + +--- + +```cpp +operator != +``` +**Description** +`true` if the contents of the lists are not equal, otherwise `false`. + +--- + +```cpp +operator < +``` +**Description** +`true` if the contents of the lhs are lexicographically less than the contents of the rhs, otherwise `false`. + +--- + +```cpp +operator <= +``` +**Description** +`true` if the contents of the lhs are lexicographically less than or equal to the contents of the rhs, otherwise `false`. + +--- + +```cpp +operator > +``` +**Description** +`true` if the contents of the lhs are lexicographically greater than the contents of the rhs, otherwise `false`. + +--- + +```cpp +operator >= +``` +**Description** +`true` if the contents of the lhs are lexicographically greater than or equal to the contents of the rhs, otherwise `false`. diff --git a/docs/containers/intrusive-list.md b/docs/containers/intrusive-list.md index a58cad9a..57f6aae3 100644 --- a/docs/containers/intrusive-list.md +++ b/docs/containers/intrusive-list.md @@ -36,6 +36,7 @@ size_type size_t ```cpp etl::intrusive_list() ``` +Default constructor. --- @@ -44,7 +45,7 @@ template etl::intrusive_list(TIterator begin, TIterator end) ``` **Description** -Default constructor. +Creates the list from the range [`begin`, `end`) of node links. --- @@ -314,30 +315,40 @@ operator == **Description** `true` if the contents of the lists are equal, otherwise `false`. +--- + ```cpp operator != ``` **Description** `true` if the contents of the lists are not equal, otherwise `false`. +--- + ```cpp operator < ``` **Description** `true` if the contents of the lhs are lexicographically less than the contents of the rhs, otherwise `false`. +--- + ```cpp operator <= ``` **Description** `true` if the contents of the lhs are lexicographically less than or equal to the contents of the rhs, otherwise `false`. +--- + ```cpp operator > ``` **Description** `true` if the contents of the lhs are lexicographically greater than the contents of the rhs, otherwise `false`. +--- + ```cpp operator >= ``` diff --git a/docs/containers/list.md b/docs/containers/list.md index 5423444b..75050fbf 100644 --- a/docs/containers/list.md +++ b/docs/containers/list.md @@ -17,8 +17,9 @@ etl::list_ext Inherits from `etl::ilist`. `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. +{{< callout type="warning">}} + Does not support the member function `swap`. +{{< /callout >}} ## Shared Pools @@ -291,81 +292,23 @@ If the list is full then emits an `etl::list_full error`. --- -**C++03** +```cpp +emplace_front +``` + +### C++03 + ```cpp template void emplace_front(const T1& value1) -``` -**Description** -Emplaces a value at the front, constructed using the supplied arguments. -Before: `20.35.10` ---- - -```cpp -template -reference emplace_front(const T1& value1) -``` -**Description** -Emplaces a value at the front, constructed using the supplied arguments. -From: `20.35.10` - ---- - -```cpp template void emplace_front(const T1& value1, const T2& value2) -``` -**Description** -Emplaces a value at the front, constructed using the supplied arguments. -Before: `20.35.10` ---- - -```cpp -template -reference emplace_front(const T1& value1, const T2& value2) -``` -**Description** -Emplaces a value at the front, constructed using the supplied arguments. -From: `20.35.10` - ---- - -```cpp template void emplace_front(const T1& value1, const T2& value2, const T3& value3) -``` -**Description** -Emplaces a value at the front, constructed using the supplied arguments. -Before: `20.35.10` ---- - -```cpp -template -reference emplace_front(const T1& value1, const T2& value2, - const T3& value3) -``` -**Description** -Emplaces a value at the front, constructed using the supplied arguments. -From: `20.35.10` - ---- - -```cpp -template -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. -From: `20.35.10` - ---- - -```cpp template void emplace_front(const T1& value1, const T2& value2, const T3& value3, const T4& value4) @@ -374,9 +317,26 @@ void emplace_front(const T1& value1, const T2& value2, Emplaces a value at the front, constructed using the supplied arguments. Before: `20.35.10` ---- +```cpp +template +reference emplace_front(const T1& value1) -**C++11 and above** +template +reference emplace_front(const T1& value1, const T2& value2) + +template +reference emplace_front(const T1& value1, const T2& value2, + const T3& value3) + +template +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 ```cpp template reference emplace_front(Args&& …args) @@ -396,93 +356,48 @@ If the list is full and `ETL_CHECK_PUSH_POP` is defined then emits an `etl::list --- +```cpp +emplace_back +``` +**Description** +Emplaces a value at the back, constructed using the supplied arguments. + **C++03** ```cpp template void emplace_back(const T1& value1) -``` -**Description** -Emplaces a value at the back, constructed using the supplied arguments. -Before: `20.35.10` ---- - -```cpp -template -reference emplace_back(const T1& value1) -``` -**Description** -Emplaces a value at the back, constructed using the supplied arguments. -From: `20.35.10` - ---- - -```cpp template void emplace_back(const T1& value1, const T2& value2) -``` -**Description** -Emplaces a value at the back, constructed using the supplied arguments. -Before: `20.35.10` ---- - - -```cpp -template -reference emplace_back(const T1& value1, const T2& value2) -``` -**Description** -Emplaces a value at the back, constructed using the supplied arguments. -From: `20.35.10` - ---- - -```cpp template void emplace_back(const T1& value1, const T2& value2, const T3& value3) -``` -**Description** -Emplaces a value at the back, constructed using the supplied arguments. -Before: `20.35.10` ---- - -```cpp -template -reference emplace_back(const T1& value1, const T2& value2, - const T3& value3) -``` -**Description** -Emplaces a value at the back, constructed using the supplied arguments. -From: `20.35.10` - ---- - -```cpp template void emplace_back(const T1& value1, const T2& value2, const T3& value3, const T4& value4) ``` -**Description** -Emplaces a value at the back, constructed using the supplied arguments. Before: `20.35.10` ---- - ```cpp +template +reference emplace_back(const T1& value1) + +template +reference emplace_back(const T1& value1, const T2& value2) + +template +reference emplace_back(const T1& value1, const T2& value2, + const T3& value3) + template reference emplace_back(const T1& value1, const T2& value2, const T3& value3, const T4& value4) ``` -**Description** -Emplaces a value at the back, constructed using the supplied arguments. -From: `20.35.10` +Since: `20.35.10` ---- - -**C++11 and above** +### C++11 and above ```cpp template reference emplace_back(Args&& ... args) @@ -554,69 +469,43 @@ Inserts values in to the list. If the list is full then emits an `etl::list_full --- -**C++03** ```cpp -void emplace(iterator position, const T1& value1) +emplace ``` **Description** -Before: `20.20.0` - ---- +Constructs an item at the insert point in the list 'in place'. +### C++03 ```cpp +void emplace(iterator position, const T1& value1) + void emplace(iterator position, const T1& value1, const T2& value2) -``` ---- - -```cpp void emplace(iterator position, const T1& value1, const T2& value2, const T3& value3) -``` ---- - -```cpp void emplace(iterator position, const T1& value1, const T2& value2, const T3& value3, const T4& value4) ``` - +Before: `20.20.0` ```cpp 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` ---- - -```cpp -iterator emplace(const_iterator position, const T1& value1, const T2& value2) -``` - ---- - -```cpp -iterator emplace(const_iterator position, const T1& value1, const T2& value2, const T3& value3) -``` - ---- - -```cpp -iterator emplace(const_iterator position, const T1& value1, const T2& value2, const T3& value3, const T4& value4) -``` -**Description** -Constructs an item at the insert point in the list 'in place'. -Supports up to four constructor parameters. - ---- - -**C++11** +### C++11 ```cpp void emplace(iterator position, Args&& ... args) ``` **Description** +Constructs an item at the insert point in the the list 'in place'. Before: `20.20.0` ---- - ```cpp void emplace(const_iterator position, Args&& ... args) ``` @@ -785,23 +674,52 @@ Reverses the order of the list. ## Non-member functions -`==` - `true` if the contents of the lists are equal, otherwise `false`. +```cpp +operator == +``` +**Description** +`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`. +```cpp +operator != +``` +**Description** +`true` if the contents of the lists are not equal, 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`. +```cpp +operator < +``` +**Description** +`true` if the contents of the lhs are lexicographically less than the contents of the rhs, otherwise `false`. + +--- + +```cpp +operator <= +``` +**Description** +`true` if the contents of the lhs are lexicographically less than or equal to the contents of the rhs, otherwise `false`. + +--- + +```cpp +operator > +``` +**Description** +`true` if the contents of the lhs are lexicographically greater than the contents of the rhs, otherwise `false`. + +--- + +```cpp +operator >= +``` +**Description** +`true` if the contents of the lhs are lexicographically greater than or equal to 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 diff --git a/docs/containers/maps/const-multimap.md b/docs/containers/maps/const-multimap.md index 59d4de03..19867bd4 100644 --- a/docs/containers/maps/const-multimap.md +++ b/docs/containers/maps/const-multimap.md @@ -184,14 +184,51 @@ Checks if the container contains the key. ## Non-member functions **Lexicographically comparisons** -| Operator | Description | -| -------- | ----------------------------------------------------------------------------------- | -| `==` | `true` if the contents of the maps are equal, otherwise `false`. | -| `!=` | `true` if the contents of the maps are not equal, otherwise `false`. | -| `<` | `true` if the contents of the lhs is less-than the rhs, otherwise `false`. | -| `<=` | `true` if the contents of the lhs is less-than-equal the rhs, otherwise `false`. | -| `>` | `true` if the contents of the lhs is greater-than the rhs, otherwise `false`. | -| `>=` | `true` if the contents of the lhs is greater-than-equal the rhs, otherwise `false`. | +```cpp +operator == +``` +**Description** +`true` if the contents of the lists are equal, otherwise `false`. + +--- + +```cpp +operator != +``` +**Description** +`true` if the contents of the lists are not equal, otherwise `false`. + +--- + +```cpp +operator < +``` +**Description** +`true` if the contents of the lhs are lexicographically less than the contents of the rhs, otherwise `false`. + +--- + +```cpp +operator <= +``` +**Description** +`true` if the contents of the lhs are lexicographically less than or equal to the contents of the rhs, otherwise `false`. + +--- + +```cpp +operator > +``` +**Description** +`true` if the contents of the lhs are lexicographically greater than the contents of the rhs, otherwise `false`. + +--- + +```cpp +operator >= +``` +**Description** +`true` if the contents of the lhs are lexicographically greater than or equal to the contents of the rhs, otherwise `false`. ## Technical stuff diff --git a/docs/containers/maps/flat-multimap.md b/docs/containers/maps/flat-multimap.md new file mode 100644 index 00000000..b6f6832d --- /dev/null +++ b/docs/containers/maps/flat-multimap.md @@ -0,0 +1,500 @@ +--- +title: "flat_multimap" +--- + +{{< callout type="info">}} + Header: `flat_multimap.h` + Similar to: `std::multimap` +{{< /callout >}} + +A fixed capacity multimap based on a sorted vector. +The container is an associative lookup table with O(N) insertion and erase, and O(log N) search. +This container is best used for tables that are occasionally updated and spend most of their time being searched. +Uses `etl::less` as the default key comparison method. + +```cpp +etl::flat_multimap +``` + +Inherits from `etl::iflat_map`. +`etl::iflat_map` may be used as a size independent pointer or reference type for any `etl::flat_multimap` instance. + +## Template deduction guides +C++17 and above + +```cpp +template +etl::flat_multimap(TPairs...) +``` + +### Example +```cpp +etl::flat_multimap data{ etl::pair{0, 1}, etl::pair{2, 3}, etl::pair{4, 5}, etl::pair{6, 7} }; +``` +Defines data as an `flat_multimap` of `int`/`int` pairs, of length 4, containing the supplied data. + +## make_flat_map +C++11 and above +```cpp +template , + typename... TPairs> +constexpr auto make_flat_map(TValues&&... values) +``` + +### Example +```cpp +auto data = etl::make_flat_map(etl::pair{0, 1}, etl::pair{2, 3}, + etl::pair{4, 5}, etl::pair{6, 7}); +``` + +## Member types + +```cpp +key_type TKey +mapped_type TMapped +value_type pair + The type is either std::pair (default) or etl::pair (ETL_NO_STL) +size_type std::size_t +difference_type std::ptrdiff_t +reference T& +const_reference const T& +rvalue_reference T&& +pointer T* +const_pointer const T* +iterator Random access iterator +const_iterator Constant random access iterator +reverse_iterator reverse_iterator +const_reverse_iterator reverse_iterator +``` + +## Static Constants + +`MAX_SIZE` The maximum size of the flat map. + +## Constructors + +```cpp +etl::flat_multimap() +``` +**Description** +Default constructor. + +--- + +```cpp +etl::flat_multimap(const flat_multimap& other) +``` +**Description** +Copy constructor. + +--- + +```cpp +etl::flat_multimap(flat_multimap&& other) +``` +**Description** +Move constructor. + +--- + +```cpp +template +etl::flat_multimap(TIterator begin, TIterator end); +``` +**Description** +Construct from the range [`begin`, `end`). + +## Element access + +```cpp +TMapped& at(const_key_reference key) +const TMapped& at(const_key_reference key) const +``` +**Description** +Returns a reference or const reference to the indexed element. +Emits an `etl::flat_map_out_of_range` if the key is not in the table. +If asserts or exceptions are not enabled then undefined behaviour occurs. + +--- + +```cpp +TMapped& operator[](const_key_reference key) +const TMapped& operator[](const_key_reference key) const +``` +**Description** +Returns a reference or const reference to the indexed element. +If the key is not in the table then a new entry is created. + +## Iterators + +```cpp +iterator begin() +const_iterator begin() const +const_iterator cbegin() const +``` +**Description** +Returns an iterator to the beginning of the map. + +--- + +```cpp +iterator end() +const_iterator end() const +const_iterator cend() const +``` +**Description** +Returns an iterator to the end of the map. + +--- + +```cpp +iterator rbegin() +const_iterator rbegin() const +const_iterator crbegin() const +``` +**Description** +Returns a reverse iterator to the beginning of the map. + +--- + +```cpp +iterator rend() +const_iterator rend() const +const_iterator crend() const +``` +**Description** +Returns a reverse iterator to the end of the map. + +## Capacity + +```cpp +bool empty() const +``` +**Description** +Returns `true` if the size of the map is zero, otherwise `false`. + +--- + +```cpp +bool full() const +``` +**Description** +Returns `true` if the size of the lookup is `SIZE`, otherwise `false`. + +--- + +```cpp +size_t size() const +``` +**Description** +Returns the size of the lookup. + +--- + +```cpp +size_t max_size() const +``` +**Description** +Returns the maximum possible size of the map. + +--- + +```cpp +size_t available() const +``` +**Description** +Returns the remaining available capacity in the map. + +## Modifiers + +```cpp +flat_multimap& operator = (const flat_multimap& rhs) +flat_multimap& operator = (flat_multimap&& rhs) +``` +**Description** +Copies or moves the data from another flat map. + +--- + +```cpp +pair insert(const value_type& value) +pair insert(value_type&& value) +iterator insert(iterator position, const value_type& value) +iterator insert(iterator position, value_type&& value) +``` +**Description** +Inserts a value into the map. + +```cpp +template +void insert(TIterator first, TIterator last) +``` +**Description** +Inserts values in to the map. +If the map is full then emits an `etl::flat_map_full`. If asserts or exceptions are not enabled then undefined behaviour occurs. +The return type is either `std::pair` (default) or `etl::pair` (`ETL_NO_STL`) + +--- + +```cpp +pair emplace((const value_type& value)) +pair emplace(const key_type& key, const mapped_type& value) +``` +**Description** +Inserts key/value pairs into the map by constructing directly into storage. +The return type is either `std::pair` (default) or `etl::pair` (`ETL_NO_STL`) + +--- + +**C++03** +The emplace functions differ from that of std::map in that, due to C++03 not supporting 'perfect forwarding', the values for constructing mapped types must be listed as parameters and not nested in a 'mapped' value parameter. +The return type is either `std::pair` (default) or `etl::pair` (`ETL_NO_STL`) + +```cpp +template +pair emplace(const key_type& key, const T1& value1) +``` +**Description** +Emplaces a value constructed from `key` and 1 argument into the map. + +```cpp +template +pair emplace(const key_type& key, const T1& value1, const T2& value2) +``` +**Description** +Emplaces a value constructed from `key` and 2 arguments into the map. + +```cpp +template +pair emplace(const key_type& key, const T1& value1, const T2& value2, const T3& value3) +``` +**Description** +Emplaces a value constructed from `key` and 3 arguments into the map. + +```cpp +template +pair emplace(const key_type& key, const T1& value1, const T2& value2, const T3& value3, const T4& value4) +``` +**Description** +Emplaces a value constructed from `key` and 4 arguments into the map. + +--- + +**C++11** +```cpp +template +pair emplace(const key_type& key, Args&& ... args) +``` +**Description** +Emplaces a value constructed from the `key` and arguments into the map. + +--- + +```cpp +size_t erase(key_value_parameter_t key) +void erase(iterator i_element) +void erase(iterator first, iterator last) +``` +**Description** +Erase elements from the map. + +--- + +```cpp +iterator erase(const_iterator i_element) +iterator erase(const_iteratorfirst, const_iteratorlast) +``` +**Description** +Erase elements from the map. +From: `20.20.0` + +--- + +```cpp +template +size_t erase(K&& key) +``` +**Description** +Erases values in the map. +Returns an iterator to the next element in the map. +Iterator parameters are not checked for validity. +From: `20.21.0` + +--- + +```cpp +void clear(); +``` +**Description** +Clears the map to a size of zero. + +## Search + +```cpp +iterator find(key_value_parameter_t key) +const_iterator find(key_value_parameter_t key) const +``` +**Description** +Searches for an element with the key `key`. +Returns an iterator to the element, or `end()` if not found. + +```cpp +iterator lower_bound(key_value_parameter_t key) +const_iterator lower_bound(key_value_parameter_t key) const +``` +**Description** +Searches for an element with the key not less than `key`. +Returns an iterator to the element, or `end()` if not found. + +```cpp +iterator upper_bound(key_value_parameter_t key) +const_iterator upper_bound(key_value_parameter_t key) const +``` +**Description** +Searches for an element with the key greater than `key`. +Returns an iterator to the element, or `end()` if not found. + +```cpp +pair equal_range(key_value_parameter_t key) +pair equal_range(key_value_parameter_t key) const +``` +**Description** +Returns the range of elements with a key equal to `key`. +The return type is either `std::pair` (default) or `etl::pair` (`ETL_NO_STL`) + +--- + +**For comparators that define is_transparent.** + +```cpp +template +iterator find(const K& key) +``` +**Description** +Searches for an element with the key `key`. +Returns an iterator to the element, or `end()` if not found. +From: `20.21.0` +Since: C++11 + +```cpp +template +const_iterator find(const K& key) const +``` +**Description** +Searches for an element with the key `key`. +Returns an iterator to the element, or `end()` if not found. +From: `20.21.0` +Since: C++11 + +--- + +```cpp +template +iterator lower_bound(const K& key) +``` +**Description** +Searches for an element with the key not less than `key`. +Returns an iterator to the element, or `end()` if not found. +From: `20.21.0` +Since: C++11 + +```cpp +template +const_iterator lower_bound(const K& key) const +``` +**Description** +Searches for an element with the key not less than `key`. +Returns an iterator to the element, or `end()` if not found. +From: `20.21.0` +Since: C++11 + +--- + +```cpp +template +iterator upper_bound(const K& key) +``` +**Description** +Searches for an element with the key greater than `key`. +Returns an iterator to the element, or `end()` if not found. +From: `20.21.0` +Since: C++11 + +```cpp +template +const_iterator upper_bound(const K& key) const +``` +**Description** +Searches for an element with the key greater than `key`. +Returns an iterator to the element, or `end()` if not found. +From: `20.21.0` +Since: C++11 + +--- + +```cpp +template +pair equal_range(const K& key) +``` +**Description** +Returns the range of elements with a key equal to `key`. +The return type is either `std::pair` (default) or `etl::pair` (`ETL_NO_STL`) +From: `20.21.0` +Since: C++11 + +```cpp +template +pair equal_range(const K& key) const +``` +**Description** +Returns the range of elements with a key equal to `key`. +The return type is either `std::pair` (default) or `etl::pair` (`ETL_NO_STL`) +From: `20.21.0` +Since: C++11 + +--- + +```cpp +bool contains(key_value_parameter_t key) const +``` +Check if the container contains the key. +From: `20.21.0` + + +--- + +```cpp +template +bool contains(const K& k) const +``` +Check if the container contains the key. +For comparators that define `is_transparent`. +From: `20.21.0` +Since: C++11 + +## Non-member functions + +**Lexicographically comparisons** + +```cpp +operator == +``` +`true` if the contents of the maps are equal, otherwise `false`. + +--- + +```cpp +operator != +``` +`true` if the contents of the maps are not equal, otherwise `false`. + +## Technical stuff + +Flat maps are usually implemented internally as a sorted vector of key/value pairs. Whilst this makes searching fast, it can have a detrimental effect when items are inserted into a container that stores complex, non-trivial keys or values. +As inserting requires that all of the items to the right of the insert position must be shifted this can become an expensive operation for larger containers. + +To improve insertion performance ETL flat maps are implemented as vectors of pointers to key/value pairs, sorted by key value. An insertion will involve a copy of a range of pointers; an operation that can be very fast. + +The downside is that access to an item via an iterator will involve one indirection and the overhead of the container will be one pointer per item. A normal flat map implementation does not have this overhead. diff --git a/docs/containers/maps/map.md b/docs/containers/maps/map.md new file mode 100644 index 00000000..5266d0d2 --- /dev/null +++ b/docs/containers/maps/map.md @@ -0,0 +1,425 @@ +--- +title: "map" +--- + +{{< callout type="info">}} + Header: `map.h` + Similar to: `std::map` +{{< /callout >}} + +A fixed capacity map. +Uses `std::less` as the default key comparison method. + +```cpp +etl::map +``` + +Inherits from `etl::imap`. +`etl::imap` may be used as a size independent pointer or reference type for any etl::map instance. + +## Template deduction guides +C++17 and above + +```cpp +template +etl::map(TPairs...) +``` + +### Example +```cpp +etl::map data{ etl::pair{0, 1}, etl::pair{2, 3}, etl::pair{4, 5}, etl::pair{6, 7} } +``` +Defines data as an map of `int`/`int` pairs, of length 4, containing the supplied data. + +## Make template +**C++11 and above** +```cpp +template , + typename... TPairs> +constexpr auto make_flat_map(TValues&&... values) +``` + +### Example +```cpp +auto data = etl::make_map(etl::pair{0, 1}, etl::pair{2, 3}, + etl::pair{4, 5}, etl::pair{6, 7}); +``` + +## Member types + +```cpp +key_type TKey +mapped_type TMapped +value_type etl or std::pair +size_type size_t +difference_type ptrdiff_t +reference value_type& +const_reference const value_type& +pointer value_type* +const_pointer const value_type* +iterator Random access iterator +const_iterator Constant random access iterator +reverse_iterator etl or std::reverse_iterator +const_reverse_iterator etl or std::reverse_iterator +``` + +## Constructor + +```cpp +etl::map(); +``` +**Description** +Default constructor. + + +```cpp +template +etl::map(TIterator begin, TIterator end); +``` +**Description** +Construct from the range [`begin`, `end`). + +## Element access + +```cpp +TMapped& at(key_parameter_t key) +const TMapped& at(key_parameter_t key) const +``` +**Description** +Returns a reference or const reference to the indexed element. +Asserts an `etl::map_out_of_range` if the key is not in the table. +If assert or exceptions are not enabled then undefined behaviour occurs. + +--- + +```cpp +TMapped& operator[](key_parameter_t key) +const TMapped& operator[](key_parameter_t key) const +``` +**Description** +Returns a reference or const reference to the indexed element. +If the key does not exist then one is created using the default constructor. +If the map is full then asserts an `etl::map_full`. If asserts or exceptions are not enabled then undefined behaviour occurs. + +--- + +```cpp +iterator find(key_parameter_t key); +const_iterator find(key_parameter_t key) const +``` +**Description** +Searches the container for an element with a key equivalent to key and returns an iterator to it if found, otherwise it returns an iterator to `etl::map::end()`. + +--- + +```cpp +size_type count(key_parameter_t key) const +``` +**Description** +Count elements with a specific key. +Searches the container for elements with a key equivalent to key and returns the number of matches + +--- + +```cpp +iterator lower_bound(key_parameter_t key); +const_iterator lower_bound(key_parameter_t key) const +``` +**Description** +Returns an iterator pointing to the first element in the container whose `key` is not considered to go before key (i.e., either it is equivalent or goes after). + +--- + +```cpp +iterator upper_bound(key_parameter_t key); +const_iterator upper_bound(key_parameter_t key) const +``` +**Description** +Returns an iterator pointing to the first element in the container whose key is considered to go after `key`. + +--- + +```cpp +pair equal_range(key_parameter_t key) const +pair equal_range(key_parameter_t key) +``` +**Description** +Returns the bounds of a range that includes all the elements in the container which have a key equivalent to `key`. +The return type is either `std::pair` (default) or `etl::pair` (`ETL_NO_STL`) + +--- + +**For comparators that define `is_transparent`.** + +```cpp +template +iterator find(const K& key) +``` +**Description** +Searches the container for an element with a key equivalent to key and returns an iterator to it if found, otherwise it returns an iterator to `etl::map::end()`. +Since: `20.21.0` +C++11 or above. + +--- + +```cpp +template +const_iterator find(const K& key) const +``` +**Description** +Searches the container for an element with a key equivalent to `key` and returns a const iterator to it if found, otherwise it returns a const iterator to `etl::map::end()`. + +--- + +```cpp +template +iterator lower_bound(const K& key) +``` +**Description** +Returns an iterator pointing to the first element in the container whose key is not considered to go before `key` (i.e., either it is equivalent or goes after). +Since: `20.21.0` +C++11 or above. + +--- + +```cpp +template +const_iterator lower_bound(const K& key) const +``` +**Description** +Returns a const iterator pointing to the first element in the container whose key is not considered to go before `key` (i.e., either it is equivalent or goes after). +Since: `20.21.0` +C++11 or above. + +--- + +```cpp +template +iterator upper_bound(const K& key) +``` +**Description** +Returns an iterator pointing to the first element in the container whose key is considered to go after `key`. +Since: `20.21.0` +C++11 or above. + +--- + +```cpp +template +const_iterator upper_bound(const K& key) const +``` +**Description** +Returns a const iterator pointing to the first element in the container whose key is considered to go after `key`. +Since: `20.21.0` +C++11 or above. + +--- + +```cpp +template +pair equal_range(const K& key) +``` +**Description** +Returns the bounds of a range that includes all the elements in the container which have a key equivalent to `key`. +The return type is either `std::pair` (default) or `etl::pair` (`ETL_NO_STL`) +Since: `20.21.0` +C++11 or above. + +--- + +```cpp +template +pair equal_range(const K& key) const +``` +**Description** +Returns the bounds of a range that includes all the elements in the container which have a key equivalent to `key`. +The return type is either `std::pair` (default) or `etl::pair` (`ETL_NO_STL`) + +--- + +```cpp +bool contains(key_value_parameter_t key) const +``` +**Description** +Check if the container contains the key. +Since: `20.21.0` + +--- + +```cpp +template +bool contains(const K& k) const +``` +**Description** +Check if the container contains the key. +Since: `20.21.0` +C++11 or above. +For comparators that define is_transparent. + +## Iterators + +```cpp +iterator begin() +const_iterator begin() const +const_iterator cbegin() const +``` +**Description** +Returns an iterator to the beginning of the map. + +--- + +```cpp +iterator end() +const_iterator end() const +const_iterator cend() const +``` +**Description** +Returns an iterator to the end of the map. + +--- + +```cpp +iterator rbegin() +const_iterator rbegin() const +const_iterator crbegin() const +``` +**Description** +Returns a reverse iterator to the beginning of the map. + +--- + +```cpp +iterator rend() +const_iterator rend() const +const_iterator crend() const +``` +**Description** +Returns a reverse iterator to the end of the map. + +## Capacity + +```cpp +bool empty() const +``` +**Description** +Returns true if the size of the map is zero, otherwise false. + +--- + +```cpp +bool full() const +``` +**Description** +Returns true if the size of the map is SIZE, otherwise false. + +--- + +```cpp +size_t size() const +``` +**Description** +Returns the size of the map. + +--- + +```cpp +size_t max_size() const +``` +**Description** +Returns the maximum possible size of the map. + +--- + +```cpp +size_t available() const +``` +**Description** +Returns the remaining available capacity in the map. + +--- + +## Modifiers + +```cpp +template +void insert(TIterator begin, TIterator end) +``` +**Description** +Before: `20.20.0` +--- + + +```cpp +template +iterator insert(TIterator begin, TIterator end) +``` +**Description** +Since: `20.20.0` + +--- + +```cpp +iterator insert(mapped_parameter_t value) +``` +**Description** +Inserts values in to the map. +If the map is full then asserts an etl::map_full error. If asserts or exceptions are not enabled then undefined behaviour occurs. + +--- + +```cpp +template +iterator erase(TIterator begin, TIterator end) +``` +**Description** + +--- + +```cpp +iterator erase(TIterator element) +``` +**Description** +Erases values in the map. +Iterator are not checked for validity. + +--- + +```cpp +size_t erase(const key_type& key) +``` +**Description** + +--- + +20.21.0 +```cpp +template +size_t erase(K&& key) +``` +**Description** + +--- + +```cpp +void clear() +``` +**Description** +Clears the map to a size of zero. + +## Non-member functions + +```cpp +operator == +``` +**Description** +`true` if the contents of the maps are equal, otherwise `false`. + +--- + +```cpp +operator != +``` +**Description** +`true` if the contents of the maps are not equal, otherwise `false`. diff --git a/docs/containers/maps/multimap.md b/docs/containers/maps/multimap.md new file mode 100644 index 00000000..96190528 --- /dev/null +++ b/docs/containers/maps/multimap.md @@ -0,0 +1,425 @@ +--- +title: "multimap" +--- + +{{< callout type="info">}} + Header: `multimap.h` + Similar to: `std::multimap` +{{< /callout >}} + +A fixed capacity multimap. +Uses `std::less` as the default key comparison method. + +```cpp +etl::multimap +``` + +Inherits from `etl::imap`. +`etl::imap` may be used as a size independent pointer or reference type for any etl::multimap instance. + +## Template deduction guides +C++17 and above + +```cpp +template +etl::multimap(TPairs...) +``` + +### Example +```cpp +etl::multimap data{ etl::pair{0, 1}, etl::pair{2, 3}, etl::pair{4, 5}, etl::pair{6, 7} } +``` +Defines data as an multimap of `int`/`int` pairs, of length 4, containing the supplied data. + +## Make template +**C++11 and above** +```cpp +template , + typename... TPairs> +constexpr auto make_flat_map(TValues&&... values) +``` + +### Example +```cpp +auto data = etl::make_map(etl::pair{0, 1}, etl::pair{2, 3}, + etl::pair{4, 5}, etl::pair{6, 7}); +``` + +## Member types + +```cpp +key_type TKey +mapped_type TMapped +value_type etl or std::pair +size_type size_t +difference_type ptrdiff_t +reference value_type& +const_reference const value_type& +pointer value_type* +const_pointer const value_type* +iterator Random access iterator +const_iterator Constant random access iterator +reverse_iterator etl or std::reverse_iterator +const_reverse_iterator etl or std::reverse_iterator +``` + +## Constructor + +```cpp +etl::multimap(); +``` +**Description** +Default constructor. + + +```cpp +template +etl::multimap(TIterator begin, TIterator end); +``` +**Description** +Construct from the range [`begin`, `end`). + +## Element access + +```cpp +TMapped& at(key_parameter_t key) +const TMapped& at(key_parameter_t key) const +``` +**Description** +Returns a reference or const reference to the indexed element. +Asserts an `etl::map_out_of_range` if the key is not in the table. +If assert or exceptions are not enabled then undefined behaviour occurs. + +--- + +```cpp +TMapped& operator[](key_parameter_t key) +const TMapped& operator[](key_parameter_t key) const +``` +**Description** +Returns a reference or const reference to the indexed element. +If the key does not exist then one is created using the default constructor. +If the multimap is full then asserts an `etl::map_full`. If asserts or exceptions are not enabled then undefined behaviour occurs. + +--- + +```cpp +iterator find(key_parameter_t key); +const_iterator find(key_parameter_t key) const +``` +**Description** +Searches the container for an element with a key equivalent to key and returns an iterator to it if found, otherwise it returns an iterator to `etl::multimap::end()`. + +--- + +```cpp +size_type count(key_parameter_t key) const +``` +**Description** +Count elements with a specific key. +Searches the container for elements with a key equivalent to key and returns the number of matches + +--- + +```cpp +iterator lower_bound(key_parameter_t key); +const_iterator lower_bound(key_parameter_t key) const +``` +**Description** +Returns an iterator pointing to the first element in the container whose `key` is not considered to go before key (i.e., either it is equivalent or goes after). + +--- + +```cpp +iterator upper_bound(key_parameter_t key); +const_iterator upper_bound(key_parameter_t key) const +``` +**Description** +Returns an iterator pointing to the first element in the container whose key is considered to go after `key`. + +--- + +```cpp +pair equal_range(key_parameter_t key) const +pair equal_range(key_parameter_t key) +``` +**Description** +Returns the bounds of a range that includes all the elements in the container which have a key equivalent to `key`. +The return type is either `std::pair` (default) or `etl::pair` (`ETL_NO_STL`) + +--- + +**For comparators that define `is_transparent`.** + +```cpp +template +iterator find(const K& key) +``` +**Description** +Searches the container for an element with a key equivalent to key and returns an iterator to it if found, otherwise it returns an iterator to `etl::multimap::end()`. +Since: `20.21.0` +C++11 or above. + +--- + +```cpp +template +const_iterator find(const K& key) const +``` +**Description** +Searches the container for an element with a key equivalent to `key` and returns a const iterator to it if found, otherwise it returns a const iterator to `etl::multimap::end()`. + +--- + +```cpp +template +iterator lower_bound(const K& key) +``` +**Description** +Returns an iterator pointing to the first element in the container whose key is not considered to go before `key` (i.e., either it is equivalent or goes after). +Since: `20.21.0` +C++11 or above. + +--- + +```cpp +template +const_iterator lower_bound(const K& key) const +``` +**Description** +Returns a const iterator pointing to the first element in the container whose key is not considered to go before `key` (i.e., either it is equivalent or goes after). +Since: `20.21.0` +C++11 or above. + +--- + +```cpp +template +iterator upper_bound(const K& key) +``` +**Description** +Returns an iterator pointing to the first element in the container whose key is considered to go after `key`. +Since: `20.21.0` +C++11 or above. + +--- + +```cpp +template +const_iterator upper_bound(const K& key) const +``` +**Description** +Returns a const iterator pointing to the first element in the container whose key is considered to go after `key`. +Since: `20.21.0` +C++11 or above. + +--- + +```cpp +template +pair equal_range(const K& key) +``` +**Description** +Returns the bounds of a range that includes all the elements in the container which have a key equivalent to `key`. +The return type is either `std::pair` (default) or `etl::pair` (`ETL_NO_STL`) +Since: `20.21.0` +C++11 or above. + +--- + +```cpp +template +pair equal_range(const K& key) const +``` +**Description** +Returns the bounds of a range that includes all the elements in the container which have a key equivalent to `key`. +The return type is either `std::pair` (default) or `etl::pair` (`ETL_NO_STL`) + +--- + +```cpp +bool contains(key_value_parameter_t key) const +``` +**Description** +Check if the container contains the key. +Since: `20.21.0` + +--- + +```cpp +template +bool contains(const K& k) const +``` +**Description** +Check if the container contains the key. +Since: `20.21.0` +C++11 or above. +For comparators that define is_transparent. + +## Iterators + +```cpp +iterator begin() +const_iterator begin() const +const_iterator cbegin() const +``` +**Description** +Returns an iterator to the beginning of the multimap. + +--- + +```cpp +iterator end() +const_iterator end() const +const_iterator cend() const +``` +**Description** +Returns an iterator to the end of the multimap. + +--- + +```cpp +iterator rbegin() +const_iterator rbegin() const +const_iterator crbegin() const +``` +**Description** +Returns a reverse iterator to the beginning of the multimap. + +--- + +```cpp +iterator rend() +const_iterator rend() const +const_iterator crend() const +``` +**Description** +Returns a reverse iterator to the end of the multimap. + +## Capacity + +```cpp +bool empty() const +``` +**Description** +Returns true if the size of the multimap is zero, otherwise false. + +--- + +```cpp +bool full() const +``` +**Description** +Returns true if the size of the multimap is SIZE, otherwise false. + +--- + +```cpp +size_t size() const +``` +**Description** +Returns the size of the multimap. + +--- + +```cpp +size_t max_size() const +``` +**Description** +Returns the maximum possible size of the multimap. + +--- + +```cpp +size_t available() const +``` +**Description** +Returns the remaining available capacity in the multimap. + +--- + +## Modifiers + +```cpp +template +void insert(TIterator begin, TIterator end) +``` +**Description** +Before: `20.20.0` +--- + + +```cpp +template +iterator insert(TIterator begin, TIterator end) +``` +**Description** +Since: `20.20.0` + +--- + +```cpp +iterator insert(mapped_parameter_t value) +``` +**Description** +Inserts values in to the multimap. +If the multimap is full then asserts an etl::map_full error. If asserts or exceptions are not enabled then undefined behaviour occurs. + +--- + +```cpp +template +iterator erase(TIterator begin, TIterator end) +``` +**Description** + +--- + +```cpp +iterator erase(TIterator element) +``` +**Description** +Erases values in the multimap. +Iterator are not checked for validity. + +--- + +```cpp +size_t erase(const key_type& key) +``` +**Description** + +--- + +20.21.0 +```cpp +template +size_t erase(K&& key) +``` +**Description** + +--- + +```cpp +void clear() +``` +**Description** +Clears the multimap to a size of zero. + +## Non-member functions + +```cpp +operator == +``` +**Description** +`true` if the contents of the maps are equal, otherwise `false`. + +--- + +```cpp +operator != +``` +**Description** +`true` if the contents of the maps are not equal, otherwise `false`. diff --git a/docs/containers/queues/circular-buffer.md b/docs/containers/queues/circular-buffer.md index 389f5910..687ac4b9 100644 --- a/docs/containers/queues/circular-buffer.md +++ b/docs/containers/queues/circular-buffer.md @@ -286,7 +286,20 @@ The internal pointers to the external buffers are swapped. ## 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`. +```cpp +operator == +``` +**Description** +`true` if the contents of the lists are equal, otherwise `false`. + +--- + +```cpp +operator != +``` +**Description** +`true` if the contents of the lists are not equal, otherwise `false`. + +--- `swap` Swaps two circular buffers. A circular buffer with internal storage copies items, while one with an external buffer will swap pointers. diff --git a/docs/containers/sets/flat_multiset.md b/docs/containers/sets/flat_multiset.md new file mode 100644 index 00000000..890fcd52 --- /dev/null +++ b/docs/containers/sets/flat_multiset.md @@ -0,0 +1,500 @@ +--- +title: "flat_multiset" +--- + +{{< callout type="info">}} + Header: `flat_multiset.h` + Similar to: `std::multiset` +{{< /callout >}} + +A fixed capacity multiset based on a sorted vector. +The container is an associative lookup table with O(N) insertion and erase, and O(log N) search. +This container is best used for tables that are occasionally updated and spend most of their time being searched. +Uses `etl::less` as the default key comparison method. + +```cpp +etl::flat_multiset +``` + +Inherits from `etl::iflat_set`. +`etl::iflat_set` may be used as a size independent pointer or reference type for any `etl::flat_multiset` instance. + +## Template deduction guides +C++17 and above + +```cpp +template +etl::flat_multiset(T...) +``` + +### Example +```cpp +etl::flat_multiset data{ 0, 1, 2, 3 }; +``` +Defines data as an `flat_multiset` of `int`, of length 4, containing the supplied data. + +## make_flat_set +C++11 and above +```cpp +template > +constexpr auto make_flat_set(TValues&&... values) +``` + +### Example +```cpp +auto data = etl::make_flat_set({0, 1, 2, 3 }); +``` + +## Member types + +```cpp +key_type T +value_type T +size_type std::size_t +difference_type std::ptrdiff_t +reference reference +const_reference const_reference +rvalue_reference reference& +pointer T* +const_pointer const T* +iterator Random access iterator +const_iterator Constant random access iterator +reverse_iterator reverse_iterator +const_reverse_iterator reverse_iterator +``` + +## Static Constants + +`MAX_SIZE` The maximum size of the flat set. + +## Constructors + +```cpp +etl::flat_multiset() +``` +**Description** +Default constructor. + +--- + +```cpp +etl::flat_multiset(const flat_multiset& other) +``` +**Description** +Copy constructor. + +--- + +```cpp +etl::flat_multiset(flat_multiset&& other) +``` +**Description** +Move constructor. + +--- + +```cpp +template +etl::flat_multiset(TIterator begin, TIterator end); +``` +**Description** +Construct from the range [`begin`, `end`). + +## Element access + +```cpp +reference at(const_reference key) +const_reference at(const_reference key) const +``` +**Description** +Returns a reference or const reference to the indexed element. +Emits an `etl::flat_set_out_of_range` if the key is not in the table. +If asserts or exceptions are not enabled then undefined behaviour occurs. + +--- + +```cpp +reference operator[](const_reference key) +const_reference operator[](const_reference key) const +``` +**Description** +Returns a reference or const reference to the indexed element. +If the key is not in the table then a new entry is created. + +## Iterators + +```cpp +iterator begin() +const_iterator begin() const +const_iterator cbegin() const +``` +**Description** +Returns an iterator to the beginning of the set. + +--- + +```cpp +iterator end() +const_iterator end() const +const_iterator cend() const +``` +**Description** +Returns an iterator to the end of the set. + +--- + +```cpp +iterator rbegin() +const_iterator rbegin() const +const_iterator crbegin() const +``` +**Description** +Returns a reverse iterator to the beginning of the set. + +--- + +```cpp +iterator rend() +const_iterator rend() const +const_iterator crend() const +``` +**Description** +Returns a reverse iterator to the end of the set. + +## Capacity + +```cpp +bool empty() const +``` +**Description** +Returns `true` if the size of the set is zero, otherwise `false`. + +--- + +```cpp +bool full() const +``` +**Description** +Returns `true` if the size of the lookup is `SIZE`, otherwise `false`. + +--- + +```cpp +size_t size() const +``` +**Description** +Returns the size of the lookup. + +--- + +```cpp +size_t max_size() const +``` +**Description** +Returns the maximum possible size of the set. + +--- + +```cpp +size_t available() const +``` +**Description** +Returns the remaining available capacity in the set. + +## Modifiers + +```cpp +flat_multiset& operator = (const flat_multiset& rhs) +flat_multiset& operator = (flat_multiset&& rhs) +``` +**Description** +Copies or moves the data from another flat set. + +--- + +```cpp +pair insert(const_reference value) +pair insert(rvalue_reference value) +iterator insert(iterator position, const_reference value) +iterator insert(iterator position, rvalue_reference value) +``` +**Description** +Inserts a value into the set. + +```cpp +template +void insert(TIterator first, TIterator last) +``` +**Description** +Inserts values in to the set. +If the set is full then emits an `etl::flat_set_full`. If asserts or exceptions are not enabled then undefined behaviour occurs. +The return type is either `std::pair` (default) or `etl::pair` (`ETL_NO_STL`) + +--- + +```cpp +pair emplace((const_reference value)) +pair emplace(const key_type& key, const mapped_type& value) +``` +**Description** +Inserts key/value pairs into the set by constructing directly into storage. +The return type is either `std::pair` (default) or `etl::pair` (`ETL_NO_STL`) + +--- + +**C++03** +The emplace functions differ from that of std::set in that, due to C++03 not supporting 'perfect forwarding'. + +```cpp +template +pair emplace(const key_type& key, const T1& value1) +``` +**Description** +Emplaces a value constructed from `key` and 1 argument into the set. + +```cpp +template +pair emplace(const key_type& key, const T1& value1, const T2& value2) +``` +**Description** +Emplaces a value constructed from `key` and 2 arguments into the set. + +```cpp +template +pair emplace(const key_type& key, const T1& value1, const T2& value2, const T3& value3) +``` +**Description** +Emplaces a value constructed from `key` and 3 arguments into the set. + +```cpp +template +pair emplace(const key_type& key, const T1& value1, const T2& value2, const T3& value3, const T4& value4) +``` +**Description** +Emplaces a value constructed from `key` and 4 arguments into the set. + +--- + +**C++11** +```cpp +template +pair emplace(const key_type& key, Args&& ... args) +``` +**Description** +Emplaces a value constructed from the `key` and arguments into the set. + +--- + +```cpp +size_t erase(key_value_parameter_t key) +void erase(iterator i_element) +void erase(iterator first, iterator last) +``` +**Description** +Erase elements from the set. + +--- + +```cpp +iterator erase(const_iterator i_element) +iterator erase(const_iteratorfirst, const_iteratorlast) +``` +**Description** +Erase elements from the set. +From: `20.20.0` + +--- + +```cpp +template +size_t erase(K&& key) +``` +**Description** +Erases values in the set. +Returns an iterator to the next element in the set. +Iterator parameters are not checked for validity. +From: `20.21.0` + +--- + +```cpp +void clear(); +``` +**Description** +Clears the set to a size of zero. + +## Search + +```cpp +iterator find(key_value_parameter_t key) +const_iterator find(key_value_parameter_t key) const +``` +**Description** +Searches for an element with the key `key`. +Returns an iterator to the element, or `end()` if not found. + +--- + +```cpp +iterator lower_bound(key_value_parameter_t key) +const_iterator lower_bound(key_value_parameter_t key) const +``` +**Description** +Searches for an element with the key not less than `key`. +Returns an iterator to the element, or `end()` if not found. + +--- + +```cpp +iterator upper_bound(key_value_parameter_t key) +const_iterator upper_bound(key_value_parameter_t key) const +``` +**Description** +Searches for an element with the key greater than `key`. +Returns an iterator to the element, or `end()` if not found. + +--- + +```cpp +pair equal_range(key_value_parameter_t key) +pair equal_range(key_value_parameter_t key) const +``` +**Description** +Returns the range of elements with a key equal to `key`. +The return type is either `std::pair` (default) or `etl::pair` (`ETL_NO_STL`) + +--- + +**For comparators that define is_transparent.** + +```cpp +template +iterator find(const K& key) +``` +**Description** +Searches for an element with the key `key`. +Returns an iterator to the element, or `end()` if not found. +From: `20.21.0` +Since: C++11 + +```cpp +template +const_iterator find(const K& key) const +``` +**Description** +Searches for an element with the key `key`. +Returns an iterator to the element, or `end()` if not found. +From: `20.21.0` +Since: C++11 + +--- + +```cpp +template +iterator lower_bound(const K& key) +``` +**Description** +Searches for an element with the key not less than `key`. +Returns an iterator to the element, or `end()` if not found. +From: `20.21.0` +Since: C++11 + +```cpp +template +const_iterator lower_bound(const K& key) const +``` +**Description** +Searches for an element with the key not less than `key`. +Returns an iterator to the element, or `end()` if not found. +From: `20.21.0` +Since: C++11 + +--- + +```cpp +template +iterator upper_bound(const K& key) +``` +**Description** +Searches for an element with the key greater than `key`. +Returns an iterator to the element, or `end()` if not found. +From: `20.21.0` +Since: C++11 + +```cpp +template +const_iterator upper_bound(const K& key) const +``` +**Description** +Searches for an element with the key greater than `key`. +Returns an iterator to the element, or `end()` if not found. +From: `20.21.0` +Since: C++11 + +--- + +```cpp +template +pair equal_range(const K& key) +``` +**Description** +Returns the range of elements with a key equal to `key`. +The return type is either `std::pair` (default) or `etl::pair` (`ETL_NO_STL`) +From: `20.21.0` +Since: C++11 + +```cpp +template +pair equal_range(const K& key) const +``` +**Description** +Returns the range of elements with a key equal to `key`. +The return type is either `std::pair` (default) or `etl::pair` (`ETL_NO_STL`) +From: `20.21.0` +Since: C++11 + +--- + +```cpp +bool contains(key_value_parameter_t key) const +``` +Check if the container contains the key. +From: `20.21.0` + + +--- + +```cpp +template +bool contains(const K& k) const +``` +Check if the container contains the key. +For comparators that define `is_transparent`. +From: `20.21.0` +Since: C++11 + +## Non-member functions + +**Lexicographically comparisons** + +```cpp +operator == +``` +`true` if the contents of the maps are equal, otherwise `false`. + +--- + +```cpp +operator != +``` +`true` if the contents of the maps are not equal, otherwise `false`. + +## Technical stuff + +Flat maps are usually implemented internally as a sorted vector of key/value pairs. Whilst this makes searching fast, it can have a detrimental effect when items are inserted into a container that stores complex, non-trivial keys or values. +As inserting requires that all of the items to the right of the insert position must be shifted this can become an expensive operation for larger containers. + +To improve insertion performance ETL flat maps are implemented as vectors of pointers to key/value pairs, sorted by key value. An insertion will involve a copy of a range of pointers; an operation that can be very fast. + +The downside is that access to an item via an iterator will involve one indirection and the overhead of the container will be one pointer per item. A normal flat set implementation does not have this overhead. diff --git a/docs/containers/sets/flat_set.md b/docs/containers/sets/flat_set.md index 3c1a5e91..6f9c0540 100644 --- a/docs/containers/sets/flat_set.md +++ b/docs/containers/sets/flat_set.md @@ -244,15 +244,18 @@ The return type is either `std::pair` (default) or `etl::pair` (`ETL_NO_STL`) --- **C++03** -The emplace functions differ from that of std::set in that, due to C++03 not supporting 'perfect forwarding'. +The emplace functions differ from that of `std::set` due to C++03 not supporting 'perfect forwarding'. ```cpp template pair emplace(const key_type& key, const T1& value1) ``` **Description** + Emplaces a value constructed from `key` and 1 argument into the set. +--- + ```cpp template pair emplace(const key_type& key, const T1& value1, const T2& value2) @@ -260,6 +263,8 @@ pair emplace(const key_type& key, const T1& value1, const T2& va **Description** Emplaces a value constructed from `key` and 2 arguments into the set. +--- + ```cpp template pair emplace(const key_type& key, const T1& value1, const T2& value2, const T3& value3) @@ -267,6 +272,8 @@ pair emplace(const key_type& key, const T1& value1, const T2& va **Description** Emplaces a value constructed from `key` and 3 arguments into the set. +--- + ```cpp template pair emplace(const key_type& key, const T1& value1, const T2& value2, const T3& value3, const T4& value4) @@ -277,6 +284,7 @@ Emplaces a value constructed from `key` and 4 arguments into the set. --- **C++11** + ```cpp template pair emplace(const key_type& key, Args&& ... args) @@ -334,6 +342,8 @@ const_iterator find(key_value_parameter_t key) const Searches for an element with the key `key`. Returns an iterator to the element, or `end()` if not found. +--- + ```cpp iterator lower_bound(key_value_parameter_t key) const_iterator lower_bound(key_value_parameter_t key) const @@ -342,6 +352,8 @@ const_iterator lower_bound(key_value_parameter_t key) const Searches for an element with the key not less than `key`. Returns an iterator to the element, or `end()` if not found. +--- + ```cpp iterator upper_bound(key_value_parameter_t key) const_iterator upper_bound(key_value_parameter_t key) const @@ -350,6 +362,8 @@ const_iterator upper_bound(key_value_parameter_t key) const Searches for an element with the key greater than `key`. Returns an iterator to the element, or `end()` if not found. +--- + ```cpp pair equal_range(key_value_parameter_t key) pair equal_range(key_value_parameter_t key) const @@ -372,6 +386,8 @@ Returns an iterator to the element, or `end()` if not found. From: `20.21.0` Since: C++11 +--- + ```cpp template const_iterator find(const K& key) const @@ -394,6 +410,8 @@ Returns an iterator to the element, or `end()` if not found. From: `20.21.0` Since: C++11 +--- + ```cpp template const_iterator lower_bound(const K& key) const @@ -416,6 +434,8 @@ Returns an iterator to the element, or `end()` if not found. From: `20.21.0` Since: C++11 +--- + ```cpp template const_iterator upper_bound(const K& key) const @@ -438,6 +458,8 @@ The return type is either `std::pair` (default) or `etl::pair` (`ETL_NO_STL`) From: `20.21.0` Since: C++11 +--- + ```cpp template pair equal_range(const K& key) const diff --git a/docs/containers/sets/multiset.md b/docs/containers/sets/multiset.md new file mode 100644 index 00000000..9bf091c8 --- /dev/null +++ b/docs/containers/sets/multiset.md @@ -0,0 +1,416 @@ +--- +title: "multiset" +--- + +{{< callout type="info">}} + Header: `multiset.h` + Similar to: `std::multiset` +{{< /callout >}} + +A fixed capacity multiset. +Uses etl or `std::less` as the default key comparison method. + +```cpp +etl::multiset +``` + +Inherits from `etl::iset`. +`etl::iset` may be used as a size independent pointer or reference type for any `etl::multiset` instance. + +## Template deduction guides +C++17 and above + +```cpp +template +etl::multiset(TPairs...) +``` + +### Example +```cpp +etl::multiset data{ 0, 1, 2, 3, 4, 5, 6, 7 }; +``` +Defines data as an multiset of `int`, of length 8, containing the supplied data. + +## Make template +**C++11 and above** + +```cpp +template , + typename... TPairs> +constexpr auto make_set(TValues&&... values) +``` + +### Example +```cpp +auto data = etl::make_set(0, 1, 2, 3, 4, 5, 6, 7); +``` + +## Member types + +```cpp +value_type T +size_type size_t +difference_type ptrdiff_t +reference value_type& +const_reference const value_type& +pointer value_type* +const_pointer const value_type* +iterator Random access iterator +const_iterator Constant random access iterator +reverse_iterator ETL_OR_STD::reverse_iterator +const_reverse_iterator ETL_OR_STD::reverse_iterator +``` + +## Constructors + +```cpp +etl::multiset() +``` +**Description** + +--- + +```cpp +template +etl::multiset(TIterator begin, TIterator end) +``` +**Description** +If the map is full then emits an `etl::reference_flat_set_full`. +If asserts or exceptions are not enabled then undefined behaviour occurs. + +## Element access + +```cpp +iterator find(const value_type& v) +const_iterator find(const value_type& v) const +``` +**Description** +Searches the container for an element with a value of `v` and returns an iterator to it if found, otherwise it returns an iterator to `etl::multiset::end()`. + +--- + +```cpp +size_type count(const value_type& v) const +``` +**Description** +Count elements with a specific key. +Searches the container for elements with a value of `v` and returns the number of matches + +--- + +```cpp +iterator lower_bound(const value_type& v) +const_iterator lower_bound(const value_type& v) const +``` +**Description** +Searches for an element with the key not less than `v`. +Returns an iterator to the element, or `end()` if not found. + +--- + +```cpp +iterator upper_bound(const value_type& v) +const_iterator upper_bound (const value_type& v) const +``` +**Description** +Searches for an element with the key greater than `v`. +Returns an iterator to the element, or `end()` if not found. + +--- + +```cpp +pair equal_range(const value_type& v) const +pair equal_range(const value_type& v) +``` +**Description** +Returns the range of elements with a key equal to `v`. +The return type is either `std::pair` (default) or `etl::pair` (`ETL_NO_STL`) + +--- + +**For comparators that define `is_transparent`.** + +```cpp +template +iterator find(const K& key) +``` +**Description** +Since: `20.21.0` +C++11 or above. + + +--- + +```cpp +template +const_iterator find(const K& key) const +``` +**Description** +Since: `20.21.0` +C++11 or above. + +--- + +```cpp +template +iterator lower_bound(const K& key) +``` +**Description** +Searches for an element with the key not less than `key`. +Returns an iterator to the element, or `end()` if not found. +Since: `20.21.0` +C++11 or above. + +--- + +```cpp +template +const_iterator lower_bound(const K& key) const +``` +**Description** +Searches for an element with the key not less than `key`. +Returns a const iterator to the element, or `end()` if not found. +Since: `20.21.0` +C++11 or above. + +--- + +```cpp +template +iterator upper_bound(const K& key) +``` +**Description** +Searches for an element with the key greater than `key`. +Returns an iterator to the element, or `end()` if not found. +Since: `20.21.0` +C++11 or above. + +--- + +```cpp +template +const_iterator upper_bound(const K& key) const +``` +**Description** +Searches for an element with the key greater than `key`. +Returns a const iterator to the element, or `end()` if not found. +Since: `20.21.0` +C++11 or above. + +--- + +```cpp +template +pair equal_range(const K& key) +``` +**Description** +Returns the range of elements with a key equal to `key`. +The return type is either `std::pair` (default) or `etl::pair` (`ETL_NO_STL`) +Since: `20.21.0` +C++11 or above. + +--- + +```cpp +template +pair equal_range(const K& key) const +``` +**Description** +Returns the range of elements with a key equal to `key`. +The return type is either `std::pair` (default) or `etl::pair` (`ETL_NO_STL`) +Since: `20.21.0` +C++11 or above. + +--- + +```cpp +bool contains(key_value_parameter_t key) const +``` +**Description** +Check if the container contains the key. +Since: `20.21.0` + +--- + +For comparators that define is_transparent. +```cpp +template +``` +**Description** +Since: `20.21.0` +C++11 or above. + +--- + +```cpp +bool contains(const K& k) const +``` +Check if the container contains the key. +Since: `20.21.0` +C++11 or above. + +## Iterators + +```cpp +iterator begin() +const_iterator begin() const +const_iterator cbegin() const +``` +**Description** +Returns an iterator to the beginning of the map. + +--- + +```cpp +iterator end() +const_iterator end() const +const_iterator cend() const +``` +**Description** +Returns an iterator to the end of the map. + +--- + +```cpp +iterator rbegin() +const_iterator rbegin() const +const_iterator crbegin() const +``` +**Description** +Returns a reverse iterator to the beginning of the map. + +--- + +```cpp +iterator rbegin() +const_iterator rbegin() const +const_iterator crbegin() const +``` +**Description** +Returns a reverse iterator to the beginning of the map. + +## Capacity + +```cpp +bool empty() const +``` +**Description** +Returns true if the size of the map is zero, otherwise false. + +--- + +```cpp +bool full() const +``` +**Description** +Returns true if the size of the map is SIZE, otherwise false. + +--- + +```cpp +size_t size() const +``` +**Description** +Returns the size of the map. + +--- + +```cpp +size_t max_size() const +``` +**Description** +Returns the maximum possible size of the map. + +--- + +```cpp +size_t available() const +``` +**Description** +Returns the remaining available capacity in the map. + +## Modifiers + +<=20.19.0 +```cpp +template +void insert(TIterator begin, TIterator end) +``` +**Description** + +--- + +>=20.20.0 +```cpp +template +iterator insert(TIterator begin, TIterator end) +``` +**Description** + +--- + +```cpp +iterator insert(parameter_t value) +``` +**Description** +Inserts values in to the map. +If the multiset is full then emits an `etl::multiset_full`. +If asserts or exceptions are not enabled then undefined behaviour occurs. + +--- + +```cpp +template +iterator erase(TIterator begin, TIterator end) +``` +**Description** + +--- + +```cpp +iterator erase(TIterator element) +``` +**Description** +Erases values in the multiset. +Iterators are not checked for validity. + +--- + +```cpp +size_t erase(const key_type& key) +``` +**Description** + +---- + +20.21.0 +```cpp +template +size_t erase(K&& key) +``` +**Description** + +--- + +```cpp +void clear() +``` +**Description** +Clears the map to a size of zero. + +## Non-member functions + +```cpp +operator == +``` +**Description** +`true` if the contents of the sets are equal, otherwise `false`. + +--- + +```cpp +operator != +``` +**Description** +`true` if the contents of the sets are not equal, otherwise `false`. diff --git a/docs/containers/sets/set.md b/docs/containers/sets/set.md new file mode 100644 index 00000000..cec118bd --- /dev/null +++ b/docs/containers/sets/set.md @@ -0,0 +1,415 @@ +--- +title: "set" +--- + +{{< callout type="info">}} + Header: `set.h` + Similar to: `std::set` +{{< /callout >}} + +A fixed capacity set. +Uses etl or `std::less` as the default key comparison method. + +```cpp +etl::set +``` + +Inherits from `etl::iset`. +`etl::iset` may be used as a size independent pointer or reference type for any `etl::set` instance. + +## Template deduction guides +C++17 and above + +```cpp +template +etl::set(TPairs...) +``` + +### Example +```cpp +etl::set data{ 0, 1, 2, 3, 4, 5, 6, 7 }; +``` +Defines data as an set of `int`, of length 8, containing the supplied data. + +## Make template +**C++11 and above** + +```cpp +template , + typename... TPairs> +constexpr auto make_set(TValues&&... values) +``` + +### Example +```cpp +auto data = etl::make_set(0, 1, 2, 3, 4, 5, 6, 7); +``` + +## Member types + +```cpp +value_type T +size_type size_t +difference_type ptrdiff_t +reference value_type& +const_reference const value_type& +pointer value_type* +const_pointer const value_type* +iterator Random access iterator +const_iterator Constant random access iterator +reverse_iterator ETL_OR_STD::reverse_iterator +const_reverse_iterator ETL_OR_STD::reverse_iterator +``` + +## Constructors + +```cpp +etl::set() +``` +**Description** + +--- + +```cpp +template +etl::set(TIterator begin, TIterator end) +``` +**Description** +If the map is full then emits an `etl::reference_flat_set_full`. +If asserts or exceptions are not enabled then undefined behaviour occurs. + +## Element access + +```cpp +iterator find(const value_type& v) +const_iterator find(const value_type& v) const +``` +**Description** +Searches the container for an element with a value of `v` and returns an iterator to it if found, otherwise it returns an iterator to `etl::set::end()`. + +--- + +```cpp +size_type count(const value_type& v) const +``` +**Description** +Count elements with a specific key. +Searches the container for elements with a value of `v` and returns the number of matches + +--- + +```cpp +iterator lower_bound(const value_type& v) +const_iterator lower_bound(const value_type& v) const +``` +**Description** +Searches for an element with the key not less than `v`. +Returns an iterator to the element, or `end()` if not found. + +--- + +```cpp +iterator upper_bound(const value_type& v) +const_iterator upper_bound (const value_type& v) const +``` +**Description** +Searches for an element with the key greater than `v`. +Returns an iterator to the element, or `end()` if not found. + +--- + +```cpp +pair equal_range(const value_type& v) const +pair equal_range(const value_type& v) +``` +**Description** +Returns the range of elements with a key equal to `v`. +The return type is either `std::pair` (default) or `etl::pair` (`ETL_NO_STL`) + +--- + +**For comparators that define `is_transparent`.** + +```cpp +template +iterator find(const K& key) +``` +**Description** +Since: `20.21.0` +C++11 or above. + + +--- + +```cpp +template +const_iterator find(const K& key) const +``` +**Description** +Since: `20.21.0` +C++11 or above. + +--- + +```cpp +template +iterator lower_bound(const K& key) +``` +**Description** +Searches for an element with the key not less than `key`. +Returns an iterator to the element, or `end()` if not found. +Since: `20.21.0` +C++11 or above. + +--- + +```cpp +template +const_iterator lower_bound(const K& key) const +``` +**Description** +Searches for an element with the key not less than `key`. +Returns a const iterator to the element, or `end()` if not found. +Since: `20.21.0` +C++11 or above. + +--- + +```cpp +template +iterator upper_bound(const K& key) +``` +**Description** +Searches for an element with the key greater than `key`. +Returns an iterator to the element, or `end()` if not found. +Since: `20.21.0` +C++11 or above. + +--- + +```cpp +template +const_iterator upper_bound(const K& key) const +``` +**Description** +Searches for an element with the key greater than `key`. +Returns a const iterator to the element, or `end()` if not found. +Since: `20.21.0` +C++11 or above. + +--- + +```cpp +template +pair equal_range(const K& key) +``` +**Description** +Returns the range of elements with a key equal to `key`. +The return type is either `std::pair` (default) or `etl::pair` (`ETL_NO_STL`) +Since: `20.21.0` +C++11 or above. + +--- + +```cpp +template +pair equal_range(const K& key) const +``` +**Description** +Returns the range of elements with a key equal to `key`. +The return type is either `std::pair` (default) or `etl::pair` (`ETL_NO_STL`) +Since: `20.21.0` +C++11 or above. + +--- + +```cpp +bool contains(key_value_parameter_t key) const +``` +**Description** +Check if the container contains the key. +Since: `20.21.0` + +--- + +For comparators that define is_transparent. +```cpp +template +``` +**Description** +Since: `20.21.0` +C++11 or above. + +--- + +```cpp +bool contains(const K& k) const +``` +Check if the container contains the key. +Since: `20.21.0` +C++11 or above. + +## Iterators + +```cpp +iterator begin() +const_iterator begin() const +const_iterator cbegin() const +``` +**Description** +Returns an iterator to the beginning of the map. + +--- + +```cpp +iterator end() +const_iterator end() const +const_iterator cend() const +``` +**Description** +Returns an iterator to the end of the map. + +--- + +```cpp +iterator rbegin() +const_iterator rbegin() const +const_iterator crbegin() const +``` +**Description** +Returns a reverse iterator to the beginning of the map. + +--- + +```cpp +iterator rbegin() +const_iterator rbegin() const +const_iterator crbegin() const +``` +**Description** +Returns a reverse iterator to the beginning of the map. + +## Capacity + +```cpp +bool empty() const +``` +**Description** +Returns true if the size of the map is zero, otherwise false. + +--- + +```cpp +bool full() const +``` +**Description** +Returns true if the size of the map is SIZE, otherwise false. + +--- + +```cpp +size_t size() const +``` +**Description** +Returns the size of the map. + +--- + +```cpp +size_t max_size() const +``` +**Description** +Returns the maximum possible size of the map. + +--- + +```cpp +size_t available() const +``` +**Description** +Returns the remaining available capacity in the map. + +## Modifiers + +<=20.19.0 +```cpp +template +void insert(TIterator begin, TIterator end) +``` +**Description** + +--- + +>=20.20.0 +```cpp +template +iterator insert(TIterator begin, TIterator end) +``` +**Description** + +--- + +```cpp +iterator insert(parameter_t value) +``` +**Description** +If the set is full then emits an `etl::set_full`. +If asserts or exceptions are not enabled then undefined behaviour occurs. + +--- + +```cpp +template +iterator erase(TIterator begin, TIterator end) +``` +**Description** + +--- + +```cpp +iterator erase(TIterator element) +``` +**Description** +Erases values in the set. +Iterators are not checked for validity. + +--- + +```cpp +size_t erase(const key_type& key) +``` +**Description** + +---- + +20.21.0 +```cpp +template +size_t erase(K&& key) +``` +**Description** + +--- + +```cpp +void clear() +``` +**Description** +Clears the map to a size of zero. + +## Non-member functions + +```cpp +operator == +``` +**Description** +`true` if the contents of the sets are equal, otherwise `false`. + +--- + +```cpp +operator != +``` +**Description** +`true` if the contents of the sets are not equal, otherwise `false`. diff --git a/docs/containers/tuple.md b/docs/containers/tuple.md new file mode 100644 index 00000000..74fbaf4f --- /dev/null +++ b/docs/containers/tuple.md @@ -0,0 +1,853 @@ +--- +title: "tuple" +--- + +{{< callout type="info">}} + Header: `tuple.h` + Similar to: `std::tuple` +{{< /callout >}} + +C++11 and above. +A fixed-size collection of heterogeneous values. + +```cpp +template +class tuple +``` + +## Traits + +```cpp +template +struct is_tuple +``` +Type trait to check if a type is an `etl::tuple` + +## Types +```cpp +using value_type = THead; ///< The type contained by this tuple. +using this_type = tuple; ///< The type of this tuple. +using base_type = tuple; ///< The type of the base tuple. +using type_list = etl::type_list; ///< The type list for this tuple. +using index_sequence_type = etl::make_index_sequence< number_of_types< THead, TTail...>()>; ///< The index_sequence type for this tuple. +``` + +## Constants + +```cpp +inline constexpr private_tuple::ignore_t ignore; +``` +From: C++17 + +--- + +```cpp +static constexpr private_tuple::ignore_t ignore; +``` +Before: C++17 + +## Constructors + +```cpp +ETL_CONSTEXPR14 +tuple() +``` +**Description** +Default constructor. + +--- + +```cpp +ETL_CONSTEXPR14 +tuple(const tuple& other) = default; +``` +**Description** +Copy constructor. + +--- + +```cpp +ETL_CONSTEXPR14 +tuple(tuple&& other) = default; +``` +**Description** +Move constructor. + +--- + +```cpp +ETL_CONSTEXPR14 +tuple& operator=(const tuple& other) = default; +``` +**Description** +Copy assignment. + +--- + +```cpp +ETL_CONSTEXPR14 +tuple& operator=(tuple&& other) = default; +``` +**Description** +Move assignment. + +--- + +```cpp +template +ETL_CONSTEXPR14 +tuple(tuple& other) +``` +**Description** +Copy construct from lvalue reference tuple type. +Implicit conversion. + +Enabled if:- +- The number of `UTypes` == number of `TTypes`. +- The number of `TTYpes` >= 1. +- `UTypes` are convertible to `TTypes`. + +--- + +```cpp +template +ETL_CONSTEXPR14 +explicit tuple(tuple& other) +``` +**Description** +Copy construct from lvalue reference tuple type. +Explicit conversion. + +Enabled if:- +- The number of `UTypes` == number of `TTypes`. +- The number of `TTYpes` >= 1. +- `UTypes` are **not** convertible to `TTypes`. + +--- + +```cpp +template +ETL_CONSTEXPR14 +tuple(const tuple& other) +``` +**Description** +Copy construct from const lvalue reference tuple type. +Implicit conversion. + +Enabled if:- +- The number of `UTypes` == number of `TTypes`. +- The number of `TTYpes` >= 1. +- `UTypes` are convertible to `TTypes`. + +--- + +```cpp +template +ETL_CONSTEXPR14 +explicit tuple(const tuple& other) +``` +**Description** +Copy construct from const lvalue reference tuple type. +Explicit conversion. + +Enabled if:- +- The number of `UTypes` == number of `TTypes`. +- The number of `TTYpes` >= 1. +- `UTypes` are **not** convertible to `TTypes`. + +--- + +```cpp +template +ETL_CONSTEXPR14 +tuple(tuple&& other) +``` +**Description** +Move construct from rvalue reference tuple type. +Implicit conversion + +Enabled if:- +- The number of `UTypes` == number of `TTypes`. +- The number of `TTYpes` >= 1. +- `UTypes` are convertible to `TTypes`. + +--- + +```cpp +template +ETL_CONSTEXPR14 +explicit tuple(tuple&& other) +``` +**Description** +Move construct from rvalue reference tuple type. +Explicit conversion. + +Enabled if:- +- The number of `UTypes` == number of `TTypes`. +- The number of `TTYpes` >= 1. +- `UTypes` are **not** convertible to `TTypes`. + +--- + +```cpp +template +ETL_CONSTEXPR14 +tuple(const tuple&& other) +``` +**Description** +Move construct from const rvalue reference tuple type. +Implicit conversion + +Enabled if:- +- The number of `UTypes` == number of `TTypes`. +- The number of `TTYpes` >= 1. +- `UTypes` are convertible to `TTypes`. + +--- + +```cpp +template +ETL_CONSTEXPR14 +explicit tuple(const tuple&& other) +``` +**Description** +Move construct from const rvalue reference tuple type. +Explicit conversion. + +Enabled if:- +- The number of `UTypes` == number of `TTypes`. +- The number of `TTYpes` >= 1. +- `UTypes` are **not** convertible to `TTypes`. + +--- + +```cpp +ETL_CONSTEXPR14 +tuple(const TTypes&... args) +``` +**Description** +Construct from arguments. + +--- + +```cpp +template +ETL_CONSTEXPR14 +tuple(UHead&& head, UTail&&... tail) ETL_NOEXCEPT +``` +**Description** +Construct from arguments. +Implicit conversion. + +Enabled if:- +- The number of `UTypes` == number of `TTypes`. +- The number of `TTYpes` >= 1. +- `UTypes` are not convertible to `TTypes`. + +--- + +```cpp +template +ETL_CONSTEXPR14 +explicit tuple(UHead&& head, UTail&&... tail) ETL_NOEXCEPT +``` +**Description** +Construct from arguments. +Explicit conversion. + +Enabled if:- +- The number of `UTypes` == number of `TTypes`. +- The number of `TTYpes` >= 1. +- `UTypes` are **not** convertible to `TTypes`. + +--- + +```cpp +template & p) ETL_NOEXCEPT +``` +**Description** +Construct from lvalue reference pair. +Implicit conversion. + +Enabled if:- +- The number of `TTYpes` == 2. +- `U1` and `U2` are convertible to `TTypes`. + +--- + +```cpp +template & p) ETL_NOEXCEPT +``` +**Description** +Construct from lvalue reference pair. +Explicit conversion. + +Enabled if:- +- The number of `TTYpes` == 2. +- `U1` or `U2` are not convertible to `TTypes`. + +--- + +```cpp +template & p) ETL_NOEXCEPT +``` +**Description** +Construct from const lvalue reference pair. +Implicit conversion. + +Enabled if:- +- The number of `TTYpes` == 2. +- `U1` and `U2` are convertible to `TTypes`. + +--- + +```cpp +template & p) ETL_NOEXCEPT +``` +**Description** +Construct from const lvalue reference pair. +Explicit conversion. + +Enabled if:- +- The number of `TTYpes` == 2. +- `U1` or `U2` are not convertible to `TTypes`. + +--- + +```cpp +template && p) ETL_NOEXCEPT +``` +**Description** +Construct from rvalue reference pair. +Implicit conversion. + +Enabled if:- +- The number of `TTYpes` == 2. +- `U1` and `U2` are convertible to `TTypes`. + +--- + +```cpp +template && p) ETL_NOEXCEPT +``` +**Description** +Construct from rvalue reference pair. +Explicit conversion. + +Enabled if:- +- The number of `TTYpes` == 2. +- `U1` or `U2` are not convertible to `TTypes`. + +--- + +```cpp +template && p) ETL_NOEXCEPT +``` +**Description** +Construct from const rvalue reference pair. +Implicit conversion. + +Enabled if:- +- The number of `TTYpes` == 2. +- `U1` and `U2` are convertible to `TTypes`. + +--- + +```cpp +template && p) ETL_NOEXCEPT +``` +**Description** +Construct from const rvalue reference pair. +Explicit conversion. + +Enabled if:- +- The number of `TTYpes` == 2. +- `U1` or `U2` are not convertible to `TTypes`. + +## Assignment + +```cpp +template +ETL_CONSTEXPR14 +tuple& operator=(const tuple& other) +``` +**Description** +Copy assign from other tuple type. + +Enabled if:- +- The number of `UTypes` == number of `TTypes`. + +--- + +```cpp +template +ETL_CONSTEXPR14 +tuple& operator=(tuple&& other) +``` +**Description** +Move assign from other tuple type. + +Enabled if:- +- The number of `UTypes` == number of `TTypes`. + +--- + +```cpp +template +ETL_CONSTEXPR14 +tuple& operator=(ETL_OR_STD::pair& p) +``` +**Description** +Assign from lvalue pair tuple type. + +Enabled if:- +- The number of `TTYpes` == 2. + +--- + +```cpp +template +ETL_CONSTEXPR14 +tuple& operator=(const ETL_OR_STD::pair& p) +``` +**Description** +Assign from const lvalue pair tuple type. + +Enabled if:- +- The number of `TTYpes` == 2. + +--- + +```cpp +template +ETL_CONSTEXPR14 +tuple& operator=(ETL_OR_STD::pair&& p) +``` +**Description** +Assign from rvalue pair tuple type. + +Enabled if:- +- The number of `TTYpes` == 2. + +--- + +```cpp +template +ETL_CONSTEXPR14 +tuple& operator=(const ETL_OR_STD::pair&& p) +``` +**Description** +Assign from const rvalue pair tuple type. + +Enabled if:- +- The number of `TTYpes` == 2. + +## Other + +```cpp +ETL_CONSTEXPR14 +void swap(this_type& other) +``` +**Description** +Swaps this tuple with another. + +--- + +```cpp +ETL_NODISCARD +constexpr static size_t size() +``` +**Description** +Returns the number of elements in the tuple. + +## Template deduction guides +For C++17 and above. + +```cpp +template +tuple(TArgs... args) -> tuple; +``` +**Description** +From variadic arguments. + +--- + +```cpp +template +tuple(ETL_OR_STD::pair) -> tuple; +``` +From a `pair`. + +## Utility classes + +```cpp + template + struct tuple_element> +``` +**Description** +Gets the element type at `Index` in the tuple. + +--- + +```cpp +template +struct tuple_size> +``` +**Description** +Gets the size of the tuple. +Derived from `etl::integral_constant`. + +--- + +```cpp +template +struct common_type> +``` +**Description** +Gets the common type of a tuple. + +## Get an element + +```cpp +template +ETL_NODISCARD +ETL_CONSTEXPR14 +etl::tuple_element_t>& get(tuple& t) +``` +**Description** +Extracts the element at `Index` from the tuple. +`Index` must be an integer value in [`0`, `sizeof...(TTypes)`). +Returns a reference to the value. + +--- + +```cpp +template +ETL_NODISCARD +ETL_CONSTEXPR14 +const etl::tuple_element_t>& get(const tuple& t) +``` +**Description** +Extracts the element at `Index` from the tuple. +`Index` must be an integer value in [`0`, `sizeof...(TTypes)`). +Returns a const reference to the value. + +--- + +```cpp +template +ETL_NODISCARD +ETL_CONSTEXPR14 +etl::tuple_element_t>&& get(tuple&& t) +``` +**Description** +Extracts the element at `Index` from the tuple. +`Index` must be an integer value in [`0`, `sizeof...(TTypes)`). +Returns an rvalue reference. + +--- + +```cpp +template +ETL_NODISCARD +ETL_CONSTEXPR14 +const etl::tuple_element_t>&& get(const tuple&& t) +``` +**Description** +Extracts the element at `Index` from the tuple. +`Index` must be an integer value in [`0`, `sizeof...(TTypes)`). +Returns a const rvalue reference. + +--- + +```cpp +template +ETL_NODISCARD +ETL_CONSTEXPR14 +T& get(tuple& t) +``` +**Description** +Extracts the element with type `T` from the tuple. +Static asserts if the tuple contains more than one `T`, or does not contain a `T` element. +Returns a reference to the value. + +--- + +```cpp +template +ETL_NODISCARD +ETL_CONSTEXPR14 +const T& get(const tuple& t) +``` +**Description** +Extracts the element with type `T` from the tuple. +Static asserts if the tuple contains more than one `T`, or does not contain a `T` element. +Returns a const reference to the value. + +--- + +```cpp +template +ETL_NODISCARD +ETL_CONSTEXPR14 +T&& get(tuple&& t) +``` +**Description** +Extracts the element with type `T` from the tuple. +Static asserts if the tuple contains more than one `T`, or does not contain a `T` element. +Returns an rvalue reference to the value. + +--- + +```cpp +template +ETL_NODISCARD +ETL_CONSTEXPR14 +const T&& get(const tuple&& t) +``` +**Description** +Extracts the element with type `T` from the tuple. +Static asserts if the tuple contain more than one `T`, or does not contain a `T` element. +Returns a const rvalue reference to the value. + +--- + +```cpp +template +ETL_CONSTEXPR +etl::tuple tie(TTypes&... args) +``` +**Description** +Create a tuple of references to the provided arguments. + +--- + +```cpp +template +ETL_NODISCARD +ETL_CONSTEXPR14 +etl::tuple...> make_tuple(TTypes&&... args) +``` +**Description** +Create a tuple from the provided arguments. + +--- + +```cpp +template +ETL_NODISCARD +ETL_CONSTEXPR14 +auto select_from_tuple(TTuple&& tuple, + etl::index_sequence) + -> etl::tuple>...> +``` +**Description** +Create a new tuple by selecting elements from another, given a run time index sequence. +Static asserts if the number of indices does not match the tuple size. + +--- + +```cpp +template +ETL_NODISCARD +ETL_CONSTEXPR14 +auto select_from_tuple(TTuple&& tuple) + -> etl::tuple>...> +``` +**Description** +Create a new tuple by selecting elements from another, given a template parameter index sequence. +Static asserts if the number of indices does not match the tuple size. + +--- + +```cpp +template +ETL_NODISCARD +ETL_CONSTEXPR14 +etl::tuple forward_as_tuple(TTypes&&... args) +``` +**Description** +Forward the arguments as a tuple. + +--- + +```cpp +template +ETL_NODISCARD +ETL_CONSTEXPR14 +auto tuple_cat(Tuples&&... t) -> Tuple +``` +**Description** +Concatenate the list of tuples. + +--- + + ## If using the STL + +Converts an etl::tuple to a std::tuple. + +```cpp +template +ETL_NODISCARD +ETL_CONSTEXPR14 +auto to_std(const etl::tuple& etl_tuple) -> std::tuple...> +``` +**Description** +Converts a `const etl::tuple` to a `std::tuple`. + +--- + +```cpp +template +ETL_NODISCARD +ETL_CONSTEXPR14 +auto to_std(etl::tuple&& etl_tuple) -> std::tuple...> +``` +**Description** +Converts an `etl::tuple` to a `std::tuple`. + +--- + +```cpp +template +ETL_NODISCARD +ETL_CONSTEXPR14 +auto to_etl(const std::tuple& std_tuple) -> etl::tuple...> +``` +**Description** +Converts a `const std::tuple` to an `etl::tuple`. + +--- + +```cpp +template +ETL_NODISCARD +ETL_CONSTEXPR14 +auto to_etl(std::tuple&& std_tuple) -> etl::tuple...> +``` +**Description** +Converts a `std::tuple` to an `etl::tuple`. + +## Comparisons + +```cpp +template +ETL_NODISCARD +ETL_CONSTEXPR14 +bool operator==(const etl::tuple& lhs, const etl::tuple& rhs) +``` +**Description** +Equality operator. + +--- + +```cpp +template +ETL_NODISCARD +ETL_CONSTEXPR14 +bool operator!=(const etl::tuple& lhs, const etl::tuple& rhs) +``` +**Description** +Inequality operator. + +--- + +```cpp +template +ETL_NODISCARD +ETL_CONSTEXPR14 +bool operator<(const etl::tuple& lhs, const etl::tuple& rhs) +``` +**Description** +Less than operator. + +--- + +```cpp +template +ETL_NODISCARD +ETL_CONSTEXPR14 +bool operator<=(const etl::tuple& lhs, const etl::tuple& rhs) +``` +**Description** +Less than or equals operator. + +--- + +```cpp +template +ETL_NODISCARD +ETL_CONSTEXPR14 +bool operator>(const etl::tuple& lhs, const etl::tuple& rhs) +``` +**Description** +Greater than operator. + +--- + +```cpp +template +ETL_NODISCARD ETL_CONSTEXPR14 bool operator>=(const etl::tuple& lhs, const etl::tuple& rhs) +``` +**Description** +Greater than or equals operator. + +## Swap + +```cpp +template +ETL_CONSTEXPR14 +void swap(etl::tuple& lhs, etl::tuple& rhs) +``` +**Description** +Swap two tuples. + +## Helpers + +```cpp +template +struct tuple_from_type_list> +``` +**Description** +Helper to turn `etl::type_list` into `etl::tuple` + +--- + +```cpp +template +using tuple_from_type_list_t = typename tuple_from_type_list::type +``` + +## STL namespace definitions + +```cpp +template +struct tuple_size> : etl::integral_constant +``` +**Description** +Specialisation of `tuple_size` to allow the use of C++ structured bindings. + +--- + +```cpp +template +struct tuple_element> +``` +**Description** +Specialisation of `tuple_element` to allow the use of C++ structured bindings. diff --git a/docs/containers/variant-legacy.md b/docs/containers/variant-legacy.md new file mode 100644 index 00000000..333fab1d --- /dev/null +++ b/docs/containers/variant-legacy.md @@ -0,0 +1,195 @@ +--- +title: "variant (legacy)" +--- + +{{< callout type="info">}} + Header: `variant.h` + Similar to: `std::variant` +{{< /callout >}} + +{{< callout type="warning">}} + Deprecated for C++11 and above. + This version is automatically selected if either the compiler does not support C++11, or `ETL_USE_LEGACY_VARIANT` is defined. +{{< /callout >}} + +A class that can contain one a several specified types in a type safe manner. +Supports up to eight types. +Supplies a nested reader visitor class that allows type safe access via sets of overloaded virtual read functions for each type. + +Accepts etl::visit since `20.28.0`. + +If `ETL_USE_LEGACY_VARIANT` is defined then `etl::variant` is in the `etl` namespace. +If `ETL_USE_LEGACY_VARIANT` is not defined then `etl::variant` is in the `etl::legacy` namespace. +Since: `20.30.0`. + +## Constructors + +```cpp +variant() +``` +**Description** +Default constructor. + +--- + +```cpp +template +variant(T value) +``` +**Description** +Construct from value. +A static assert will occur if `T` is not a supported type. + +## Operations + +```cpp +template +variant& operator =(typename parameter_type::type value) +``` +**Description** +Assigns a value. +A static assert occurs if the type `T` is not supported. + +### If C++11 is **not** supported + +```cpp +template +T& emplace(const TP1& value1) + +template +T& emplace(const TP1& value1, const TP2& value2) + +template +T& emplace(const TP1& value1, const TP2& value2, const TP3& value3) + +template +T& emplace(const TP1& value1, const TP2& value2, const TP3& value3, const TP4& value4) +``` +**Description** +Construct a `T` from multiple arguments. + +### If C++11 or greater is supported +```cpp +template +T& emplace(Args&&... args) +``` +**Description** +Construct a `T`s in-place using the supplied parameters. + +--- + +```cpp +void clear() +``` +**Description** +Clears the variant of holding any type. + +## Access + +```cpp +template +T& get() +``` +Gets a value. +If `T` is a type not supported by the variant then a static assert occurs. +If `T` is a type that is not the type currently stored then a `variant_incorrect_type_exception()` error is raised. +If asserts or exceptions are not enabled then undefined behaviour occurs. + +--- + +```cpp +const template +T& get() const +``` +Gets a value. +If `T` is a type not supported by the variant then a static assert occurs. +If `T` is a type that is not the type currently stored then a `variant_incorrect_type_exception()` error is raised. +If asserts or exceptions are not enabled then undefined behaviour occurs. + +--- + +```cpp +T* upcast_ptr() +const T* upcast_ptr() const +``` +For variant types that are polymorphic. +Up-casts the variant to type `T*`. +Types that cannot be up-cast will result in a `nullptr` return. +Since: `20.30.0` + +--- + +```cpp +T& upcast() +const T& upcast() const +``` +For variant types that are polymorphic. +Up-casts the variant to type` T`. +Types that cannot be up-cast will result in a runtime error `etl::variant_not_a_base`. +Since: `20.30.0` + +--- + +```cpp +bool is_base_of() const +``` +Tests if the type `T` is a base of the current variant type. +Since: `20.30.0` + +--- + +```cpp +call(reader& r) +``` +Calls the appropriate overloaded `r.read()` function with the value. + +--- + +```cpp +template +variant& operator =(typename parameter_type::type value) +``` +Assigns a value. +A static assert occurs if the type `T` is not supported. + +--- + +Any value stored in the variant can be implicitly cast to its current type. +If the implicit cast is to a type not supported by the variant then a static assert occurs. +If the implicit cast is to a type that is not the type currently stored then a `etl::variant_incorrect_type_exception` error is raised. + +## Tests + +```cpp +template +static bool is_supported_type() +``` +Returns true if `T` is supported by the variant, otherwise `false`. + +--- + +```cpp +bool is_same_type(const variant& other) const +``` +Returns `true` if the variant holds the same type as the other, otherwise `false`. + +--- + +```cpp +bool is_valid() const +``` +Returns `true` if the variant holds a valid value, otherwise `false`. + +--- + +```cpp +template +bool is_type() const +``` +Returns `true` if `T` is the type currently stored in the variant, otherwise `false`. + +## Visitation +For STL style `etl::visit` +`20.28.0` + +The ETL implements an STL style visit function. diff --git a/docs/containers/variant-variadic.md b/docs/containers/variant-variadic.md new file mode 100644 index 00000000..62ebd7e9 --- /dev/null +++ b/docs/containers/variant-variadic.md @@ -0,0 +1,501 @@ +--- +title: "variant" +--- + +{{< callout type="info">}} + Header: `variant.h` + Similar to: `std::variant` +{{< /callout >}} + +**For C++11 and above.** + +```cpp +template +class variant +``` + +A variadic class that can contain one a several specified types in a type safe manner. +C++11 and C++14 support up to 32 types for visitor callback callbacks. +C++17 and above supports any number of visitor callback types. + +Accepts functors, `etl::overload` and `etl::visitor` types as visitor callbacks. + +Accepts `etl::visit` since `20.28.0`. + +## Error exception types + +```cpp +class variant_exception +``` +**Description** +The base for all variant exceptions. +Derived from `etl::exception`. + +--- + +```cpp +class variant_incorrect_type_exception +``` +**Description** +The error types emitted when a non-supported type is requested from the variant. + +## Construction + +```cpp +ETL_CONSTEXPR14 variant() +``` +**Description** +Default constructor. + +--- + +```cpp +template +ETL_CONSTEXPR14 variant(T&& value) +``` +**Description** +Constructor from a value. + +--- + +```cpp +template +ETL_CONSTEXPR14 explicit variant(etl::in_place_type_t, TArgs&&... args) +``` +**Description** +Construct T from arguments. + +--- + +```cpp +template +ETL_CONSTEXPR14 explicit variant(etl::in_place_index_t, TArgs&&... args) +``` +**Description** +Construct from Index using args. + +--- + +```cpp +template +ETL_CONSTEXPR14 explicit variant(etl::in_place_type_t, + std::initializer_list init, + TArgs&&... args) +``` +**Description** +Construct from type, `initializer_list` and arguments. + +--- + +```cpp +template +ETL_CONSTEXPR14 explicit variant(etl::in_place_index_t, + std::initializer_list init, + TArgs&&... args) +``` +**Description** +Construct from `Index`, initializer_list and arguments. + +--- + +```cpp +ETL_CONSTEXPR14 variant(const variant& other) +``` +**Description** +Copy constructor. + +--- + +```cpp +ETL_CONSTEXPR14 variant(variant&& other) +``` +**Description** +Move constructor. + +## Operations + +```cpp +template +T& emplace(TArgs&&... args) +``` +**Description** +Set to type `T` using the construction parameters args. + +--- + +```cpp +template +variant& operator =(T&& value) +``` +**Description** + +--- + +```cpp +variant& operator =(const variant& other) +``` +**Description** +Copies other to the current variant. + +--- + +```cpp +variant& operator =(variant&& other) +``` +**Description** +Moves other to the current variant. + +--- + +```cpp +constexpr bool valueless_by_exception() const noexcept +``` +**Description** +Returns `true` if the type id is `etl::variant_npos`. + +--- + +```cpp +constexpr size_t index() const noexcept +``` +**Description** +Returns the index of the type contained in the variant. +Returns `etl::variant_npos` if the variant does not hold a valid type. + +--- + +```cpp +void swap(variant& rhs) noexcept +``` +**Description** +Swaps rhs with the current variant. + +## Access + +**Non-member functions** + +### get + +```cpp +template +ETL_CONSTEXPR14 etl::variant_alternative_t>& + get(etl::variant& v) +``` +**Description** +Get the value based on `Index`. +If `Index` matches the current index of the variant, returns a reference to the stored value, otherwise, asserts `etl::variant_incorrect_type_exception`. + +**Parameters** +A reference to a variant. + +--- + +```cpp +template +ETL_CONSTEXPR14 etl::variant_alternative_t>&& + get(etl::variant&& v) +``` +**Description** +Get the value based on `Index`. +If `Index` matches the current index of the variant, returns a reference to the stored value, otherwise, asserts `etl::variant_incorrect_type_exception`. + +**Parameters** +An rvalue reference to a variant. + +--- + +```cpp +template +ETL_CONSTEXPR14 const etl::variant_alternative_t>& + get(const etl::variant& v) +``` +**Description** +Get the value based on `Index`. +If `Index` matches the current index of the variant, returns a reference to the stored value, otherwise, asserts `etl::variant_incorrect_type_exception`. + +**Parameters** +A const reference to a variant. + +--- + +```cpp +template +ETL_CONSTEXPR14 const etl::variant_alternative_t>&& + get(const etl::variant&& v) +``` +**Description** +Get the value based on `Index`. +If `Index` matches the current index of the variant, returns a reference to the stored value, otherwise, asserts `etl::variant_incorrect_type_exception`. + +**Parameters** +A const rvalue reference to a variant. + +--- + +```cpp +template +ETL_CONSTEXPR14 T& get(etl::variant& v) +``` +**Description** +Get the value based on `T`. +If `T` matches the current type stored in the variant, returns a reference to the stored value, otherwise, asserts `etl::variant_incorrect_type_exception`. + +**Parameters** +A reference to a variant. + +--- + +```cpp +template +ETL_CONSTEXPR14 T&& get(etl::variant&& v) +``` +**Description** +Get the value based on `T`. +If `T` matches the current type stored in the variant, returns a reference to the stored value, otherwise, asserts `etl::variant_incorrect_type_exception`. + +**Parameters** +An rvalue reference to a variant. + +--- + +```cpp +template +ETL_CONSTEXPR14 const T& get(const etl::variant& v) +``` +**Description** +Get the value based on `T`. +If `T` matches the current type stored in the variant, returns a reference to the stored value, otherwise, asserts `etl::variant_incorrect_type_exception`. + +**Parameters** +A const reference to a variant. + +--- + +```cpp +template +ETL_CONSTEXPR14 const T&& get(const etl::variant&& v) +``` +**Description** +Get the value based on `T`. +If `T` matches the current type stored in the variant, returns a reference to the stored value, otherwise, asserts `etl::variant_incorrect_type_exception`. + +**Parameters** +A const rvalue reference to a variant. + +### get_if + +```cpp +template +ETL_CONSTEXPR14 etl::add_pointer_t>> + get_if(etl::variant* pv) noexcept +``` +**Description** +Get the value based on `Index`. +If `Index` matches the current index of the variant, returns a pointer to the stored value, otherwise returns `nullptr`. + +**Parameters** +A pointer to a variant. + +--- + +```cpp +template +ETL_CONSTEXPR14 etl::add_pointer_t>> + get_if(const etl::variant* pv) noexcept +``` +**Description** +Get the value based on `Index`. +If `Index` matches the current index of the variant, returns a const pointer to the stored value, otherwise returns `nullptr`. + +**Parameters** +A const pointer to a variant. + +--- + +```cpp +template +ETL_CONSTEXPR14 etl::add_pointer_t get_if(etl::variant* pv) noexcept +``` +**Description** +Get the value based on `T`. +If `T` matches the current type stored in the variant, returns a pointer to the stored value, otherwise return `nullptr`. + +**Parameters** +An pointer to a variant. + +--- + + +```cpp +template +ETL_CONSTEXPR14 etl::add_pointer_t get_if(const etl::variant* pv) noexcept +``` +**Description** +Get the value based on `T`. +If `T` matches the current type stored in the variant, returns a const pointer to the stored value, otherwise return `nullptr`. + +**Parameters** +An const pointer to a variant. + +## Other + +```cpp +struct monostate +``` +**Description** +A default constructible type. +For use as the first state to turn a non-default constructible variant into a default constructible variant. + +--- + +```cpp +template +void swap(etl::variant& lhs, etl::variant& rhs) +``` +**Description** +Swaps lhs and rhs. + +--- + +```cpp +template +struct variant_size> +``` +**Description** +The member constant value contains the number of types. + +For C++17 and above. +```cpp +template +inline constexpr size_t variant_size_v = variant_size::value; +``` +**Description** +Has the value equal to the number of types. + +## Tests +### Non-member functions +```cpp +template +ETL_CONSTEXPR14 bool holds_alternative(const etl::variant& v) noexcept +``` +**Description** +Checks if the variant v holds the alternative T. + +--- + +```cpp +template +ETL_CONSTEXPR14 bool holds_alternative(const etl::variant& v) noexcept +``` +**Description** +Checks if the variant v holds the alternative Index. + +--- + +```cpp +template +ETL_CONSTEXPR14 bool holds_alternative(size_t index, const etl::variant& v) noexcept +``` +**Description** +Checks if the variant v holds the alternative index. + +## Visitation +For `etl::visitor` + +For C++11 and C++14 the maximum number of visitor types is 32. +Code size may be minimised if one of the following macros are defined. + +```cpp +ETL_VARIANT_CPP11_MAX_8_TYPES +ETL_VARIANT_CPP11_MAX_16_TYPES +ETL_VARIANT_CPP11_MAX_24_TYPES +``` +**Description** +C++17 and above support any number of visitor callback types. + +`etl::variant` provides member functions that support two methods of visitation. + +--- + +```cpp +void accept_visitor(etl::visitor& v) +``` +**Description** +Accepts an `etl::visitor` derived type. +Deprecated from `20.36.0` + +```cpp +void accept_visitor(etl::visitor& v) const +``` +**Description** +Accepts `an etl::visitor` derived type. +Deprecated +Since: `20.36.0` + +--- + +```cpp +void accept(etl::visitor& v) +``` +**Description** +Accepts an `etl::visitor` derived type. +Since: `20.36.0` + +--- + +```cpp +void accept(etl::visitor& v) const +``` +**Description** +Accepts an `etl::visitor` derived type. +Since: `20.36.0` + +See `visitor` + +--- + +```cpp +template +void accept_functor(TVisitor& v) +``` +**Description** +Accepts a functor that overrides `operator()` for each type. +Deprecated since `20.36.0` + +--- + +```cpp +template +void accept_functor(TVisitor& v) const +``` +**Description** +Accepts a functor that overrides `operator()` for each type. +Deprecated since `20.36.0` + +--- + +```cpp +template +void accept(TVisitor& v) +``` +**Description** +Accepts a functor that overrides `operator()` for each type. +Since: `20.36.0` + +--- + +```cpp +template +void accept(TVisitor& v) const +``` +**Description** +Accepts a functor that overrides `operator()` for each type. +Since: `20.36.0` + +See overload + +## Visitation +For STL style `etl::visit`. +Since: `20.28.0` + +The ETL implements an STL style visit function. diff --git a/docs/containers/vector.md b/docs/containers/vector.md index 8ff8d28b..5b56a247 100644 --- a/docs/containers/vector.md +++ b/docs/containers/vector.md @@ -427,15 +427,50 @@ typename etl::ivector::difference_type erase_if(etl::ivector& v, TPredicat 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`. + +```cpp +operator == +``` +**Description** +`true` if the contents of the lists are equal, otherwise `false`. + +--- + +```cpp +operator != +``` +**Description** +`true` if the contents of the lists are not equal, otherwise `false`. + +--- + +```cpp +operator < +``` +**Description** +`true` if the contents of the lhs are lexicographically less than the contents of the rhs, otherwise `false`. + +--- + +```cpp +operator <= +``` +**Description** +`true` if the contents of the lhs are lexicographically less than or equal to the contents of the rhs, otherwise `false`. + +--- + +```cpp +operator > +``` +**Description** +`true` if the contents of the lhs are lexicographically greater than the contents of the rhs, otherwise `false`. + +--- + +```cpp +operator >= +``` +**Description** +`true` if the contents of the lhs are lexicographically greater than or equal to the contents of the rhs, otherwise `false`. + diff --git a/docs/raw/containers/intrusive_forward_list.txt b/docs/raw/containers/intrusive_forward_list.txt deleted file mode 100644 index 67dfdaa0..00000000 --- a/docs/raw/containers/intrusive_forward_list.txt +++ /dev/null @@ -1,176 +0,0 @@ -intrusive_forward_list - -An intrusive list. -No STL equivalent. - -etl::intrusive_forward_list - -TValue is the type that contains the actual values. It is derived from Tlink. Tlink is the link type for this list. -See Intrusive links. - -Before 20.37.0 the default link type was etl::forward_link<0> -____________________________________________________________________________________________________ -Member types - -typedef TLink link_type; -typedef TValue value_type; -typedef value_type* pointer; -typedef const value_type* const_pointer; -typedef value_type& reference; -typedef const value_type& const_reference; -typedef size_t size_type; - -____________________________________________________________________________________________________ -Constructors - -etl::intrusive_forward_list(); -____________________________________________________________________________________________________ -template -etl::intrusive_forward_list(TIterator begin, TIterator end); -____________________________________________________________________________________________________ -template -intrusive_forward_list(TLink& first, TLinks&... links); - -____________________________________________________________________________________________________ -Element access - -TValue& front() -const T& front() const -Returns a reference or const reference to the first element. -____________________________________________________________________________________________________ - -TValue& back() -const T& back() const -Returns a reference or const reference to the last element. - -____________________________________________________________________________________________________ -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. -____________________________________________________________________________________________________ - -iterator rbegin() -const_iterator rbegin() const -const_iterator crbegin() const -Returns a reverse iterator to the beginning of the list. -____________________________________________________________________________________________________ - -iterator rend() -const_iterator rend() const -const_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. -____________________________________________________________________________________________________ - -size_t size() const -Returns the size of the list. - -____________________________________________________________________________________________________ -Modifiers - -template -void assign(TIterator begin, TIterator end); -Fills the list with the values. -____________________________________________________________________________________________________ - -void push_front(value_type& value); -Pushes a value to the front of the list. -___________________________________________________________________________________________________ - -void pop_front(); -Pop a value from the front of the list. -Emits an etl::intrusive_forward_list_empty if the list is empty. If asserts or exceptions are disabled then undefined behaviour occurs. -____________________________________________________________________________________________________ - -template -void insert_after(iterator position, TIterator begin, TIterator end); - -iterator insert_after(iterator position, value_type& value); -Inserts values in to the list. -position is not checked for validity. -____________________________________________________________________________________________________ - -template -iterator erase_after(TIterator begin, TIterator end); - -iterator erase_after(iterator position); -Erases values in the list. -Iterators are not checked for validity. -____________________________________________________________________________________________________ - -void clear(); -Clears the list to a size of zero. No elements are destructed. -____________________________________________________________________________________________________ - -void splice_after(iterator position, list_type& list); -void splice_after(iterator position, list_type& list, iterator isource); -void splice_after(iterator position, list_type& list, iterator begin_, iterator end_); -Splices elements from a list into this list. -Iterators are not checked for validity. -____________________________________________________________________________________________________ - -void merge(list_type& list); -Merges the sorted elements of 'list' into this list. Merges are stable. -If a debug compile and asserts or exceptions are enabled than an etl::intrusive_list_unsorted is emitted if either list is unsorted, otherwise undefined behaviour occurs. -____________________________________________________________________________________________________ - -template -void merge(list_type& list, Tcompare compare); -Merges the sorted elements of list into this list. Comparison functor is supplied in compare. Merges are stable. -If a debug compile and asserts or exceptions are enabled than an etl::intrusive_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 -void remove_if(TPredicate predicate); -Removes from the container all the elements that satisfy predicate. -____________________________________________________________________________________________________ - -void unique(); - -template -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 -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. - diff --git a/docs/raw/containers/map.txt b/docs/raw/containers/map.txt deleted file mode 100644 index 0ed44461..00000000 --- a/docs/raw/containers/map.txt +++ /dev/null @@ -1,214 +0,0 @@ -map -multimap - -A fixed capacity map. -Uses std::less as the default key comparison method. -STL equivalent: std::map / std::multimap - -This page just describes etl::map. - -etl::map - -Inherits from etl::imap -etl::imap may be used as a size independent pointer or reference type for any etl::map instance. -____________________________________________________________________________________________________ -Template deduction guides -C++17 and above - -template -etl::map(TPairs...) - -Example -etl::map data{ etl::pair{0, 1}, etl::pair{2, 3}, etl::pair{4, 5}, etl::pair{6, 7} }; -Defines data as an map of int/int pairs, of length 4, containing the supplied data. -____________________________________________________________________________________________________ -Make template -C++11 and above -template , - typename... TPairs> -constexpr auto make_flat_map(TValues&&... values) - -Example -auto data = etl::make_map(etl::pair{0, 1}, etl::pair{2, 3}, - etl::pair{4, 5}, etl::pair{6, 7}); -____________________________________________________________________________________________________ -Member types - -key_type TKey -mapped_type TMapped -value_type etl or std::pair -size_type size_t -difference_type ptrdiff_t -reference value_type& -const_reference const value_type& -pointer value_type* -const_pointer const value_type* -iterator Random access iterator -const_iterator Constant random access iterator -reverse_iterator etl or std::reverse_iterator -const_reverse_iterator etl or std::reverse_iterator -____________________________________________________________________________________________________ -Constructor - -etl::map(); - -template -etl::map(TIterator begin, TIterator end); - -____________________________________________________________________________________________________ -Element access - -TMapped& at(key_parameter_t key) -const TMapped& at(key_parameter_t key) const -Returns a reference or const reference to the indexed element. -Emits an etl::map_out_of_range if the key is not in the table. If assert or exceptions are not enabled then undefined behaviour occurs. -____________________________________________________________________________________________________ -TMapped& operator[](key_parameter_t key) -const TMapped& operator[](key_parameter_t key) const -Returns a reference or const reference to the indexed element. -If the key does not exist then one is created using the default constructor. If the map is full then emits an etl::map_full. If asserts or exceptions are not enabled then undefined behaviour occurs. -____________________________________________________________________________________________________ -iterator find(key_parameter_t key); -const_iterator find(key_parameter_t key) const; -Searches the container for an element with a key equivalent to key and returns an iterator to it if found, otherwise it returns an iterator to etl::map::end() -____________________________________________________________________________________________________ -size_type count(key_parameter_t key) const; -Count elements with a specific key. -Searches the container for elements with a key equivalent to key and returns the number of matches -____________________________________________________________________________________________________ -iterator lower_bound(key_parameter_t key); -const_iterator lower_bound(key_parameter_t key) const; -Returns the iterator to the lower bound. -Returns an iterator pointing to the first element in the container whose key is not considered to go before key (i.e., either it is equivalent or goes after). -____________________________________________________________________________________________________ -iterator upper_bound(key_parameter_t key); -const_iterator upper_bound(key_parameter_t key) const; -Return the iterator to the upper bound. -Returns an iterator pointing to the first element in the container whose key is considered to go after key. -____________________________________________________________________________________________________ -pair equal_range(key_parameter_t key) const; -pair equal_range(key_parameter_t key); -Get the range of equal elements. -Returns the bounds of a range that includes all the elements in the container which have a key equivalent to key. -The return type is either std::pair (default) or etl::pair (ETL_NO_STL) -____________________________________________________________________________________________________ -20.21.0 -C++11 or above -For comparators that define is_transparent. - -template -iterator find(const K& key) - -template -const_iterator find(const K& key) const -____________________________________________________________________________________________________ -20.21.0 -C++11 or above -template -iterator lower_bound(const K& key) - -template -const_iterator lower_bound(const K& key) const -____________________________________________________________________________________________________ -20.21.0 -C++11 or above -template -iterator upper_bound(const K& key) - -template -const_iterator upper_bound(const K& key) const -____________________________________________________________________________________________________ -20.21.0 -C++11 or above -template -pair equal_range(const K& key) - -template -pair equal_range(const K& key) const -____________________________________________________________________________________________________ -20.21.0 -bool contains(key_value_parameter_t key) const -Check if the container contains the key. - -20.21.0 -C++11 or above -For comparators that define is_transparent. -template -bool contains(const K& k) const -Check if the container contains the key. -____________________________________________________________________________________________________ -Iterators - -iterator begin() -const_iterator begin() const -const_iterator cbegin() const -Returns an iterator to the beginning of the map. -____________________________________________________________________________________________________ -iterator end() -const_iterator end() const -const_iterator cend() const -Returns an iterator to the end of the map. -____________________________________________________________________________________________________ -iterator rbegin() -const_iterator rbegin() const -const_iterator crbegin() const -Returns a reverse iterator to the beginning of the map. -____________________________________________________________________________________________________ -iterator rend() -const_iterator rend() const -const_iterator crend() const -Returns a reverse iterator to the end of the map. -____________________________________________________________________________________________________ -Capacity - -bool empty() const -Returns true if the size of the map is zero, otherwise false. -____________________________________________________________________________________________________ -bool full() const -Returns true if the size of the map is SIZE, otherwise false. -____________________________________________________________________________________________________ -size_t size() const -Returns the size of the map. -____________________________________________________________________________________________________ -size_t max_size() const -Returns the maximum possible size of the map. -____________________________________________________________________________________________________ -size_t available() const -Returns the remaining available capacity in the map. -____________________________________________________________________________________________________ -Modifiers -<=20.19.0 -template -void insert(TIterator begin, TIterator end); - ->=20.20.0 -template -iterator insert(TIterator begin, TIterator end); -____________ -iterator insert(mapped_parameter_t value); -Inserts values in to the map. -If the map is full then emits an etl::map_full error. If asserts or exceptions are not enabled then undefined behaviour occurs. -____________________________________________________________________________________________________ -template -iterator erase(TIterator begin, TIterator end); -____________ -iterator erase(TIterator element); -Erases values in the map. -Iterator are not checked for validity. -____________ -size_t erase(const key_type& key) - -20.21.0 -template -size_t erase(K&& key) -____________________________________________________________________________________________________ -void clear(); -Clears the map to a size of zero. -____________________________________________________________________________________________________ -Non-member functions - -== true if the contents of the maps are equal, otherwise false. -!= true if the contents of the maps are not equal, otherwise false. - diff --git a/docs/raw/containers/optional.txt b/docs/raw/containers/optional.txt deleted file mode 100644 index c1c09fc4..00000000 --- a/docs/raw/containers/optional.txt +++ /dev/null @@ -1,161 +0,0 @@ -optional - -A class where the value is optional. -If a value is not assigned then an object of the contained type is not constructed. - -etl::optional - -If _DEBUG is defined then accesses to invalid data is detected either by throwing (ETL_THROW_EXCEPTIONS defined) or calling the error handler. -____________________________________________________________________________________________________ -Template deduction guides -C++17 and above - -template -etl::optional(T) - -> etl::optional; - -Example - -std::string text = "Hello"; -etl::optional opt{ text }; - -Defines opt as containing a std::string, containing the supplied text. - -____________________________________________________________________________________________________ -Constructor - -optional() - -Default constructor. -____________________________________________________________________________________________________ - -optional(const T& value) -optional(T&& value) - -Construct from value. Constructs a T. -____________________________________________________________________________________________________ - -optional(const optional& other) -optional(optional&& other) - -Construct copy. Constructs a T. -____________________________________________________________________________________________________ - -optional(nullopt) - -Construct empty value (same as default constructor). -____________________________________________________________________________________________________ - -template -ETL_CONSTEXPR14 -optional_impl(etl::in_place_t, TArgs&&... args) - -Constructor from variadic args. -20.43.0 -____________________________________________________________________________________________________ - -template -ETL_CONSTEXPR14 -optional_impl(etl::in_place_t, std::initializer_list ilist, TArgs&&... args) - -Constructor from variadic args. -20.43.0 - -____________________________________________________________________________________________________ - -~optional() - -Destructor. Destructs a T if a value has been assigned. - -____________________________________________________________________________________________________ -Operations - -optional& operator =(etl::nullopt) - -optional& operator =(const optional& value) -optional& operator =(optional&& value) - -optional& operator =(const T& value) -optional& operator =(T&& value) - -Note: -Unlike std::optional, assigning from { } will not clear the optional item to 'empty'. -It will be assigned a default constructed 'value'. - -etl::optional opt; -opt = { }; // opt will contain 0. -____________________________________________________________________________________________________ -void swap(optional& other) - -Swaps with the other optional - -____________________________________________________________________________________________________ -void reset() - -Resets the optional back to default. -____________________________________________________________________________________________________ -C++03 -template -void emplace(const T1& value1) - -template -void emplace(const T1& value1, const T2& value2) - -template -void emplace(const T1& value1, const T2& value2, const T3& value3) - -template -void emplace(const T1& value1, const T2& value2, const T3& value3, const T4& value4) - -C++11 -template -void emplace(Args && ... args) - -____________________________________________________________________________________________________ -Observers - -const T& value() const -T& value(); - -Returns the contained value. -____________________________________________________________________________________________________ - -template -T value_or(T value) const - -template -T value_or(T value) - -Returns the contained value if *this is valid, otherwise returns value. -____________________________________________________________________________________________________ - -const T* operator->() const -T* operator->(); - -Returns a pointer to the contained value. -____________________________________________________________________________________________________ - -const T& operator *() const -T* operator *(); - -Returns a reference to the contained value. - -____________________________________________________________________________________________________ -Tests - -explicit operator bool() const -bool has_value() const - -Checks whether *this is in a valid state, i.e. whether the contained value is initialised. -Returns true if valid, otherwise false. - -____________________________________________________________________________________________________ -Non-member functions - -== true if the contents are equal, otherwise false. -!= true if the contents are not equal, otherwise false. -< true if the contents of the lhs are less than the contents of the rhs, otherwise false. -<= true if the contents of the lhs are less than or equal to the contents of the rhs, otherwise false. -> true if the contents of the lhs are greater than the contents of the rhs, otherwise false. ->= true if the contents of the lhs are greater than or equal to the contents of the rhs, otherwise false. - diff --git a/docs/raw/containers/set.txt b/docs/raw/containers/set.txt deleted file mode 100644 index d04764fa..00000000 --- a/docs/raw/containers/set.txt +++ /dev/null @@ -1,201 +0,0 @@ -set -multiset - -A fixed capacity set. -Uses etl or std::less as the default key comparison method. -STL equivalent: std::set / std::multiset - -This page just describes etl::set. - -etl::set - -Inherits from etl::iset -etl::iset may be used as a size independent pointer or reference type for any etl::set instance. -____________________________________________________________________________________________________ -Template deduction guides -C++17 and above - -template -etl::set(TPairs...) - -Example -etl::set data{ 0, 1, 2, 3, 4, 5, 6, 7 }; -Defines data as an set of int, of length 8, containing the supplied data. -____________________________________________________________________________________________________ -Make template -C++11 and above -template , - typename... TPairs> -constexpr auto make_set(TValues&&... values) - -Example -auto data = etl::make_set(0, 1, 2, 3, 4, 5, 6, 7); - -____________________________________________________________________________________________________ -Member types - -value_type T -size_type size_t -difference_type ptrdiff_t -reference value_type& -const_reference const value_type& -pointer value_type* -const_pointer const value_type* -iterator Random access iterator -const_iterator Constant random access iterator -reverse_iterator ETL_OR_STD::reverse_iterator -const_reverse_iterator ETL_OR_STD::reverse_iterator -____________________________________________________________________________________________________ -Constructor - -etl::set(); - -template -etl::set(TIterator begin, TIterator end); -If the map is full then emits an etl::reference_flat_set_full. If asserts or exceptions are not enabled then undefined behaviour occurs. -____________________________________________________________________________________________________ -Element access - -iterator find(const value_type& v); -const_iterator find(const value_type& v) const; -Searches the container for an element with a key equivalent to k and returns an iterator to it if found, otherwise it returns an iterator to etl::set::end() -____________________________________________________________________________________________________ -size_type count(const value_type& v) const; -Count elements with a specific key. -Searches the container for elements with a key equivalent to k and returns the number of matches -____________________________________________________________________________________________________ -iterator lower_bound(const value_type& v); -const_iterator lower_bound(const value_type& v) const; -Returns the iterator to the lower bound. -Returns an iterator pointing to the first element in the container whose key is not considered to go before v (i.e., either it is equivalent or goes after). -____________________________________________________________________________________________________ -iterator upper_bound(const value_type& v); -const_iterator upper_bound (const value_type& v) const; -Return the iterator to the upper bound. -Returns an iterator pointing to the first element in the container whose key is considered to go after v. -____________________________________________________________________________________________________ -pair equal_range(const value_type& v) const; -pair equal_range(const value_type& v); -Get the range of equal elements. -Returns the bounds of a range that includes all the elements in the container which have a key equivalent to v. -____________________________________________________________________________________________________ -20.21.0 -C++11 or above -For comparators that define is_transparent. - -template -iterator find(const K& key) - -template -const_iterator find(const K& key) const -____________________________________________________________________________________________________ -20.21.0 -C++11 or above -template -iterator lower_bound(const K& key) - -template -const_iterator lower_bound(const K& key) const -____________________________________________________________________________________________________ -20.21.0 -C++11 or above -template -iterator upper_bound(const K& key) - -template -const_iterator upper_bound(const K& key) const -____________________________________________________________________________________________________ -20.21.0 -C++11 or above -template -pair equal_range(const K& key) - -template -pair equal_range(const K& key) const -____________________________________________________________________________________________________ -20.21.0 -bool contains(key_value_parameter_t key) const -Check if the container contains the key. - -20.21.0 -C++11 or above -For comparators that define is_transparent. -template -bool contains(const K& k) const -Check if the container contains the key. -____________________________________________________________________________________________________ -Iterators - -iterator begin() -const_iterator begin() const -const_iterator cbegin() const -Returns an iterator to the beginning of the map. -____________________________________________________________________________________________________ -iterator end() -const_iterator end() const -const_iterator cend() const -Returns an iterator to the end of the map. -____________________________________________________________________________________________________ -iterator rbegin() -const_iterator rbegin() const -const_iterator crbegin() const -Returns a reverse iterator to the beginning of the map. -____________________________________________________________________________________________________ -iterator rbegin() -const_iterator rbegin() const -const_iterator crbegin() const -Returns a reverse iterator to the beginning of the map. -____________________________________________________________________________________________________ -Capacity - -bool empty() const -Returns true if the size of the map is zero, otherwise false. -____________________________________________________________________________________________________ -bool full() const -Returns true if the size of the map is SIZE, otherwise false. -____________________________________________________________________________________________________ -size_t size() const -Returns the size of the map. -____________________________________________________________________________________________________ -size_t max_size() const -Returns the maximum possible size of the map. -____________________________________________________________________________________________________ -size_t available() const -Returns the remaining available capacity in the map. -____________________________________________________________________________________________________ -Modifiers - -<=20.19.0 -template -void insert(TIterator begin, TIterator end); - ->=20.20.0 -template -iterator insert(TIterator begin, TIterator end); - -iterator insert(parameter_t value); -Inserts values in to the map. If the map is full then emits an etl::set_full error. -If the set is full then emits an etl::set_full. If asserts or exceptions are not enabled then undefined behaviour occurs. -____________________________________________________________________________________________________ -template -iterator erase(TIterator begin, TIterator end); - -iterator erase(TIterator element); -Erases values in the set. -Iterators are not checked for validity. - -size_t erase(const key_type& key) - -20.21.0 -template -size_t erase(K&& key) -____________________________________________________________________________________________________ -void clear(); -Clears the map to a size of zero. -____________________________________________________________________________________________________ -Non-member functions - -== true if the contents of the maps are equal, otherwise false. -!= true if the contents of the maps are not equal, otherwise false. - diff --git a/docs/raw/containers/tuple.txt b/docs/raw/containers/tuple.txt deleted file mode 100644 index b51d61d6..00000000 --- a/docs/raw/containers/tuple.txt +++ /dev/null @@ -1,17 +0,0 @@ -tuple - -C++11 and above -A fixed-size collection of heterogeneous values. -STL equivalent: std::tuple - -std::tuple -____________________________________________________________________________________________________ -template -struct is_tuple -Defined as etl::true_type if T is an etl::tuple, otherwise etl::false_type. -____________________________________________________________________________________________________ -Constructor - -etl::tuplestack(); - - diff --git a/docs/raw/containers/variant (legacy).txt b/docs/raw/containers/variant (legacy).txt deleted file mode 100644 index 173af7a3..00000000 --- a/docs/raw/containers/variant (legacy).txt +++ /dev/null @@ -1,110 +0,0 @@ -variant (legacy) -Deprecated for C++11 and above. -This version is automatically selected if either the compiler does not support C++11, or ETL_USE_LEGACY_VARIANT is defined. See variant (new) - -A class that can contain one a several specified types in a type safe manner. -Supports up to eight types. -Supplies a nested reader visitor class that allows type safe access via sets of overloaded virtual read functions for each type. - -Accepts etl::visit -20.28.0 - -If ETL_USE_LEGACY_VARIANT is defined then variant is in the etl namespace. -If ETL_USE_LEGACY_VARIANT is not defined then variant is in the etl::legacy namespace. -20.30.0 -____________________________________________________________________________________________________ -Constructor - -variant() -Default constructor. -____________________________________________________________________________________________________ -template -variant(T value) -Construct from value. A static assert will occur if T is not a supported type. -____________________________________________________________________________________________________ -Operations - -template -variant& operator =(typename parameter_type::type value) -Assigns a value. A static assert occurs if the type T is not supported. - -If C++11 is not supported -template -T& emplace(const TP1& value1) -____________________________________________________________________________________________________ -template -T& emplace(const TP1& value1, const TP2& value2) -____________________________________________________________________________________________________ -template -T& emplace(const TP1& value1, const TP2& value2, const TP3& value3) -____________________________________________________________________________________________________ -template -T& emplace(const TP1& value1, const TP2& value2, const TP3& value3, const TP4& value4) -____________________________________________________________________________________________________ -If C++11 or greater is supported -template -T& emplace(Args&&... args) -Constructs the value in-place using the supplied parameters. -____________________________________________________________________________________________________ -void clear() -Clears the variant of holding any type. -____________________________________________________________________________________________________ -Access - -template -T& get() - -const template -T& get() const -Gets a value. -If T is a type not supported by the variant then a static assert occurs. -If T is a type that is not the type currently stored then a variant_incorrect_type_exception() error is emitted. If asserts or exceptions are not enabled then undefined behaviour occurs. -____________________________________________________________________________________________________ -T* upcast_ptr() -const T* upcast_ptr() const -20.30.0 -For variant types that are polymorphic. Up-casts the variant to type T*. -Types that cannot be up-cast will result in a nullptr return. -____________________________________________________________________________________________________ -T& upcast() -const T& upcast() const -For variant types that are polymorphic. Up-casts the variant to type T. -Types that cannot be up-cast will result in a runtime error etl::variant_not_a_base. 20.30.0 -____________________________________________________________________________________________________ -bool is_base_of() const -20.30.0 -Tests if the type T is a base of the current variant type. -____________________________________________________________________________________________________ -call(reader& r) -Calls the appropriate overloaded r.read() function with the value. -____________________________________________________________________________________________________ -template -variant& operator =(typename parameter_type::type value) -Assigns a value. A static assert occurs if the type T is not supported. -____________________________________________________________________________________________________ -Any value stored in the variant can be implicitly cast to its current type. -If the implicit cast is to a type not supported by the variant then a static assert occurs. -If the implicit cast is to a type that is not the type currently stored then a etl::variant_incorrect_type_exception error is emitted. -____________________________________________________________________________________________________ -Tests - -template -static bool is_supported_type() -Returns true if T is supported by the variant, otherwise false. -____________________________________________________________________________________________________ -bool is_same_type(const variant& other) const -Returns true if the variant holds the same type as the other, otherwise false. -____________________________________________________________________________________________________ -bool is_valid() const -Returns true if the variant holds a valid value, otherwise false. -____________________________________________________________________________________________________ -template -bool is_type() const -Returns true if T is the type currently stored in the variant, otherwise false. -____________________________________________________________________________________________________ -Visitation -For STL style etl::visit -20.28.0 - -The ETL implements an STL style visit function. - diff --git a/docs/raw/containers/variant (variadic).txt b/docs/raw/containers/variant (variadic).txt deleted file mode 100644 index 704c1b2e..00000000 --- a/docs/raw/containers/variant (variadic).txt +++ /dev/null @@ -1,227 +0,0 @@ -variant (variadic) -For C++11 and above. -STL equivalent:- std::variant - -template -class variant - -A variadic class that can contain one a several specified types in a type safe manner. -C++11 and C++14 support up to 32 types for visitor callback callbacks. -C++17 and above supports any number of visitor callback types. - -Accepts functors, etl::overload and etl::visitor types as visitor callbacks. - -Accepts etl::visit -20.28.0 -____________________________________________________________________________________________________ -Error exception types - -class variant_exception : public exception - -class variant_incorrect_type_exception : public variant_exception -The error types emitted when a non-supported type is requested from the variant. -____________________________________________________________________________________________________ -Construction -____________________________________________________________________________________________________ -ETL_CONSTEXPR14 variant() -Default constructor. -____________________________________________________________________________________________________ -template -ETL_CONSTEXPR14 variant(T&& value) -Constructor from a value. -____________________________________________________________________________________________________ -template -ETL_CONSTEXPR14 explicit variant(etl::in_place_type_t, TArgs&&... args) -Construct T from arguments. -____________________________________________________________________________________________________ -template -ETL_CONSTEXPR14 explicit variant(etl::in_place_index_t, TArgs&&... args) -Construct from Index using args. -____________________________________________________________________________________________________ -template -ETL_CONSTEXPR14 explicit variant(etl::in_place_type_t, - std::initializer_list init, - TArgs&&... args) -Construct from type, initializer_list and arguments. -____________________________________________________________________________________________________ -template -ETL_CONSTEXPR14 explicit variant(etl::in_place_index_t, - std::initializer_list init, - TArgs&&... args) -Construct from Index, initializer_list and arguments. -____________________________________________________________________________________________________ -ETL_CONSTEXPR14 variant(const variant& other) -Copy constructor. -____________________________________________________________________________________________________ -ETL_CONSTEXPR14 variant(variant&& other) -Move constructor. -____________________________________________________________________________________________________ -Operations -____________________________________________________________________________________________________ -template -T& emplace(TArgs&&... args) -Set to type T using the construction parameters args. -____________________________________________________________________________________________________ -template -variant& operator =(T&& value) -____________________________________________________________________________________________________ -variant& operator =(const variant& other) -Copies other to the current variant. -____________________________________________________________________________________________________ -variant& operator =(variant&& other) -Moves other to the current variant. -____________________________________________________________________________________________________ -constexpr bool valueless_by_exception() const noexcept -Returns true if the type id is etl::variant_npos. -____________________________________________________________________________________________________ -constexpr size_t index() const noexcept -Returns the index of the type contained in the variant. -Returns etl::variant_npos if the variant does not hold a valid type. -____________________________________________________________________________________________________ -void swap(variant& rhs) noexcept -Swaps rhs with the current variant. -____________________________________________________________________________________________________ -Access -Non-member functions -____________________________________________________________________________________________________ -get -____________________________________________________________________________________________________ -template -ETL_CONSTEXPR14 etl::variant_alternative_t>& - get(etl::variant& v) -____________________________________________________________________________________________________ -template -ETL_CONSTEXPR14 etl::variant_alternative_t>&& - get(etl::variant&& v) -____________________________________________________________________________________________________ -template -ETL_CONSTEXPR14 const etl::variant_alternative_t>& - get(const etl::variant& v) -____________________________________________________________________________________________________ -template -ETL_CONSTEXPR14 const etl::variant_alternative_t>&& - get(const etl::variant&& v) -____________________________________________________________________________________________________ -template -ETL_CONSTEXPR14 T& get(etl::variant& v) -____________________________________________________________________________________________________ -template -ETL_CONSTEXPR14 T&& get(etl::variant&& v) -____________________________________________________________________________________________________ -template -ETL_CONSTEXPR14 const T& get(const etl::variant& v) -____________________________________________________________________________________________________ -template -ETL_CONSTEXPR14 const T&& get(const etl::variant&& v) -____________________________________________________________________________________________________ -get_if -____________________________________________________________________________________________________ -template -ETL_CONSTEXPR14 etl::add_pointer_t>> - get_if(etl::variant* pv) noexcept -____________________________________________________________________________________________________ -template -ETL_CONSTEXPR14 etl::add_pointer_t>> - get_if(const etl::variant* pv) noexcept -____________________________________________________________________________________________________ -template -ETL_CONSTEXPR14 etl::add_pointer_t get_if(etl::variant* pv) noexcept -____________________________________________________________________________________________________ -template -ETL_CONSTEXPR14 etl::add_pointer_t get_if(const etl::variant* pv) noexcept -____________________________________________________________________________________________________ -Other - -struct monostate -A default constructible type. -For use as the first state to turn a non-default constructible variant into a default constructible variant. -____________________________________________________________________________________________________ -template -void swap(etl::variant& lhs, etl::variant& rhs) -Swaps lhs and rhs. -____________________________________________________________________________________________________ -template -struct variant_size> -The member constant value contains the number of types. - -For C++17 and above. -template -inline constexpr size_t variant_size_v = variant_size::value; -Has the value equal to the number of types. -____________________________________________________________________________________________________ -Tests -Non-member functions -____________________________________________________________________________________________________ -template -ETL_CONSTEXPR14 bool holds_alternative(const etl::variant& v) noexcept -Checks if the variant v holds the alternative T. -____________________________________________________________________________________________________ -template -ETL_CONSTEXPR14 bool holds_alternative(const etl::variant& v) noexcept -Checks if the variant v holds the alternative Index. -____________________________________________________________________________________________________ -template -ETL_CONSTEXPR14 bool holds_alternative(size_t index, const etl::variant& v) noexcept -Checks if the variant v holds the alternative index. -____________________________________________________________________________________________________ -Visitation -For etl::visitor - -For C++11 and C++14 the maximum number of visitor types is 32. -Code size may be minimised if one of the following macros are defined. -ETL_VARIANT_CPP11_MAX_8_TYPES -ETL_VARIANT_CPP11_MAX_16_TYPES -ETL_VARIANT_CPP11_MAX_24_TYPES - -C++17 and above support any number of visitor callback types. - -etl::variant provides member functions that support two methods of visitation. -____________________________________________________________________________________________________ -void accept_visitor(etl::visitor& v) -Accepts an etl::visitor derived type. -Deprecated from 20.36.0 - -void accept_visitor(etl::visitor& v) const -Accepts an etl::visitor derived type. -Deprecated -20.36.0 - -void accept(etl::visitor& v) -Accepts an etl::visitor derived type. -20.36.0 - -void accept(etl::visitor& v) const -Accepts an etl::visitor derived type. -20.36.0 - -See visitor -____________________________________________________________________________________________________ -template -void accept_functor(TVisitor& v) -Accepts a functor that overrides operator() for each type. -Deprecated from 20.36.0 - -template -void accept_functor(TVisitor& v) const -Accepts a functor that overrides operator() for each type. -Deprecated -20.36.0 - -template -void accept(TVisitor& v) -Accepts a functor that overrides operator() for each type. -20.36.0 - -template -void accept(TVisitor& v) const -Accepts a functor that overrides operator() for each type. -20.36.0 - -See overload -____________________________________________________________________________________________________ -Visitation -For STL style etl::visit -20.28.0 - -The ETL implements an STL style visit function. - diff --git a/docs/strings/string.md b/docs/strings/string.md index 48a6485c..b884fc58 100644 --- a/docs/strings/string.md +++ b/docs/strings/string.md @@ -952,15 +952,48 @@ auto text = etl::make_string_with_capacity<10>("Hello World"); ``` ## Comparisons -`==` `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`. +```cpp +operator == +``` +**Description** +`true` if the contents of the lists are equal, otherwise `false`. + +--- + +```cpp +operator != +``` +**Description** +`true` if the contents of the lists are not equal, otherwise `false`. + +--- + +```cpp +operator < +``` +**Description** +`true` if the contents of the lhs are lexicographically less than the contents of the rhs, otherwise `false`. + +--- + +```cpp +operator <= +``` +**Description** +`true` if the contents of the lhs are lexicographically less than or equal to the contents of the rhs, otherwise `false`. + +--- + +```cpp +operator > +``` +**Description** +`true` if the contents of the lhs are lexicographically greater than the contents of the rhs, otherwise `false`. + +--- + +```cpp +operator >= +``` +**Description** +`true` if the contents of the lhs are lexicographically greater than or equal to the contents of the rhs, otherwise `false`. diff --git a/docs/strings/string_view.md b/docs/strings/string_view.md index 5bdcb5a3..7c236fc6 100644 --- a/docs/strings/string_view.md +++ b/docs/strings/string_view.md @@ -349,23 +349,52 @@ Finds the first character not equal to any of the characters in the given charac ## Non-member functions **Lexicographically comparisons** -`==` `true` if the contents of the string views are equal, -otherwise `false`. +```cpp +operator == +``` +**Description** +`true` if the contents of the lists are equal, otherwise `false`. -`!=` `true` if the contents of the string views are not equal, -otherwise `false`. +--- -`< ` `true` if the contents of the lhs are lexicographically less than the contents of the rhs, -otherwise `false`. +```cpp +operator != +``` +**Description** +`true` if the contents of the lists are not equal, 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`. +```cpp +operator < +``` +**Description** +`true` if the contents of the lhs are lexicographically less than the contents of the rhs, otherwise `false`. + +--- + +```cpp +operator <= +``` +**Description** +`true` if the contents of the lhs are lexicographically less than or equal to the contents of the rhs, otherwise `false`. + +--- + +```cpp +operator > +``` +**Description** +`true` if the contents of the lhs are lexicographically greater than the contents of the rhs, otherwise `false`. + +--- + +```cpp +operator >= +``` +**Description** +`true` if the contents of the lhs are lexicographically greater than or equal to 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`. --- diff --git a/docs/utilities/intrusive-links.md b/docs/utilities/intrusive-links.md index e3fe9780..6ee73e3f 100644 --- a/docs/utilities/intrusive-links.md +++ b/docs/utilities/intrusive-links.md @@ -2,6 +2,10 @@ title: "Intrusive Links" --- +{{< callout type="info">}} + Header: `intrusive_links.h` +{{< /callout >}} + A set of link structures designed to be used within containers such as `etl::intrusive_list`. They are parameterised by an id that allows them to be multiply inherited from when creating objects that must exist in more than one intrusive container. diff --git a/docs/utilities/optional.md b/docs/utilities/optional.md new file mode 100644 index 00000000..a12aac75 --- /dev/null +++ b/docs/utilities/optional.md @@ -0,0 +1,271 @@ +--- +title: "optional" +--- + +{{< callout type="info">}} + Header: `optional.h` + Similar to: `std::optional` +{{< /callout >}} + +A class where the value is optional. +If a value is not assigned then an object of the contained type is not constructed. + +```cpp +template +etl::optional +``` + +If `_DEBUG` is defined then accesses to invalid data is detected either by throwing (`ETL_THROW_EXCEPTIONS` defined) or calling the error handler. + +## Template deduction guides +C++17 and above + +```cpp +template +etl::optional(T) + -> etl::optional +``` + +### Example + +```cpp +std::string text = "Hello"; +etl::optional opt{ text }; +``` + +Defines `opt` as containing a `std::string`, containing the supplied text. + +## Constructor + +```cpp +optional() +``` +**Description** +Default constructor. + +--- + +```cpp +optional(const T& value) +optional(T&& value) +``` +**Description** +Construct from value. Constructs a `T`. + +--- + +```cpp +optional(const optional& other) +optional(optional&& other) +``` +**Description** +Construct copy. Constructs a `T`. + +--- + +```cpp +optional(nullopt) +``` +**Description** +Construct empty value (same as default constructor). + +--- + +```cpp +template +ETL_CONSTEXPR14 +optional_impl(etl::in_place_t, TArgs&&... args) +``` +**Description** +Constructor from variadic args. +20.43.0 + +--- + +```cpp +template +ETL_CONSTEXPR14 +optional_impl(etl::in_place_t, std::initializer_list ilist, TArgs&&... args) +``` +**Description** +Constructor from variadic args. +20.43.0 + +--- + +```cpp +~optional() +``` +**Description** +Destructor. +Destructs a `T` if a value has been assigned. + +## Operations + +```cpp +optional& operator =(etl::nullopt) +``` +**Description** +Clears the optional. + +```cpp +optional& operator =(const optional& value) +optional& operator =(optional&& value) +``` +**Description** +Copy constructor. + +```cpp +optional& operator =(const T& value) +optional& operator =(T&& value) +``` +**Description** +Assigns a value to the optional. + +### Note +Unlike `std::optional`, assigning from `{ }` will not clear the optional item to 'empty'. +It will be assigned a default constructed 'T'. + +```cpp +etl::optional opt; +opt = { }; // opt will contain 0. +``` + +--- + +```cpp +void swap(optional& other) +``` +**Description** +Swaps with the `other` optional + +--- + +```cpp +void reset() +``` +**Description** +Resets the optional back to default. + +--- + +```cpp +emplace +``` +**Description** +Construct in-place from arguments. + +### C++03 +```cpp +template +void emplace(const T1& value1) + +template +void emplace(const T1& value1, const T2& value2) + +template +void emplace(const T1& value1, const T2& value2, const T3& value3) + +template +void emplace(const T1& value1, const T2& value2, const T3& value3, const T4& value4) +``` + +### C++11 +```cpp +template +void emplace(Args && ... args) +``` + +## Observers + +```cpp +const T& value() const +T& value() +``` +**Description** +Returns the contained value. + +--- + +```cpp +template +T value_or(T value) +``` +**Description** +Returns the contained value if `*this` is valid, otherwise returns `value`. + +--- + +```cpp +const T* operator->() const +T* operator->() +``` +**Description** +Returns a pointer to the contained value. + +--- + +```cpp +const T& operator *() const +T* operator *() +``` +**Description** +Returns a reference to the contained value. + +## Tests + +```cpp +explicit operator bool() const +bool has_value() const +``` +**Description** +Checks whether *this is in a valid state, i.e. whether the contained value is initialised. +Returns `true` if valid, otherwise `false`. + +## Non-member functions + +```cpp +operator == +``` +**Description** +`true` if the contents of the lists are equal, otherwise `false`. + +--- + +```cpp +operator != +``` +**Description** +`true` if the contents of the lists are not equal, otherwise `false`. + +--- + +```cpp +operator < +``` +**Description** +`true` if the contents of the lhs are lexicographically less than the contents of the rhs, otherwise `false`. + +--- + +```cpp +operator <= +``` +**Description** +`true` if the contents of the lhs are lexicographically less than or equal to the contents of the rhs, otherwise `false`. + +--- + +```cpp +operator > +``` +**Description** +`true` if the contents of the lhs are lexicographically greater than the contents of the rhs, otherwise `false`. + +--- + +```cpp +operator >= +``` +**Description** +`true` if the contents of the lhs are lexicographically greater than or equal to the contents of the rhs, otherwise `false`.