diff --git a/docs/containers/arrays/array_view.md b/docs/containers/Views/array-view.md similarity index 100% rename from docs/containers/arrays/array_view.md rename to docs/containers/Views/array-view.md diff --git a/docs/containers/arrays/array_wrapper.md b/docs/containers/Views/array-wrapper.md similarity index 100% rename from docs/containers/arrays/array_wrapper.md rename to docs/containers/Views/array-wrapper.md diff --git a/docs/containers/Views/multi_range.md b/docs/containers/Views/multi-range.md similarity index 100% rename from docs/containers/Views/multi_range.md rename to docs/containers/Views/multi-range.md diff --git a/docs/containers/Views/poly_span.md b/docs/containers/Views/poly-span.md similarity index 93% rename from docs/containers/Views/poly_span.md rename to docs/containers/Views/poly-span.md index 16555eba..26dc55bc 100644 --- a/docs/containers/Views/poly_span.md +++ b/docs/containers/Views/poly-span.md @@ -3,10 +3,11 @@ title: "poly_span" --- {{< callout >}} - Header: `priority_queue.h` + Header: `poly_span.h` Since: `20.31.0` {{< /callout >}} +Polymorphic span. This class implements a view in to a contiguous range through a base type. ```cpp @@ -85,6 +86,7 @@ ETL_CONSTEXPR poly_span() ETL_NOEXCEPT template ETL_CONSTEXPR poly_span(const TIterator begin, const TSize size) ETL_NOEXCEPT ``` +**Description** Static asserts if `etl::iterator_traits::iterator_category` is not `random_access_iterator_tag` or `etl::iterator_traits::value_type` is not the same as, or not derived from `TBase`. @@ -94,6 +96,7 @@ or `etl::iterator_traits::value_type` is not the same as, or not deri template ETL_CONSTEXPR poly_span(const TIterator begin, const TIterator end) ``` +**Description** Static asserts if `etl::iterator_traits::iterator_category` is not `random_access_iterator_tag` or `etl::iterator_traits::value_type` is not the same as, or not derived from `TBase`. @@ -103,6 +106,7 @@ or `etl::iterator_traits::value_type` is not the same as, or not deri template ETL_CONSTEXPR poly_span(U(&begin_)[N]) ETL_NOEXCEPT ``` +**Description** Static asserts if `N` is greater than `Extent` or `etl::iterator_traits::value_type` is not the same as, or not derived from `TBase`. --- @@ -111,6 +115,7 @@ Static asserts if `N` is greater than `Extent` or `etl::iterator_traits ETL_CONSTEXPR poly_span(etl::array& a) ETL_NOEXCEPT ``` +**Description** Static asserts if `N` is greater than `Extent` or `etl::iterator_traits::value_type` is not the same as, or not derived from `TBase`. --- @@ -119,6 +124,7 @@ Static asserts if `N` is greater than `Extent` or `etl::iterator_traits ETL_CONSTEXPR poly_span(const etl::array& a) ETL_NOEXCEPT ``` +**Description** Static asserts if `N` is greater than `Extent` or `etl::iterator_traits::value_type` is not the same as, or not derived from `TBase`. --- @@ -127,6 +133,7 @@ Static asserts if `N` is greater than `Extent` or `etl::iterator_traits ETL_CONSTEXPR poly_span(std::array& a) ETL_NOEXCEPT ``` +**Description** Enabled if `ETL_USING_CPP11` and `ETL_USING_STL` are `true`. Static asserts if `N` is greater than `Extent` or `etl::iterator_traits::value_type` is not the same as, or not derived from `TBase`. @@ -136,6 +143,7 @@ Static asserts if `N` is greater than `Extent` or `etl::iterator_traits ETL_CONSTEXPR poly_span(const std::array& a) ETL_NOEXCEPT ``` +**Description** Enabled if `ETL_USING_CPP11` and `ETL_USING_STL` are `true`. Static asserts if `N` is greater than `Extent` or `etl::iterator_traits::value_type` is not the same as, or not derived from `TBase`. @@ -144,6 +152,7 @@ Static asserts if `N` is greater than `Extent` or `etl::iterator_traits ETL_CONSTEXPR14 poly_span& operator =(const poly_span& other) ETL_NOEXCEPT ``` +**Description** Assign from a other span. --- @@ -196,6 +211,7 @@ Assign from a other span. template ETL_NODISCARD ETL_CONSTEXPR etl::poly_span first() const ``` +**Description** Returns a span consisting of the first `COUNT` elements of the current span. --- @@ -203,6 +219,7 @@ Returns a span consisting of the first `COUNT` elements of the current span. ```cpp ETL_NODISCARD ETL_CONSTEXPR etl::poly_span last(size_t count) const ``` +**Description** Returns a span consisting of the last count elements of the current span. --- @@ -210,7 +227,8 @@ Returns a span consisting of the last count elements of the current span. ```cpp template ETL_NODISCARD ETL_CONSTEXPR etl::poly_span last() const -```cpp +``` +**Description** Returns a span consisting of the last `COUNT` elements of the current span --- @@ -218,6 +236,7 @@ Returns a span consisting of the last `COUNT` elements of the current span ```cpp ETL_NODISCARD ETL_CONSTEXPR etl::poly_span first(size_t count) const ``` +**Description** Returns a span consisting of the first count elements of the current span. --- @@ -226,6 +245,7 @@ Returns a span consisting of the first count elements of the current span. template ETL_NODISCARD ETL_CONSTEXPR etl::poly_span subspan() const ``` +**Description** Returns a subspan consisting of the range starting at `OFFSET` for `COUNT` elements of the current span. --- @@ -233,6 +253,7 @@ Returns a subspan consisting of the range starting at `OFFSET` for `COUNT` eleme ```cpp ETL_NODISCARD ETL_CONSTEXPR etl::poly_span subspan(size_t offset, size_t count = etl::dynamic_extent) const ``` +**Description** Returns a subspan consisting of the range starting at `offset` for `count` elements of the current span. ## Iterators @@ -240,6 +261,7 @@ Returns a subspan consisting of the range starting at `offset` for `count` eleme ```cpp ETL_NODISCARD ETL_CONSTEXPR iterator begin() const ETL_NOEXCEPT ``` +**Description** Returns an iterator to the beginning of the span. --- @@ -247,6 +269,7 @@ Returns an iterator to the beginning of the span. ```cpp ETL_NODISCARD ETL_CONSTEXPR iterator end() const ETL_NOEXCEPT ``` +**Description** Returns an iterator to the end of the span. --- @@ -254,6 +277,7 @@ Returns an iterator to the end of the span. ```cpp ETL_NODISCARD ETL_CONSTEXPR iterator rbegin() const ETL_NOEXCEPT ``` +**Description** Returns a reverse iterator to the beginning of the span. --- @@ -261,6 +285,7 @@ Returns a reverse iterator to the beginning of the span. ```cpp ETL_NODISCARD ETL_CONSTEXPR iterator rend() const ETL_NOEXCEPT ``` +**Description** Returns a reverse iterator to the end of the span. ## Capacity @@ -268,6 +293,7 @@ Returns a reverse iterator to the end of the span. ```cpp ETL_NODISCARD ETL_CONSTEXPR bool empty() const ETL_NOEXCEPT ``` +**Description** Returns true if the size of the span is zero, otherwise false. --- @@ -275,6 +301,7 @@ Returns true if the size of the span is zero, otherwise false. ```cpp ETL_NODISCARD ETL_CONSTEXPR size_t size() const ETL_NOEXCEPT ``` +**Description** Returns the size of the span. --- @@ -282,6 +309,7 @@ Returns the size of the span. ```cpp ETL_NODISCARD ETL_CONSTEXPR size_t size_bytes() const ETL_NOEXCEPT ``` +**Description** Returns the size of the span in bytes. --- @@ -289,6 +317,7 @@ Returns the size of the span in bytes. ```cpp ETL_NODISCARD ETL_CONSTEXPR size_t size_of_element() const ETL_NOEXCEPT ``` +**Description** Returns the size of the elements pointed to by the span, in bytes. ## Non-member functions diff --git a/docs/containers/arrays/array.md b/docs/containers/arrays/array.md index 540c2e4f..3fd23a7a 100644 --- a/docs/containers/arrays/array.md +++ b/docs/containers/arrays/array.md @@ -17,8 +17,8 @@ etl::array ``` See also: -[array_view]({{< relref "array_view" >}}) -[multi_array]({{< relref "multi_array" >}}) +[array_view]({{< relref "array-view" >}}) +[multi_array]({{< relref "multi-array" >}}) ## Template deduction guides **C++17 and above** diff --git a/docs/containers/arrays/multi_array.md b/docs/containers/arrays/multi-array.md similarity index 93% rename from docs/containers/arrays/multi_array.md rename to docs/containers/arrays/multi-array.md index c052a1ba..e78e50dd 100644 --- a/docs/containers/arrays/multi_array.md +++ b/docs/containers/arrays/multi-array.md @@ -16,7 +16,7 @@ etl::multi_array See also: [array]({{< relref "array" >}}) -[array_view]({{< relref "array_view" >}}) +[array_view]({{< relref "array-view" >}}) ## Description diff --git a/docs/containers/bloom_filter.md b/docs/containers/bloom-filter.md similarity index 100% rename from docs/containers/bloom_filter.md rename to docs/containers/bloom-filter.md diff --git a/docs/containers/const-multiset.md b/docs/containers/const-multiset.md new file mode 100644 index 00000000..546f62c0 --- /dev/null +++ b/docs/containers/const-multiset.md @@ -0,0 +1,336 @@ +--- +title: "const_multiset / const_multiset_ext" +--- + +{{< callout >}} + Header: `const_multiset.h` + Similar to: `std::set` +{{< /callout >}} + +A fixed capacity read-only set based on a sorted array. +The containers are designed to be able to be `constexpr` for C++14 and up. + +Uses `etl::less` as the default key comparison method. + +**Internal storage** +```cpp +etl::const_multiset +``` + +**Enternal storage** +```cpp +etl::const_multiset_ext +``` + +Inherits from `etl::iconst_multiset`. +`etl::iconst_multiset` may be used as a Size independent pointer or reference type for any `etl::const_multiset` or `etl::const_multiset_ext` instance. +Both the key type must be default constructible. + +## Template deduction guides +**C++17 and above.** + +### const_multiset +```cpp +template +etl::const_multiset(TElements...) +``` + +**Example** +```cpp +constexpr etl::const_multiset data{ 0, 1, 2, 3 }; +``` +Defines data as an `const_multiset` of `int`, of length 4, containing the supplied data. + +### const_multiset_ext +```cpp +template +etl::const_multiset_ext(TElements...) +``` + +**Example** +```cpp +constexpr etl::pair values{ 0, 1, 2, 3 }; +constexpr etl::const_multiset_ext data{ values }; +``` +Defines data as an `const_multiset` of int, of length 4, containing the supplied data. + +--- + +```cpp +constexpr values[]{ 0, 1, 2, 3 }; +constexpr etl::span span{ values }; +constexpr etl::const_multiset_ext data{ span }; +``` +Defines data as an `const_multiset` of `int` of length 4, containing the supplied data. + +--- + +## Member types +```cpp +key_type TKey Must be default constructible. +value_type key_type +size_type std::size_t +difference_type std::ptrdiff_t +const_reference const T& +const_pointer const T* +const_iterator Constant random access iterator +``` + +## Constructors + +### const_multiset +```cpp +template +ETL_CONSTEXPR14 explicit const_multiset(TElements&&... elements) ETL_NOEXCEPT +``` +**Decsription** +Construct a `const_multiset` from a variadic list of elements. +Static asserts if the elements are not of type `value_type`. +Static asserts if the number of elements is greater than the capacity of the `const_multiset`. + +### const_multiset_ext + +```cpp +ETL_CONSTEXPR14 const_multiset_ext() ETL_NOEXCEPT +``` +**Decsription** +Default construct a `const_multiset`. + +--- + +```cpp +template +ETL_CONSTEXPR14 explicit const_multiset_ext(const etl::span& sp) ETL_NOEXCEPT +``` +**Decsription** +Construct a `const_multiset` from a variadic list of elements. + +--- + +```cpp +template +ETL_CONSTEXPR14 explicit const_multiset_ext(const value_type (&begin_)[Size]) ETL_NOEXCEPT +``` +**Decsription** +Construct a `const_multiset` from an array. + +## Iterators + +```cpp +const_iterator begin() const ETL_NOEXCEPT +const_iterator cbegin() const ETL_NOEXCEPT +``` +**Decsription** +Returns an iterator to the beginning of the set. + +--- + +```cpp +const_iterator end() const ETL_NOEXCEPT +const_iterator cend() const ETL_NOEXCEPT +``` +**Decsription** +Returns an iterator to the end of the set. + +## Capacity + +```cpp +ETL_CONSTEXPR14 bool empty() const ETL_NOEXCEPT +``` +**Decsription** +Returns `true` if the size of the set is zero, otherwise `false`. + +--- + +```cpp +ETL_CONSTEXPR14 bool full() const ETL_NOEXCEPT +``` +**Decsription** +Returns `true` if the size of the lookup is size, otherwise `false`. + +--- + +```cpp +ETL_CONSTEXPR14 size_t size() const ETL_NOEXCEPT +``` +**Decsription** +Returns the size of the lookup. + +--- + +```cpp +ETL_CONSTEXPR14 size_t max_size() const ETL_NOEXCEPT +``` +**Decsription** +Returns the maximum possible size of the set. + +## Status + +```cpp +ETL_CONSTEXPR14 bool is_valid() const ETL_NOEXCEPT +``` +Check that the elements are valid for a set. +The elements must be sorted and contain no duplicates. + +## Search + +```cpp +ETL_CONSTEXPR14 const_iterator find(const key_type& key) const ETL_NOEXCEPT +``` +**Decsription** +Find the `key` in the container. + +**Return** +A `const_iterator` to the element, or `end()` if it could not be found. + +--- + +```cpp +ETL_CONSTEXPR14 const_iterator lower_bound(const key_type& key) const ETL_NOEXCEPT +``` +**Decsription** +Searches for the first element after the `key`. + +**Return** +A `const_iterator` to the element, or `end()` if it could not be found. + +--- + +```cpp +ETL_CONSTEXPR14 const_iterator upper_bound(const key_type& key) const ETL_NOEXCEPT +``` +**Decsription** +Searches for the first element with the `key`. + +**Return** +A `const_iterator` to the element, or `end()` if it could not be found. + +--- + +```cpp +ETL_CONSTEXPR14 pair equal_range(const key_type& key) const ETL_NOEXCEPT +``` +**Decsription** +The return type is either `std::pair` (default) or `etl::pair` (`ETL_NO_STL`) + +**Return** +Returns a range containing all elements equivalent to `key`. + +--- + +```cpp +ETL_CONSTEXPR14 bool contains(const key_type& k) const ETL_NOEXCEPT +``` +**Decsription** +Check if the container contains the key. + +**Return** +`true` if the container contains the key, otherwise `false`. + +## Search (transparent comparators) + +```cpp +template +ETL_CONSTEXPR14 const_iterator find(const K& key) const ETL_NOEXCEPT +``` +**Decsription** +Find the `key` in the container. + +**Return** +A `const_iterator` to the element, or `end()` if it could not be found. + +--- + +```cpp +template +ETL_CONSTEXPR14 const_iterator lower_bound(const K& key) const ETL_NOEXCEPT +``` +**Decsription** +Searches for the first element after the `key`. + +**Return** +A `const_iterator` to the element, or `end()` if it could not be found. + +--- + +```cpp +template +ETL_CONSTEXPR14 const_iterator upper_bound(const K& key) const ETL_NOEXCEPT +``` +**Decsription** +Searches for the first element with the `key`. + +**Return** +A `const_iterator` to the element, or `end()` if it could not be found. + +--- + +```cpp +template +ETL_CONSTEXPR14 pair equal_range(const K& key) const ETL_NOEXCEPT +``` +**Decsription** +The return type is either `std::pair` (default) or `etl::pair` (`ETL_NO_STL`) + +**Return** +Returns a range containing all elements equivalent to `key`. + +--- + +```cpp +template +ETL_CONSTEXPR14 bool contains(const K& k) const ETL_NOEXCEPT +``` +**Decsription** +Check if the container contains the key. + +**Return** +`true` if the container contains the key, otherwise `false`. + +## Non-member functions + +**Lexicographically comparisons** + +```cpp +operator == +``` +`true` if the contents of the sets are equal, otherwise `false`. + +--- + +```cpp +operator != +``` +`true` if the contents of the sets are not equal, otherwise `false`. + +--- + +```cpp +operator < +``` +`true` if the contents of the lhs is less-than the rhs, otherwise `false`. + +--- + +```cpp +operator <= +``` +`true` if the contents of the lhs is less-than-equal the rhs, otherwise `false`. + +--- + +```cpp +operator > +``` +`true` if the contents of the lhs is greater-than the rhs, otherwise `false`. + +--- + +```cpp +operator >= +``` +`true` if the contents of the lhs is greater-than-equal the rhs, otherwise `false`. + +## Technical stuff + +The const set is implemented as a sorted array key/value pairs. diff --git a/docs/containers/const-set.md b/docs/containers/const-set.md new file mode 100644 index 00000000..0bca91c1 --- /dev/null +++ b/docs/containers/const-set.md @@ -0,0 +1,336 @@ +--- +title: "const_set / const_set_ext" +--- + +{{< callout >}} + Header: `const_set.h` + Similar to: `std::set` +{{< /callout >}} + +A fixed capacity read-only set based on a sorted array. +The containers are designed to be able to be `constexpr` for C++14 and up. + +Uses `etl::less` as the default key comparison method. + +**Internal storage** +```cpp +etl::const_set +``` + +**Enternal storage** +```cpp +etl::const_set_ext +``` + +Inherits from `etl::iconst_set`. +`etl::iconst_set` may be used as a Size independent pointer or reference type for any `etl::const_set` or `etl::const_set_ext` instance. +Both the key type must be default constructible. + +## Template deduction guides +**C++17 and above.** + +### const_set +```cpp +template +etl::const_set(TElements...) +``` + +**Example** +```cpp +constexpr etl::const_set data{ 0, 1, 2, 3 }; +``` +Defines data as an `const_set` of `int`, of length 4, containing the supplied data. + +### const_set_ext +```cpp +template +etl::const_set_ext(TElements...) +``` + +**Example** +```cpp +constexpr etl::pair values{ 0, 1, 2, 3 }; +constexpr etl::const_set_ext data{ values }; +``` +Defines data as an `const_set` of int, of length 4, containing the supplied data. + +--- + +```cpp +constexpr values[]{ 0, 1, 2, 3 }; +constexpr etl::span span{ values }; +constexpr etl::const_set_ext data{ span }; +``` +Defines data as an `const_set` of `int` of length 4, containing the supplied data. + +--- + +## Member types +```cpp +key_type TKey Must be default constructible. +value_type key_type +size_type std::size_t +difference_type std::ptrdiff_t +const_reference const T& +const_pointer const T* +const_iterator Constant random access iterator +``` + +## Constructors + +### const_set +```cpp +template +ETL_CONSTEXPR14 explicit const_set(TElements&&... elements) ETL_NOEXCEPT +``` +**Decsription** +Construct a `const_set` from a variadic list of elements. +Static asserts if the elements are not of type `value_type`. +Static asserts if the number of elements is greater than the capacity of the `const_set`. + +### const_set_ext + +```cpp +ETL_CONSTEXPR14 const_set_ext() ETL_NOEXCEPT +``` +**Decsription** +Default construct a `const_set`. + +--- + +```cpp +template +ETL_CONSTEXPR14 explicit const_set_ext(const etl::span& sp) ETL_NOEXCEPT +``` +**Decsription** +Construct a `const_set` from a variadic list of elements. + +--- + +```cpp +template +ETL_CONSTEXPR14 explicit const_set_ext(const value_type (&begin_)[Size]) ETL_NOEXCEPT +``` +**Decsription** +Construct a `const_set` from an array. + +## Iterators + +```cpp +const_iterator begin() const ETL_NOEXCEPT +const_iterator cbegin() const ETL_NOEXCEPT +``` +**Decsription** +Returns an iterator to the beginning of the set. + +--- + +```cpp +const_iterator end() const ETL_NOEXCEPT +const_iterator cend() const ETL_NOEXCEPT +``` +**Decsription** +Returns an iterator to the end of the set. + +## Capacity + +```cpp +ETL_CONSTEXPR14 bool empty() const ETL_NOEXCEPT +``` +**Decsription** +Returns `true` if the size of the set is zero, otherwise `false`. + +--- + +```cpp +ETL_CONSTEXPR14 bool full() const ETL_NOEXCEPT +``` +**Decsription** +Returns `true` if the size of the lookup is size, otherwise `false`. + +--- + +```cpp +ETL_CONSTEXPR14 size_t size() const ETL_NOEXCEPT +``` +**Decsription** +Returns the size of the lookup. + +--- + +```cpp +ETL_CONSTEXPR14 size_t max_size() const ETL_NOEXCEPT +``` +**Decsription** +Returns the maximum possible size of the set. + +## Status + +```cpp +ETL_CONSTEXPR14 bool is_valid() const ETL_NOEXCEPT +``` +Check that the elements are valid for a set. +The elements must be sorted and contain no duplicates. + +## Search + +```cpp +ETL_CONSTEXPR14 const_iterator find(const key_type& key) const ETL_NOEXCEPT +``` +**Decsription** +Find the `key` in the container. + +**Return** +A `const_iterator` to the element, or `end()` if it could not be found. + +--- + +```cpp +ETL_CONSTEXPR14 const_iterator lower_bound(const key_type& key) const ETL_NOEXCEPT +``` +**Decsription** +Searches for the first element after the `key`. + +**Return** +A `const_iterator` to the element, or `end()` if it could not be found. + +--- + +```cpp +ETL_CONSTEXPR14 const_iterator upper_bound(const key_type& key) const ETL_NOEXCEPT +``` +**Decsription** +Searches for the first element with the `key`. + +**Return** +A `const_iterator` to the element, or `end()` if it could not be found. + +--- + +```cpp +ETL_CONSTEXPR14 pair equal_range(const key_type& key) const ETL_NOEXCEPT +``` +**Decsription** +The return type is either `std::pair` (default) or `etl::pair` (`ETL_NO_STL`) + +**Return** +Returns a range containing all elements equivalent to `key`. + +--- + +```cpp +ETL_CONSTEXPR14 bool contains(const key_type& k) const ETL_NOEXCEPT +``` +**Decsription** +Check if the container contains the key. + +**Return** +`true` if the container contains the key, otherwise `false`. + +## Search (transparent comparators) + +```cpp +template +ETL_CONSTEXPR14 const_iterator find(const K& key) const ETL_NOEXCEPT +``` +**Decsription** +Find the `key` in the container. + +**Return** +A `const_iterator` to the element, or `end()` if it could not be found. + +--- + +```cpp +template +ETL_CONSTEXPR14 const_iterator lower_bound(const K& key) const ETL_NOEXCEPT +``` +**Decsription** +Searches for the first element after the `key`. + +**Return** +A `const_iterator` to the element, or `end()` if it could not be found. + +--- + +```cpp +template +ETL_CONSTEXPR14 const_iterator upper_bound(const K& key) const ETL_NOEXCEPT +``` +**Decsription** +Searches for the first element with the `key`. + +**Return** +A `const_iterator` to the element, or `end()` if it could not be found. + +--- + +```cpp +template +ETL_CONSTEXPR14 pair equal_range(const K& key) const ETL_NOEXCEPT +``` +**Decsription** +The return type is either `std::pair` (default) or `etl::pair` (`ETL_NO_STL`) + +**Return** +Returns a range containing all elements equivalent to `key`. + +--- + +```cpp +template +ETL_CONSTEXPR14 bool contains(const K& k) const ETL_NOEXCEPT +``` +**Decsription** +Check if the container contains the key. + +**Return** +`true` if the container contains the key, otherwise `false`. + +## Non-member functions + +**Lexicographically comparisons** + +```cpp +operator == +``` +`true` if the contents of the sets are equal, otherwise `false`. + +--- + +```cpp +operator != +``` +`true` if the contents of the sets are not equal, otherwise `false`. + +--- + +```cpp +operator < +``` +`true` if the contents of the lhs is less-than the rhs, otherwise `false`. + +--- + +```cpp +operator <= +``` +`true` if the contents of the lhs is less-than-equal the rhs, otherwise `false`. + +--- + +```cpp +operator > +``` +`true` if the contents of the lhs is greater-than the rhs, otherwise `false`. + +--- + +```cpp +operator >= +``` +`true` if the contents of the lhs is greater-than-equal the rhs, otherwise `false`. + +## Technical stuff + +The const set is implemented as a sorted array key/value pairs. diff --git a/docs/containers/fixed-sized-memory-block-allocator.md b/docs/containers/fixed-sized-memory-block-allocator.md new file mode 100644 index 00000000..90d1e2d3 --- /dev/null +++ b/docs/containers/fixed-sized-memory-block-allocator.md @@ -0,0 +1,45 @@ +--- +title: "fixed_sized_memory_block_allocator" +--- + +{{< callout >}} + Header: `fixed_sized_memory_block_allocator.h` +{{< /callout >}} + +A fixed capacity memory block pool. +Implements an `etl::imemory_block_allocator`. + +```cpp +template +class fixed_sized_memory_block_allocator : public imemory_block_allocator +``` + +## Template parameters + +```cpp +VBlock_Size +``` +The required size of each block. + +--- + +```cpp +VAlignment +``` +The required alignment of each block. + +--- + +```cpp +VSize +``` +The number of blocks. + +## Constants + +```cpp +size_t Block_Size = VBlock_Size; +size_t Alignment = VAlignment; +size_t Size = VSize; +``` + diff --git a/docs/raw/containers/forward_list.txt b/docs/containers/forward-list.md similarity index 56% rename from docs/raw/containers/forward_list.txt rename to docs/containers/forward-list.md index 8705eaf2..7f42e078 100644 --- a/docs/raw/containers/forward_list.txt +++ b/docs/containers/forward-list.md @@ -1,31 +1,41 @@ -forward_list +--- +title: "forward_list" +--- + +{{< callout >}} + Header: `forward_list.h` + Similar to: `std::forward_list` +{{< /callout >}} A fixed capacity forward list. -STL equivalent: std::forward_list +```cpp etl::forward_list etl::forward_list_ext +``` -Inherits from etl::iforward_list -etl::iforward_list may be used as a size independent pointer or reference type for any etl::forward_list instance. +Inherits from `etl::iforward_list`. +`etl::iforward_list` may be used as a size independent pointer or reference type for any `etl::forward_list` instance. -Note: Does not support the member function swap. -____________________________________________________________________________________________________ -Shared Pools +**Note:** Does not support the member function swap. -etl::forward_list_ext -This template may share pools with another etl::forward_list of the same type. -The list is initialised with the pool either at construction time or a call to set_pool(etl::ipool& pool) -When pools are shared there are a few side effects that must be noted. +## Shared Pools -size() and empty() will be O(N) complexity. For a normal etl::forward_list they are O(1) +`etl::forward_list_ext` +This template may share pools with another `etl::forward_list` of the same type. +The list is initialised with the pool either at construction time or a call to `set_pool(etl::ipool& pool)`. +When pools are shared there are a few side effects that must be noted. -Destruction of the container will always be O(N) regardless of whether the type store is trivially destructible or not. +`size()` and `empty()` will be O(N) complexity. For a normal `etl::forward_list` they are O(1). -max_size() will return the potential maximum size of the list. The actual maximum size will dependent of how many elements the other lists sharing the pool have allocated. +Destruction of the container will always be O(N) regardless of whether the type store is trivially destructible or not. -Pool must be declared with the list's pool_type. -i.e. +`max_size()` will return the potential maximum size of the list. The actual maximum size will dependent of how many elements the other lists sharing the pool have allocated. + +Pool must be declared with the list's `pool_type`. + +### Example +```cpp // The element type struct Point { int x; int y; }; @@ -34,28 +44,38 @@ using List = etl::forward_list_ext; // The shared pool etl::pool pool; -____________________________________________________________________________________________________ -Template deduction guides -C++17 and above +``` +## Template deduction guides +**C++17 and above** + +```cpp template etl::forward_list(T...) +``` -Example +### Example +```cpp etl::forward_list data{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 }; +``` -Defines data as an forward_list of int, of length 10, containing the supplied data. -____________________________________________________________________________________________________ -Make template -C++11 and above +Defines data as an `forward_list` of int, of length 10, containing the supplied data. + +## Make template +**C++11 and above** +```cpp template constexpr auto make_forward_list(TValues&&... values) +``` -Example +### Example +```cpp auto data = etl::make_forward_list(0, 1, 2, 3, 4, 5, 6, 7, 8, 9); -____________________________________________________________________________________________________ -Member types +``` +## Member types + +```cpp value_type T size_type std::size_t difference_type std::ptrdiff_t @@ -65,109 +85,170 @@ pointer value_type* const_pointer const value_type* iterator Bi-directional iterator const_iterator Constant bi-directional iterator -____________________________________________________________________________________________________ -Constructor +``` -etl::forward_list(); -etl::forward_list(size_t initialSize, parameter_t value = T()); +## Constructors + +```cpp +etl::forward_list() +``` + +--- + +```cpp +etl::forward_list(size_t initialSize, parameter_t value = T()) +``` + +--- + +```cpp template -etl::forward_list(TIterator begin, TIterator end); +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. +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. -Copy constructor -etl::forward_list - (etl::forward_list& other); -____________________________________________________________________________________________________ -For shared pool lists -etl::forward_list(etl::pool& pool); -etl::forward_list(size_t initialSize, parameter_t value, etl::pool& pool); +## For shared pool lists +```cpp +etl::forward_list(etl::pool& pool) +``` + +--- + +```cpp +etl::forward_list(size_t initialSize, parameter_t value, etl::pool& pool) +``` + +--- + +```cpp template -etl::forward_list(TIterator begin, TIterator end, etl::pool& pool); +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. +Emits 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. +## Copy constructor +**Implicit pool** +Uses the pool from other. +```cpp etl::forward_list(etl::forward_list& other); +``` -Explicit pool +**Explicit pool** +```cpp etl::forward_list(etl::forward_list& other, etl::pool& pool); +``` -____________________________________________________________________________________________________ -Element access +## Element access +```cpp T& front() const T& front() const -Returns a reference or const reference to the first element. +``` +**Description** +Returns a reference or const reference to the first element. Undefined behaviour if the list is empty. -____________________________________________________________________________________________________ -Iterators +## Iterators + +```cpp iterator begin() const_iterator begin() const const_iterator cbegin() const +``` +**Description** Returns an iterator to the beginning of the forward list. Returns end() if the list is empty. -____________________________________________________________________________________________________ + +--- + iterator end() const_iterator end() const const_iterator cend() const +**Description** Returns an iterator to the end of the forward list. -____________________________________________________________________________________________________ + +--- + iterator before_begin() const_iterator before_begin() const const_iterator cbefore_begin() const +**Description** Returns an iterator to before the beginning of the forward list. -____________________________________________________________________________________________________ -Capacity + +## Capacity bool empty() const +**Description** Returns true if the size of the forward list is zero, otherwise false. -____________________________________________________________________________________________________ + +--- + bool full() const +**Description** Returns true if the size of the forward list is SIZE, otherwise false. -____________________________________________________________________________________________________ + +--- + size_t size() const +**Description** Returns the size of the forward list. -____________________________________________________________________________________________________ + +--- + size_t available() const +**Description** Returns the remaining available capacity in the forward list. -____________________________________________________________________________________________________ + +--- + size_t max_size() const +**Description** Returns the maximum possible size of the forward list . -____________________________________________________________________________________________________ -Modifiers + +## Modifiers template void assign(TIterator begin, TIterator end); void assign(size_t n, parameter_t value); - -Fills the forward list with the values. +**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. -____________________________________________________________________________________________________ -void push_front(parameter_t value); +--- + +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. -____________________________________________________________________________________________________ + +--- + <=20.35.9 C++03 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) +--- + C++11 and above template void emplace_front(Args&& ... args) @@ -175,100 +256,202 @@ 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. +--- + >=20.35.10 C++03 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) +--- + C++11 and above 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. -____________________________________________________________________________________________________ + +--- + <=20.19.0 template void insert_after(iterator position, TIterator begin, TIterator end); +--- + iterator insert_after(iterator position, parameter_t value); void insert_after(iterator position, size_t n, parameter_t value); +--- + >=20.20.0 template iterator insert_after(const_iterator position, TIterator begin, TIterator end); +--- + iterator insert_after(const_iterator position, parameter_t value); + +--- + iterator insert_after(const_iterator position, size_t n, parameter_t value); -Inserts values in to the forward list after the specified position. +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. -____________________________________________________________________________________________________ + +--- + <=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); -Erases elements after the specified position. +Erases elements after the specified position. The second version erases up to, but not including end. -____________________________________________________________________________________________________ + +--- + void resize(size_t n); + +--- + 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. +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. -____________________________________________________________________________________________________ + +--- + void clear(); Clears the forward list to a size of zero. -____________________________________________________________________________________________________ -Operations + +## 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(); +--- + +```cpp +void sort() +``` +**Description** +Sorts using the `<` operator. + +--- + +```cpp template -void sort(TCompare compare); -The first version sorts using the < operator. -The second uses the supplied compare function. -____________________________________________________________________________________________________ -void reverse(); +void sort(TCompare compare) +``` +**Description** +Sorts using the supplied `compare` function. + +--- + +```cpp +void reverse() +``` +**Description** Reverses the order of the container. -____________________________________________________________________________________________________ -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. +## Non-member functions +```cpp +operator == +``` +**Return** +`true` if the contents of the lists are equal, otherwise `false`. + +--- + +```cpp +operator != +``` +**Return** +`true` if the contents of the lists are not equal, otherwise `false`. + +--- + +```cpp +operator < +``` +**Return** +`true` if the contents of the lhs are lexicographically less than the contents of the rhs, otherwise `false`. + +--- + +```cpp +operator <= +``` +**Return** +`true` if the contents of the lhs are lexicographically less than or equal to the contents of the rhs, otherwise `false`. + +--- + +```cpp +operator > +``` +**Return** +`true` if the contents of the lhs are lexicographically greater than the contents of the rhs, otherwise `false`. + +--- + +```cpp +operator >= +``` +**Return** +`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/indirect_vector.md b/docs/containers/indirect-vector.md similarity index 100% rename from docs/containers/indirect_vector.md rename to docs/containers/indirect-vector.md diff --git a/docs/containers/list.md b/docs/containers/list.md new file mode 100644 index 00000000..6bdaba55 --- /dev/null +++ b/docs/containers/list.md @@ -0,0 +1,834 @@ +--- +title: "list" +--- + +{{< callout >}} + Header: `list.h` + Similar to: `std::list` +{{< /callout >}} + +A fixed capacity bidirectional list. + +```cpp +etl::list +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. + +## Shared Pools + +```cpp +etl::list +``` +This template may share pools with another `etl::list` of the same type. +The list is initialised with the pool either at construction time or a call to `set_pool(etl::ipool& pool)`. +When pools are shared there are a few side effects that must be noted. + +`size()` and `empty()` will have O(N) complexity. +For a normal `etl::list` they are O(1). + +Destruction of the container will always be O(N) regardless of whether the type store is trivially destructible or not. + +`max_size()` will return the potential maximum size of the list. The actual maximum size will dependent of how many elements the other lists sharing the pool have allocated. + +The pool must be declared with the list's `pool_type`. + +### Example +```cpp +// The element type +struct Point { int x; int y; }; + +// The list type +using List = etl::list_ext; + +// The shared pool +etl::pool pool; +``` + +## Template deduction guides +**C++17 and above** + +```cpp +template +etl::list(T...) +``` + +### Example +```cpp +etl::list data{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 }; +``` +Defines data as an list of `int`, of length `10`, containing the supplied data. + +## Make template +**C++11 and above** +```cpp +template +constexpr auto make_list(TValues&&... values) +``` + +### Example +```cpp +auto data = etl::make_list(0, 1, 2, 3, 4, 5, 6, 7, 8, 9); +``` + +## Member types + +```cpp +value_type T +size_type std::size_t +difference_type std::ptrdiff_t +reference value_type& +const_reference const value_type& +rvalue_reference value_type&& +pointer value_type* +const_pointer const value_type* +iterator Bi-directional iterator +const_iterator Constant bi-directional iterator +reverse_iterator ETL_OR_STD::reverse_iterator +const_reverse_iterator ETL_OR_STD::reverse_iterator +``` + +## Constructors + +```cpp +etl::list() +``` + +--- + +```cpp +etl::list(size_t initialSize, parameter_t value = T()) +``` + +--- + +```cpp +etl::list(const etl::list&) +``` + +--- + +```cpp +etl::list(etl::list&&) +``` + +--- + +```cpp +template +etl::list(TIterator begin, TIterator end) +``` +**Description** +Emits an `etl::list_iterator` if the iterators are invalid. If asserts or exceptions are disabled then undefined behaviour occurs. + +## For shared pool lists + +```cpp +etl::list(etl::pool& pool) +``` + +```cpp +etl::list(size_t initialSize, parameter_t value, etl::pool& pool) +``` + +```cpp +template +etl::list(TIterator begin, TIterator end, etl::pool& pool) +``` +**Description** +Emits an `etl::list_iterator` if the iterators are invalid. If asserts or exceptions are disabled then undefined behaviour occurs. + +### Copy constructor +**Implicit pool** +Uses the pool from other. +```cpp +etl::list(etl::list& other) +``` + +**Explicit pool** +```cpp +etl::list(etl::list& other, etl::pool& pool) +``` + +### Initialisation + +if the list is sharing pools then a `set_pool(etl::pool&)` is available. +If a pool has already been set then the list is first cleared before updating to the new pool. + +The pool instance can be retrieved by call `get_pool()` + +## Element access + +```cpp +T& front() +const T& front() const +``` +**Description** +Returns a reference or const reference to the first element. +Undefined behaviour if the list is empty. + +--- + +```cpp +T& back() +const T& back() const +``` +**Description** +Returns a reference or const reference to the last element. +Undefined behaviour if the list is empty. + +## Iterators + +```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 +reverse_iterator rbegin() +const_reverse_iterator rbegin() const +const_reverse_iterator crbegin() const +``` +**Description** +Returns a reverse iterator to the beginning of the list. + +--- + +```cpp +reverse_iterator rend() +const_reverse_iterator rend() const +const_reverse_iterator crend() const +``` +**Description** +Returns a reverse iterator to the end of the list. + +## Capacity + +```cpp +bool empty() const +``` +**Description** +Returns true if the size of the list is zero, otherwise false. + +--- + +```cpp +bool full() const +``` +**Description** +Returns true if the size of the list is SIZE, otherwise false. + +--- + +```cpp +size_t size() const +``` +**Description** +Returns the size of the list. + +--- + +```cpp +size_t available() const +``` +**Description** +Returns the remaining available capacity in the list. + +--- + +```cpp +size_t max_size() const +``` +**Description** +Returns the maximum possible size of the list. + +## Modifiers + +```cpp +template +void assign(TIterator begin, TIterator end) +``` +**Description** +Assigns from a range of values. + +--- + +```cpp +void assign(size_t n, parameter_t value) +``` +**Description** +Fills the list with the values. + +--- + +```cpp +void push_front(const T& value) +void push_front(T&& value) +``` +**Description** +Pushes a value to the front of the list. +If the list is full then emits an `etl::list_full error`. + +--- + +**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. +Since: `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. +Since: `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. +Since: `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. +Since: `20.35.10` + +--- + +```cpp +template +void emplace_front(const T1& value1, const T2& value2, + const T3& value3, const T4& value4) +``` +**Description** +Emplaces a value at the front, constructed using the supplied arguments. +Before: `20.35.10` + +--- + +**C++11 and above** +```cpp +template +reference emplace_front(Args&& …args) +``` +**Description** +Emplaces a value at the front, constructed using the supplied arguments. + +--- + +```cpp +void push_back(const T& value); +void push_back(T&& value); +``` +**Description** +Pushes a value to the back of the list. +If the list is full and `ETL_CHECK_PUSH_POP` is defined then emits an `etl::list_full` error, otherwise undefined behaviour occurs. + +--- + +**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. +Since: `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. +Since: `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. +Since: `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, const T2& value2, + const T3& value3, const T4& value4) +``` +**Description** +Emplaces a value at the back, constructed using the supplied arguments. +Since: `20.35.10` + +--- + +**C++11 and above** +```cpp +template +reference emplace_back(Args&& ... args) +``` +**Description** +Emplaces a value at the back, constructed using the supplied arguments. +Since: `20.35.10` + +--- + +**C++11 and above** +```cpp +template +reference emplace_back(Args&& ... args) +``` +**Description** +Emplaces a value at the back, constructed using the supplied arguments. +Since: `20.35.10` + +--- + +```cpp +void pop_front() +``` +**Description** +Pop a value from the front of the list. +If the list is empty and `ETL_CHECK_PUSH_POP` is defined then emits an `etl::list_empty` error, otherwise undefined behaviour occurs. + +--- + +```cpp +void pop_back() +``` +**Description** +Pop a value from the back of the list. +If the list is empty and `ETL_CHECK_PUSH_POP` is defined then emits an `etl::list_empty` error, otherwise undefined behaviour occurs. + +--- + +```cpp +template +void insert(iterator position, TIterator begin, TIterator end) +``` +**Description** +Before: `20.20.0` + +--- + +```cpp +iterator insert(iterator position, parameter_t value); +void insert(iterator position, size_t n, parameter_t value) +``` + +```cpp +template +iterator insert(const_iterator position, TIterator begin, TIterator end) +``` +**Description** +Since `20.20.0` + +--- + +```cpp +iterator insert(const_iterator position, parameter_t value) +iterator insert(const_iterator position, size_t n, parameter_t value) +``` +**Description** +Inserts values in to the list. If the list is full then emits an `etl::list_full` error. + +--- + +**C++03** +```cpp +void emplace(iterator position, const T1& value1) +``` +**Description** +Before: `20.20.0` + +--- + +```cpp +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) +``` + +```cpp +iterator emplace(const_iterator position, const T1& value1) +``` +**Description** +Since: `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** +```cpp +void emplace(iterator position, Args&& ... args) +``` +**Description** +Before: `20.20.0` + +--- + +```cpp +void emplace(const_iterator position, Args&& ... args) +``` +**Description** +Constructs an item at the insert point in the the list 'in place'. +Since: `20.20.0` + +--- + +```cpp +template +iterator erase(TIterator begin, TIterator end) +``` + +--- + +```cpp +iterator erase(iterator position) +``` +**Description** +Before: `20.20.0` + +--- + +```cpp +iterator erase(iterator position) +iterator erase(const_iterator position) +``` +**Description** +Erases values in the list. +Before: `20.21.0` + +--- + +```cpp +void resize(size_t n); +void resize(size_t n, parameter_t value) +``` +**Description** +Resizes the list. If the new size is larger then the first assigns default constructed values, the second assigns the supplied value. +If `n` is larger than the capacity then emits an `etl::list_full` error, if asserts or exceptions are not enabled then undefined behaviour occurs. + +--- + +```cpp +void clear(); +``` +**Description** +Clears the list to a size of zero. + +--- + +```cpp +void splice(iterator to, etl::ilist& other) +void splice(iterator to, etl::ilist&& other) +``` +**Description** +Moves the elements in list other to before the position to. +The operation performs copies between the different lists. + +--- + +```cpp +void splice(iterator to, etl::ilist& other, iterator from) +void splice(iterator to, etl::ilist&& other, iterator from) +``` +**Description** +Moves the element at position from in list other to before the position to. +The operation is fast when spicing within the same list, otherwise performs copies between different lists. +If from is not valid then undefined behaviour occurs. + +--- + +```cpp +void splice(iterator to, etl::ilist& other, iterator first, iterator last) +void splice(iterator to, etl::ilist&& other, iterator first, iterator last) +``` +**Description** +Moves the elements in the range first to one before last in list other to before the position to. +The operation is fast when spicing within the same list, otherwise performs copies between different lists. + +--- + +```cpp +void merge(etl::ilist& other) +void merge(etl::ilist&& other) +``` +**Description** +Merges the elements in list other to this list. +The lists must be sorted. If a debug compile and asserts or exceptions are enabled than an etl::list_unsorted is emitted if either list is unsorted, otherwise undefined behaviour occurs. + +--- + +```cpp +template +void merge(etl::ilist& other, TCompare compare) +``` + +--- + +```cpp +template +void merge(etl::ilist&& other, TCompare compare) +``` +**Description** +Merges the elements in list other to this list using the supplied comparison function to determine order. +The lists must already be sorted according to the compare function. +If a debug compile and asserts or exceptions are enabled than an etl::list_unsorted is emitted if either list is unsorted, otherwise undefined behaviour occurs. + +## Operations + +```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 + +`==` + `true` if the contents of the lists are equal, otherwise `false`. + +`!=` + `true` if the contents of the lists are not equal, otherwise `false`. + +`<` + `true` if the contents of the lhs are lexicographically less than the contents of the rhs, otherwise `false`. + +`<=` + `true` if the contents of the lhs are lexicographically less than or equal to the contents of the rhs, otherwise `false`. + +`>` + `true` if the contents of the lhs are lexicographically greater than the contents of the rhs, otherwise `false`. + +`>=` + `true` if the contents of the lhs are lexicographically greater than or equal to the contents of the rhs, otherwise `false`. + +## Shared pool example + +```cpp +// The element type. +struct Point { int x; int y; }; + +// The list type +using List = etl::list_ext; + +// The shared pool. Maximum of 10 items. +etl::pool pool; + +// The vector of lists with shared pools. +etl::vector vector_of_lists(3, List(pool)); + +// Make some data. +Point point = { 1, 2 }; + +// Push one to each list. +vector_of_lists[0].push_back(point); +vector_of_lists[1].push_back(point); +vector_of_lists[2].push_back(point); + +size_t available = 0; + +available = vector_of_lists[0].available(); // Reports '7' +available = vector_of_lists[1].available(); // Reports '7' +available = vector_of_lists[2].available(); // Reports '7' +``` diff --git a/docs/containers/maps/const_map.md b/docs/containers/maps/const-map.md similarity index 100% rename from docs/containers/maps/const_map.md rename to docs/containers/maps/const-map.md diff --git a/docs/containers/maps/const_multimap.md b/docs/containers/maps/const-multimap.md similarity index 100% rename from docs/containers/maps/const_multimap.md rename to docs/containers/maps/const-multimap.md diff --git a/docs/containers/pools/_index.md b/docs/containers/pools/_index.md new file mode 100644 index 00000000..778a5979 --- /dev/null +++ b/docs/containers/pools/_index.md @@ -0,0 +1,6 @@ +--- +title: "Pools" +weight: 100 +--- + +Pool like containers. \ No newline at end of file diff --git a/docs/containers/pools/generic-pool.md b/docs/containers/pools/generic-pool.md new file mode 100644 index 00000000..eb400d36 --- /dev/null +++ b/docs/containers/pools/generic-pool.md @@ -0,0 +1,217 @@ +--- +title: "generic_pool" +weight: 2 +--- + +{{< callout >}} + Header: `generic_pool.h` +{{< /callout >}} + +A fixed capacity object pool, where allocation and release are O(1) operations. + +**Internally defined storage** +```cpp +etl::generic_pool +``` + +**Externally defined storage** +```cpp +etl::generic_pool_ext +``` + +--- + +`etl::generic_pool` inherits from `etl::ipool` +etl::ipool may be used as a size and type independent pointer or reference type for any `etl::generic_pool` instance. + +--- + +`ipool.h` defines `etl::ipool`. +`generic_pool.h` defines `etl::generic_pool`. + +**Notes** +When using `etl::generic_pool`, `Type_Size` must be set to the size of the largest type to be stored, and `Alignment` set to the largest alignment of all of the types to be stored. +This may be achieved using `etl::largest`. + +```cpp +typedef etl::largest largest; +etl::generic_pool pool; +``` + +**Notes** +There are two methods for allocating objects from the pool. + +```cpp +allocate +release +``` +`allocate` does not construct. It merely provides access to memory that is sized and aligned to contain a `T` object. The programmer must use placement `new` to construct the object. +`release` returns the memory allocation to the to the pool. + +```cpp +create +destroy +``` +`create` allocates memory from the pool and calls its constructor. +`destroy` will call the destructor for the object and release it back to the pool. + +## Constructors + +```cpp +generic_pool() +``` +**Description** +For `etl::generic_pool`. +Constructs a generic_pool. +No elements are constructed. + +--- + +```cpp +generic_pool_ext(char* buffer, size_t size) +``` +**Description** +For `etl::generic_pool_ext`. +Constructs a generic_pool from an external bufffer. +No elements are constructed. + +## Operations + +```cpp +template +T* allocate() +``` +**Description** +Allocates an item from the pool and returns a pointer to it. +If the pool has no free items then an `etl::pool_no_allocation()` is emitted and a `nullptr` is returned. +**Note:** Does not call the object's constructor. + +--- + +```cpp +void release(const void* const p_object); +``` +**Description** +Releases an object back to the pool. +If the object does not belong to the pool an `etl::pool_object_not_in_pool()` is emitted. +**Note:** Does not call the object's destructor. + +--- + +```cpp +void release_all(); +``` +Releases all objects back to the pool. +**Note:** Does not destruct any `T` objects. + +--- + +```cpp +bool is_in_pool(const T* const p_object) const; +``` +**Description** +Checks to see if an object belongs to the pool. +Returns `true` if it does, otherwise `false`. + +--- + +**C++03** +**Description** +```cpp +template +T* create() +``` + +```cpp +template +T* create(const T1& value1) +``` + +```cpp +template +T* create(const T1& value1, const T2& value2) +``` + +```cpp +template +T* create(const T1& value1, const T2& value2, const T3& value3) +``` + +```cpp +template +T* create(const T1& value1, const T2& value2, const T3& value3, const T4& value4) +``` + +--- + +**C++11** +```cpp +template +T* create(Args&&... args) +``` + +--- + +There is a matching destroy function. + +```cpp +template +void destroy(const void* const p_object) +``` + +## Capacity + +```cpp +bool empty() const +``` +**Description** +Returns `true` if there are no allocated objects in the pool, otherwise `false`. + +--- + +```cpp +bool full() const +``` +**Description** +Returns `true` if there are no free objects in the pool, otherwise `false`. + +--- + +```cpp +size_t available() const +``` +**Description** +Returns the remaining available free objects in the pool. + +--- + +```cpp +size_t size() const +``` +**Description** +Returns the number of allocated objects in the pool. + +--- + +```cpp +size_t max_size() const +``` +**Description** +Returns the maximum number of objects in the pool. + +## Constants + +`TYPE_SIZE` The size of an item in the pool. +`SIZE` The maximum number of items in the pool. +`ALIGNMENT` The alignment of items in the pool. + +## The Technical Bit + +The pool is based around a block of memory, with storage for Size items, properly aligned for type `T`. +Each item in the pool is a `union` of a `uintptr_t` and a type `T`. Free items contain a pointer to the next free item. Allocated items contain a `T` value. + +Allocation is quick, as all that is necessary is to return the address of the next free item. + +Release is similarly quick, as the item's content is simply replaced with the address of the current next free item. + +On first use the memory block is uninitialised. On each new allocation a new item is initialised with the address of the next free item. This just-in-time initialisation means that construction does not involve writing to a potentially large amount of memory in one go. diff --git a/docs/containers/pools/ipool.md b/docs/containers/pools/ipool.md new file mode 100644 index 00000000..fc3ffb03 --- /dev/null +++ b/docs/containers/pools/ipool.md @@ -0,0 +1,273 @@ +--- +title: "ipool" +weight: 1 +--- + +{{< callout >}} + Header: `ipool.h` +{{< /callout >}} + +The base of all fixed capacity object pools. + +## Exceptions classes + +```cpp +class pool_exception : public exception +``` +**Description** +The base class for pool exceptions. + +--- + +```cpp +class pool_no_allocation : public pool_exception +``` +**Description** +The exception thrown when the pool has no more free items. + +--- + +```cpp +class pool_object_not_in_pool : public pool_exception +``` +**Description** +The exception thrown when an object is released which does not belong to the pool. + +--- + +```cpp +class pool_element_size : public pool_exception +``` +**Description** +The exception thrown when an the type requested is larger than the element size. + +## Member Types + +`size_type = size_t` + +## Iterators + +```cpp +ipool_iterator +``` +**Description** +Supports increment, dereference and comparison. + +--- + +```cpp +const_ipool_iterator +``` +**Description** +Supports increment, dereference and comparison. + +## Member funcctions + +```cpp +iterator begin() +``` + +--- + +```cpp +iterator end() +``` + +--- + +```cpp +const_iterator begin() const +``` + +--- + +```cpp +const_iterator end() const +``` + +--- + +```cpp +const_iterator cbegin() const +``` + +--- + +```cpp +const_iterator cend() const +``` + +--- + +```cpp +template +T* allocate() +``` +**Description** +Allocates storage for an object from the pool. +If asserts or exceptions are enabled and there are no more free items an `etl::pool_no_allocation` if emitted, otherwise a null pointer is returned. + +--- + +**C++03** +```cpp +template +T* create() +``` +**Description** +Emplace with no parameters. + +--- + +```cpp +template +T* create(const T1& value1) +``` +**Description** +Emplace with 1 parameter. + +--- + +```cpp +template +T* create(const T1& value1, const T2& value2) +``` +**Description** +Emplace with 2 parameters. + +--- + +```cpp +template +T* create(const T1& value1, const T2& value2, const T3& value3) +``` +**Description** +Emplace with 3 parameters. + +--- + +```cpp +template +T* create(const T1& value1, const T2& value2, const T3& value3, const T4& value4) +``` +**Description** +Emplace with 4 parameters. + +--- + +**C++11 and above** +```cpp +template +T* create(Args&&... args) +``` +**Description** +Emplace with variadic constructor parameters. + +--- + +```cpp + template + void destroy(const T* const p_object) +``` +**Description** +Destroys the object. +Undefined behaviour if the pool does not contain a `T`. + +**Parameters** +`p_object` A pointer to the object to be destroyed. + +--- + +```cpp +void release(const void* const p_object) +``` +**Description** +Release an object in the pool. +If asserts or exceptions are enabled and the object does not belong to this pool then an `etl::pool_object_not_in_pool` is thrown. + +**Parameters** +`p_object` A pointer to the object to be released. + +--- + +```cpp +void release_all() +``` +**Description** +Release all objects in the pool. + +--- + +```cpp +bool is_in_pool(const void* const p_object) const +``` +**Description** +Check to see if the object belongs to the pool. + +**Parameters** +`p_object` A pointer to the object to be checked. + +**Return** +`true` if it does, otherwise `false`. + +--- + +```cpp +size_t max_size() const +``` +**Description** +Returns the maximum number of items in the pool. + +--- + +```cpp +size_t max_item_size() const +``` +**Description** +Returns the maximum size of an item in the pool. + +--- + +```cpp +size_t capacity() const +``` +**Description** +Returns the maximum number of items in the pool. + +--- + +```cpp +size_t available() const +``` +**Description** +Returns the number of free items in the pool. + +--- + +```cpp +size_t size() const +``` +**Description** +Returns the number of allocated items in the pool. + +--- + +```cpp +bool empty() const +``` +**Description** +Checks to see if there are no allocated items in the pool. + +**Return** +`true` if there are none allocated. + +--- + +```cpp +bool full() const +``` +**Description** +Checks to see if there are no free items in the pool. + +**Return** +`true` if there are none free. diff --git a/docs/containers/pools/pool.md b/docs/containers/pools/pool.md new file mode 100644 index 00000000..4b1e6fbf --- /dev/null +++ b/docs/containers/pools/pool.md @@ -0,0 +1,239 @@ +--- +title: "pool" +weight: 3 +--- + +{{< callout >}} + Header: `pool.h` +{{< /callout >}} + +A fixed capacity object pool, where allocation and release are O(1) operations. + +**Internally defined storage** +```cpp +etl::pool +``` + +**Externally defined storage** +```cpp +etl::pool_ext +``` + +--- + +`etl::pool` inherits from `etl::generic_pool`, which itself inherits from `etl::ipool`. +`etl::ipool` may be used as a size and type independent pointer or reference type for any `etl::pool`. + +**Notes** +There are two methods for allocating objects from the pool. + +```cpp +allocate +release +``` +`allocate` does not construct. It merely provides access to memory that is sized and aligned to contain a `T` object. The programmer must use placement `new` to construct the object. +`release` returns the memory allocation to the to the pool. + +```cpp +create +destroy +``` +`create` allocates memory from the pool and calls its constructor. +`destroy` will call the destructor for the object and release it back to the pool. + +## Example +```cpp +class Data +{ + ... +}; + +etl::pool data_pool; + +// Create. +Data* pdata = new (data_pool.allocate()) Data(); + +// Destroy +pdata->~Data(); +data_pool.release(pdata); +``` + +--- + +Heterogeneous pools may be constructed by basing the pool's type on a `union`, or using `etl::variant`. + +```cpp +union Data +{ + char text[100]; + int counter; + double ratio; +}; + +etl::pool data_pool; + +char *pc = data_pool.allocate(); +int *pi = data_pool.allocate(); +double *pd = data_pool.allocate(); +``` + +## Constructors + +```cpp +pool() +``` +**Description** +For `etl::pool`. +Constructs a pool. +No elements are constructed. + +--- + +```cpp +pool_ext(char* buffer, size_t size) +``` +**Description** +For `etl::pool_ext`. +Constructs a pool from an external bufffer. +No elements are constructed. + +## Operations + +```cpp +template +T* allocate() +``` +**Description** +Allocates an item from the pool and returns a pointer to it. +If the pool has no free items then an `etl::pool_no_allocation()` is emitted and a `nullptr` is returned. +**Note:** Does not call the object's constructor. + +--- + +```cpp +void release(const void* const p_object); +``` +**Description** +Releases an object back to the pool. +If the object does not belong to the pool an `etl::pool_object_not_in_pool()` is emitted. +**Note:** Does not call the object's destructor. + +--- + +```cpp +void release_all(); +``` +Releases all objects back to the pool. +**Note:** Does not destruct any `T` objects. + +--- + +```cpp +bool is_in_pool(const T* const p_object) const; +``` +**Description** +Checks to see if an object belongs to the pool. +Returns `true` if it does, otherwise `false`. + +--- + +**C++03** +**Description** +```cpp +template +T* create() +``` + +```cpp +template +T* create(const T1& value1) +``` + +```cpp +template +T* create(const T1& value1, const T2& value2) +``` + +```cpp +template +T* create(const T1& value1, const T2& value2, const T3& value3) +``` + +```cpp +template +T* create(const T1& value1, const T2& value2, const T3& value3, const T4& value4) +``` + +--- + +**C++11** +```cpp +template +T* create(Args&&... args) +``` + +--- + +There is a matching destroy function. + +```cpp +template +void destroy(const void* const p_object) +``` + +## Capacity + +```cpp +bool empty() const +``` +**Description** +Returns `true` if there are no allocated objects in the pool, otherwise `false`. + +--- + +```cpp +bool full() const +``` +**Description** +Returns `true` if there are no free objects in the pool, otherwise `false`. + +--- + +```cpp +size_t available() const +``` +**Description** +Returns the remaining available free objects in the pool. + +--- + +```cpp +size_t size() const +``` +**Description** +Returns the number of allocated objects in the pool. + +--- + +```cpp +size_t max_size() const +``` +**Description** +Returns the maximum number of objects in the pool. + +## Constants + +`TYPE_SIZE` The size of an item in the pool. +`SIZE` The maximum number of items in the pool. +`ALIGNMENT` The alignment of items in the pool. + +## The Technical Bit + +The pool is based around a block of memory, with storage for Size items, properly aligned for type `T`. +Each item in the pool is a `union` of a `uintptr_t` and a type `T`. Free items contain a pointer to the next free item. Allocated items contain a `T` value. + +Allocation is quick, as all that is necessary is to return the address of the next free item. + +Release is similarly quick, as the item's content is simply replaced with the address of the current next free item. + +On first use the memory block is uninitialised. On each new allocation a new item is initialised with the address of the next free item. This just-in-time initialisation means that construction does not involve writing to a potentially large amount of memory in one go. diff --git a/docs/containers/queues/priority_queue.md b/docs/containers/queues/priority-queue.md similarity index 100% rename from docs/containers/queues/priority_queue.md rename to docs/containers/queues/priority-queue.md diff --git a/docs/containers/queues/queue-lockable.md b/docs/containers/queues/queue-lockable.md new file mode 100644 index 00000000..6124a75e --- /dev/null +++ b/docs/containers/queues/queue-lockable.md @@ -0,0 +1,210 @@ +--- +title: "queue_lockable" +--- + +This class is designed to be an alternative to `etl::queue_spsc_locked`. +It is an abstract class and requires that the user derives their own type from it. + +The derived class must override the two pure virtual functions `void lock() const` and `void unlock() const` to implement the required locking functionality, whether this be a mutex, ISR control or something else. +They must perform the requisite memory barriers to preserve the order of execution. + +Many functions have two versions. One locks and unlocks access and is used from the foreground task. The other, with a `_from_unlocked` suffix, are called from the background task. + +```cpp +etl::queue_lockable +``` + +Inherits from `etl::iqueue_lockable`. +`etl::iqueue_lockable` may be used as a size independent pointer or reference type for any `etl::queue_lockable` instance of the same implementation. + +The memory model determines the type used internally for indexes and size, to allow for the most efficient implementation for the application. + +## Maximum queue sizes + +```cpp +MEMORY_MODEL_SMALL 255 +MEMORY_MODEL_MEDIUM 65535 +MEMORY_MODEL_LARGE 2147483647 +MEMORY_MODEL_HUGE 9223372036854775807 +``` +See memory_model.h + +## Member types + +```cpp +value_type T +size_type +pointer value_type* +const_pointer const value_type* +reference value_type& +const_reference const value_type& +``` + +## Constructor + +```cpp +queue_lockable() +``` + +## Capacity + +```cpp +bool empty() const +bool empty_from_unlocked() const +``` +**Description** +Returns `true` if the size of the queue is zero, otherwise `false`. + +--- + +```cpp +bool full() const +bool full_from_unlocked() const +``` +**Description** +Returns `true` if the size of the queue is SIZE, otherwise `false`. + +--- + +```cpp +size_type size() const +size_type size_from_unlocked() const +``` +**Description** +Returns the size of the queue. + +--- + +```cpp +size_type available() const +size_type available_from_unlocked() const +``` +**Description** +Returns the remaining available capacity in the queue. + +--- + +```cpp +size_type max_size() const +``` +**Description** +Returns the maximum possible size of the queue. + +--- + +```cpp +size_type capacity() const +``` +**Description** +Returns the maximum possible size of the queue. + +## Modifiers + +```cpp +bool push(const T& value) +bool push(T&& value) +bool push_from_unlocked(const T& value) +bool push_from_unlocked(T&& value) +``` +**Description** +Pushes a value to the back of the queue. +Returns true if successful, otherwise false. + +--- + +```cpp +bool pop() +bool pop_from_unlocked() +``` +**Description** +Pop a value from the front of the list. +Returns true if successful, otherwise false. + +--- + +```cpp +bool pop(T& value) +bool pop_from_unlocked(T& value) +``` +**Description** +Pop a value from the front of the list and place it in value. +Returns true if successful, otherwise false. + +--- + +```cpp +void clear() +void clear_from_unlocked() +``` +**Description** +Clears the queue to a size of zero. + +--- + +### C++03 +```cpp +bool emplace(const T1& value1); +bool emplace(const T1& value1, const T2& value2); +bool emplace(const T1& value1, const T2& value2, const T3& value3); +bool emplace(const T1& value1, const T2& value2, const T3& value3, const T4& value4); +``` +**Description** +Constructs an item in the the queue 'in place'. + +### C++11 +```cpp +bool emplace(Args&&… args); +``` +**Description** +Constructs an item in the the queue 'in place'. + +## Notes + +Remember that interrupts may occur between calls to the access protected functions. For example, a call to `empty()` may return `true`, but a subsequent call to `pop()` may succeed if an interrupt occurred between the two and pushed a new value. + +## Example + +```cpp +class InterruptControl +{ +public: + + void lock() + { + // Store current interrupt control register and disable the relevant interrupt. + } + + void unlock() + { + // Restore the interrupt control register. + } +}; + +InterruptControl interruptControl; + +// Create function wrappers with direct calls to the instance's member functions. +etl::function_imv lock; +etl::function_imv unlock; + +etl::queue_spsc_locked queue(lock, unlock); + +int main() +{ + while (true) + { + char c; + + if (queue.pop(c)) + { + Print(c); + } + } +} + +void ISR(char c) +{ + queue.push_from_unlocked(c); +} +``` diff --git a/docs/containers/queues/queue-mpmc-mutex.md b/docs/containers/queues/queue-mpmc-mutex.md new file mode 100644 index 00000000..136b8459 --- /dev/null +++ b/docs/containers/queues/queue-mpmc-mutex.md @@ -0,0 +1,190 @@ +--- +title: "queue_mpmc_mutex" +--- + +{{< callout >}} + Header: `queue_mpmc_mutex.h` +{{< /callout >}} + +A fixed capacity multi-producer, multi-consumer queue for multi-threaded systems that uses etl::mutex to control access. + +```cpp +etl::queue_mpmc_mutex +``` + +Inherits from `etl::iqueue_mpmc_mutex`. +`etl::iqueue_mpmc_mutex` may be used as a size independent pointer or reference type for any `etl::queue_mpmc_mutex` instance of the same implementation. + +The memory model determines the type used internally for indexes and size, to allow for the most efficient implementation for the application. + +## Maximum queue sizes + +```cpp +MEMORY_MODEL_SMALL 255 +MEMORY_MODEL_MEDIUM 65535 +MEMORY_MODEL_LARGE 2147483647 +MEMORY_MODEL_HUGE 9223372036854775807 +``` + +See `memory_model.h` + +## Member types + +```cpp +value_type T +size_type +pointer value_type* +const_pointer const value_type* +reference value_type& +const_reference const value_type& +``` + +## Constructor + +```cpp +queue_mpmc_mutex() +``` + +## Capacity + +```cpp +bool empty() const +``` +**Description** +Returns `true` if the size of the queue is zero, otherwise `false`. + +--- + +```cpp +bool full() const +``` +**Description** +Returns `true` if the size of the queue is SIZE, otherwise `false`. + +--- + +```cpp +size_t size() const +``` +**Description** +Returns the size of the queue. + +--- + +```cpp +size_t available() const +size_t available_from_isr() const +``` +**Description** +Returns the remaining available capacity in the queue. + +--- + +```cpp +ETL_CONSTEXPR size_t max_size() const +``` +**Description** +Returns the maximum possible size of the queue. + +--- + +```cpp +ETL_CONSTEXPR size_t capacity() const +``` +**Description** +Returns the maximum possible size of the queue. + +## Modifiers + +```cpp +bool push(const T& value) +bool push(T&& value) +``` +**Description** +Pushes a value to the back of the queue. +Returns `true` if successful, otherwise `false`. + +--- + +```cpp +bool pop() +``` +**Description** +Pop a value from the front of the list. +Returns `true` if successful, otherwise `false`. + +--- + +```cpp +bool pop(T& value) +bool pop(T&& value) +``` +**Description** +Pop a value from the front of the list and place it in value. +Returns `true` if successful, otherwise `false`. + +--- + +```cpp +void clear() +``` +**Description** +Clears the queue to a size of zero + +--- + +### C++03 +```cpp +bool emplace(const T1& value1) +bool emplace(const T1& value1, const T2& value2) +bool emplace(const T1& value1, const T2& value2, const T3& value3) +bool emplace(const T1& value1, const T2& value2, const T3& value3, const T4& value4) +``` +**Description** +Constructs an item in the the queue 'in place'. + +### C++11 +```cpp +bool emplace(Args&&… args) +``` +**Description** +Constructs an item in the the queue 'in place'. + +## Notes + +Remember that thread context switches may occur between calls to the access protected functions. For example, a call to `empty()` may return `true`, but a subsequent call to `pop()` may succeed if a context switch occurred between the two and pushed a new value. + +## Example + +```cpp +etl::queue_mpmc_mutex queue; + +int main() +{ + while (true) + { + char c; + + if (queue.pop(c)) + { + Print(c); + } + } +} + +void FunctionInThread1(char c) +{ + while (!queue.push(c)) + { + } +} + +void FunctionInThread2(char c) +{ + while (!queue.push(c)) + { + } +} +``` diff --git a/docs/containers/queues/queue-spsc-atomic.md b/docs/containers/queues/queue-spsc-atomic.md new file mode 100644 index 00000000..6c3ad05a --- /dev/null +++ b/docs/containers/queues/queue-spsc-atomic.md @@ -0,0 +1,186 @@ +--- +title: "queue_spsc_atomic" +--- + +A fixed capacity single-producer, single-consumer queue for multi-threaded and interrupt driven systems. +The queue may be used to transfer data to or from two threads or an ISR. + +The queue makes use of `etl::atomic_size_t`. + +```cpp +etl::queue_spsc_atomic +``` + +Inherits from `etl::iqueue_spsc_atomic`. +`etl::iqueue_spsc_atomic` may be used as a size independent pointer or reference type for any `etl::queue_spsc_atomic` instance of the same implementation. + +The memory model determines the type used internally for indexes and size, to allow for the most efficient implementation for the application. + +## Maximum queue sizes +```cpp +MEMORY_MODEL_SMALL 255 +MEMORY_MODEL_MEDIUM 65535 +MEMORY_MODEL_LARGE 2147483647 +MEMORY_MODEL_HUGE 9223372036854775807 +``` + +See `memory_model.h` + +## Member types + +```cpp +value_type T +size_type +pointer value_type* +const_pointer const value_type* +reference value_type& +const_reference const value_type& +``` + +## Constructor + +```cpp +queue_spsc_atomic() +``` + +## Capacity + +```cpp +bool empty() const +``` +**Description** +Returns true if the size of the queue is zero, otherwise false. +Accurate from the 'pop' thread. +'Not empty' is a guess from the 'push' thread. + +--- + +```cpp +bool full() const +``` +**Description** +Returns true if the size of the queue is SIZE, otherwise false. +Accurate from the 'push' thread. +'Not full' is a guess from the 'pop' thread. + +--- + +```cpp +size_t size() const +``` +**Description** +Returns the size of the queue. +Due to concurrency, this is a guess. + +--- + +```cpp +size_t available() const +``` +**Description** +Returns the remaining available capacity in the queue. +Due to concurrency, this is a guess. + +--- + +```cpp +ETL_CONSTEXPR size_t max_size() const +``` +**Description** +Returns the maximum possible size of the queue. + +--- + +```cpp +ETL_CONSTEXPR size_t capacity() const +``` +**Description** +Returns the maximum possible size of the queue. + +## Modifiers +```cpp +bool push(const T& value) +bool push(T&& value) +``` +**Description** +Pushes a value to the back of the queue. +Returns true if successful, otherwise false. + +--- + +```cpp +bool pop() +```cpp +**Description** +Pop a value from the front of the list. +Returns true if successful, otherwise false. + +--- + +```cpp +bool pop(T& value) +bool pop(T&& value) +``` +**Description** +Pop a value from the front of the list and place it in value. +Returns true if successful, otherwise false. + +--- + +```cpp +void clear() +``` +**Description** +Clears the queue to a size of zero. +Must be called from thread that pops the queue or when there is no possibility of concurrent access. + +--- + +### C++03 +```cpp +bool emplace(const T1& value1) +bool emplace(const T1& value1, const T2& value2) +bool emplace(const T1& value1, const T2& value2, const T3& value3) +bool emplace(const T1& value1, const T2& value2, const T3& value3, const T4& value4) +``` +**Description** +Constructs an item in the the queue 'in place'. + +### C++11 +```cpp +bool emplace(Args&&… args) +``` +**Description** +Constructs an item in the the queue 'in place'. + +## Notes + +Remember that thread context switches may occur between calls to the access protected functions. For example, a call to `empty()` may return `true`, but a subsequent call to `pop()` may succeed if a context switch occurred between the two and pushed a new value. + +## Example +```cpp +etl::queue_spsc_atomic queue; + +int main() +{ + while (true) + { + char c; + + if (queue.pop(c)) + { + Print(c); + } + } +} + +void Thread() +{ + while (true) + { + queue.push('A'); + } +} +``` diff --git a/docs/containers/queues/queue-spsc-isr.md b/docs/containers/queues/queue-spsc-isr.md new file mode 100644 index 00000000..9ce4f212 --- /dev/null +++ b/docs/containers/queues/queue-spsc-isr.md @@ -0,0 +1,214 @@ +--- +title: "queue_spsc_isr" +--- + +{{< callout >}} + Header: `queue_spsc_isr.h` +{{< /callout >}} + +{{< callout type="warning">}} +**This class is deprecated.** +`Use queue_spsc_locked` as a replacement. +{{< /callout >}} + +**This class is deprecated. +`Use queue_spsc_locked` as a replacement.** + +A fixed capacity single-producer, single-consumer queue for interrupt driven systems. +The queue may be used to transfer data to or from an ISR. Calls to the queue from the ISR must use the `_from_isr` versions. + +A helper class must be supplied that defines static void `lock()` and void `unlock()` functions. They must perform the requisite memory barriers to preserve the order of execution. + +```cpp +etl::queue_spsc_isr +``` + +Inherits from `etl::iqueue_spsc_isr`. +`etl::iqueue_spsc_isr` may be used as a size independent pointer or reference type for any `etl::queue_spsc_isr` instance of the same implementation. + +The memory model determines the type used internally for indexes and size, to allow for the most efficient implementation for the application. + +## Maximum queue sizes +```cpp +MEMORY_MODEL_SMALL 255 +MEMORY_MODEL_MEDIUM 65535 +MEMORY_MODEL_LARGE 2147483647 +MEMORY_MODEL_HUGE 9223372036854775807 +``` +See `memory_model.h` + +## Member types + +```cpp +value_type T +size_type +pointer value_type* +const_pointer const value_type* +reference value_type& +const_reference const value_type& +``` + +## Constructor + +```cpp +queue_spsc_isr() +``` + +## Capacity + +```cpp +bool empty() const +bool empty_from_isr() const +``` +**Description** +Returns true if the size of the queue is zero, otherwise false. + +--- + +```cpp +bool full() const +bool full_from_isr() const +``` +**Description** +Returns true if the size of the queue is SIZE, otherwise false. + +--- + +```cpp +size_type size() const +size_type size_from_isr() const +``` +**Description** +Returns the size of the queue. + +--- + +```cpp +size_type available() const +size_type available_from_isr() const +``` +**Description** +Returns the remaining available capacity in the queue. + +--- + +```cpp +size_type max_size() const +``` +**Description** +Returns the maximum possible size of the queue. + +--- + +```cpp +size_type capacity() const +``` +**Description** +Returns the maximum possible size of the queue. + +## Modifiers + +```cpp +bool push(const T& value) +bool push(T&& value) +bool push_from_isr(const T& value) +bool push_from_isr(T&& value) +``` +**Description** +Pushes a value to the back of the queue. +Returns true if successful, otherwise false. + +--- + +```cpp +bool pop() +bool pop_from_isr() +``` +**Description** +Pop a value from the front of the list. +Returns true if successful, otherwise false. + +--- + +```cpp +bool pop(T& value) +bool pop_from_isr(T& value) +bool pop(T&& value) +bool pop_from_isr(T&& value) +``` +**Description** +Pop a value from the front of the list and place it in value. +Returns true if successful, otherwise false. + +--- + +```cpp +void clear() +void clear_from_isr() +``` +**Description** +Clears the queue to a size of zero. + +### C++03 +```cpp +bool emplace(const T1& value1) +bool emplace(const T1& value1, const T2& value2) +bool emplace(const T1& value1, const T2& value2, const T3& value3) +bool emplace(const T1& value1, const T2& value2, const T3& value3, const T4& value4) +``` +**Description** +Constructs an item in the the queue 'in place'. + +### C++11 +```cpp +bool emplace(Args&&… args) +``` +**Description** +Constructs an item in the the queue 'in place'. + + +## Notes + +Remember that interrupts may occur between calls to the access protected functions. For example, a call to `empty()` may return `true`, but a subsequent call to pop() may succeed if an interrupt occurred between the two and pushed a new value. + +## Example + +```cpp +class InterruptControl +{ +public: + + static void lock() + { + // Store current interrupt control register and disable the relevant interrupt. + } + + static void unlock() + { + // Restore the interrupt control register. + } +}; + +etl::queue_spsc_isr queue; + +int main() +{ + while (true) + { + char c; + + if (queue.pop(c)) + { + Print(c); + } + } +} + +void ISR(char c) +{ + queue.push_from_isr(c); +} +``` diff --git a/docs/containers/queues/queue-spsc-locked.md b/docs/containers/queues/queue-spsc-locked.md new file mode 100644 index 00000000..ed925688 --- /dev/null +++ b/docs/containers/queues/queue-spsc-locked.md @@ -0,0 +1,235 @@ +--- +title: "queue_spsc_locked" +--- + +This class is designed to be a more generally useful version of `etl::queue_spsc_isr` and can replace it. + +A fixed capacity single-producer, single-consumer queue, generally used to transfer data to or from an ISR. +Calls from the 'unlocked' thread of execution (ISR) must use the `_from_unlocked` versions. + +Helper functions must be supplied at construction that lock (disable) and unlock (enable) the relevant ISR. +They are passed as const references to `etl::ifunction`. +They must perform the requisite memory barriers to preserve the order of execution. + +Many functions have two versions. One locks and unlocks access and is used from the foreground task (non-ISR). The other, with a `_from_unlocked` suffix, are called from the ISR. + +```cpp +etl::queue_spsc_locked +``` + +Inherits from `etl::iqueue_spsc_locked`. +`etl::iqueue_spsc_locked` may be used as a size independent pointer or reference type for any `etl::queue_spsc_locked` instance of the same implementation. + +The memory model determines the type used internally for indexes and size, to allow for the most efficient implementation for the application. + +## Maximum queue sizes +```cpp +MEMORY_MODEL_SMALL 255 +MEMORY_MODEL_MEDIUM 65535 +MEMORY_MODEL_LARGE 2147483647 +MEMORY_MODEL_HUGE 9223372036854775807 +``` + +## Member types + +```cpp +value_type T +size_type +pointer value_type* +const_pointer const value_type* +reference value_type& +const_reference const value_type& +``` + +## Constructor + +```cpp +queue_spsc_locked(const etl::ifunction& lock, const etl::ifunction& unlock) +``` +**Parameters** +`lock` The lock function wrapper. +`unlock` The unlock function wrapper. + +## Capacity + +```cpp +bool empty() const +bool empty_from_unlocked() const +``` +**Description** +Returns `true` if the size of the queue is zero, otherwise `false`. + +--- + +```cpp +bool full() const +bool full_from_unlocked() const +``` +**Description** +Returns `true` if the size of the queue is SIZE, otherwise `false`. + +--- + +```cpp +size_type size() const +size_type size_from_unlocked() const +``` +**Description** +Returns the size of the queue. + +--- + +```cpp +size_type available() const +size_type available_from_unlocked() const +``` +**Description** +Returns the remaining available capacity in the queue. + +--- + +```cpp +size_type max_size() const +``` +**Description** +Returns the maximum possible size of the queue. + +--- + +```cpp +size_type capacity() const +``` +**Description** +Returns the maximum possible size of the queue. + +## Modifiers + +```cpp +bool push(const T& value) +bool push(T&& value) +bool push_from_locked(const T& value) +bool push_from_locked(T&& value) +``` +**Description** +Pushes a value to the back of the queue. +Returns `true` if successful, otherwise `false`. + +--- + +```cpp +bool pop() +bool pop_from_unlocked() +``` +**Description** +Pop a value from the front of the list. +Returns `true` if successful, otherwise `false`. + +--- + +```cpp +bool pop(T& value) +bool pop_from_locked(T& value) +bool pop(T&& value) +bool pop_from_locked(T&& value) +``` +**Description** +Pop a value from the front of the list and place it in value. +Returns `true` if successful, otherwise `false`. + +--- + +```cpp +void clear() +void clear_from_unlocked() +``` +**Description** +Clears the queue to a size of zero. + +### C++03 +```cpp +bool emplace(const T1& value1) +bool emplace(const T1& value1, const T2& value2) +bool emplace(const T1& value1, const T2& value2, const T3& value3) +bool emplace(const T1& value1, const T2& value2, const T3& value3, const T4& value4) +``` +**Description** +Constructs an item in the the queue 'in place'. + +--- + +```cpp +bool emplace_from_unlocked(const T1& value1) +bool emplace_from_unlocked(const T1& value1, const T2& value2) +bool emplace_from_unlocked(const T1& value1, const T2& value2, const T3& value3) +bool emplace_from_unlocked(const T1& value1, const T2& value2, const T3& value3, const T4& value4) +``` +**Description** +Constructs an item in the the queue 'in place'. + +### C++11 +```cpp +template +bool emplace(Args&&… args) +``` +**Description** +Constructs an item in the the queue 'in place'. + +--- + +```cpp +template +bool emplace_from_unlocked(Args&&... args) +``` +**Description** +Constructs an item in the the queue 'in place'. + +## Notes + +Remember that interrupts may occur between calls to the access protected functions. For example, a call to `empty()` may return `true`, but a subsequent call to `pop()` may succeed if an interrupt occurred between the two and pushed a new value. + +## Example + +```cpp +class InterruptControl +{ +public: + + void lock() + { + // Store current interrupt control register and disable the relevant interrupt. + } + + void unlock() + { + // Restore the interrupt control register. + } +}; + +InterruptControl interruptControl; + +// Create function wrappers with direct calls to the instance's member functions. +etl::function_imv lock; +etl::function_imv unlock; + +etl::queue_spsc_locked queue(lock, unlock); + +int main() +{ + while (true) + { + char c; + + if (queue.pop(c)) + { + Print(c); + } + } +} + +void ISR(char c) +{ + queue.push_from_unlocked(c); +} +``` diff --git a/docs/containers/queues/queue.md b/docs/containers/queues/queue.md new file mode 100644 index 00000000..6d39c949 --- /dev/null +++ b/docs/containers/queues/queue.md @@ -0,0 +1,167 @@ +--- +title: "queue" +--- + +{{< callout >}} + Header: `queue.h` +{{< /callout >}} + +A fixed capacity queue. + +```cpp +etl::queue +``` + +Inherits from `etl::iqueue`. +`etl::iqueue` may be used as a size independent pointer or reference type for any `etl::queue` instance. + +The memory model determines the type used internally for indexes and size, to allow for the most efficient implementation for the application. + +## Maximum queue sizes +```cpp +MEMORY_MODEL_SMALL 255 +MEMORY_MODEL_MEDIUM 65535 +MEMORY_MODEL_LARGE 2147483647 +MEMORY_MODEL_HUGE 9223372036854775807 +``` + +See `memory_model.h` + +## Member types + +value_type T +size_type +pointer value_type* +const_pointer const value_type* +reference value_type& +const_reference const value_type& +rvalue_reference value_type&& + +## Constructor + +etl::queue() + +## Element access + +```cpp +T& front() +const T& front() const +``` +**Description** +Returns a reference or const reference to the first element. + +--- + +```cpp +T& back() +const T& back() const +``` +**Description** +Returns a reference or const reference to the last element. + +## Capacity + +```cpp +bool empty() const +``` +**Description** +Returns true if the size of the queue is zero, otherwise false. + +--- + +```cpp +bool full() const +``` +**Description** +Returns true if the size of the queue is SIZE, otherwise false. + +--- + +```cpp +size_type size() const +``` +**Description** +Returns the size of the queue. + +--- + +```cpp +size_type available() const +``` +**Description** +Returns the remaining available capacity in the queue. + +--- + +```cpp +ETL_CONSTEXPR size_type max_size() const +``` +**Description** +Returns the maximum possible size of the queue. + +--- + +```cpp +ETL_CONSTEXPR size_type capacity() const +``` +**Description** +Returns the maximum possible size of the queue. + +## Modifiers + +```cpp +void push(const_reference value) +void push(rvalue_reference value) +``` +**Description** +Pushes a value to the back of the queue. +Emits an `etl::queue_full` if the queue is full and `ETL_CHECK_PUSH_POP` is defined. If asserts or exceptions are not enabled then undefined behaviour occurs. + +--- + +### C++03 +```cpp +void emplace(const T1& value1) +void emplace(const T1& value1, const T2& value2) +void emplace(const T1& value1, const T2& value2, const T3& value3) +void emplace(const T1& value1, const T2& value2, const T3& value3, const T4& value4) +``` +**Description** +Constructs an item in the the queue 'in place'. +Emits an `etl::queue_full` if the queue is full and `ETL_CHECK_PUSH_POP` is defined. If asserts or exceptions are not enabled then undefined behaviour occurs. + +### C++11 +```cpp +void emplace(Args&&… args) +``` +**Description** +Constructs an item in the the queue 'in place'. +Emits an `etl::queue_full` if the queue is full and `ETL_CHECK_PUSH_POP` is defined. If asserts or exceptions are not enabled then undefined behaviour occurs. + +--- + +```cpp +void pop() +``` +**Description** +Pop a value from the front of the list. +Emits an `etl::queue_empty` if the queue is empty and `ETL_CHECK_PUSH_POP` is defined. Undefined behaviour if the queue is empty. + +--- + +```cpp +void pop_into(TContainer& destination) +``` +**Description** +Pop a value from the front of the list and places it in destination. +Emits an `etl::queue_empty` if the queue is empty and `ETL_CHECK_PUSH_POP` is defined. Undefined behaviour if the queue is empty. + +--- + +```cpp +void clear() +``` +**Description** +Clears the queue to a size of zero. diff --git a/docs/containers/variant-pool.md b/docs/containers/variant-pool.md new file mode 100644 index 00000000..507cea3c --- /dev/null +++ b/docs/containers/variant-pool.md @@ -0,0 +1,214 @@ +--- +title: "variant_pool" +--- + +This template class allows instances of multiple derived types to be constructed from a common store. + +**C++03** +It may support up to 16 types and MAX_SIZE instances. + +```cpp +template +``` + +--- + +**C++11 and above** +It supports a variable number of types and `MAX_SIZE` instances. + +```cpp +template +class variant_pool +``` + +```cpp +template +class variant_pool_ext : public etl::generic_pool_ext::size, etl::largest::alignment> +``` + +Note: The caller of the pools's `create` becomes the owner of the instance. It must call `destroy`. + +## Constants + +`MAX_SIZE` +The maximum number of instances that may be created. + +## Member functions + +```cpp +template +T* create() +``` + +**C++03** +```cpp +template +T* create(const TP1& p1) + +template +T* create(const TP1& p1, const TP2& p2) + +template +T* create(const TP1& p1, const TP2& p2, const TP3& p3) + +template +T* create(const TP1& p1, const TP2& p2, const TP3& p3, const TP4& p4) +``` + +Creates an instance of T with zero to four constructor parameters. The parameters are forwarded to T's constructor. +Returns a pointer to the constructed instance or `nullptr`. +If T if not one of those declared in the template parameter list then a compile time error will occur. +If `T` cannot be created due to there being no spare capacity then an `etl::pool_element_size` is emitted. If exceptions are not configured to be thrown then the function returns `nullptr`. + +--- + +**C++11 and above** +template +T* create(Args&&... args) +**Description** +Creates an instance of `T` with the supplied parameters. The parameters are forwarded to `T`'s constructor. +Returns a pointer to the constructed instance or `nullptr`. +If `T` if not one of those declared in the template parameter list then a compile time error will occur. +If `T` cannot be created due to there being no spare capacity then an `etl::pool_element_size` is emitted. If exceptions are not configured to be thrown then the function returns `nullptr`. + +--- + +```cpp +bool destroy(const T* const p) +``` +**Description** +Destroys the instance pointed to by `p`. +Compile time error if `T` is not one of, or not a base of, one the supported types. +If the pool is empty or `p` does not belong to it then an `etl::pool_object_not_in_pool` is emitted. +If exceptions are not configured to be thrown then the function returns `true` for success and `false` for failure. + +--- + +```cpp +size_t max_size() const +``` +**Description** +Returns the maximum number of items in the pool. + +--- + +```cpp +size_t available() const +``` +**Description** +Returns the number of free items in the pool. + +--- + +```cpp +size_t size() const +``` +**Description** +Returns the number of allocated items in the pool. + +--- + +```cpp +bool empty() const +``` +**Description** +Checks to see if there are no allocated items in the pool. + +--- + +```cpp +bool full() const +``` +**Description** +Checks to see if there are no free items in the pool. + +## Example + +```cpp +//*********************************** +struct Base +{ + virtual ~Base() + { + } +}; + +//*********************************** +struct Derived1 : public Base +{ + enum + { + ID = 1 + }; +}; + +//*********************************** +struct Derived2 : public Base +{ + enum + { + ID = 2 + }; + + Derived2(int a_) + : a(a_) + { + } + + int a; +}; + +//*********************************** +struct Derived3 : public Base +{ + enum + { + ID = 3 + }; + + Derived3(int a_, double b_) + : a(a_), + b(b_) + { + } + + int a; + double b; +} + +//*********************************** +struct Derived4 : public Base +{ + enum + { + ID = 4 + }; +}; + +// A pool that can create up to three instances of Derived1, Derived2, Derived3. +// Notice that the types can be declared in any order. +typedef etl::variant_pool<3, Derived1, Derived3, Derived2> VariantPool; + +VariantPool pool; + +// Create an instance of Derived1. +Derived1* pb1 = pool.create(); + +// Create an instance of Derived2 from its id, with constructor parameter 3. +Derived2* pb2 = pool.create(3); + +// Create an instance of Derived3 with constructor parameters 4 and 1.2. +Derived3* pb3 = pool.create(4, 1.2); + +// Create an instance of Derived4. +Derived4* pb4 = pool.create(); // Compile time error. + +// Destroy the instances. +pool.destroy(pb2); +pool.destroy(pb1); +pool.destroy(pb3); +``` diff --git a/docs/getting-started/View the docs locally/view-the-docs.md b/docs/getting-started/View the docs locally/view-the-docs.md index 131eb63f..383a081e 100644 --- a/docs/getting-started/View the docs locally/view-the-docs.md +++ b/docs/getting-started/View the docs locally/view-the-docs.md @@ -9,10 +9,11 @@ The Hugo created website is viewable locally by running the **Hugo** server. Run this command. ```bash -hugo server --disableFastRender +hugo server ``` >Remember to keep this terminal window open, otherwise the server will terminate. +> >You may want to add this to your startup script ## View the documentation diff --git a/docs/raw/containers/queue_lockable.txt b/docs/queue_lockable.md similarity index 56% rename from docs/raw/containers/queue_lockable.txt rename to docs/queue_lockable.md index 40e3b7bf..4f17df2a 100644 --- a/docs/raw/containers/queue_lockable.txt +++ b/docs/queue_lockable.md @@ -1,34 +1,37 @@ -queue_lockable +--- +title: "queue_lockable" +--- -See Locked Queues +This class is designed to be an alternative to `etl::queue_spsc_locked`. +It is an abstract class and requires that the user derives their own type from it. -This class is designed to be an alternative to etl::queue_spsc_locked. -It is an abstract class and requires that the user derives their own type from it. +The derived class must override the two pure virtual functions `void lock() const` and `void unlock() const` to implement the required locking functionality, whether this be a mutex, ISR control or something else. +They must perform the requisite memory barriers to preserve the order of execution. -The derived class must override the two pure virtual functions void lock() const and void unlock() const to implement the required locking functionality, whether this be a mutex, ISR control or something else. -They must perform the requisite memory barriers to preserve the order of execution. - -Many functions have two versions. One locks and unlocks access and is used from the foreground task. The other, with a _from_unlocked suffix, are called from the +Many functions have two versions. One locks and unlocks access and is used from the foreground task. The other, with a `_from_unlocked` suffix, are called from the background task. +```cpp etl::queue_lockable +``` -Inherits from etl::iqueue_lockable -etl::iqueue_lockable may be used as a size independent pointer or reference type for any etl::queue_lockable instance of the same implementation. +Inherits from `etl::iqueue_lockable`. +`etl::iqueue_lockable` may be used as a size independent pointer or reference type for any `etl::queue_lockable` instance of the same implementation. The memory model determines the type used internally for indexes and size, to allow for the most efficient implementation for the application. -Maximum queue sizes: +## Maximum queue sizes + +```cpp MEMORY_MODEL_SMALL 255 MEMORY_MODEL_MEDIUM 65535 MEMORY_MODEL_LARGE 2147483647 MEMORY_MODEL_HUGE 9223372036854775807 - +``` See memory_model.h -____________________________________________________________________________________________________ -Member types +## Member types value_type T size_type @@ -37,43 +40,45 @@ const_pointer const value_type* reference value_type& const_reference const value_type& -____________________________________________________________________________________________________ -Constructor +## Constructor queue_lockable(); -____________________________________________________________________________________________________ -Capacity +## Capacity bool empty() const bool empty_from_unlocked() const Returns true if the size of the queue is zero, otherwise false. -____________________________________________________________________________________________________ + +--- bool full() const bool full_from_unlocked() const Returns true if the size of the queue is SIZE, otherwise false. -____________________________________________________________________________________________________ + +--- size_type size() const size_type size_from_unlocked() const Returns the size of the queue. -____________________________________________________________________________________________________ + +--- size_type available() const size_type available_from_unlocked() const Returns the remaining available capacity in the queue. -____________________________________________________________________________________________________ + +--- size_type max_size() const Returns the maximum possible size of the queue. -____________________________________________________________________________________________________ + +--- size_type capacity() const Returns the maximum possible size of the queue. -____________________________________________________________________________________________________ -Modifiers +## Modifiers bool push(const T& value); bool push(T&& value); @@ -81,44 +86,51 @@ bool push_from_unlocked(const T& value); bool push_from_unlocked(T&& value); Pushes a value to the back of the queue. Returns true if successful, otherwise false. -____________________________________________________________________________________________________ + +--- bool pop(); bool pop_from_unlocked(); Pop a value from the front of the list. Returns true if successful, otherwise false. -____________________________________________________________________________________________________ + +--- bool pop(T& value); bool pop_from_unlocked(T& value); Pop a value from the front of the list and place it in value. Returns true if successful, otherwise false. -____________________________________________________________________________________________________ + +--- void clear(); void clear_from_unlocked(); Clears the queue to a size of zero. -____________________________________________________________________________________________________ -C++03 +--- + +### C++03 +```cpp bool emplace(const T1& value1); bool emplace(const T1& value1, const T2& value2); bool emplace(const T1& value1, const T2& value2, const T3& value3); bool emplace(const T1& value1, const T2& value2, const T3& value3, const T4& value4); +``` -C++11 +### C++11 +```cpp bool emplace(Args&&… args); - -Constructs an item in the the queue 'in place'. +``` +Constructs an item in the the queue 'in place'. C++03: Supports up to four constructor parameters. -____________________________________________________________________________________________________ -Notes +## Notes -Remember that interrupts may occur between calls to the access protected functions. For example, a call to empty() may return true, but a subsequent call to pop() may succeed if an interrupt occurred between the two and pushed a new value. +Remember that interrupts may occur between calls to the access protected functions. For example, a call to `empty()` may return `true`, but a subsequent call to `pop()` may succeed if an interrupt occurred between the two and pushed a new value. -Example +## Example +```cpp class InterruptControl { public: @@ -159,4 +171,4 @@ void ISR(char c) { queue.push_from_unlocked(c); } - +``` diff --git a/docs/raw/containers/const_multiset.txt b/docs/raw/containers/const_multiset.txt deleted file mode 100644 index 88d7f959..00000000 --- a/docs/raw/containers/const_multiset.txt +++ /dev/null @@ -1,130 +0,0 @@ -const_multiset -const_multiset_ext -A fixed capacity read-only multiset based on a sorted array. -The containers are designed to be able to be constexpr for C++14 and up. - -The interface is most similar to std::multiset. -Uses etl::less as the default key comparison method. -etl::const_multiset -etl::const_multiset_ext - -Inherits from etl::iconst_multiset -etl::iconst_multiset may be used as a Size independent pointer or reference type for any etl::const_multiset instance. -Both the key type must be default constructible. -____________________________________________________________________________________________________ -Template deduction guides -C++17 and above - -template -etl::const_multiset(TElements...) - -Example -constexpr etl::const_multiset data{ 0, 1, 2, 3 }; -Defines data as an const_multiset of int, of length 4, containing the supplied data. -____________________________________________________________________________________________________ -template -etl::const_multiset_ext(TElements...) - -Example -constexpr etl::pair values{ 0, 1, 2, 3 }; -constexpr etl::const_multiset_ext data{ values }; -Defines data as an const_multiset of int, of length 4, containing the supplied data. - -constexpr values[]{ 0, 1, 2, 3 }; -constexpr etl::span span{ values }; -constexpr etl::const_multiset_ext data{ span }; -Defines data as an const_multiset of int of length 4, containing the supplied data. -____________________________________________________________________________________________________ -Member types - -key_type TKey Must be default constructible. -value_type key_type -size_type std::size_t -difference_type std::ptrdiff_t -const_reference const T& -const_pointer const T* -const_iterator Constant random access iterator -____________________________________________________________________________________________________ -Constructor - -template -ETL_CONSTEXPR14 explicit const_multiset(TElements&&... elements) ETL_NOEXCEPT -Construct a const_multiset from a variadic list of elements. -Static asserts if the elements are not of type value_type. -Static asserts if the number of elements is greater than the capacity of the const_multiset. -____________________________________________________________________________________________________ -Iterators - -const_iterator begin() const ETL_NOEXCEPT -const_iterator cbegin() const ETL_NOEXCEPT -Returns an iterator to the beginning of the multiset. -____________________________________________________________________________________________________ -const_iterator end() const ETL_NOEXCEPT -const_iterator cend() const ETL_NOEXCEPT -Returns an iterator to the end of the multiset. -____________________________________________________________________________________________________ -Capacity - -ETL_CONSTEXPR14 bool empty() const ETL_NOEXCEPT -Returns true if the size of the multiset is zero, otherwise false. -____________________________________________________________________________________________________ -ETL_CONSTEXPR14 bool full() const ETL_NOEXCEPT -Returns true if the size of the lookup is size, otherwise false. -____________________________________________________________________________________________________ -ETL_CONSTEXPR14 size_t size() const ETL_NOEXCEPT -Returns the size of the lookup. -____________________________________________________________________________________________________ -ETL_CONSTEXPR14 size_t max_size() const ETL_NOEXCEPT -Returns the maximum possible Size of the multiset. -____________________________________________________________________________________________________ -Status - -ETL_CONSTEXPR14 bool is_valid() const ETL_NOEXCEPT -Check that the elements are valid for a multiset. -The elements must be sorted and contain no duplicates. -____________________________________________________________________________________________________ -Search - -ETL_CONSTEXPR14 const_iterator find(const key_type& key) const ETL_NOEXCEPT - -ETL_CONSTEXPR14 const_iterator lower_bound(const key_type& key) const ETL_NOEXCEPT - -ETL_CONSTEXPR14 const_iterator upper_bound(const key_type& key) const ETL_NOEXCEPT - -ETL_CONSTEXPR14 pair equal_range(const key_type& key) const ETL_NOEXCEPT -The return type is either std::pair (default) or etl::pair (ETL_NO_STL) - -ETL_CONSTEXPR14 bool contains(const key_type& k) const ETL_NOEXCEPT -Check if the container contains the key. -____________________________________________________________________________________________________ -For comparators that define is_transparent. - -template -ETL_CONSTEXPR14 const_iterator find(const K& key) const ETL_NOEXCEPT - -template -ETL_CONSTEXPR14 const_iterator lower_bound(const K& key) const ETL_NOEXCEPT - -template -ETL_CONSTEXPR14 const_iterator upper_bound(const K& key) const ETL_NOEXCEPT - -template -ETL_CONSTEXPR14 pair equal_range(const K& key) const ETL_NOEXCEPT - -template -ETL_CONSTEXPR14 bool contains(const K& k) const ETL_NOEXCEPT -Check if the container contains the key. -____________________________________________________________________________________________________ -Non-member functions - -Lexicographically comparisons -== true if the contents of the multisets are equal, otherwise false. -!= true if the contents of the multisets 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. -___________________________________________________________________________________________________ -Technical stuff - -The const multiset is implemented as a sorted array key/value pairs. diff --git a/docs/raw/containers/const_set.txt b/docs/raw/containers/const_set.txt deleted file mode 100644 index 12bda6df..00000000 --- a/docs/raw/containers/const_set.txt +++ /dev/null @@ -1,130 +0,0 @@ -const_set -const_set_ext -A fixed capacity read-only set based on a sorted array. -The containers are designed to be able to be constexpr for C++14 and up. - -The interface is most similar to std::set. -Uses etl::less as the default key comparison method. -etl::const_set -etl::const_set_ext - -Inherits from etl::iconst_set -etl::iconst_set may be used as a Size independent pointer or reference type for any etl::const_set instance. -Both the key type must be default constructible. -____________________________________________________________________________________________________ -Template deduction guides -C++17 and above - -template -etl::const_set(TElements...) - -Example -constexpr etl::const_set data{ 0, 1, 2, 3 }; -Defines data as an const_set of int, of length 4, containing the supplied data. -____________________________________________________________________________________________________ -template -etl::const_set_ext(TElements...) - -Example -constexpr etl::pair values{ 0, 1, 2, 3 }; -constexpr etl::const_set_ext data{ values }; -Defines data as an const_set of int, of length 4, containing the supplied data. - -constexpr values[]{ 0, 1, 2, 3 }; -constexpr etl::span span{ values }; -constexpr etl::const_set_ext data{ span }; -Defines data as an const_set of int of length 4, containing the supplied data. -____________________________________________________________________________________________________ -Member types - -key_type TKey Must be default constructible. -value_type key_type -size_type std::size_t -difference_type std::ptrdiff_t -const_reference const T& -const_pointer const T* -const_iterator Constant random access iterator -____________________________________________________________________________________________________ -Constructor - -template -ETL_CONSTEXPR14 explicit const_set(TElements&&... elements) ETL_NOEXCEPT -Construct a const_set from a variadic list of elements. -Static asserts if the elements are not of type value_type. -Static asserts if the number of elements is greater than the capacity of the const_set. -____________________________________________________________________________________________________ -Iterators - -const_iterator begin() const ETL_NOEXCEPT -const_iterator cbegin() const ETL_NOEXCEPT -Returns an iterator to the beginning of the set. -____________________________________________________________________________________________________ -const_iterator end() const ETL_NOEXCEPT -const_iterator cend() const ETL_NOEXCEPT -Returns an iterator to the end of the set. -____________________________________________________________________________________________________ -Capacity - -ETL_CONSTEXPR14 bool empty() const ETL_NOEXCEPT -Returns true if the size of the set is zero, otherwise false. -____________________________________________________________________________________________________ -ETL_CONSTEXPR14 bool full() const ETL_NOEXCEPT -Returns true if the size of the lookup is size, otherwise false. -____________________________________________________________________________________________________ -ETL_CONSTEXPR14 size_t size() const ETL_NOEXCEPT -Returns the size of the lookup. -____________________________________________________________________________________________________ -ETL_CONSTEXPR14 size_t max_size() const ETL_NOEXCEPT -Returns the maximum possible Size of the set. -____________________________________________________________________________________________________ -Status - -ETL_CONSTEXPR14 bool is_valid() const ETL_NOEXCEPT -Check that the elements are valid for a set. -The elements must be sorted and contain no duplicates. -____________________________________________________________________________________________________ -Search - -ETL_CONSTEXPR14 const_iterator find(const key_type& key) const ETL_NOEXCEPT - -ETL_CONSTEXPR14 const_iterator lower_bound(const key_type& key) const ETL_NOEXCEPT - -ETL_CONSTEXPR14 const_iterator upper_bound(const key_type& key) const ETL_NOEXCEPT - -ETL_CONSTEXPR14 pair equal_range(const key_type& key) const ETL_NOEXCEPT -The return type is either std::pair (default) or etl::pair (ETL_NO_STL) - -ETL_CONSTEXPR14 bool contains(const key_type& k) const ETL_NOEXCEPT -Check if the container contains the key. -____________________________________________________________________________________________________ -For comparators that define is_transparent. - -template -ETL_CONSTEXPR14 const_iterator find(const K& key) const ETL_NOEXCEPT - -template -ETL_CONSTEXPR14 const_iterator lower_bound(const K& key) const ETL_NOEXCEPT - -template -ETL_CONSTEXPR14 const_iterator upper_bound(const K& key) const ETL_NOEXCEPT - -template -ETL_CONSTEXPR14 pair equal_range(const K& key) const ETL_NOEXCEPT - -template -ETL_CONSTEXPR14 bool contains(const K& k) const ETL_NOEXCEPT -Check if the container contains the key. -____________________________________________________________________________________________________ -Non-member functions - -Lexicographically comparisons -== true if the contents of the sets are equal, otherwise false. -!= true if the contents of the sets 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. -___________________________________________________________________________________________________ -Technical stuff - -The const set is implemented as a sorted array key/value pairs. diff --git a/docs/raw/containers/fixed_sized_memory_block_allocator.txt b/docs/raw/containers/fixed_sized_memory_block_allocator.txt deleted file mode 100644 index f37f58ad..00000000 --- a/docs/raw/containers/fixed_sized_memory_block_allocator.txt +++ /dev/null @@ -1,20 +0,0 @@ -fixed_sized_memory_block_allocator - -A fixed capacity memory block pool. -Implements an etl::imemory_block_allocator. See here. - -template -class fixed_sized_memory_block_allocator : public imemory_block_allocator -____________________________________________________________________________________________________ -Template parameters - -VBlock_Size The required size of each block. -VAlignment The required alignment of each block. -VSize The number of blocks. -____________________________________________________________________________________________________ -Constants - -size_t Block_Size = VBlock_Size; -size_t Alignment = VAlignment; -size_t Size = VSize; - diff --git a/docs/raw/containers/list.txt b/docs/raw/containers/list.txt deleted file mode 100644 index 2b4f3cf5..00000000 --- a/docs/raw/containers/list.txt +++ /dev/null @@ -1,416 +0,0 @@ -list - -A fixed capacity list. -STL equivalent: std::list - -etl::list -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 -____________________________________________________________________________________________________ -Shared Pools - -etl::list -This template may share pools with another etl::list of the same type. -The list is initialised with the pool either at construction time or a call to set_pool(etl::ipool& pool) -When pools are shared there are a few side effects that must be noted. - -size() and empty() will be O(N) complexity. For a normal etl::list they are O(1) - -Destruction of the container will always be O(N) regardless of whether the type store is trivially destructible or not. - -max_size() will return the potential maximum size of the list. The actual maximum size will dependent of how many elements the other lists sharing the pool have allocated. - -Pool must be declared with the list's pool_type. -i.e. -// The element type -struct Point { int x; int y; }; - -// The list type -using List = etl::list_ext; - -// The shared pool -etl::pool pool; -____________________________________________________________________________________________________ -Template deduction guides -C++17 and above - -template -etl::list(T...) - -Example -etl::list data{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 }; -Defines data as an list of int, of length 10, containing the supplied data. -____________________________________________________________________________________________________ -Make template -C++11 and above -template - constexpr auto make_list(TValues&&... values) - -Example -auto data = etl::make_list(0, 1, 2, 3, 4, 5, 6, 7, 8, 9); -____________________________________________________________________________________________________ -Member types - -value_type T -size_type std::size_t -difference_type std::ptrdiff_t -reference value_type& -const_reference const value_type& -rvalue_reference value_type&& -pointer value_type* -const_pointer const value_type* -iterator Bi-directional iterator -const_iterator Constant bi-directional iterator -reverse_iterator ETL_OR_STD::reverse_iterator -const_reverse_iterator ETL_OR_STD::reverse_iterator -____________________________________________________________________________________________________ -Constructor - -etl::list(); -etl::list(size_t initialSize, parameter_t value = T()); - -etl::list(const etl::list&); -etl::list(etl::list&&); - -template -etl::list(TIterator begin, TIterator end); - -Emits an etl::list_iterator if the iterators are invalid. If asserts or exceptions are disabled then undefined behaviour occurs. -____________________________________________________________________________________________________ -For shared pool lists -etl::list(etl::pool& pool); -etl::list(size_t initialSize, parameter_t value, etl::pool& pool); - -template -etl::list(TIterator begin, TIterator end, etl::pool& pool); - -Emits an etl::list_iterator if the iterators are invalid. If asserts or exceptions are disabled then undefined behaviour occurs. - -Copy constructor -Implicit pool -Uses the pool from other. -etl::list(etl::list& other); - -Explicit pool -etl::list(etl::list& other, etl::pool& pool); - -____________________________________________________________________________________________________ -Initialisation - -if the list is sharing pools then a set_pool(etl::pool&) is available. -If a pool has already been set then the list is first cleared before updating to the new pool. - -The pool instance can be retrieved by call get_pool() -____________________________________________________________________________________________________ -Element access - -T& front() -const T& front() const -Returns a reference or const reference to the first element. -Undefined behaviour if the list is empty. -____________________________________________________________________________________________________ -T& back() -const T& back() const -Returns a reference or const reference to the last element. -Undefined behaviour if the list is empty. -____________________________________________________________________________________________________ -Iterators - -iterator begin() -const_iterator begin() const -const_iterator cbegin() const -Returns an iterator to the beginning of the list. -____________________________________________________________________________________________________ -iterator end() -const_iterator end() const -const_iterator cend() const -Returns an iterator to the end of the list. -____________________________________________________________________________________________________ -reverse_iterator rbegin() -const_reverse_iterator rbegin() const -const_reverse_iterator crbegin() const -Returns a reverse iterator to the beginning of the list. -____________________________________________________________________________________________________ -reverse_iterator rend() -const_reverse_iterator rend() const -const_reverse_iterator crend() const -Returns a reverse iterator to the end of the list. -____________________________________________________________________________________________________ -Capacity - -bool empty() const -Returns true if the size of the list is zero, otherwise false. -____________________________________________________________________________________________________ -bool full() const -Returns true if the size of the list is SIZE, otherwise false. -____________________________________________________________________________________________________ -size_t size() const -Returns the size of the list. -____________________________________________________________________________________________________ -size_t available() const -Returns the remaining available capacity in the list. -____________________________________________________________________________________________________ -size_t max_size() const -Returns the maximum possible size of the list . -____________________________________________________________________________________________________ -Modifiers - -template -void assign(TIterator begin, TIterator end); - -void assign(size_t n, parameter_t value); -Fills the list with the values. -____________________________________________________________________________________________________ -void push_front(const T& value); -void push_front(T&& value); -Pushes a value to the front of the list. -initialise it. If the list is full then emits an etl::list_full error. -____________________________________________________________________________________________________ -<=20.35.9 -C++03 -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) - -C++11 and above -template -void emplace_front(Args&& ... args) - ->=20.35.10 -C++03 -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) - -C++11 and above -template -reference emplace_front(Args&& …args) -____________________________________________________________________________________________________ -void push_back(const T& value); -void push_back(T&& value); -Pushes a value to the back of the list. -If the list is full and ETL_CHECK_PUSH_POP is defined then emits an etl::list_full error, otherwise undefined behaviour occurs. -____________________________________________________________________________________________________ -<=20.35.9 -C++03 -template -void emplace_back(const T1& value1) - -template -void emplace_back(const T1& value1, const T2& value2) - -template -void emplace_back(const T1& value1, const T2& value2, - const T3& value3) - -template -void emplace_back(const T1& value1, const T2& value2, - const T3& value3, const T4& value4) - -C++11 and above -template -void emplace_back(Args&& ... args) - ->=20.35.10 -C++03 -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) - -C++11 and above -template -reference emplace_back(Args&& ... args) -____________________________________________________________________________________________________ -void pop_front(); -Pop a value from the front of the list. -If the list is empty and ETL_CHECK_PUSH_POP is defined then emits an etl::list_empty error, otherwise undefined behaviour occurs. -____________________________________________________________________________________________________ -void pop_back(); -Pop a value from the back of the list. -If the list is empty and ETL_CHECK_PUSH_POP is defined then emits an etl::list_empty error, otherwise undefined behaviour occurs. -____________________________________________________________________________________________________ -<=20.19.0 -template -void insert(iterator position, TIterator begin, TIterator end); - -iterator insert(iterator position, parameter_t value); -void insert(iterator position, size_t n, parameter_t value); - ->=20.20.0 -template -iterator insert(const_iterator position, TIterator begin, TIterator end); - -iterator insert(const_iterator position, parameter_t value); -iterator insert(const_iterator position, size_t n, parameter_t value); -Inserts values in to the list. If the list is full then emits an etl::list_full error. -____________________________________________________________________________________________________ -C++03 -<=20.19.0 -void emplace(iterator position, const T1& value1); -void emplace(iterator position, const T1& value1, const T2& value2); -void emplace(iterator position, const T1& value1, const T2& value2, const T3& value3); -void emplace(iterator position, const T1& value1, const T2& value2, const T3& value3, const T4& value4); - ->=20.20.0 -iterator emplace(const_iterator position, const T1& value1); -iterator emplace(const_iterator position, const T1& value1, const T2& value2); -iterator emplace(const_iterator position, const T1& value1, const T2& value2, const T3& value3); -iterator emplace(const_iterator position, const T1& value1, const T2& value2, const T3& value3, const T4& value4); -Constructs an item at the insert point in the list 'in place'. -Supports up to four constructor parameters. - -C++11 -<=20.19.0 -void emplace(iterator position, Args&& ... args) - ->=20.20.0 -void emplace(const_iterator position, Args&& ... args) -Constructs an item at the insert point in the the list 'in place'. -____________________________________________________________________________________________________ -template -iterator erase(TIterator begin, TIterator end); - -<=20.19.0 -iterator erase(iterator position); - -<=20.20.0 -iterator erase(iterator position); -iterator erase(const_iterator position); -Erases values in the list. -____________________________________________________________________________________________________ -void resize(size_t n); -void resize(size_t n, parameter_t value); -Resizes the list. If the new size is larger then the first assigns default constructed values, the second assigns the supplied value. -If n is larger than the capacity then emits an etl::list_full error, if asserts or exceptions are not enabled then undefined behaviour occurs. -____________________________________________________________________________________________________ -void clear(); -Clears the list to a size of zero. -____________________________________________________________________________________________________ -void splice(iterator to, etl::ilist& other); -void splice(iterator to, etl::ilist&& other); -Moves the elements in list other to before the position to. -The operation performs copies between the different lists. -____________________________________________________________________________________________________ -void splice(iterator to, etl::ilist& other, iterator from); -void splice(iterator to, etl::ilist&& other, iterator from); -Moves the element at position from in list other to before the position to. -The operation is fast when spicing within the same list, otherwise performs copies between different lists. -If from is not valid then undefined behaviour occurs. -____________________________________________________________________________________________________ -void splice(iterator to, etl::ilist& other, iterator first, iterator last); -void splice(iterator to, etl::ilist&& other, iterator first, iterator last); -Moves the elements in the range first to one before last in list other to before the position to. -The operation is fast when spicing within the same list, otherwise performs copies between different lists. -____________________________________________________________________________________________________ -void merge(etl::ilist& other); -void merge(etl::ilist&& other); -Merges the elements in list other to this list. -The lists must be sorted. If a debug compile and asserts or exceptions are enabled than an etl::list_unsorted is emitted if either list is unsorted, otherwise undefined behaviour occurs. -____________________________________________________________________________________________________ -template -void merge(etl::ilist& other, TCompare compare); - -template -void merge(etl::ilist&& other, TCompare compare); -Merges the elements in list other to this list using the supplied comparison function to determine order. -The lists must already be sorted according to the compare function. -If a debug compile and asserts or exceptions are enabled than an etl::list_unsorted is emitted if either list is unsorted, otherwise undefined behaviour occurs. -____________________________________________________________________________________________________ -Operations - -void remove(const T& value); -Removes from the container all the elements that compare equal to value. -____________________________________________________________________________________________________ -template -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. -____________________________________________________________________________________________________ -Shared pool example - -// The element type. -struct Point { int x; int y; }; - -// The list type -using List = etl::list_ext; - -// The shared pool. Maximum of 10 items. -etl::pool pool; - -// The vector of lists with shared pools. -etl::vector vector_of_lists(3, List(pool)); - -// Make some data. -Point point = { 1, 2 }; - -// Push one to each list. -vector_of_lists[0].push_back(point); -vector_of_lists[1].push_back(point); -vector_of_lists[2].push_back(point); - -size_t available = 0; - -available = vector_of_lists[0].available(); // Reports '7' -available = vector_of_lists[1].available(); // Reports '7' -available = vector_of_lists[2].available(); // Reports '7' - - diff --git a/docs/raw/containers/pool.txt b/docs/raw/containers/pool.txt deleted file mode 100644 index bbb0324f..00000000 --- a/docs/raw/containers/pool.txt +++ /dev/null @@ -1,173 +0,0 @@ -pool - -A fixed capacity object pool, where allocation and release are O(1) operations. -STL equivalent: none - -Internally define storage -etl::pool -etl::generic_pool - -Externally define storage -etl::pool_ext -etl::generic_pool_ext - -____________________________________________________________________________________________________ -etl::generic_pool Inherits from etl::ipool -etl::pool Inherits from etl::generic_pool -etl::ipool may be used as a size and type independent pointer or reference type for any etl::pool or etl::generic_pool instance. -____________________________________________________________________________________________________ -ipool.h defines etl::ipool -generic_pool.h defines etl::generic_pool -pool.h defines etl::pool and includes ipool.h and ipool.h. - -Notes -When using etl::generic_pool, Type_Size must be set to the size of the largest type to be stored, and Alignment set to the largest alignment of all of the types to be stored. -This may be achieved using etl::largest. - -typedef etl::largest largest; -etl::generic_pool pool; - -When using allocate the pool does not construct or destruct anything. It merely provides access to memory that is sized and aligned to contain a T object, or any type that has a compatible alignment, in the case of etl::generic_pool. -It is up to the user of the pool to handle the lifetime of the object. Objects are returned to the pool by calling release. - -Objects can be constructed by calling a create function which will call the objects constructor. Calling destroy will call the destructor for the object and release it back to the pool. - -class Data -{ - ... -}; - -etl::pool data_pool; - -// Create. -Data* pdata = new (data_pool.allocate()) Data(); - -// Destroy -pdata->~Data(); -data_pool.release(pdata); -____________________________________________________________________________________________________ -Heterogeneous pools may be constructed by either basing the pool's type on a union, using etl::variant or etl::generic_pool. - -union Data -{ - char text[100]; - int counter; - double ratio; -}; - -etl::pool data_pool; - -char *pc = data_pool.allocate(); -int *pi = data_pool.allocate(); -double *pd = data_pool.allocate(); - -pool -____________________________________________________________________________________________________ -Constructor - -pool() - -Constructs a pool. No elements are constructed. - -____________________________________________________________________________________________________ -Operations - -template -T* allocate() - -Allocates an item from the pool and returns a pointer to it. -If the pool has no free items then an etl::pool_no_allocation() is emitted and a nullptr is returned. -Note: Does not call the object's constructor. -____________________________________________________________________________________________________ - -void release(const void* const p_object); - -Releases an object back to the pool. -If the object does not belong to the pool an etl::pool_object_not_in_pool() is emitted. -Note: Does not call the object's destructor. -____________________________________________________________________________________________________ - -void release_all(); - -Releases all objects back to the pool. -Note: Does not destruct any T objects. -____________________________________________________________________________________________________ - -bool is_in_pool(const T* const p_object) const; - -Checks to see if an object belongs to the pool. -Returns true if it does, otherwise false. -____________________________________________________________________________________________________ - -C++03 -template -T* create() - -template -T* create(const T1& value1) - -template -T* create(const T1& value1, const T2& value2) - -template -T* create(const T1& value1, const T2& value2, const T3& value3) - -template -T* create(const T1& value1, const T2& value2, const T3& value3, const T4& value4) - -C++11 -template -T* create(Args&&... args) - -There is a matching destroy function. -template -void destroy(const void* const p_object) - -____________________________________________________________________________________________________ -Capacity - -bool empty() const - -Returns true if there are no allocated objects in the pool, otherwise false. -____________________________________________________________________________________________________ - -bool full() const - -Returns true if there are no free objects in the pool, otherwise false. -____________________________________________________________________________________________________ - -size_t available() const - -Returns the remaining available free objects in the pool. -____________________________________________________________________________________________________ - -size_t size() const - -Returns the number of allocated objects in the pool. -____________________________________________________________________________________________________ - -size_t max_size() const - -Returns the maximum number of objects in the pool. - -____________________________________________________________________________________________________ -Constants - -etl::pool -TYPE_SIZE The size of an item in the pool. -SIZE The maximum number of items in the pool. -ALIGNMENT The alignment of items in the pool. - -etl::generic_pool -TYPE_SIZE The maximum size of an item in the pool. -SIZE The maximum number of items in the pool. -ALIGNMENT The alignment of items in the pool. - -____________________________________________________________________________________________________ -Technical stuff - -The pool is based around a block of memory, with storage for Size items, properly aligned for type T. -Each item in the pool is a union of a uintptr_t and a type T. Free items contain a pointer to the next free item. Allocated items contain a T value. Allocation is quick as all that is necessary is to return the address of the next free item. Release is also very quick as the item's content is simply replaced with the address of the current next free item. - -On first use the memory block is uninitialised. On each new allocation a new item is initialised with the address of the next free item. This just-in-time initialisation means that construction does not involve writing to a potentially large amount of memory in one go. - diff --git a/docs/raw/containers/priority_queue.txt b/docs/raw/containers/priority_queue.txt deleted file mode 100644 index 692e0516..00000000 --- a/docs/raw/containers/priority_queue.txt +++ /dev/null @@ -1,77 +0,0 @@ -priority_queue - -A fixed capacity priority queue. -STL equivalent: std::priority_queue - -etl::priority_queue - -Inherits from etl::ipriority_queue -etl::ipriority_queue may be used as a size independent pointer or reference type for any etl::priority_queue instance. -____________________________________________________________________________________________________ -Member types - -value_type T -size_type std::size_t -____________________________________________________________________________________________________ -Constructor - -etl::priority_queue(); -____________________________________________________________________________________________________ -Element access - -T& top() -const T& top() const -Returns a reference or const reference to the first element. -Undefined behaviour if the queue is empty. -____________________________________________________________________________________________________ -Capacity - -bool empty() const -Returns true if the size of the queue is zero, otherwise false. -____________________________________________________________________________________________________ - -bool full() const -Returns true if the size of the queue is SIZE, otherwise false. -____________________________________________________________________________________________________ - -size_t size() const -Returns the size of the queue. -____________________________________________________________________________________________________ - -size_t available() const -Returns the remaining available capacity in the queue. -____________________________________________________________________________________________________ - -size_t max_size() const -Returns the maximum possible size of the queue. -____________________________________________________________________________________________________ - -size_t capacity() const -Returns the maximum possible size of the queue . -____________________________________________________________________________________________________ -Modifiers - -void push(const T& value); -void push(T&& value); -Pushes a value to the queue. -If the queue is full then emits an etl::queue_full error. If asserts or exceptions are not enabled then undefined behaviour occurs. -____________________________________________________________________________________________________ -C++03 -void emplace(const T1& value1); -void emplace(const T1& value1, const T2& value2); -void emplace(const T1& value1, const T2& value2, const T3& value3); -void emplace(const T1& value1, const T2& value2, const T3& value3, const T4& value4); - -C++11 -void emplace(Args&&… args); -Constructs an item in the the queue 'in place'. -C++03: Supports up to four constructor parameters. -Emits an etl::queue_full if the queue is full and ETL_CHECK_PUSH_POP is defined. If asserts or exceptions are not enabled then undefined behaviour occurs. -____________________________________________________________________________________________________ -void pop(); -Pop a value from the front of the list. -Undefined behaviour if the queue is empty. -____________________________________________________________________________________________________ -void clear(); -Clears the queue to a size of zero. - diff --git a/docs/raw/containers/queue.txt b/docs/raw/containers/queue.txt deleted file mode 100644 index 11ea6eff..00000000 --- a/docs/raw/containers/queue.txt +++ /dev/null @@ -1,124 +0,0 @@ -queue - -A fixed capacity queue. -STL equivalent: std::queue - -etl::queue - -Inherits from etl::iqueue -etl::iqueue may be used as a size independent pointer or reference type for any etl::queue instance. - -The memory model determines the type used internally for indexes and size, to allow for the most efficient implementation for the application. - -Maximum queue sizes: -MEMORY_MODEL_SMALL 255 -MEMORY_MODEL_MEDIUM 65535 -MEMORY_MODEL_LARGE 2147483647 -MEMORY_MODEL_HUGE 9223372036854775807 - -See memory_model.h - -____________________________________________________________________________________________________ -Member types - -value_type T -size_type -pointer value_type* -const_pointer const value_type* -reference value_type& -const_reference const value_type& -rvalue_reference value_type&& - -____________________________________________________________________________________________________ -Constructor - -etl::queue(); - -____________________________________________________________________________________________________ -Element access - -T& front() -const T& front() const - -Returns a reference or const reference to the first element. -____________________________________________________________________________________________________ - -T& back() -const T& back() const - -Returns a reference or const reference to the last element. - -____________________________________________________________________________________________________ -Capacity - -bool empty() const - -Returns true if the size of the queue is zero, otherwise false. -____________________________________________________________________________________________________ - -bool full() const - -Returns true if the size of the queue is SIZE, otherwise false. -____________________________________________________________________________________________________ - -size_type size() const - -Returns the size of the queue. -____________________________________________________________________________________________________ - -size_type available() const - -Returns the remaining available capacity in the queue. -____________________________________________________________________________________________________ - -ETL_CONSTEXPR size_type max_size() const - -Returns the maximum possible size of the queue. -____________________________________________________________________________________________________ - -ETL_CONSTEXPR size_type capacity() const - -Returns the maximum possible size of the queue. - -____________________________________________________________________________________________________ -Modifiers - -void push(const_reference value); -void push(rvalue_reference value); - -Pushes a value to the back of the queue. -Emits an etl::queue_full if the queue is full and ETL_CHECK_PUSH_POP is defined. If asserts or exceptions are not enabled then undefined behaviour occurs. -____________________________________________________________________________________________________ - -C++03 -void emplace(const T1& value1); -void emplace(const T1& value1, const T2& value2); -void emplace(const T1& value1, const T2& value2, const T3& value3); -void emplace(const T1& value1, const T2& value2, const T3& value3, const T4& value4); - -C++11 -void emplace(Args&&… args); - -Constructs an item in the the queue 'in place'. -C++03: Supports up to four constructor parameters. -Emits an etl::queue_full if the queue is full and ETL_CHECK_PUSH_POP is defined. If asserts or exceptions are not enabled then undefined behaviour occurs. -____________________________________________________________________________________________________ - -void pop(); - -Pop a value from the front of the list. -Emits an etl::queue_empty if the queue is empty and ETL_CHECK_PUSH_POP is defined. Undefined behaviour if the queue is empty. -____________________________________________________________________________________________________ - -void pop_into(TContainer& destination); - -Pop a value from the front of the list and places it in destination. -Emits an etl::queue_empty if the queue is empty and ETL_CHECK_PUSH_POP is defined. Undefined behaviour if the queue is empty. -____________________________________________________________________________________________________ - -void clear(); - -Clears the queue to a size of zero. - diff --git a/docs/raw/containers/queue_mpmc_mutex.txt b/docs/raw/containers/queue_mpmc_mutex.txt deleted file mode 100644 index 8e4a2c8d..00000000 --- a/docs/raw/containers/queue_mpmc_mutex.txt +++ /dev/null @@ -1,145 +0,0 @@ -queue_mpmc_mutex - -A fixed capacity multi-producer, multi-consumer queue for multi-threaded systems that uses etl::mutex to control access. - -etl::queue_mpmc_mutex - -Inherits from etl::iqueue_mpmc_mutex -etl::iqueue_mpmc_mutex may be used as a size independent pointer or reference type for any etl::queue_mpmc_mutex instance of the same implementation. - -The memory model determines the type used internally for indexes and size, to allow for the most efficient implementation for the application. - -Maximum queue sizes: -MEMORY_MODEL_SMALL 255 -MEMORY_MODEL_MEDIUM 65535 -MEMORY_MODEL_LARGE 2147483647 -MEMORY_MODEL_HUGE 9223372036854775807 - -See memory_model.h - -____________________________________________________________________________________________________ -Member types - -value_type T -size_type -pointer value_type* -const_pointer const value_type* -reference value_type& -const_reference const value_type& - -____________________________________________________________________________________________________ -Constructor - -queue_mpmc_mutex(); - -____________________________________________________________________________________________________ -Capacity - -bool empty() const - -Returns true if the size of the queue is zero, otherwise false. -____________________________________________________________________________________________________ - -bool full() const - -Returns true if the size of the queue is SIZE, otherwise false. -____________________________________________________________________________________________________ - -size_t size() const - -Returns the size of the queue. -____________________________________________________________________________________________________ - -size_t available() const -size_t available_from_isr() const - -Returns the remaining available capacity in the queue. -____________________________________________________________________________________________________ - -ETL_CONSTEXPR size_t max_size() const - -Returns the maximum possible size of the queue. -____________________________________________________________________________________________________ - -ETL_CONSTEXPR size_t capacity() const - -Returns the maximum possible size of the queue. - -____________________________________________________________________________________________________ -Modifiers -bool push(const T& value); -bool push(T&& value); - -Pushes a value to the back of the queue. -Returns true if successful, otherwise false. -____________________________________________________________________________________________________ - -bool pop(); - -Pop a value from the front of the list. -Returns true if successful, otherwise false. -____________________________________________________________________________________________________ - -bool pop(T& value); -bool pop(T&& value); - -Pop a value from the front of the list and place it in value. -Returns true if successful, otherwise false. -____________________________________________________________________________________________________ - -void clear(); - -Clears the queue to a size of zero -____________________________________________________________________________________________________ - -C++03 -bool emplace(const T1& value1); -bool emplace(const T1& value1, const T2& value2); -bool emplace(const T1& value1, const T2& value2, const T3& value3); -bool emplace(const T1& value1, const T2& value2, const T3& value3, const T4& value4); - -C++11 -bool emplace(Args&&… args); - -Constructs an item in the the queue 'in place'. -C++03: Supports up to four constructor parameters. - -____________________________________________________________________________________________________ -Notes - -Remember that thread context switches may occur between calls to the access protected functions. For example, a call to empty() may return true, but a subsequent call to pop() may succeed if a context switch occurred between the two and pushed a new value. - -____________________________________________________________________________________________________ -Example - -etl::queue_mpmc_mutex queue; - -int main() -{ - while (true) - { - char c; - - if (queue.pop(c)) - { - Print(c); - } - } -} - -void FunctionInThread1(char c) -{ - while (!queue.push(c)) - { - } -} - -void FunctionInThread2(char c) -{ - while (!queue.push(c)) - { - } -} - diff --git a/docs/raw/containers/queue_spsc_atomic.txt b/docs/raw/containers/queue_spsc_atomic.txt deleted file mode 100644 index 1ef4a2ba..00000000 --- a/docs/raw/containers/queue_spsc_atomic.txt +++ /dev/null @@ -1,148 +0,0 @@ -queue_spsc_atomic - -A fixed capacity single-producer, single-consumer queue for multi-threaded and interrupt driven systems. -The queue may be used to transfer data to or from two threads or an ISR. - -The queue makes use of etl::atomic_size_t - -etl::queue_spsc_atomic - -Inherits from etl::iqueue_spsc_atomic -etl::iqueue_spsc_atomic may be used as a size independent pointer or reference type for any etl::queue_spsc_atomic instance of the same implementation. - -The memory model determines the type used internally for indexes and size, to allow for the most efficient implementation for the application. - -Maximum queue sizes: -MEMORY_MODEL_SMALL 255 -MEMORY_MODEL_MEDIUM 65535 -MEMORY_MODEL_LARGE 2147483647 -MEMORY_MODEL_HUGE 9223372036854775807 - -See memory_model.h - -____________________________________________________________________________________________________ -Member types - -value_type T -size_type -pointer value_type* -const_pointer const value_type* -reference value_type& -const_reference const value_type& - -____________________________________________________________________________________________________ -Constructor - -queue_spsc_atomic(); - -____________________________________________________________________________________________________ -Capacity - -bool empty() const - -Returns true if the size of the queue is zero, otherwise false. -Accurate from the 'pop' thread. -'Not empty' is a guess from the 'push' thread. -____________________________________________________________________________________________________ - -bool full() const - -Returns true if the size of the queue is SIZE, otherwise false. -Accurate from the 'push' thread. -'Not full' is a guess from the 'pop' thread. -____________________________________________________________________________________________________ - -size_t size() const - -Returns the size of the queue. -Due to concurrency, this is a guess. -____________________________________________________________________________________________________ - -size_t available() const - -Returns the remaining available capacity in the queue. -Due to concurrency, this is a guess. -____________________________________________________________________________________________________ - -ETL_CONSTEXPR size_t max_size() const - -Returns the maximum possible size of the queue. -____________________________________________________________________________________________________ - -ETL_CONSTEXPR size_t capacity() const - -Returns the maximum possible size of the queue. - -____________________________________________________________________________________________________ -Modifiers -bool push(const T& value); -bool push(T&& value); - -Pushes a value to the back of the queue. -Returns true if successful, otherwise false. -____________________________________________________________________________________________________ - -bool pop(); - -Pop a value from the front of the list. -Returns true if successful, otherwise false. -____________________________________________________________________________________________________ - -bool pop(T& value); -bool pop(T&& value); - -Pop a value from the front of the list and place it in value. -Returns true if successful, otherwise false. -____________________________________________________________________________________________________ - -void clear(); - -Clears the queue to a size of zero. -Must be called from thread that pops the queue or when there is no possibility of concurrent access. -____________________________________________________________________________________________________ - -C++03 -bool emplace(const T1& value1); -bool emplace(const T1& value1, const T2& value2); -bool emplace(const T1& value1, const T2& value2, const T3& value3); -bool emplace(const T1& value1, const T2& value2, const T3& value3, const T4& value4); - -C++11 -bool emplace(Args&&… args); - -Constructs an item in the the queue 'in place'. -C++03: Supports up to four constructor parameters. - -____________________________________________________________________________________________________ -Notes - -Remember that thread context switches may occur between calls to the access protected functions. For example, a call to empty() may return true, but a subsequent call to pop() may succeed if a context switch occurred between the two and pushed a new value. - -____________________________________________________________________________________________________ -Example - -etl::queue_spsc_atomic queue; - -int main() -{ - while (true) - { - char c; - - if (queue.pop(c)) - { - Print(c); - } - } -} - -void Thread() -{ - while (true) - { - queue.push('A'); - } -} - diff --git a/docs/raw/containers/queue_spsc_isr.txt b/docs/raw/containers/queue_spsc_isr.txt deleted file mode 100644 index ee0a96c1..00000000 --- a/docs/raw/containers/queue_spsc_isr.txt +++ /dev/null @@ -1,168 +0,0 @@ -queue_spsc_isr - -See Locked Queues - -This class is deprecated. Use queue_spsc_locked as a replacement. - -A fixed capacity single-producer, single-consumer queue for interrupt driven systems. -The queue may be used to transfer data to or from an ISR. Calls to the queue from the ISR must use the _from_isr versions. - -A helper class must be supplied that defines static void lock() and void unlock() functions. They must perform the requisite memory barriers to preserve the order of execution. - -etl::queue_spsc_isr - -Inherits from etl::iqueue_spsc_isr -etl::iqueue_spsc_isr may be used as a size independent pointer or reference type for any etl::queue_spsc_isr instance of the same implementation. - -The memory model determines the type used internally for indexes and size, to allow for the most efficient implementation for the application. - -Maximum queue sizes: -MEMORY_MODEL_SMALL 255 -MEMORY_MODEL_MEDIUM 65535 -MEMORY_MODEL_LARGE 2147483647 -MEMORY_MODEL_HUGE 9223372036854775807 - -See memory_model.h - -____________________________________________________________________________________________________ -Member types - -value_type T -size_type -pointer value_type* -const_pointer const value_type* -reference value_type& -const_reference const value_type& - -____________________________________________________________________________________________________ -Constructor - -queue_spsc_isr(); - -____________________________________________________________________________________________________ -Capacity - -bool empty() const -bool empty_from_isr() const - -Returns true if the size of the queue is zero, otherwise false. -____________________________________________________________________________________________________ - -bool full() const -bool full_from_isr() const - -Returns true if the size of the queue is SIZE, otherwise false. -____________________________________________________________________________________________________ - -size_type size() const -size_type size_from_isr() const - -Returns the size of the queue. -____________________________________________________________________________________________________ - -size_type available() const -size_type available_from_isr() const - -Returns the remaining available capacity in the queue. -____________________________________________________________________________________________________ - -size_type max_size() const - -Returns the maximum possible size of the queue. -____________________________________________________________________________________________________ - -size_type capacity() const - -Returns the maximum possible size of the queue. - -____________________________________________________________________________________________________ -Modifiers - -bool push(const T& value); -bool push(T&& value); -bool push_from_isr(const T& value); -bool push_from_isr(T&& value); - -Pushes a value to the back of the queue. -Returns true if successful, otherwise false. -____________________________________________________________________________________________________ - -bool pop(); -bool pop_from_isr(); - -Pop a value from the front of the list. -Returns true if successful, otherwise false. -____________________________________________________________________________________________________ - -bool pop(T& value); -bool pop_from_isr(T& value); -bool pop(T&& value); -bool pop_from_isr(T&& value); - -Pop a value from the front of the list and place it in value. -Returns true if successful, otherwise false. -____________________________________________________________________________________________________ - -void clear(); -void clear_from_isr(); - -Clears the queue to a size of zero. -____________________________________________________________________________________________________ - -C++03 -bool emplace(const T1& value1); -bool emplace(const T1& value1, const T2& value2); -bool emplace(const T1& value1, const T2& value2, const T3& value3); -bool emplace(const T1& value1, const T2& value2, const T3& value3, const T4& value4); - -C++11 -bool emplace(Args&&… args); - -Constructs an item in the the queue 'in place'. -C++03: Supports up to four constructor parameters. - -____________________________________________________________________________________________________ -Notes - -Remember that interrupts may occur between calls to the access protected functions. For example, a call to empty() may return true, but a subsequent call to pop() may succeed if an interrupt occurred between the two and pushed a new value. - -Example - -class InterruptControl -{ -public: - - static void lock() - { - // Store current interrupt control register and disable the relevant interrupt. - } - - static void unlock() - { - // Restore the interrupt control register. - } -}; - -etl::queue_spsc_isr queue; - -int main() -{ - while (true) - { - char c; - - if (queue.pop(c)) - { - Print(c); - } - } -} - -void ISR(char c) -{ - queue.push_from_isr(c); -} - diff --git a/docs/raw/containers/queue_spsc_locked.txt b/docs/raw/containers/queue_spsc_locked.txt deleted file mode 100644 index 2f90792b..00000000 --- a/docs/raw/containers/queue_spsc_locked.txt +++ /dev/null @@ -1,175 +0,0 @@ -queue_spsc_locked - -See Locked Queues - -This class is designed to be a more generally useful version of etl::queue_spsc_isr and can replace it. - -A fixed capacity single-producer, single-consumer queue, generally used to transfer data to or from an ISR. -Calls from the 'unlocked' thread of execution (ISR) must use the _from_unlocked versions. - -Helper functions must be supplied at construction that lock (disable) and unlock (enable) the relevant ISR. -They are passed as const references to etl::ifunction. -They must perform the requisite memory barriers to preserve the order of execution. - -Many functions have two versions. One locks and unlocks access and is used from the foreground task (non-ISR). The other, with a _from_unlocked suffix, are called from the ISR. - -etl::queue_spsc_locked - -Inherits from etl::iqueue_spsc_locked -etl::iqueue_spsc_locked may be used as a size independent pointer or reference type for any etl::queue_spsc_locked instance of the same implementation. - -The memory model determines the type used internally for indexes and size, to allow for the most efficient implementation for the application. - -Maximum queue sizes: -MEMORY_MODEL_SMALL 255 -MEMORY_MODEL_MEDIUM 65535 -MEMORY_MODEL_LARGE 2147483647 -MEMORY_MODEL_HUGE 9223372036854775807 - -See memory_model.h - -____________________________________________________________________________________________________ -Member types - -value_type T -size_type -pointer value_type* -const_pointer const value_type* -reference value_type& -const_reference const value_type& - -____________________________________________________________________________________________________ -Constructor - -queue_spsc_locked(const etl::ifunction& lock, const etl::ifunction& unlock); - -____________________________________________________________________________________________________ -Capacity - -bool empty() const -bool empty_from_unlocked() const -Returns true if the size of the queue is zero, otherwise false. -____________________________________________________________________________________________________ - -bool full() const -bool full_from_unlocked() const -Returns true if the size of the queue is SIZE, otherwise false. -____________________________________________________________________________________________________ - -size_type size() const -size_type size_from_unlocked() const -Returns the size of the queue. -____________________________________________________________________________________________________ - -size_type available() const -size_type available_from_unlocked() const -Returns the remaining available capacity in the queue. -____________________________________________________________________________________________________ - -size_type max_size() const -Returns the maximum possible size of the queue. -____________________________________________________________________________________________________ - -size_type capacity() const -Returns the maximum possible size of the queue. - -____________________________________________________________________________________________________ -Modifiers - -bool push(const T& value); -bool push(T&& value); -bool push_from_locked(const T& value); -bool push_from_locked(T&& value); -Pushes a value to the back of the queue. -Returns true if successful, otherwise false. -____________________________________________________________________________________________________ - -bool pop(); -bool pop_from_unlocked(); -Pop a value from the front of the list. -Returns true if successful, otherwise false. -____________________________________________________________________________________________________ - -bool pop(T& value); -bool pop_from_locked(T& value); -bool pop(T&& value); -bool pop_from_locked(T&& value); -Pop a value from the front of the list and place it in value. -Returns true if successful, otherwise false. -____________________________________________________________________________________________________ - -void clear(); -void clear_from_unlocked(); -Clears the queue to a size of zero. -____________________________________________________________________________________________________ - -C++03 -bool emplace(const T1& value1); -bool emplace(const T1& value1, const T2& value2); -bool emplace(const T1& value1, const T2& value2, const T3& value3); -bool emplace(const T1& value1, const T2& value2, const T3& value3, const T4& value4); - -bool emplace_from_unlocked(const T1& value1); -bool emplace_from_unlocked(const T1& value1, const T2& value2); -bool emplace_from_unlocked(const T1& value1, const T2& value2, const T3& value3); -bool emplace_from_unlocked(const T1& value1, const T2& value2, const T3& value3, const T4& value4); - -C++11 -template -bool emplace(Args&&… args); - -template -bool emplace_from_unlocked(Args&&... args); -Constructs an item in the the queue 'in place'. -C++03: Supports up to four constructor parameters. - -____________________________________________________________________________________________________ -Notes - -Remember that interrupts may occur between calls to the access protected functions. For example, a call to empty() may return true, but a subsequent call to pop() may succeed if an interrupt occurred between the two and pushed a new value. - -Example - -class InterruptControl -{ -public: - - void lock() - { - // Store current interrupt control register and disable the relevant interrupt. - } - - void unlock() - { - // Restore the interrupt control register. - } -}; - -InterruptControl interruptControl; - -// Create function wrappers with direct calls to the instance's member functions. -etl::function_imv lock; -etl::function_imv unlock; - -etl::queue_spsc_locked queue(lock, unlock); - -int main() -{ - while (true) - { - char c; - - if (queue.pop(c)) - { - Print(c); - } - } -} - -void ISR(char c) -{ - queue.push_from_unlocked(c); -} - diff --git a/docs/raw/containers/variant_pool.txt b/docs/raw/containers/variant_pool.txt deleted file mode 100644 index 4f81ff84..00000000 --- a/docs/raw/containers/variant_pool.txt +++ /dev/null @@ -1,175 +0,0 @@ -variant_pool - -This template class allows instances of multiple derived types to be constructed from a common store. -It may support up to 16 types and MAX_SIZE instances. - -Note: The caller of the factory's create becomes the owner of the instance. It must call destroy. - -template - -____________________________________________________________________________________________________ -Constants - -MAX_SIZE - -The maximum number of instances that may be created. - -____________________________________________________________________________________________________ -Member functions - -template -T* create() - -Pre C++11 -template -T* create(const TP1& p1) - -template -T* create(const TP1& p1, const TP2& p2) - -template -T* create(const TP1& p1, const TP2& p2, const TP3& p3) - -template -T* create(const TP1& p1, const TP2& p2, const TP3& p3, const TP4& p4) - -Creates an instance of T with zero to four constructor parameters. The parameters are forwarded to T's constructor. -Returns a pointer to the constructed instance or nullptr. -If T if not one of those declared in the template parameter list then a compile time error will occur. -If T cannot be created due to there being no spare capacity then an etl::factory_cannot_create is emitted. If exceptions are not configured to be thrown then the function returns nullptr. -____________________________________________________________________________________________________ - -C++11 -template -T* create(Args&&... args) - -Creates an instance of T with the supplied parameters. The parameters are forwarded to T's constructor. -Returns a pointer to the constructed instance or nullptr. -If T if not one of those declared in the template parameter list then a compile time error will occur. -If T cannot be created due to there being no spare capacity then an etl::factory_cannot_create is emitted. If exceptions are not configured to be thrown then the function returns nullptr. -____________________________________________________________________________________________________ - -bool destroy(const T* const p) - -Destroys the instance pointed to by p. -Compile time error if T is not one of, or not a base of, one the supported types. -If the factory is empty or p does not belong to it then an etl::factory_did_not_create is emitted. -If exceptions are not configured to be thrown then the function returns true for success and false for failure. -____________________________________________________________________________________________________ - -size_t max_size() const - -Returns the maximum number of items in the factory. -____________________________________________________________________________________________________ - - -size_t available() const - -Returns the number of free items in the factory. -____________________________________________________________________________________________________ - -size_t size() const - -Returns the number of allocated items in the factory. -____________________________________________________________________________________________________ - -bool empty() const - -Checks to see if there are no allocated items in the factory. -____________________________________________________________________________________________________ - -bool full() const - -Checks to see if there are no free items in the factory. - -____________________________________________________________________________________________________ -Example - -//*********************************** -struct Base -{ - virtual ~Base() - { - } -}; - -//*********************************** -struct Derived1 : public Base -{ - enum - { - ID = 1 - }; -}; - -//*********************************** -struct Derived2 : public Base -{ - enum - { - ID = 2 - }; - - Derived2(int a_) - : a(a_) - { - } - - int a; -}; - -//*********************************** -struct Derived3 : public Base -{ - enum - { - ID = 3 - }; - - Derived3(int a_, double b_) - : a(a_), - b(b_) - { - } - - int a; - double b; -} - -//*********************************** -struct Derived4 : public Base -{ - enum - { - ID = 4 - }; -}; - -// A factory that can create up to three instances of Derived1, Derived2, Derived3. -// Notice that the types can be declared in any order. -typedef etl::factory<3, Derived1, Derived3, Derived2> VariantPool; - -VariantPool pool; - -// Create an instance of Derived1. -Derived1* pb1 = pool.create(); - -// Create an instance of Derived2 from its id, with constructor parameter 3. -Derived2* pb2 = pool.create(3); - -// Create an instance of Derived3 with constructor parameters 4 and 1.2. -Derived3* pb3 = pool.create(4, 1.2); - -// Create an instance of Derived4. -Derived4* pb4 = pool.create(); // Compile time error. - -// Destroy the instances. -factory.destroy(pb2); -factory.destroy(pb1); -factory.destroy(pb3); - - diff --git a/docs/raw/utilities/error_handler.txt b/docs/raw/utilities/error_handler.txt deleted file mode 100644 index 0e12ccd9..00000000 --- a/docs/raw/utilities/error_handler.txt +++ /dev/null @@ -1,166 +0,0 @@ -error_handler -Finding errors within an embedded system can be difficult due to the performance and space restrictions imposed upon the platform. The library allows a variety of methods to catch errors, allowing the performance and space overheads to be chosen according to the situation and requirements. - -The library allows the method to be chosen at compile time. - -You have a choice of:- -• Exceptions -• Asserts -• Error log -• No error checking - -The type of error handler used is dependant on the compile time macro defined. -Note: This are usually set as a project wide definition. - -• ETL_NO_CHECKS No checks are mode at all, not even in debug mode. -• ETL_THROW_EXCEPTIONS Exceptions are thrown for an error. -• ETL_USE_ASSERT_FUNCTION Errors are sent to a user defined assert handler. -• ETL_LOG_ERRORS Errors are sent to a user defined error handler. - This can be used in conjunction with other options. - -If none of the above macros are defined then the library will use assert. These are only active is NDEBUG is not defined. -____________________________________________________________________________________________________ -Errors are checked for by calling one of the following:- - -ETL_ASSERT(condition, ETL_ERROR(error_exception_class)) -Raises the error if the condition is false. -____________________________________________________________________________________________________ -ETL_ASSERT_AND_RETURN(condition, ETL_ERROR(error_exception_class)) -Raises the error if the condition is false and calls return. -____________________________________________________________________________________________________ -ETL_ASSERT_AND_RETURN_VALUE(condition, ETL_ERROR(error_exception_class), value) -Raises the error if the condition is false and calls return(value). -____________________________________________________________________________________________________ -ETL_ALWAYS_ASSERT(ETL_ERROR(error_exception_class)) -Raises the error. -____________________________________________________________________________________________________ -ETL_ALWAYS_ASSERT_AND_RETURN(ETL_ERROR(error_exception_class)) -Raises the error and calls return. -____________________________________________________________________________________________________ -ETL_ALWAYS_ASSERT_AND_RETURN_VALUE(ETL_ERROR(error_exception_class), value) -Raises the error and calls return(value). - -Note: Not all error methods will call the return, such as when using C++ exceptions. -The macro will call return for the following combinations:- -ETL_LOG_ERRORS only. -ETL_DEBUG not defined. -____________________________________________________________________________________________________ -If ETL_VERBOSE_ERRORS is defined then the filename is included as part of the error, otherwise it will be omitted, so reducing storage requirements. - -Error messages by be declared using the ETL_ERROR_TEXT macro. -ETL_ERROR_TEXT("Verbose text", "terse text") -If ETL_VERBOSE_ERRORS is defined then ETL_TEXT uses the verbose text. By default the terse text is used. - -The terse text used in the library follows a pattern. For example, errors in etl::vector start with "17" and the alpha code for 'vector full' is "A". The return from the what() member function in this case will be "17A". - -When ETL_LOG_ERRORS is defined, error exceptions are passed to etl::error_handler::error() before throwing the exception or calling the assert. This will do nothing until a user defined handler function is set. The user function may either be a free function or a member function. - -There is an additional switch that enables checks to be made on pushes and pops to containers, ETL_CHECK_PUSH_POP. -This is not enabled by default as empty/full checks will usually be made by the calling code. - ____________________________________________________________________________________________________ -There are versions of the assert macros that are only enabled when ETL_IS_DEBUG_BUILD is true:- - -ETL_DEBUG_ASSERT(condition, ETL_ERROR(error_exception_class)) -Raises the error if the condition is false. -____________________________________________________________________________________________________ -ETL_DEBUG_ASSERT_AND_RETURN(condition, ETL_ERROR(error_exception_class)) -Raises the error if the condition is false and calls return. -____________________________________________________________________________________________________ -ETL_DEBUG_ASSERT_AND_RETURN_VALUE(condition, ETL_ERROR(error_exception_class), value) -Raises the error if the condition is false and calls return(value). -____________________________________________________________________________________________________ -ETL_DEBUG_ALWAYS_ASSERT(ETL_ERROR(error_exception_class)) -Raises the error. -____________________________________________________________________________________________________ -ETL_DEBUG_ALWAYS_ASSERT_AND_RETURN(ETL_ERROR(error_exception_class)) -Raises the error and calls return. -____________________________________________________________________________________________________ -ETL_DEBUG_ALWAYS_ASSERT_AND_RETURN_VALUE(ETL_ERROR(error_exception_class), value) -Raises the error and calls return(value). -____________________________________________________________________________________________________ -Example macro combinations - -No error macros defined Asserts are generated when a check fails. -____________________________________________________________________________________________________ -ETL_LOG_ERRORS The error handler is called. -____________________________________________________________________________________________________ -ETL_NO_CHECKS No checks are made. No asserts or exceptions are generated. - No calls to the error handler are made, even if ETL_LOG_ERRORS is defined. -____________________________________________________________________________________________________ -ETL_THROW_EXCEPTIONS An exception is thrown when a check fails. -____________________________________________________________________________________________________ -ETL_USE_ASSERT_FUNCTION Calls a user defined assert function. Set with etl::set_assert_function() - The assert function must have the signature void(const etl::exception&) - If an assert handler is not specified then assert(false) is called. -____________________________________________________________________________________________________ -ETL_LOG_ERRORS When a check fails the error handler is called, then an exception is thrown. -ETL_THROW_EXCEPTIONS -____________________________________________________________________________________________________ -ETL_LOG_ERRORS Asserts are generated when a check fails and the error handler is called and -ETL_CHECK_PUSH_POP additional checks for pushes and pops are made. -____________________________________________________________________________________________________ -Example error handlers - -void free_function(const etl::exception& e) -{ - std::cout << "The error was " << e.what() << " in " << e.file_name() << " at " - << e.line_number() << "\n"; -} - -struct error_log -{ - void member_function(const etl::exception& e) - { - std::cout << "The error was " << e.what() << " in " << e.file_name() << " at " - << e.line_number() << "\n"; - } -}; -____________________________________________________________________________________________________ -Setting a free function as the recipient -int main() -{ - etl::error_handler::set_callback(); -} -____________________________________________________________________________________________________ -Setting a member function as the recipient - -error_log log; - -// Run-time -int main() -{ - etl::error_handler::set_callback(log); -} - -// Compile-time. 'log' must have static linkage. -int main() -{ - etl::error_handler::set_callback(); -} -____________________________________________________________________________________________________ -Setting an etl::ifunction as the recipient -This is not recommended for new applications. -Use one of the methods above instead. - -// Free function -etl::function error_callback(free_function); - -// Member function -etl::function error_callback(log, &error_log::member_function); - -// Free function using the nested struct (Deprecated) -etl::error_handler::free_function error_callback(free_function); - -// Member function using the nested struct (Deprecated) -etl::error_handler::member_function error_callback(log, error_log::member_function); - -Use one of the above -int main() -{ - // Tell the error handler about it. - etl::error_handler::set_callback(error_callback); -} -____________________________________________________________________________________________________ -Deprecated -The nested structures free_function and member_function may still be used, but are deprecated. - diff --git a/docs/utilities/algorithms.md b/docs/utilities/algorithms.md new file mode 100644 index 00000000..25b06828 --- /dev/null +++ b/docs/utilities/algorithms.md @@ -0,0 +1,1382 @@ +--- +title: "Algorithms" +--- + +A set of algorithms from the STL. + +If `ETL_NO_STL` is defined then the ETL implements its own reverse engineered versions. +Otherwise, the ETL will often be a wrapper around the STL's implementation. + +Functions returning pair will either use `std::pair` or, if `ETL_NO_STL` is defined, `etl::pair`. + +**Note:** +Some algorithms will be `constexpr`, dependent on the compiler support and ETL setup. + +## swap +Only defined if `ETL_NO_STL` is defined. + +```cpp +template +void swap(T& a, T& b) ETL_NOEXCEPT +``` +**Description** +Swaps two values. + +--- + +```cpp +template +void swap(T(&a)[N], T(&b)[N]) ETL_NOEXCEPT +``` +**Description** +Swaps two arrays. + +## iter_swap + +```cpp +template +void iter_swap(TIterator1 a, TIterator2 b) +``` +**Description** +Swaps the elements pointed to by two iterators. + +## swap_ranges + +```cpp +template +TIterator2 swap_ranges(T1terator1 first1, + T1terator1 last1, + TIterator2 first2) +``` +**Description** +Swaps two ranges of elements. + +## copy + +```cpp +template +TOutputIterator copy(TInputIterator sb, TInputIterator se, TOutputIterator db) +``` +**Description** +Copies the elements in the range, defined by `sb`, `se`, to another range beginning at `db`. + +**constexpr** +This function is `constexpr` under the following conditions. +- The STL is in use and C++20 is supported. +- The iterator is non-pointer or the type is not trivially copyable and C++14 is supported. +- The iterator is a pointer, the type is trivially copyable, built-in `memcpy` is supported, and C++14 is supported. +- The iterator is a pointer, the type is trivially copyable, `ETL_FORCE_CONSTEXPR_ALGORITHMS` is defined as `1`, and C++14 is supported. + +## copy_s +**ETL extension** + +```cpp +template +TOutputIterator copy_s(TInputIterator i_begin, TInputIterator i_end, + TOutputIterator o_begin, TOutputIterator o_end) +``` +**Description** +A safer four parameter version that will stop copying when either iterator reaches the end of its range. + +**constexpr** +This function is `constexpr` under the following conditions. +- The STL is in use and C++20 is supported. +- The iterator is non-pointer or the type is not trivially copyable and C++14 is supported. +- The iterator is a pointer, the type is trivially copyable, built-in `memcpy` is supported, and C++14 is supported. +- The iterator is a pointer, the type is trivially copyable, `ETL_FORCE_CONSTEXPR_ALGORITHMS` is defined as `1`, and C++14 is supported. + +## copy_n + +```cpp +template +TOutputIterator copy_n(TInputIterator begin, TSize n, TOutputIterator result) +``` +**Description** +Copies exactly `n` values from the range beginning at `begin` to the range beginning at `result`. + +**constexpr** +This function is `constexpr` under the following conditions. +- The STL is in use and C++20 is supported. +- The iterator is non-pointer or the type is not trivially copyable and C++14 is supported. +- The iterator is a pointer, the type is trivially copyable, built-in `memcpy` is supported, and C++14 is supported. +- The iterator is a pointer, the type is trivially copyable, `ETL_FORCE_CONSTEXPR_ALGORITHMS` is defined as `1`, and C++14 is supported. + +## copy_n_s +**ETL extension** +```cpp +template +TOutputIterator copy_n_s(TInputIterator i_begin, + TSize n, + TOutputIterator o_begin, TOutputIterator o_end) +``` +**Description** +A safer version that will stop copying when either `n` items have been copied or the output iterator reaches the end of its range. + +--- + +```cpp +template +TOutputIterator copy_n_s(TIterator i_begin, + TSize1 n1, + TOutputIterator o_begin, + TSize1 n2,) +``` +**Description** +A safer version that will stop copying when either n1 or n2 items have been copied. + +**constexpr** +This function is constexpr under the following conditions. +- The STL is in use and C++20 is supported. +- The iterator is non-pointer or the type is not trivially copyable and C++14 is supported. +- The iterator is a pointer, the type is trivially copyable, built-in `memcpy` is supported, and C++14 is supported. +- The iterator is a pointer, the type is trivially copyable, `ETL_FORCE_CONSTEXPR_ALGORITHMS` is defined as `1`, and C++14 is supported. + +## copy_if + +```cpp +template +ETL_CONSTEXPR14 +TOutputIterator copy_if(TIterator begin, TIterator end, TOutputIterator out, TUnaryPredicate predicate) +``` +**Description** +Only copies the elements for which the predicate predicate returns `true`. + +## copy_if_s +**ETL extension** +```cpp +template +ETL_CONSTEXPR14 +TOutputIterator copy_if_s(TIterator i_begin, TIterator i_end, + TOutputIterator o_begin, TOutputIterator o_end, + TUnaryPredicate predicate) +``` +**Description** +A safer version that will stop copying when either iterator reaches the end of its range. + +## copy_n_if +**ETL extension** + +```cpp +template +ETL_CONSTEXPR14 +TOutputIterator copy_n_if(TIterator begin, TSize n, TOutputIterator out, TUnaryPredicate predicate) +``` +**Description** +A combination of `copy_if` and `copy_n`. + +## reverse_copy +```cpp +template +TIterator2 reverse_copy(TIterator1 sb, TIterator1 se, TIterator2 db) +``` +**Description** +Copies the elements from the range `sb`, `se` to another range beginning at `db` in such a way that the elements in the new range are in reverse order. + +**constexpr** +This function is `constexpr` under the following conditions. +- The STL is in use and C++20 is supported. +- The STL is not in use. + +## copy_backward + +```cpp +template +TIterator2 copy_backward(TIterator1 sb, TIterator1 se, TIterator2 de) +``` +**Description** +Copies the elements from the range, defined by `sb`, `se` to another range ending at `db`. +The elements are copied in reverse order. + +**constexpr** +This function is constexpr under the following conditions. +- The STL is in use and C++20 is supported. +- The STL is not in use. + +## count + +```cpp +template +typename iterator_traits::difference_type count(TIterator first, + TIterator last, + const T& value) +``` +**Description** +Counts the elements that are equal to value. + +## count_if + +```cpp +template +typename iterator_traits::difference_type count_if(TIterator first, + TIterator last, + TUnaryPredicate predicate) +``` +**Description** +Counts the elements where predicate returns `true`. + +## equal +```cpp +template +bool equal(TIterator1 first1, TIterator1 last1, TIterator2 first2) +``` +**Description** +Returns `true` if the range [`first1`, `last1`) is equal to the range []`first2`, `first2 + distance(first2, last2)`). + +## lexicographical_compare +```cpp +template +bool lexicographical_compare(TIterator1 first1, TIterator1 last1, + TIterator2 first2, TIterator2 last2) +``` +**Description** +Checks if the range [`first1`, `last1`) is lexicographically less than the range [`first2`, `last2`), using the 'less-than' operator. + +--- + +```cpp +template +bool lexicographical_compare(TIterator1 first1, TIterator1 last1, + TIterator2 first2, TIterator2 last2, + TCompare compare) +``` +**Description** +Checks if the range [`first1`, `last1`) is lexicographically less than the range [`first2`, `last2`), using `compare`. + +## make_heap +```cpp +template +void make_heap(TIterator first, TIterator last) +``` +**Description** +Makes a heap from the range [`first`, `last`). + +--- + +```cpp +template +void make_heap(TIterator first, TIterator last, TCompare compare) +``` +**Description** +Makes a heap from the range [`first`, `last`). +Uses `compare` to compare elements. + +## is_heap +```cpp +template +bool is_heap(TIterator first, TIterator last) +``` +**Description** +Returns `true` is the range [`first`, `last`) is a heap, otherwise `false`. + +--- + +```cpp +template +bool is_heap(TIterator first, TIterator last, TCompare compare) +``` +**Description** +Returns `true` is the range [`first`, `last`) is a heap, otherwise `false`. +Uses `compare` to compare elements. + +## pop_heap +```cpp +template +void pop_heap(TIterator first, TIterator last) +``` +**Description** +Removes the first element from the heap. + +--- + +```cpp +template +void pop_heap(TIterator first, TIterator last, TCompare compare) +``` +**Description** +Removes the first element from the heap. +Uses `compare` to compare elements. + +## push_heap +```cpp +template +void push_heap(TIterator first, TIterator last) +``` +**Description** +Inserts the element at the position `last - 1` into the heap. + +--- + +```cpp +template +void push_heap(TIterator first, TIterator last, TCompare compare) +``` +**Description** +Inserts the element at the position `last - 1` into the heap. +Uses `compare` to compare elements. + +## min +```cpp +template +ETL_CONSTEXPR const T& min(const T& a, const T& b) +``` +**Description** +Returns the minimum of the two values. + +--- + +```cpp +template +ETL_CONSTEXPR const T& min(const T& a, const T& b, TCompare compare) +``` +**Description** +Returns the value where compare returns `true` if `a is less than `b`. + +## max +```cpp +template +ETL_CONSTEXPR const T& max(const T& a, const T& b) +``` +**Description** +Returns the maximum of the two values. + +--- + +```cpp +template +ETL_CONSTEXPR const T& max(const T& a, const T& b, TCompare compare) +``` +**Description** +Returns the value where `compare` returns `true` if `a` is less than `b`. + +## minmax +```cpp +template +pair minmax(const T& a, const T& b) +``` +**Description** +Returns the lesser and greater values. + +--- + +```cpp +template +pair minmax(const T& a, const T& b, TCompare compare) +``` +**Description** +Returns the lesser and greater values using `compare`. + +## min_element +```cpp +template +TIterator min_element(TIterator begin, TIterator end) +``` +**Description** +Finds the smallest element in the range [`begin`, `end`). + +--- + +```cpp +template +TIterator min_element(TIterator begin, TIterator end, TCompare compare) +``` +**Description** +Finds the smallest element in the range [`begin`, `end`) using `compare`. + +## max_element +```cpp +template +TIterator max_element(TIterator begin, TIterator end) +``` +**Description** +Finds the greatest element in the range [`begin`, `end`). + +--- + +```cpp +template +TIterator max_element(TIterator begin, TIterator end, TCompare compare) +``` +**Description** +Finds the greatest element in the range [`begin`, `end`) using `compare`. + +## minmax_element +```cpp +template +pair minmax_element(TIterator begin, TIterator end) +``` +**Description** +Finds the smallest and greatest element in the range [`begin`, `end`). + +--- + +```cpp +template +pair minmax_element(TIterator begin, TIterator end, TCompare compare) +``` +**Description** +Finds the smallest and greatest element in the range [`begin`, `end`) using `compare`. + +## multimin +**ETL extension** +C++11 only +Variadic functions to return the minimum value, or iterator to value, from a variable length parameter list. + +```cpp +template +constexpr const T& multimin(const T& t, const Tx&... tx) +``` +**Description** +Returns the minimum of the supplied arguments. + +--- + +```cpp +template +constexpr const T& multimin_compare(TCompare compare, const T& t, const Tx&... tx) +``` +**Description** +Returns the minimum of the supplied arguments. +Uses `compare` to compare values. + +--- + +```cpp +template +constexpr const TIterator& multimin_iter(const TIterator& t, const TIteratorx&... tx) +``` +**Description** +Returns the minimum of the dereferenced supplied arguments. + +--- + +```cpp +template +constexpr const TIterator& multimin_iter_compare(TCompare compare, + const TIterator& t, const TIteratorx&... tx) +``` +**Description** +Returns the minimum of the dereferenced supplied arguments. +Uses `compare` to compare values. + +### Example +```cpp +int minimum; + +minimum = etl::multimin(1, 2, 3, 4, 5, 6, 7, 8)); +minimum = etl::multimin_compare(std::less(), 1, 2, 3, 4, 5, 6, 7, 8)); +minimum = etl::multimin_compare(std::greater(), 1, 2, 3, 4, 5, 6, 7, 8)); + +int i[8] = { 1, 2, 3, 4, 5, 6, 7, 8 }; + +int* p_minimum; + +p_minimum = etl::multimin_iter(&i[0], &i[1], &i[2], &i[3], &i[4], &i[5], &i[6], &i[7])); +p_minimum = etl::multimin_iter_compare(std::less(), + &i[0], &i[1], &i[2], &i[3], &i[4], &i[5], &i[6], &i[7])); +p_minimum = etl::multimin_iter_compare(std::greater(), + &i[0], &i[1], &i[2], &i[3], &i[4], &i[5], &i[6], &i[7])); + +``` + +--- + +## multimax +**ETL extension** +C++11 only +Variadic functions to return the maximum value, or iterator to value, from a variable length parameter list. + +```cpp +template +constexpr const T& multimax(const T& t, const Tx&... tx) +``` +**Description** +Returns the maximum of the supplied arguments. + +--- + +```cpp +template +constexpr const T& multimax_compare(TCompare compare, const T& t, const Tx&... tx) +``` +**Description** +Returns the maximum of the supplied arguments. +Uses `compare` to compare values. + +--- + +```cpp +template +constexpr const TIterator& multimax_iter(const TIterator& t, const TIteratorx&... tx) +``` +**Description** +Returns the maximum of the dereferenced supplied arguments. + +--- + +```cpp +template +constexpr const TIterator& multimax_iter_compare(TCompare compare, + const TIterator& t, + const TIteratorx&... tx) +``` +**Description** +Returns the maximum of the dereferenced supplied arguments. +Uses `compare` to compare values. + +### Example +```cpp +int maximum; + +maximum = etl::multimax(1, 2, 3, 4, 5, 6, 7, 8)); +maximum = etl::multimax_compare(std::less(), 1, 2, 3, 4, 5, 6, 7, 8)); +maximum = etl::multimax_compare(std::greater(), 1, 2, 3, 4, 5, 6, 7, 8)); + +int i[8] = { 1, 2, 3, 4, 5, 6, 7, 8 }; + +int* p_maximum; + +p_maximum = etl::multimax_iter(&i[0], &i[1], &i[2], &i[3], &i[4], &i[5], &i[6], &i[7])); +p_maximum = etl::multimax_iter_compare(std::less(), + &i[0], &i[1], &i[2], &i[3], &i[4], &i[5], &i[6], &i[7])); +p_maximum = etl::multimax_iter_compare(std::greater(), + &i[0], &i[1], &i[2], &i[3], &i[4], &i[5], &i[6], &i[7])); +``` + +## move + +```cpp +template +TIterator2 move(TIterator1 sb, TIterator1 se, TIterator2 db) +``` +**Description** +Moves the elements in the range `sb`, `se` to another range beginning at `db`. + +**constexpr** +This function is constexpr under the following conditions. +- The STL is in use and C++20 is supported. +- The iterator is non-pointer or the type is not trivially copyable and C++14 is supported. +- The iterator is a pointer, the type is trivially copyable, built-in `memcpy` is supported, and C++14 is supported. +- The iterator is a pointer, the type is trivially copyable, `ETL_FORCE_CONSTEXPR_ALGORITHMS` is defined as 1, and C++14 is supported. + +## move_s +**ETL extension** + +```cpp +template +TOutputIterator move_s(TInputIterator i_begin, TInputIterator i_end, + TOutputIterator o_begin, TOutputIterator o_end) +``` +**Description** +A safer four parameter version that will stop moving when either iterator reaches the end of its range. + +**constexpr** +This function is constexpr under the following conditions. +- The STL is in use and C++20 is supported. +- The iterator is non-pointer or the type is not trivially copyable and C++14 is supported. +- The iterator is a pointer, the type is trivially copyable, built-in `memcpy` is supported, and C++14 is supported. +- The iterator is a pointer, the type is trivially copyable, `ETL_FORCE_CONSTEXPR_ALGORITHMS` is defined as `1`, and C++14 is supported. + +## move_backward + +```cpp +template +TIterator2 move_backward(TIterator1 sb, TIterator1 se, TIterator2 de) +``` +**Description** +Moves the elements in the range `sb`, `se` to another range ending at `de`. +The elements are moved in reverse order. + +**constexpr** +This function is constexpr under the following conditions. +- The STL is in use and C++20 is supported. +- The iterator is non-pointer or the type is not trivially copyable and C++14 is supported. +- The iterator is a pointer, the type is trivially copyable, built-in `memcpy` is supported, and C++14 is supported. +- The iterator is a pointer, the type is trivially copyable, `ETL_FORCE_CONSTEXPR_ALGORITHMS` is defined as 1, and C++14 is supported. + +## reverse + +```cpp +template +void reverse(TIterator b, TIterator e) +``` +**Description** +Reverses the order of the elements in the range `b`, `e`. + +## for_each_if +**ETL extension** + +```cpp +template +TUnaryFunction for_each_if(TIterator begin, + const TIterator end, + TUnaryFunction function, + TUnaryPredicate predicate) +``` +**Description** +Applies function to each element if `predicate` returns `true`. + +## for_each_n +**ETL extension** + +```cpp +template +TIterator for_each_n(TIterator begin, + TSize n, + TUnaryFunction function) +``` +**Description** +Applies function to `n` elements, starting from `begin`. + +## for_each_n_if +**ETL extension** + +```cpp +template +TIterator for_each_n_if(TIterator begin, + TSize n, + TUnaryFunction function, + TUnaryPredicate predicate) +``` +**Description** +Combination of `for_each_if` and `for_each_n`. + +## fill + +```cpp +template +void fill(TIterator first, TIterator last, const TValue& value) +``` +**Description** +Assigns the given `value` to the elements in the range `first`, `last`. + +## fill_n + +```cpp +template +TIterator fill_n(TIterator first, TSize count, const TValue& value) +``` +**Description** +Assigns the given `value` to the first `count` elements in the range beginning at `first`. + +## find + +```cpp +template +TIterator find(TIterator first, TIterator last, const T& value) +``` +**Description** +Searches for an element equal to `value`. + +## find_end + +```cpp +template +TIterator1 find_end(TIterator1 b, TIterator1 e, + TIterator2 sb, TIterator2 se) +``` +**Description** +Searches for the last occurrence of the sequence `b`, `e` in the range `sb`, `be`. + +--- + +```cpp +template +TIterator1 find_end(TIterator1 b, TIterator1 e, + TIterator2 sb, TIterator2 se, + TPredicate predicate) +``` +**Description** +Searches for the last occurrence of the sequence `b`, `e` in the range `sb`, `be`, using `predicate`. + +## find_if + +```cpp +template +TIterator find_if(TIterator first, TIterator last, TUnaryPredicate predicate) +``` +**Description** +Searches for the first element that satisfies the `predicate`. + +## find_if_not + +```cpp +template +TIterator find_if_not(TIterator begin, TIterator end, TUnaryPredicate predicate) +``` +**Description** +Searches for the first element that does not satisfy the `predicate`. + +## lower_bound + +```cpp +template +TIterator lower_bound(TIterator first, TIterator last, const TValue& value) +``` +**Description** +Searches for the first element in the range [`first`, `last`) which is **not* ordered before `value`. + +**Return** +An iterator to the element, or `last` if not found. + +--- + +```cpp +template +TIterator lower_bound(TIterator first, TIterator last, const TValue& value, TCompare compare) +``` +**Description** +Searches for the first element in the range [`first`, `last`) which is **not* ordered before `value`. +Uses `compare` to compare elements. + + +**Return** +An iterator to the element, or `last` if not found. + +## upper_bound + +```cpp +template +TIterator upper_bound(TIterator first, TIterator last, const TValue& value) +``` +**Description** +Searches for the first element in the range [`first`, `last`) which is ordered after `value`. + +**Return** +An iterator to the element, or `last` if not found. + +--- + +```cpp +template +TIterator upper_bound(TIterator first, TIterator last, const TValue& value, TCompare compare) +``` +**Description** +Searches for the first element in the range [`first`, `last`) which is ordered after `value`. +Uses `compare` to compare elements. + +**Return** +An iterator to the element, or `last` if not found. + +## equal_range + +```cpp +template +pair equal_range(TIterator first, TIterator last, const TValue& value) +``` +**Description** +Returns a range containing all elements equivalent to `value` in the range [`first`, `last`). + +**Return** +A `pair` containing a pair of iterators. + +`first` is is the result of `lower_bound(first, last)`. +`last` is is the result of `upper_bound(first, last)`. + +--- + +```cpp +template +pair equal_range(TIterator first, TIterator last, + const TValue& value, TCompare compare) +``` +**Description** +Returns a range containing all elements equivalent to `value` in the range [`first`, `last`). +Uses compare to `compare` elements. + + +**Return** +A `pair` containing a pair of iterators. + +`first` is is the result of `lower_bound(first, last)`. +`last` is is the result of `upper_bound(first, last)`. + +## binary_find +**ETL extension** + +```cpp +template +TIterator binary_find(TIterator begin, + TIterator end, + const TValue& value) +``` +**Description** +Finds the first item in a sorted container that matches the `value`. +Returns an iterator to the `value` or `end`. + +--- + +```cpp +template +TIterator binary_find(TIterator begin, + TIterator end, + const TValue& value, + TBinaryPredicate predicate, + TBinaryEquality equality) +``` +**Description** +Finds the first item in a sorted container that matches the value. +Returns an iterator to the `value` or `end`. +Comparison and equality predicates are supplied. + +--- + +## search + +```cpp +template +TIterator1 search(TIterator1 first, TIterator1 last, + TIterator2 search_first, TIterator2 search_last) +``` +**Description** +Searches for the first occurrence of the sequence of elements `first`, `last` in the range `search_first`, `search_last`. + +--- + +```cpp +template +TIterator1 search(TIterator1 first, TIterator1 last, + TIterator2 search_first, TIterator2 search_last, + TCompare compare) +``` +**Description** +Searches for the first occurrence of the sequence of elements `first`, `last` in the range `search_first`, `search_last` +Uses `compare` to check equality of the values. + +## binary_search + +```cpp +template +bool binary_search(TIterator first, TIterator last, const T& value) +``` +**Description** +Checks if an element equivalent to value appears within the range [`first`, `last`). + +```cpp +template +bool binary_search(TIterator first, TIterator last, const T& value, Compare compare) +``` +**Description** +Checks if an element equivalent to value appears within the range [`first`, `last`). +Uses `compare` to check equality of the values. + +## all_of + +```cpp +template +bool all_of(TIterator begin, TIterator end, TUnaryPredicate predicate) +``` +**Description** +Checks if `predicate` returns `true` for all elements in the range [`begin`, `end`). + +## any_of + +```cpp +template +bool any_of(TIterator begin, TIterator end, TUnaryPredicate predicate) +``` +**Description** +Checks if `predicate` returns `true` for at least one element in the range [`begin`, `end`). + +## none_of + +```cpp +template +bool none_of(TIterator begin, TIterator end, TUnaryPredicate predicate) +``` +**Description** +Checks if `predicate` returns `true` for no elements in the range [`begin`, `end`). + +## is_permutation + +```cpp +template +bool is_permutation(TIterator1 begin1, + TIterator1 end1, + TIterator2 begin2) +``` +**Description** +Returns `true` if there exists a permutation of the elements in the range [`begin1`, `end1`) that makes that range equal to the second range. + +--- + +```cpp +template +bool is_permutation(TIterator1 begin1, + TIterator1 end1, + TIterator2 begin2, + TIterator2 end2) +``` +**Description** +Returns `true` if there exists a permutation of the elements in the range [`begin1`, `end1`) that makes that range equal to the second range. + +--- + +```cpp +template +bool is_permutation(TIterator1 begin1, + TIterator1 end1, + TIterator2 begin2, + TBinaryPredicate predicate) +``` +**Description** +Returns `true` if there exists a permutation of the elements in the range [`begin1`, `end1`) that makes that range equal to the second range. +Uses `predicate` to checks elements in the range. + +--- + +```cpp +template +bool is_permutation(TIterator1 begin1, + TIterator1 end1, + TIterator2 begin2, + TIterator2 end2, + TBinaryPredicate predicate) +``` +**Description** +Returns `true` if there exists a permutation of the elements in the range [`begin1`, `end1`) that makes that range equal to the second range. +Uses `predicate` to checks elements in the range. + +## is_partitioned + +```cpp +template +bool is_partitioned(TIterator begin, + TIterator end, + TUnaryPredicate predicate) +``` +**Description** +Returns `true` if all elements in the range [`begin`, `end`) that satisfy the predicate appear before all elements that don't. Also returns `true` if [`begin`, `end`) is empty. + +## partition_point +```cpp +template +TIterator partition_point(TIterator begin, + TIterator end, + TUnaryPredicate predicate) +``` +**Description** +Examines the partitioned range [`begin`, `end`) and locates the end of the first partition according to `predicate`. + +## partition_copy + +```cpp +template +pair partition_copy(TSource begin, + TSource end, + TDestinationTrue destination_true, + TDestinationFalse destination_false, + TUnaryPredicate predicate) +``` +**Description** +Copies the elements from the range [`begin`, `end`) to two different ranges depending on the value returned by the `predicate`. +The elements that satisfy `predicate` are copied to the range beginning at `destination_true`. +The rest of the elements are copied to the range beginning at `destination_false`. + +## partition_transform +**ETL extension** + +### One input range +```cpp +template +pair + partition_transform(TSource begin, + TSource end, + TDestinationTrue destination_true, + TDestinationFalse destination_false, + TUnaryFunctionTrue function_true, + TUnaryFunctionFalse function_false, + TUnaryPredicate predicate) +``` +**Description** +Transforms data from the source to one of two destinations. +If `predicate` returns `true` then the source data if modified by `function_true` and stored in `destination_true`. +If `predicate` returns `false` then the source data if modified by `function_false` and stored in `destination_false`. + +--- + +### Two input ranges +```cpp +template +pair + partition_transform(TSource1 begin1, + TSource1 end1, + TSource2 begin2, + TDestinationTrue destination_true, + TDestinationFalse destination_false, + TBinaryFunctionTrue function_true, + TBinaryFunctionFalse function_false, + TBinaryPredicate predicate) +``` +**Description** +Transforms data from the source to one of two destinations. +If `predicate` returns `true` then the source data if modified by `function_true` and stored in `destination_true`. +If `predicate` returns `false` then the source data if modified by `function_false` and stored in `destination_false`. + +## rotate + +```cpp +template +TIterator rotate(TIterator first, TIterator middle, TIterator last) +``` +**Description** +Performs a left rotation on the range of elements. + +## transform_s +**ETL extension** + +```cpp +template +void transform_s(TIterator i_begin, + TIterator i_end, + TOutputIterator o_begin, + TOutputIterator o_end, + TUnaryFunction function) +``` +**Description** +A safer version that will stop transforming when either iterator reaches the end of its range. + +## transform_n +**ETL extension** + +### One input range +```cpp +template +void transform_n(TInputIterator i_begin, + TSize n, + TOutputIterator o_begin, + TUnaryFunction function) +``` +**Description** +Transform over `n` elements. + +--- + +### Two input ranges +```cpp +template +void transform_n(TInputIterator1 i_begin1, + TInputIterator2 i_begin2, + TSize n, + TOutputIterator o_begin, + TBinaryFunction function) +``` +**Description** +Transform over `n` elements. + +## transform_if +**ETL extension** + +### One input range +```cpp +template +TOutputIterator transform_if(TInputIterator i_begin, + TInputIterator i_end, + TOutputIterator o_begin, + TUnaryFunction function, + TUnaryPredicate predicate) +``` +**Description** +Transforms data from the source based on a predicate. +If `predicate` returns `true` then the source data if modified by function and stored in the output range. +If `predicate` returns `false` then the source data is ignored. + +--- + +### Two input ranges +```cpp +template +TOutputIterator transform_if(TInputIterator1 i_begin1, + TInputIterator1 i_end1, + TInputIterator2 i_begin2, + TOutputIterator o_begin, + TBinaryFunction function, + TBinaryPredicate predicate) +``` +**Description** +Transforms data from the source based on a predicate. +If `predicate` returns `true` then the source data if modified by function and stored in the output range. +If `predicate` returns `false` then the source data is ignored. + +## transform_n_if +**ETL extension** + +### One input range +```cpp +template +TOutputIterator transform_if(TInputIterator i_begin, + TSize n, + TOutputIterator o_begin, + TUnaryFunction function, + TUnaryPredicate predicate) +``` +**Description** +Transforms data from the source based on a predicate for `n` items. +If `predicate` returns `true` then the source data if modified by function and stored in the output range. +If `predicate` returns `false` then the source data is ignored. + +--- + +### Two input ranges +```cpp +template +TOutputIterator transform_if(TInputIterator1 i_begin1, + TSize n, + TInputIterator2 i_begin2, + TOutputIterator o_begin, + TBinaryFunction function, + TBinaryPredicate predicate) +``` +**Description** +Transforms data from the source based on a predicate for `n` items. +If `predicate` returns `true` then the source data if modified by function and stored in the output range. +If `predicate` returns `false` then the source data is ignored. + +## shell_sort +**ETL extension** +https://en.wikipedia.org/wiki/Shellsort + +```cpp +template +void shell_sort(TIterator first, TIterator last) +``` +**Description** +Sorts a range using the shell sort algorithm. + +--- + +```cpp +template +void shell_sort(TIterator first, TIterator last, TCompare compare) +``` +**Description** +Sorts a range using the shell sort algorithm, using `compare`. + +## insertion_sort +**ETL extension** +https://en.wikipedia.org/wiki/Insertion_sort + +```cpp +template +void insertion_sort(TIterator first, TIterator last) +``` +**Description** +Sorts a range using the insertion sort algorithm. + +--- + +```cpp +template +void insertion_sort(TIterator first, TIterator last, TCompare compare) +``` +**Description** +Sorts a range using the insertion sort algorithm. + +## heap_sort +**ETL extension** +https://en.wikipedia.org/wiki/Heapsort + +```cpp +template +void heap_sort(TIterator first, TIterator last) +``` +Sorts a range using the heap sort algorithm. +Since: `16.2.0` + +--- + +```cpp +template +void heap_sort(TIterator first, TIterator last, TCompare compare) +``` +**Description** +Sorts a range using the heap sort algorithm, using `compare`. +Since: `16.2.0` + +## selection_sort +**ETL extension** +https://en.wikipedia.org/wiki/Selectionsort + + +```cpp +template +void selection_sort(TIterator first, TIterator last) +``` +**Description** +Sorts a range using the selection sort algorithm. +Since: `20.7.0` + +--- + +```cpp +template +void selection_sort(TIterator first, TIterator last, TCompare compare) +``` +**Description** +Sorts a range using the selection sort algorithm. +Since: `20.7.0` + +## sort + +```cpp +template +void sort(TIterator first, TIterator last) +``` +**Description** +If `ETL_NO_STL` is defined then uses `etl::shell_sort`, otherwise calls `std::sort`. + +--- + +```cpp +template +void sort(TIterator first, TIterator last, TCompare compare) +``` +**Description** +If `ETL_NO_STL` is defined then uses `etl::shell_sort`, otherwise calls `std::sort`. + +## stable_sort + +```cpp +template +void stable_sort(TIterator first, TIterator last) +``` +**Description** +If `ETL_NO_STL` is defined then uses `etl::insertion_sort`, otherwise calls `std::stable_sort`. + +--- + +```cpp +template +void stable_sort(TIterator first, TIterator last, TCompare compare) +``` +**Description** +If `ETL_NO_STL` is defined then uses `etl::insertion_sort`, otherwise calls `std::stable_sort`. + +## is_sorted + +```cpp +template +bool is_sorted(TIterator begin, TIterator end) +``` +**Description** +Returns true is the range is sorted. + +--- + +```cpp +template +bool is_sorted(TIterator begin, TIterator end, TCompare compare) +``` +**Description** +Returns true is the range is sorted. + +## is_sorted_until + +```cpp +template +TIterator is_sorted_until(TIterator begin, TIterator end) +``` +**Description** +Returns an iterator to the first element that is not sorted + +--- + +```cpp +template +TIterator is_sorted_until(TIterator begin, TIterator end, TCompare compare) +``` +**Description** +Returns an iterator to the first element that is not sorted + +## clamp + +```cpp +template +ETL_CONSTEXPR const T& clamp(const T& value, const T& low, const T& high ) +``` +**Description** +Clamps `value` between two limits. + +--- + +```cpp +template +ETL_CONSTEXPR const T& clamp(const T& value, const T& low, const T& high, TCompare compare) +``` +**Description** +Clamps `value` between two limits, using `compare`. + +## accumulate + +```cpp +template +ETL_CONSTEXPR14 T accumulate(TIterator first, TIterator last, T sum) +``` +Computes the sum of the given `sum` and the elements in the range `first`, `last`. + +```cpp +template +ETL_CONSTEXPR14 T accumulate(TIterator first, TIterator last, T init, TBinaryOperation operation) +``` +Computes the sum of the given `init` and the elements in the range `first`, `last`. +Uses `operation` to compute the final value. + +## remove + +```cpp +template +TIterator remove(TIterator first, TIterator last, const T& value) +``` +**Description** +Removes all elements that are equal to value. + +## remove_if + +```cpp +template +TIterator remove_if(TIterator first, TIterator last, TPredicate predicate) +``` +**Description** +Removes all elements that satisfy `predicate`. diff --git a/docs/utilities/bit_stream_reader.md b/docs/utilities/bit-stream-reader.md similarity index 100% rename from docs/utilities/bit_stream_reader.md rename to docs/utilities/bit-stream-reader.md diff --git a/docs/utilities/byte_stream_reader.md b/docs/utilities/byte-stream-reader.md similarity index 100% rename from docs/utilities/byte_stream_reader.md rename to docs/utilities/byte-stream-reader.md diff --git a/docs/utilities/cyclic_value.md b/docs/utilities/cyclic-value.md similarity index 100% rename from docs/utilities/cyclic_value.md rename to docs/utilities/cyclic-value.md diff --git a/docs/utilities/debug_count.md b/docs/utilities/debug-count.md similarity index 100% rename from docs/utilities/debug_count.md rename to docs/utilities/debug-count.md diff --git a/docs/utilities/enum_type.md b/docs/utilities/enum-type.md similarity index 100% rename from docs/utilities/enum_type.md rename to docs/utilities/enum-type.md diff --git a/docs/utilities/error-handler.md b/docs/utilities/error-handler.md index ea3ab091..ab317500 100644 --- a/docs/utilities/error-handler.md +++ b/docs/utilities/error-handler.md @@ -10,7 +10,7 @@ Finding errors within an embedded system can be difficult due to the performance The library allows the method to be chosen at compile time. -You have a choice of:- +You have a choice of: - Exceptions - Asserts - Error log diff --git a/docs/utilities/ETL Traits.md b/docs/utilities/etl-traits.md similarity index 100% rename from docs/utilities/ETL Traits.md rename to docs/utilities/etl-traits.md diff --git a/docs/raw/utilities/Exception.txt b/docs/utilities/exceptions.md similarity index 64% rename from docs/raw/utilities/Exception.txt rename to docs/utilities/exceptions.md index a0fadac4..b99373a1 100644 --- a/docs/raw/utilities/Exception.txt +++ b/docs/utilities/exceptions.md @@ -1,18 +1,29 @@ -Exception +--- +title: "Exceptions" +--- + The base class for all ETL exceptions. -Typedefs -typedef string_type const char*; -typedef numeric_type int; +## Typedefs +```cpp +string_type = const char*; +numeric_type = int; +``` -Constructor -exception(string_type reason, string_type file_name, numeric_type line_number); +## Constructor +```cpp +exception(string_type reason, string_type file_name, numeric_type line_number) +``` -Access -string_type what() const; +## Access +```cpp +string_type what() const +``` +**Description** Gets the reason for the exception. -Example +## Example +```cpp struct vector_full : public etl::exception { vector_full(string_type file_name, numeric_type line_number) @@ -20,10 +31,10 @@ struct vector_full : public etl::exception { } }; +``` Usually error will be called via the ETL error macro. +```cpp ETL_ERROR(derived_exception_class) - -See error_handler.h - +``` diff --git a/docs/utilities/function_traits.md b/docs/utilities/function-traits.md similarity index 100% rename from docs/utilities/function_traits.md rename to docs/utilities/function-traits.md diff --git a/docs/utilities/initializer_list.md b/docs/utilities/initializer-list.md similarity index 100% rename from docs/utilities/initializer_list.md rename to docs/utilities/initializer-list.md diff --git a/docs/utilities/integral_limits.md b/docs/utilities/integral-limits.md similarity index 100% rename from docs/utilities/integral_limits.md rename to docs/utilities/integral-limits.md diff --git a/docs/utilities/not_null.md b/docs/utilities/not-null.md similarity index 100% rename from docs/utilities/not_null.md rename to docs/utilities/not-null.md diff --git a/docs/utilities/nth_type.md b/docs/utilities/nth-type.md similarity index 100% rename from docs/utilities/nth_type.md rename to docs/utilities/nth-type.md diff --git a/docs/utilities/null_type.md b/docs/utilities/null-type.md similarity index 100% rename from docs/utilities/null_type.md rename to docs/utilities/null-type.md diff --git a/docs/utilities/static_assert.md b/docs/utilities/static-assert.md similarity index 100% rename from docs/utilities/static_assert.md rename to docs/utilities/static-assert.md diff --git a/docs/utilities/type_id.md b/docs/utilities/type-id.md similarity index 100% rename from docs/utilities/type_id.md rename to docs/utilities/type-id.md