From 78be6f298ed6afd4802624a894dc99fde73b6661 Mon Sep 17 00:00:00 2001 From: John Wellbelove Date: Mon, 18 May 2026 11:10:40 +0100 Subject: [PATCH] New documentation files. --- docs/containers/maps/flat-map.md | 498 ++++++++++ docs/containers/queues/queue-spsc-isr.md | 2 +- .../enabling-compiler-built-ins.md | 80 ++ docs/getting-started/generators.md | 12 + docs/raw/Enabling compiler built-ins.txt | 71 -- docs/raw/Generators.txt | 6 - docs/raw/Overview.txt | 52 - docs/raw/utilities/Algorithms.txt | 926 ------------------ docs/raw/utilities/Mutex.txt | 13 - docs/raw/utilities/expected.txt | 297 ------ docs/raw/utilities/functional.txt | 105 -- docs/raw/utilities/result.txt | 81 -- docs/utilities/expected.md | 588 +++++++++++ docs/utilities/functional.md | 219 +++++ .../memory-model.md} | 41 +- docs/utilities/mutex.md | 15 + .../parameter-pack.md} | 66 +- .../parameter-type.md} | 27 +- docs/utilities/result.md | 195 ++++ 19 files changed, 1703 insertions(+), 1591 deletions(-) create mode 100644 docs/containers/maps/flat-map.md create mode 100644 docs/getting-started/enabling-compiler-built-ins.md create mode 100644 docs/getting-started/generators.md delete mode 100644 docs/raw/Enabling compiler built-ins.txt delete mode 100644 docs/raw/Generators.txt delete mode 100644 docs/raw/Overview.txt delete mode 100644 docs/raw/utilities/Algorithms.txt delete mode 100644 docs/raw/utilities/Mutex.txt delete mode 100644 docs/raw/utilities/expected.txt delete mode 100644 docs/raw/utilities/functional.txt delete mode 100644 docs/raw/utilities/result.txt create mode 100644 docs/utilities/expected.md create mode 100644 docs/utilities/functional.md rename docs/{raw/utilities/Memory Model.txt => utilities/memory-model.md} (59%) create mode 100644 docs/utilities/mutex.md rename docs/{raw/utilities/Parameter Pack.txt => utilities/parameter-pack.md} (71%) rename docs/{raw/utilities/parameter_type.txt => utilities/parameter-type.md} (72%) create mode 100644 docs/utilities/result.md diff --git a/docs/containers/maps/flat-map.md b/docs/containers/maps/flat-map.md new file mode 100644 index 00000000..9f2564e9 --- /dev/null +++ b/docs/containers/maps/flat-map.md @@ -0,0 +1,498 @@ +--- +title: "flat_map" +--- + +{{< callout type="info">}} + Header: `flat_map.h` + Similar to: `std::map` +{{< /callout >}} + +A fixed capacity map based on a sorted vector. +The container is an associative lookup table with O(N) insertion and erase, and O(log N) search. +This container is best used for tables that are occasionally updated and spend most of their time being searched. +Uses `etl::less` as the default key comparison method. + +```cpp +etl::flat_map +``` + +Inherits from `etl::iflat_map`. +`etl::iflat_map` may be used as a size independent pointer or reference type for any `etl::flat_map` instance. + +## Template deduction guides +C++17 and above + +```cpp +template +etl::flat_map(TPairs...) +``` + +### Example +```cpp +etl::flat_map data{ etl::pair{0, 1}, etl::pair{2, 3}, etl::pair{4, 5}, etl::pair{6, 7} }; +``` +Defines data as an `flat_map` of `int`/`int` pairs, of length 4, containing the supplied data. + +## make_flat_map +C++11 and above +template , + typename... TPairs> +constexpr auto make_flat_map(TValues&&... values) + +### Example +```cpp +auto data = etl::make_flat_map(etl::pair{0, 1}, etl::pair{2, 3}, + etl::pair{4, 5}, etl::pair{6, 7}); +``` + +## Member types + +```cpp +key_type TKey +mapped_type TMapped +value_type pair + The type is either std::pair (default) or etl::pair (ETL_NO_STL) +size_type std::size_t +difference_type std::ptrdiff_t +reference T& +const_reference const T& +rvalue_reference T&& +pointer T* +const_pointer const T* +iterator Random access iterator +const_iterator Constant random access iterator +reverse_iterator reverse_iterator +const_reverse_iterator reverse_iterator +``` + +## Static Constants + +`MAX_SIZE` The maximum size of the flat map. + +## Constructors + +```cpp +etl::flat_map() +``` +**Description** +Default constructor. + +--- + +```cpp +etl::flat_map(const flat_map& other) +``` +**Description** +Copy constructor. + +--- + +```cpp +etl::flat_map(flat_map&& other) +``` +**Description** +Move constructor. + +--- + +```cpp +template +etl::flat_map(TIterator begin, TIterator end); +``` +**Description** +Construct from the range [`begin`, `end`). + +## Element access + +```cpp +TMapped& at(key_parameter_t key) +const TMapped& at(key_parameter_t key) const +``` +**Description** +Returns a reference or const reference to the indexed element. +Emits an `etl::flat_map_out_of_range` if the key is not in the table. +If asserts or exceptions are not enabled then undefined behaviour occurs. + +--- + +```cpp +TMapped& operator[](key_parameter_t key) +const TMapped& operator[](key_parameter_t key) const +``` +**Description** +Returns a reference or const reference to the indexed element. +If the key is not in the table then a new entry is created. + +## Iterators + +```cpp +iterator begin() +const_iterator begin() const +const_iterator cbegin() const +``` +**Description** +Returns an iterator to the beginning of the map. + +--- + +```cpp +iterator end() +const_iterator end() const +const_iterator cend() const +``` +**Description** +Returns an iterator to the end of the map. + +--- + +```cpp +iterator rbegin() +const_iterator rbegin() const +const_iterator crbegin() const +``` +**Description** +Returns a reverse iterator to the beginning of the map. + +--- + +```cpp +iterator rend() +const_iterator rend() const +const_iterator crend() const +``` +**Description** +Returns a reverse iterator to the end of the map. + +## Capacity + +```cpp +bool empty() const +``` +**Description** +Returns `true` if the size of the map is zero, otherwise `false`. + +--- + +```cpp +bool full() const +``` +**Description** +Returns `true` if the size of the lookup is `SIZE`, otherwise `false`. + +--- + +```cpp +size_t size() const +``` +**Description** +Returns the size of the lookup. + +--- + +```cpp +size_t max_size() const +``` +**Description** +Returns the maximum possible size of the map. + +--- + +```cpp +size_t available() const +``` +**Description** +Returns the remaining available capacity in the map. + +## Modifiers + +```cpp +flat_map& operator = (const flat_map& rhs) +flat_map& operator = (flat_map&& rhs) +``` +**Description** +Copies or moves the data from another flat map. + +--- + +```cpp +pair insert(const value_type& value) +pair insert(value_type&& value) +iterator insert(iterator position, const value_type& value) +iterator insert(iterator position, value_type&& value) +``` +**Description** +Inserts a value into the map. + +```cpp +template +void insert(TIterator first, TIterator last) +``` +**Description** +Inserts values in to the map. +If the map is full then emits an `etl::flat_map_full`. If asserts or exceptions are not enabled then undefined behaviour occurs. +The return type is either `std::pair` (default) or `etl::pair` (`ETL_NO_STL`) + +--- + +```cpp +pair emplace((const value_type& value)) +pair emplace(const key_type& key, const mapped_type& value) +``` +**Description** +Inserts key/value pairs into the map by constructing directly into storage. +The return type is either `std::pair` (default) or `etl::pair` (`ETL_NO_STL`) + +--- + +**C++03** +The emplace functions differ from that of std::map in that, due to C++03 not supporting 'perfect forwarding', the values for constructing mapped types must be listed as parameters and not nested in a 'mapped' value parameter. +The return type is either `std::pair` (default) or `etl::pair` (`ETL_NO_STL`) + +```cpp +template +pair emplace(const key_type& key, const T1& value1) +``` +**Description** +Emplaces a value consructed from `key` and 1 argument into the map. + +```cpp +template +pair emplace(const key_type& key, const T1& value1, const T2& value2) +``` +**Description** +Emplaces a value constructed from `key` and 2 arguments into the map. + +```cpp +template +pair emplace(const key_type& key, const T1& value1, const T2& value2, const T3& value3) +``` +**Description** +Emplaces a value constructed from `key` and 3 arguments into the map. + +```cpp +template +pair emplace(const key_type& key, const T1& value1, const T2& value2, const T3& value3, const T4& value4) +``` +**Description** +Emplaces a value constructed from `key` and 4 arguments into the map. + +**C++11** +```cpp +template +pair emplace(const key_type& key, Args&& ... args) +``` +**Description** +Emplaces a value constructed from the `key` and arguments into the map. + +--- + +```cpp +size_t erase(key_value_parameter_t key) +void erase(iterator i_element) +void erase(iterator first, iterator last) +``` +**Description** +Erase elements from the map. + +--- + +```cpp +iterator erase(const_iterator i_element) +iterator erase(const_iteratorfirst, const_iteratorlast) +``` +**Description** +Erase elements from the map. +Since: `20.20.0` + +--- + +```cpp +template +size_t erase(K&& key) +``` +**Description** +Erases values in the map. +Returns an iterator to the next element in the map. +Iterator parameters are not checked for validity. +Since: `20.21.0` + +--- + +```cpp +void clear(); +``` +**Description** +Clears the map to a size of zero. + +## Search + +```cpp +iterator find(key_value_parameter_t key) +const_iterator find(key_value_parameter_t key) const +``` +**Description** +Searches for an element with the key `key`. +Returns an iterator to the element, or `end()` if not found. + +```cpp +iterator lower_bound(key_value_parameter_t key) +const_iterator lower_bound(key_value_parameter_t key) const +``` +**Description** +Searches for an element with the key not less than `key`. +Returns an iterator to the element, or `end()` if not found. + +```cpp +iterator upper_bound(key_value_parameter_t key) +const_iterator upper_bound(key_value_parameter_t key) const +``` +**Description** +Searches for an element with the key greater than `key`. +Returns an iterator to the element, or `end()` if not found. + +```cpp +pair equal_range(key_value_parameter_t key) +pair equal_range(key_value_parameter_t key) const +``` +**Description** +Returns the range of elements with a key equal to `key`. +The return type is either `std::pair` (default) or `etl::pair` (`ETL_NO_STL`) + +--- + +**For comparators that define is_transparent.** + +```cpp +template +iterator find(const K& key) +``` +**Description** +Searches for an element with the key `key`. +Returns an iterator to the element, or `end()` if not found. +Since: `20.21.0` +Since: C++11 + +```cpp +template +const_iterator find(const K& key) const +``` +**Description** +Searches for an element with the key `key`. +Returns an iterator to the element, or `end()` if not found. +Since: `20.21.0` +Since: C++11 + +--- + +```cpp +template +iterator lower_bound(const K& key) +``` +**Description** +Searches for an element with the key not less than `key`. +Returns an iterator to the element, or `end()` if not found. +Since: `20.21.0` +Since: C++11 + +```cpp +template +const_iterator lower_bound(const K& key) const +``` +**Description** +Searches for an element with the key not less than `key`. +Returns an iterator to the element, or `end()` if not found. +Since: `20.21.0` +Since: C++11 + +--- + +```cpp +template +iterator upper_bound(const K& key) +``` +**Description** +Searches for an element with the key greater than `key`. +Returns an iterator to the element, or `end()` if not found. +Since: `20.21.0` +Since: C++11 + +```cpp +template +const_iterator upper_bound(const K& key) const +``` +**Description** +Searches for an element with the key greater than `key`. +Returns an iterator to the element, or `end()` if not found. +Since: `20.21.0` +Since: C++11 + +--- + +20.21.0 +C++11 or above +```cpp +template +pair equal_range(const K& key) +``` +**Description** +Returns the range of elements with a key equal to `key`. +The return type is either `std::pair` (default) or `etl::pair` (`ETL_NO_STL`) +Since: `20.21.0` +Since: C++11 + +```cpp +template +pair equal_range(const K& key) const +``` +**Description** +Returns the range of elements with a key equal to `key`. +The return type is either `std::pair` (default) or `etl::pair` (`ETL_NO_STL`) +Since: `20.21.0` +Since: C++11 + +--- + +```cpp +bool contains(key_value_parameter_t key) const +``` +Check if the container contains the key. +Since: `20.21.0` + + +--- + +```cpp +template +bool contains(const K& k) const +``` +Check if the container contains the key. +For comparators that define `is_transparent`. +Since: `20.21.0` +Since: C++11 + +## Non-member functions + +**Lexicographically comparisons** + +```cpp +operator == +``` +`true` if the contents of the maps are equal, otherwise `false`. + +--- + +```cpp +operator != +``` +`true` if the contents of the maps are not equal, otherwise `false`. + +## Technical stuff + +Flat maps are usually implemented internally as a sorted vector of key/value pairs. Whilst this makes searching fast, it can have a detrimental effect when items are inserted into a container that stores complex, non-trivial keys or values. +As inserting requires that all of the items to the right of the insert position must be shifted this can become an expensive operation for larger containers. + +To improve insertion performance ETL flat maps are implemented as vectors of pointers to key/value pairs, sorted by key value. An insertion will involve a copy of a range of pointers; an operation that can be very fast. + +The downside is that access to an item via an iterator will involve one indirection and the overhead of the container will be one pointer per item. A normal flat map implementation does not have this overhead. diff --git a/docs/containers/queues/queue-spsc-isr.md b/docs/containers/queues/queue-spsc-isr.md index 9ce4f212..bc0326cc 100644 --- a/docs/containers/queues/queue-spsc-isr.md +++ b/docs/containers/queues/queue-spsc-isr.md @@ -8,7 +8,7 @@ title: "queue_spsc_isr" {{< callout type="warning">}} **This class is deprecated.** -`Use queue_spsc_locked` as a replacement. +Use `queue_spsc_locked` as a replacement. {{< /callout >}} **This class is deprecated. diff --git a/docs/getting-started/enabling-compiler-built-ins.md b/docs/getting-started/enabling-compiler-built-ins.md new file mode 100644 index 00000000..93050ffd --- /dev/null +++ b/docs/getting-started/enabling-compiler-built-ins.md @@ -0,0 +1,80 @@ +--- +title: "Enabling compiler built-ins" +weight: 7 +--- + +Since: `20.24.0` + +Many of the features or options in the ETL can be enhanced by the use of compiler built-ins. +If built-ins are available and the STL is not used, then many copy type algorithms may be declared as `constexpr`. +Also, some type traits can detect types more correctly. + +## Controlling Macros +If any of these are set to `1`, then the ETL will use the compiler built-ins, were applicable. +Setting them to `0` will disable the use of the built-in. +Setting any of these in the project or `etl_profile.h` will override any later tests. + +```cpp +ETL_USE_BUILTIN_MEMCPY +ETL_USE_BUILTIN_MEMCMP +ETL_USE_BUILTIN_MEMMOVE +ETL_USE_BUILTIN_MEMSET +``` + +```cpp +ETL_USE_BUILTIN_IS_ASSIGNABLE +ETL_USE_BUILTIN_IS_CONSTRUCTIBLE +ETL_USE_BUILTIN_IS_TRIVIALLY_CONSTRUCTIBLE +ETL_USE_BUILTIN_IS_TRIVIALLY_DESTRUCTIBLE +ETL_USE_BUILTIN_IS_TRIVIALLY_COPYABLE +``` + +## Defining macros +The use of built-ins can be controlled by macros. + +If `ETL_USING_MEM_BUILTINS` is defined and the corresponding macro has not already been set, then following will be set to `1`. +```cpp +ETL_USE_BUILTIN_MEMCPY +ETL_USE_BUILTIN_MEMCMP +ETL_USE_BUILTIN_MEMMOVE +ETL_USE_BUILTIN_MEMSET +``` + +If `ETL_USING_TYPE_TRAITS_BUILTINS` is defined and the corresponding macro has not already been set, then following will be set to `1`. +```cpp +ETL_USE_BUILTIN_IS_ASSIGNABLE +ETL_USE_BUILTIN_IS_CONSTRUCTIBLE +ETL_USE_BUILTIN_IS_TRIVIALLY_CONSTRUCTIBLE +ETL_USE_BUILTIN_IS_TRIVIALLY_DESTRUCTIBLE +ETL_USE_BUILTIN_IS_TRIVIALLY_COPYABLE +``` + +## Detection of built-ins +These tests occur after the above macro tests. +The ETL will attempt to check the availability of compiler built-ins. + +If `__has_builtin` exists, then the existence of the following built-ins are checked. +If not already defined, the corresponding macro is set according to the result. + +--- + +Sets `ETL_USE_BUILTIN_MEMCPY = 1` if `__builtin_memcmp` exists, otherwise `0`. + +Sets `ETL_USE_BUILTIN_MEMCPY = 1` if `__builtin_memcpy exists`, otherwise `0`. + +Sets `ETL_USE_BUILTIN_MEMMOVE = 1` if `__builtin_memmove` exists, otherwise `0`. + +Sets `ETL_USE_BUILTIN_MEMSET = 1` if `__builtin_memset` exists, otherwise `0`. + +Sets `ETL_USE_BUILTIN_IS_ASSIGNABLE = 1` if `__is_assignable exists`, otherwise `0`. + +Sets `ETL_USE_BUILTIN_IS_CONSTRUCTIBLE = 1` if `__is_constructible` exists, otherwise `0`. + +Sets `ETL_USE_BUILTIN_IS_TRIVIALLY_CONSTRUCTIBLE = 1` if `__has_trivial_constructor` or `__is_trivially_constructible` exists, otherwise `0`. + +Sets `ETL_USE_BUILTIN_IS_TRIVIALLY_DESTRUCTIBLE = 1` if `__has_trivial_destructor` or `__is_trivially_destructible exists`, otherwise `0`. + +Sets `ETL_USE_BUILTIN_IS_TRIVIALLY_COPYABLE = 1` if `__has_trivial_copy` or `__is_trivially_copyable` exists, otherwise `0`. + +## Default +Finally, any macro that has so far not been defined will be defined as `0`. diff --git a/docs/getting-started/generators.md b/docs/getting-started/generators.md new file mode 100644 index 00000000..dff66f58 --- /dev/null +++ b/docs/getting-started/generators.md @@ -0,0 +1,12 @@ +--- +title: "Generators" +weight: 8 +--- + +Several of the framework classes have 'generators'. + +Some template classes in the ETL have specialisations to handle a variable numbers of template parameters. It is not possible to know beforehand what the maximum size will be required for any particular project, so the ETL supplies definitions with what seems to be a reasonable default size. + +For many of the classes this is set to 16. To enable the use of the library in projects that require a higher capacity, generators have been created to automatically create the source code for supporting N variants. + +See Generators Tutorial for more information. diff --git a/docs/raw/Enabling compiler built-ins.txt b/docs/raw/Enabling compiler built-ins.txt deleted file mode 100644 index ca2dfea2..00000000 --- a/docs/raw/Enabling compiler built-ins.txt +++ /dev/null @@ -1,71 +0,0 @@ -Enabling compiler built-ins -20.24.0 - -Many of the features or options in the ETL can be enhanced by the use of compiler built-ins. -If built-ins are available and the STL is not used, then many copy type algorithms may be declared as constexpr. -Also, some type traits can detect types more correctly. -____________________________________________________________________________________________________ -Controlling Macros -If any of these are set to 1, then the ETL will use the compiler built-ins, were applicable. -Setting them to 0 will disable the use of the built-in. -Setting any of these in the project or etl_profile.h will override any later tests. - -ETL_USE_BUILTIN_MEMCPY -ETL_USE_BUILTIN_MEMCMP -ETL_USE_BUILTIN_MEMMOVE -ETL_USE_BUILTIN_MEMSET - -ETL_USE_BUILTIN_IS_ASSIGNABLE -ETL_USE_BUILTIN_IS_CONSTRUCTIBLE -ETL_USE_BUILTIN_IS_TRIVIALLY_CONSTRUCTIBLE -ETL_USE_BUILTIN_IS_TRIVIALLY_DESTRUCTIBLE -ETL_USE_BUILTIN_IS_TRIVIALLY_COPYABLE -____________________________________________________________________________________________________ -Defining macros -The use of built-ins can be controlled by macros. - -If ETL_USING_MEM_BUILTINS is defined and the corresponding macro has not already been set, then following -will be set to 1. -ETL_USE_BUILTIN_MEMCPY -ETL_USE_BUILTIN_MEMCMP -ETL_USE_BUILTIN_MEMMOVE -ETL_USE_BUILTIN_MEMSET - -If ETL_USING_TYPE_TRAITS_BUILTINS is defined and the corresponding macro has not already been set, then following -will be set to 1. -ETL_USE_BUILTIN_IS_ASSIGNABLE -ETL_USE_BUILTIN_IS_CONSTRUCTIBLE -ETL_USE_BUILTIN_IS_TRIVIALLY_CONSTRUCTIBLE -ETL_USE_BUILTIN_IS_TRIVIALLY_DESTRUCTIBLE -ETL_USE_BUILTIN_IS_TRIVIALLY_COPYABLE -____________________________________________________________________________________________________ -Detection of built-ins -These tests occur after the above macro tests. -The ETL will attempt to check the availability of compiler built-ins. - -If __has_builtin exists, then the existence of the following built-ins are checked. -If not already defined, the corresponding macro is set according to the result. -____________________________________________________________________________________________________ -Sets ETL_USE_BUILTIN_MEMCPY = 1 if __builtin_memcmp exists, otherwise 0. - -Sets ETL_USE_BUILTIN_MEMCPY = 1 if __builtin_memcpy exists, otherwise 0. - -Sets ETL_USE_BUILTIN_MEMMOVE = 1 if __builtin_memmove exists, otherwise 0. - -Sets ETL_USE_BUILTIN_MEMSET = 1 if __builtin_memset exists, otherwise 0. - -Sets ETL_USE_BUILTIN_IS_ASSIGNABLE = 1 if __is_assignable exists, otherwise 0. - -Sets ETL_USE_BUILTIN_IS_CONSTRUCTIBLE = 1 if __is_constructible exists, otherwise 0. - -Sets ETL_USE_BUILTIN_IS_TRIVIALLY_CONSTRUCTIBLE = 1 if __has_trivial_constructor or __is_trivially_constructible exists, otherwise 0. - -Sets ETL_USE_BUILTIN_IS_TRIVIALLY_DESTRUCTIBLE = 1 if __has_trivial_destructor -or __is_trivially_destructible exists, otherwise 0. - -Sets ETL_USE_BUILTIN_IS_TRIVIALLY_COPYABLE = 1 if __has_trivial_copy -or __is_trivially_copyable exists, otherwise 0. -____________________________________________________________________________________________________ -Default -Finally, any macro that has so far not been defined will be defined as 0. - diff --git a/docs/raw/Generators.txt b/docs/raw/Generators.txt deleted file mode 100644 index 6a9ec697..00000000 --- a/docs/raw/Generators.txt +++ /dev/null @@ -1,6 +0,0 @@ -Generators -Several of the framework classes have 'generators'. -Some template classes in the ETL have specialisations to handle a variable numbers of template parameters. It is not possible to know beforehand what the maximum size will be required for any particular project, so the ETL supplies definitions with what seems to be a reasonable default size. For many of the classes this is set to 16. To enable the use of the library in projects that require a higher capacity, generators have been created to automatically create the source code for supporting N variants. - -See Generators Tutorial for more information. - diff --git a/docs/raw/Overview.txt b/docs/raw/Overview.txt deleted file mode 100644 index 65824294..00000000 --- a/docs/raw/Overview.txt +++ /dev/null @@ -1,52 +0,0 @@ -Overview -The contents of template class library can be classified in to one of five areas. - -Containers -A set of containers that have their capacity fixed at compile time. The APIs are designed to match those in the STL as closely as possible whilst also including extensions applicable to their fixed size nature. Some are equivalents of STL containers; others have no standard equivalent. Due to the underlying storage architecture the containers are extremely cache friendly. - -Patterns -A set of templates that supply the basic framework for implementing popular design patterns. Template techniques are used to ensure that implementation mistakes are usually caught at compile time. - -Maths -A set of mathematical templates; both compile time constants and algorithms such as hash codes and CRCs. - -Utilities -A catch-all for all other template classes. Some of these are reverse engineered from the C++ 11 standard; others being generally useful utilities. - -Frameworks -A set of templates that present the framework code for functionality such as state machines, message routers etc. - -Generators -Some files in the library are created from a 'generator' header using Python and COG. This is to accommodate handling of unknown numbers of types. The default number is often set at 16. If you wish to handle more types than this then the generator scripts must be rerun with the updated sizes. -See Generators for more information on how this is done. - -Error handling -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. See error_handler - -Macros -Optional features in the ETL are controlled by project wide macro definitions. -See Macros - -Unit tests -The library is supplied with a full set of unit tests, with project files for Visual Studio 2017 and Code::Blocks with GCC (Windows & Linux configurations are included). There are currently over 3300 tests. - -The library is also automatically built online using AppVeyor. - -There are also Keil, MDK5 and IAR projects. These are not unit tests; they are merely there to test that the code compiles without errors under these compilers. - -There are examples for Arduino provided. - -Why use ETL containers? -You may be thinking "Why should I use ETL containers over what the STL or Boost has to offer?". - -STL -By default STL containers allocate their storage from the heap. This can often be a issue for embedded projects with limited RAM. Alternatively, the STL containers allow an allocator class to be provided as a template parameter. These will be used in place of the standard heap based allocators. There are a couple of issues with this technique that make it awkward to implement and use. - -The easiest way to implement a fixed allocation custom allocator is to have the it contain the fixed storage. I have found issues with this technique in the past. One is that allocators should be normally be equivalent (one instance of an allocator should be able to release the memory allocated by another) and should not have state. To implement fixed capacity allocators in this way makes the use of fixed capacity containers very awkward. - -Boost -The Boost library is an amazing collection of very useful and innovative classes, but its usefulness for embedded work is debatable. Many classes in Boost will use heap memory 'under the hood'. - -ETL -The ETL containers have a fixed maximum size. This allows the memory requirements for the application to be known at compile time. Also, as the storage for ETL containers is contiguous, there is no possibility of memory fragmentation. This ensures deterministic performance for all containers. - diff --git a/docs/raw/utilities/Algorithms.txt b/docs/raw/utilities/Algorithms.txt deleted file mode 100644 index a1510427..00000000 --- a/docs/raw/utilities/Algorithms.txt +++ /dev/null @@ -1,926 +0,0 @@ -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. - -Constexpr -Some algorithms will be constexpr, dependent on the compiler support and ETL setup. - -____________________________________________________________________________________________________ -swap -Only defined if ETL_NO_STL is defined. - -template -void swap(T& a, T& b) ETL_NOEXCEPT -Swaps two values -____________________________________________________________________________________________________ -template -void swap(T(&a)[N], T(&b)[N]) ETL_NOEXCEPT -Swaps two arrays -https://en.cppreference.com/w/cpp/algorithm/swap -____________________________________________________________________________________________________ -iter_swap -template -void iter_swap(TIterator1 a, TIterator2 b) -Swaps the elements pointed to by two iterators -https://en.cppreference.com/w/cpp/algorithm/iter_swap -____________________________________________________________________________________________________ -swap_ranges -template -TIterator2 swap_ranges(T1terator1 first1, - T1terator1 last1, - TIterator2 first2) -Swaps two ranges of elements -https://en.cppreference.com/w/cpp/algorithm/swap_ranges -____________________________________________________________________________________________________ -copy -template -TOutputIterator copy(TInputIterator sb, TInputIterator se, TOutputIterator db) -Copies the elements in the range, defined by sb, se, to another range beginning at db -https://en.cppreference.com/w/cpp/algorithm/copy - -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 supports, 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 -template -TOutputIterator copy_s(TInputIterator i_begin, TInputIterator i_end, - TOutputIterator o_begin, TOutputIterator o_end) -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 supports, 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 -template -TOutputIterator copy_n(TInputIterator begin, TSize n, TOutputIterator result) -Copies exactly n values from the range beginning at begin to the range beginning at result. -https://en.cppreference.com/w/cpp/algorithm/copy_n - -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 supports, 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 -template -TOutputIterator copy_n_s(TInputIterator i_begin, - TSize n, - TOutputIterator o_begin, TOutputIterator o_end) -A safer version that will stop copying when either n items have been copied or the output iterator reaches the end of its range. -____________________________________________________________________________________________________ -template -TOutputIterator copy_n_s(TIterator i_begin, - TSize1 n1, - TOutputIterator o_begin, - TSize1 n2,) -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 supports, 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 -template -ETL_CONSTEXPR14 -TOutputIterator copy_if(TIterator begin, TIterator end, TOutputIterator out, TUnaryPredicate predicate) -Only copies the elements for which the predicate predicate returns true - -https://en.cppreference.com/w/cpp/algorithm/copy -____________________________________________________________________________________________________ -copy_if_s -ETL extension -template -ETL_CONSTEXPR14 -TOutputIterator copy_if_s(TIterator i_begin, TIterator i_end, - TOutputIterator o_begin, TOutputIterator o_end, - TUnaryPredicate predicate) -A safer version that will stop copying when either iterator reaches the end of its range -____________________________________________________________________________________________________ -copy_n_if -ETL extension -template -ETL_CONSTEXPR14 -TOutputIterator copy_n_if(TIterator begin, TSize n, TOutputIterator out, TUnaryPredicate predicate) -A combination of copy_if and copy_n -____________________________________________________________________________________________________ -reverse_copy -template -TIterator2 reverse_copy(TIterator1 sb, TIterator1 se, TIterator2 db) -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. -https://en.cppreference.com/w/cpp/algorithm/reverse_copy - -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 -template -TIterator2 copy_backward(TIterator1 sb, TIterator1 se, TIterator2 de) -Copies the elements from the range, defined by sb, se to another range ending at db -The elements are copied in reverse order. -https://en.cppreference.com/w/cpp/algorithm/copy_backward - -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 -template -typename iterator_traits::difference_type count(TIterator first, - TIterator last, - const T& value) -Counts the elements that are equal to value -https://en.cppreference.com/w/cpp/algorithm/count -____________________________________________________________________________________________________ -count_if -template -typename iterator_traits::difference_type count_if(TIterator first, - TIterator last, - TUnaryPredicate predicate) -Counts the elements where predicate returns true -https://en.cppreference.com/w/cpp/algorithm/count -____________________________________________________________________________________________________ -equal -template -bool equal(TIterator1 first1, TIterator1 last1, TIterator2 first2) -Returns true if the range first1, last1 is equal to the range first2, first2 + distance(first1, last1) -https://en.cppreference.com/w/cpp/algorithm/equal -____________________________________________________________________________________________________ -lexicographical_compare -template -bool lexicographical_compare(TIterator1 first1, TIterator1 last1, - TIterator2 first2, TIterator2 last2) -Checks if the range first1, last1 is lexicographically less than the range first2, last2, using the 'less-than' operator -____________________________________________________________________________________________________ -template -bool lexicographical_compare(TIterator1 first1, TIterator1 last1, - TIterator2 first2, TIterator2 last2, - TCompare compare) -Checks if the range first1, last1 is lexicographically less than the range first2, last2, using compare -https://en.cppreference.com/w/cpp/algorithm/lexicographical_compare -____________________________________________________________________________________________________ -heap -Heap control functions - -Make Heap -template -void make_heap(TIterator first, TIterator last) - -template -void make_heap(TIterator first, TIterator last, TCompare compare) - -https://en.cppreference.com/w/cpp/algorithm/make_heap -____________________________________________________________________________________________________ -Is Heap -template -bool is_heap(TIterator first, TIterator last) - -template -bool is_heap(TIterator first, TIterator last, TCompare compare) - -https://en.cppreference.com/w/cpp/algorithm/is_heap -____________________________________________________________________________________________________ -Pop Heap -template -void pop_heap(TIterator first, TIterator last) - -template -void pop_heap(TIterator first, TIterator last, TCompare compare) - -https://en.cppreference.com/w/cpp/algorithm/pop_heap -____________________________________________________________________________________________________ -Push Heap -template -void push_heap(TIterator first, TIterator last) - -template -void push_heap(TIterator first, TIterator last, TCompare compare) - -https://en.cppreference.com/w/cpp/algorithm/push_heap -____________________________________________________________________________________________________ -min -template -ETL_CONSTEXPR const T& min(const T& a, const T& b) -Returns the minimum of the two values -____________________________________________________________________________________________________ -template -ETL_CONSTEXPR const T& min(const T& a, const T& b, TCompare compare) -Returns the value where compare returns true if a is less than b - -https://en.cppreference.com/w/cpp/algorithm/min -____________________________________________________________________________________________________ -max -template -ETL_CONSTEXPR const T& max(const T& a, const T& b) -Returns the maximum of the two values -____________________________________________________________________________________________________ -template -ETL_CONSTEXPR const T& max(const T& a, const T& b, TCompare compare) -Returns the value where compare returns true if a is less than b - -https://en.cppreference.com/w/cpp/algorithm/max -____________________________________________________________________________________________________ -minmax -template -pair minmax(const T& a, const T& b) -Returns the lesser and greater values -____________________________________________________________________________________________________ -template -pair minmax(const T& a, const T& b, TCompare compare) -Returns the lesser and greater values using compare - -https://en.cppreference.com/w/cpp/algorithm/minmax -____________________________________________________________________________________________________ -min_element -template -TIterator min_element(TIterator begin, TIterator end) -Finds the smallest element in the range begin, end -____________________________________________________________________________________________________ -template -TIterator min_element(TIterator begin, TIterator end, TCompare compare) -Finds the smallest element in the range begin, end using compare - -https://en.cppreference.com/w/cpp/algorithm/min_element -____________________________________________________________________________________________________ -max_element -template -TIterator max_element(TIterator begin, TIterator end) -Finds the greatest element in the range begin, end -____________________________________________________________________________________________________ -template -TIterator max_element(TIterator begin, TIterator end, TCompare compare) -Finds the greatest element in the range begin, end using compare - -https://en.cppreference.com/w/cpp/algorithm/max_element -____________________________________________________________________________________________________ -minmax_element -template -pair minmax_element(TIterator begin, TIterator end) -Finds the smallest and greatest element in the range begin, end -____________________________________________________________________________________________________ -template -pair minmax_element(TIterator begin, TIterator end, TCompare compare) -Finds the smallest and greatest element in the range begin, end using compare - -https://en.cppreference.com/w/cpp/algorithm/minmax_element -____________________________________________________________________________________________________ -multimin -multimin_compare -multimin_iter -multimin_iter_compare -ETL extension -C++11 only -Variadic functions to return the minimum value, or iterator to value, from a variable length parameter list. - -template -constexpr const T& multimin(const T& t, const Tx&... tx) -____________________________________________________________________________________________________ -template -constexpr const T& multimin_compare(TCompare compare, const T& t, const Tx&... tx) -____________________________________________________________________________________________________ -template -constexpr const TIterator& multimin_iter(const TIterator& t, const TIteratorx&... tx) -____________________________________________________________________________________________________ -template -constexpr const TIterator& multimin_iter_compare(TCompare compare, - const TIterator& t, const TIteratorx&... tx) -____________________________________________________________________________________________________ -Example -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 -multimax_compare -multimax_iter -multimax_iter_compare -ETL extension - -C++11 only variadic functions to return the maximum value, or iterator to value, from a variable length parameter list. - -template -constexpr const T& multimax(const T& t, const Tx&... tx) -____________________________________________________________________________________________________ -template -constexpr const T& multimax_compare(TCompare compare, const T& t, const Tx&... tx) -____________________________________________________________________________________________________ -template -constexpr const TIterator& multimax_iter(const TIterator& t, const TIteratorx&... tx) -____________________________________________________________________________________________________ -template -constexpr const TIterator& multimax_iter_compare(TCompare compare, - const TIterator& t, - const TIteratorx&... tx) -____________________________________________________________________________________________________ -Example -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 -template -TIterator2 move(TIterator1 sb, TIterator1 se, TIterator2 db) -Moves the elements in the range sb, se to another range beginning at db - -https://en.cppreference.com/w/cpp/algorithm/move - -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 supports, 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 -template -TOutputIterator move_s(TInputIterator i_begin, TInputIterator i_end, - TOutputIterator o_begin, TOutputIterator o_end) -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 supports, 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 -template -TIterator2 move_backward(TIterator1 sb, TIterator1 se, TIterator2 de) -Moves the elements in the range sb, se to another range ending at de -The elements are moved in reverse order - -https://en.cppreference.com/w/cpp/algorithm/move_backward - -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 supports, 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 -template -void reverse(TIterator b, TIterator e) -Reverses the order of the elements in the range b, e - -https://en.cppreference.com/w/cpp/algorithm/reverse -____________________________________________________________________________________________________ -for_each_if -ETL extension -template -TUnaryFunction for_each_if(TIterator begin, - const TIterator end, - TUnaryFunction function, - TUnaryPredicate predicate) -Applies function to each element if predicate returns true -____________________________________________________________________________________________________ -for_each_n -ETL extension -template -TIterator for_each_n(TIterator begin, - TSize n, - TUnaryFunction function) -Applies function to n elements, starting from begin -____________________________________________________________________________________________________ -for_each_n_if -ETL extension -template -TIterator for_each_n_if(TIterator begin, - TSize n, - TUnaryFunction function, - TUnaryPredicate predicate) -Combination of for_each_if and for_each_n -____________________________________________________________________________________________________ -fill -template -void fill(TIterator first, TIterator last, const TValue& value) -Assigns the given value to the elements in the range first, last - -https://en.cppreference.com/w/cpp/algorithm/fill -____________________________________________________________________________________________________ -fill_n -template -TIterator fill_n(TIterator first, TSize count, const TValue& value) -Assigns the given value to the first count elements in the range beginning at first - -https://en.cppreference.com/w/cpp/algorithm/fill_n -____________________________________________________________________________________________________ -find -template -TIterator find(TIterator first, TIterator last, const T& value) -Searches for an element equal to value - -https://en.cppreference.com/w/cpp/algorithm/find -____________________________________________________________________________________________________ -find_end -Searches for the last occurrence of the sequence b, e in the range sb, be - -template -TIterator1 find_end(TIterator1 b, TIterator1 e, - TIterator2 sb, TIterator2 se) -____________________________________________________________________________________________________ -template -TIterator1 find_end(TIterator1 b, TIterator1 e, - TIterator2 sb, TIterator2 se, - TPredicate predicate) - -https://en.cppreference.com/w/cpp/algorithm/find_end -____________________________________________________________________________________________________ -find_if -template -TIterator find_if(TIterator first, TIterator last, TUnaryPredicate predicate) -Searches for the first element that satisfies the predicate - -https://en.cppreference.com/w/cpp/algorithm/find -____________________________________________________________________________________________________ -find_if_not -template -TIterator find_if_not(TIterator begin, TIterator end, TUnaryPredicate predicate) -Searches for the first element that does not satisfy the predicate - -https://en.cppreference.com/w/cpp/algorithm/find -____________________________________________________________________________________________________ -lower_bound -template -TIterator lower_bound(TIterator first, TIterator last, const TValue& value) -____________________________________________________________________________________________________ -template -TIterator lower_bound(TIterator first, TIterator last, const TValue& value, TCompare compare) - -https://en.cppreference.com/w/cpp/algorithm/lower_bound -____________________________________________________________________________________________________ -upper_bound -template -TIterator upper_bound(TIterator first, TIterator last, const TValue& value) -____________________________________________________________________________________________________ -template -TIterator upper_bound(TIterator first, TIterator last, const TValue& value, TCompare compare) - -https://en.cppreference.com/w/cpp/algorithm/upper_bound -____________________________________________________________________________________________________ -equal_range -template -pair equal_range(TIterator first, TIterator last, const TValue& value) -Returns an iterator pointing to the first element in the range first, last that is not less than value, or last if no such element is found. -____________________________________________________________________________________________________ -template -pair equal_range(TIterator first, TIterator last, - const TValue& value, TCompare compare) -Returns an iterator pointing to the first element in the range first, last that is not less than value using compare, or last if no such element is found. - -https://en.cppreference.com/w/cpp/algorithm/equal_range -____________________________________________________________________________________________________ -binary_find -ETL extension -template -TIterator binary_find(TIterator begin, - TIterator end, - const TValue& value) -Finds the first item in a sorted container that matches the value. -Returns an iterator to the value or end. -____________________________________________________________________________________________________ -ETL extension -template -TIterator binary_find(TIterator begin, - TIterator end, - const TValue& value, - TBinaryPredicate predicate, - TBinaryEquality equality) -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 -template -TIterator1 search(TIterator1 first, TIterator1 last, - TIterator2 search_first, TIterator2 search_last) -Searches for the first occurrence of the sequence of elements first, last in the range search_first, search_last -____________________________________________________________________________________________________ -template -TIterator1 search(TIterator1 first, TIterator1 last, - TIterator2 search_first, TIterator2 search_last, - TCompare compare) -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 - -https://en.cppreference.com/w/cpp/algorithm/search -____________________________________________________________________________________________________ -binary_search -template -bool binary_search(TIterator first, TIterator last, const T& value, Compare compare) - -template -bool binary_search(TIterator first, TIterator last, const T& value) - -https://en.cppreference.com/w/cpp/algorithm/binary_search -____________________________________________________________________________________________________ -all_of -template -bool all_of(TIterator begin, TIterator end, TUnaryPredicate predicate) -Checks if predicate returns true for all elements in the range begin, end - -https://en.cppreference.com/w/cpp/algorithm/all_any_none_of -____________________________________________________________________________________________________ -any_of -template -bool any_of(TIterator begin, TIterator end, TUnaryPredicate predicate) -Checks if predicate returns true for at least one element in the range begin, end - -https://en.cppreference.com/w/cpp/algorithm/all_any_none_of -____________________________________________________________________________________________________ -none_of -template -bool none_of(TIterator begin, TIterator end, TUnaryPredicate predicate) -Checks if predicate returns true for no elements in the range begin, end - -https://en.cppreference.com/w/cpp/algorithm/all_any_none_of -____________________________________________________________________________________________________ -is_permutation -Returns true if there exists a permutation of the elements in the range begin1, end1 that makes that range equal to the second range - -template -bool is_permutation(TIterator1 begin1, - TIterator1 end1, - TIterator2 begin2) -____________________________________________________________________________________________________ -template -bool is_permutation(TIterator1 begin1, - TIterator1 end1, - TIterator2 begin2, - TIterator2 end2) -____________________________________________________________________________________________________ -template -bool is_permutation(TIterator1 begin1, - TIterator1 end1, - TIterator2 begin2, - TBinaryPredicate predicate) -____________________________________________________________________________________________________ -template -bool is_permutation(TIterator1 begin1, - TIterator1 end1, - TIterator2 begin2, - TIterator2 end2, - TBinaryPredicate predicate) - -https://en.cppreference.com/w/cpp/algorithm/is_permutation -____________________________________________________________________________________________________ -is_partitioned -template -bool is_partitioned(TIterator begin, - TIterator end, - TUnaryPredicate predicate) -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. - -https://en.cppreference.com/w/cpp/algorithm/is_partitioned -____________________________________________________________________________________________________ -partition_point -template -TIterator partition_point(TIterator begin, - TIterator end, - TUnaryPredicate predicate) -Examines the partitioned range begin, end and locates the end of the first partition according to predicate - -https://en.cppreference.com/w/cpp/algorithm/partition_point -____________________________________________________________________________________________________ -partition_copy -template -pair partition_copy(TSource begin, - TSource end, - TDestinationTrue destination_true, - TDestinationFalse destination_false, - TUnaryPredicate predicate) - -Copies the elements from the range begin, end to two different ranges depending on the value returned by the predicate. -The elements that satisfy the predicate p are copied to the range beginning at destination_true. The rest of the elements are copied to the range beginning at destination_false. - -https://en.cppreference.com/w/cpp/algorithm/partition_copy -____________________________________________________________________________________________________ -partition_transform -ETL extension -Transforms data from the source to one of two destinations. -If the predicate returns true then the source data if modified by function_true and stored in destination_true. -If the predicate returns false then the source data if modified by function_false and stored in destination_false. - -One input range. -template -pair - partition_transform(TSource begin, - TSource end, - TDestinationTrue destination_true, - TDestinationFalse destination_false, - TUnaryFunctionTrue function_true, - TUnaryFunctionFalse function_false, - TUnaryPredicate predicate) -____________________________________________________________________________________________________ -Two input ranges. -template -pair - partition_transform(TSource1 begin1, - TSource1 end1, - TSource2 begin2, - TDestinationTrue destination_true, - TDestinationFalse destination_false, - TBinaryFunctionTrue function_true, - TBinaryFunctionFalse function_false, - TBinaryPredicate predicate) -____________________________________________________________________________________________________ -rotate -template -TIterator rotate(TIterator first, TIterator middle, TIterator last) -Performs a left rotation on the range of elements - -https://en.cppreference.com/w/cpp/algorithm/rotate -____________________________________________________________________________________________________ -transform_s -ETL extension -A safer version that will stop transforming when either iterator reaches the end of its range. - -template -void transform_s(TIterator i_begin, - TIterator i_end, - TOutputIterator o_begin, - TOutputIterator o_end, - TUnaryFunction function) -____________________________________________________________________________________________________ -transform_n -ETL extension -Transform over n elements - -One input range. -template -void transform_n(TInputIterator i_begin, - TSize n, - TOutputIterator o_begin, - TUnaryFunction function) -____________________________________________________________________________________________________ -Two input ranges. -template -void transform_n(TInputIterator1 i_begin1, - TInputIterator2 i_begin2, - TSize n, - TOutputIterator o_begin, - TBinaryFunction function) -____________________________________________________________________________________________________ -transform_if -ETL extension -Transforms data from the source based on a predicate. -If the predicate returns true then the source data if modified by function and stored in the output range. -If the predicate returns false then the source data is ignored. - -One input range. -template -TOutputIterator transform_if(TInputIterator i_begin, - TInputIterator i_end, - TOutputIterator o_begin, - TUnaryFunction function, - TUnaryPredicate predicate) -____________________________________________________________________________________________________ -Two input ranges. -template -TOutputIterator transform_if(TInputIterator1 i_begin1, - TInputIterator1 i_end1, - TInputIterator2 i_begin2, - TOutputIterator o_begin, - TBinaryFunction function, - TBinaryPredicate predicate) -____________________________________________________________________________________________________ -transform_n_if -ETL extension -Transforms data from the source based on a predicate for 'n' items. -If the predicate returns true then the source data if modified by function and stored in the output range. -If the predicate returns false then the source data is ignored. - -One input range. -template -TOutputIterator transform_if(TInputIterator i_begin, - TSize n, - TOutputIterator o_begin, - TUnaryFunction function, - TUnaryPredicate predicate) -____________________________________________________________________________________________________ -Two input ranges. -template -TOutputIterator transform_if(TInputIterator1 i_begin1, - TSize n, - TInputIterator2 i_begin2, - TOutputIterator o_begin, - TBinaryFunction function, - TBinaryPredicate predicate) -____________________________________________________________________________________________________ -shell_sort -ETL extension -Sorts a range using the shell sort algorithm. - -template -void shell_sort(TIterator first, TIterator last) -____________________________________________________________________________________________________ -template -void shell_sort(TIterator first, TIterator last, TCompare compare) - -https://en.wikipedia.org/wiki/Shellsort -____________________________________________________________________________________________________ -insertion_sort -ETL extension -Sorts a range using the insertion sort algorithm. - -template -void insertion_sort(TIterator first, TIterator last) -____________________________________________________________________________________________________ -template -void insertion_sort(TIterator first, TIterator last, TCompare compare) - -https://en.wikipedia.org/wiki/Insertion_sort -____________________________________________________________________________________________________ -heap_sort -ETL extension -16.2.0 -Sorts a range using the heap sort algorithm. - -template -void heap_sort(TIterator first, TIterator last) -____________________________________________________________________________________________________ -template -void heap_sort(TIterator first, TIterator last, TCompare compare) - -https://en.wikipedia.org/wiki/Heapsort -____________________________________________________________________________________________________ -selection_sort -ETL extension -20.7.0 -Sorts a range using the selection sort algorithm. - -template -void selection_sort(TIterator first, TIterator last) -____________________________________________________________________________________________________ -template -void selection_sort(TIterator first, TIterator last, TCompare compare) - -https://en.wikipedia.org/wiki/Selectionsort -____________________________________________________________________________________________________ -sort -Sorts a range. - -template -void sort(TIterator first, TIterator last) -____________________________________________________________________________________________________ -template -void sort(TIterator first, TIterator last, TCompare compare) - -If ETL_NO_STL is defined then uses etl::shell_sort, otherwise calls std::sort. - -https://en.cppreference.com/w/cpp/algorithm/sort -____________________________________________________________________________________________________ -stable_sort -Stable sorts a range. - -template -void stable_sort(TIterator first, TIterator last) -____________________________________________________________________________________________________ -template -void stable_sort(TIterator first, TIterator last, TCompare compare) - -If ETL_NO_STL is defined then uses etl::insertion_sort, otherwise calls std::stable_sort. - -https://en.cppreference.com/w/cpp/algorithm/stable_sort -____________________________________________________________________________________________________ -is_sorted -Returns true is the range is sorted - -template -bool is_sorted(TIterator begin, TIterator end) -____________________________________________________________________________________________________ - -template -bool is_sorted(TIterator begin, TIterator end, TCompare compare) - -https://en.cppreference.com/w/cpp/algorithm/is_sorted -____________________________________________________________________________________________________ -is_sorted_until -Returns an iterator the first element that is not sorted - -template -TIterator is_sorted_until(TIterator begin, TIterator end) -____________________________________________________________________________________________________ -template -TIterator is_sorted_until(TIterator begin, TIterator end, TCompare compare) - -https://en.cppreference.com/w/cpp/algorithm/is_sorted_until -____________________________________________________________________________________________________ -clamp -Clamps a value between two limits. - -template -ETL_CONSTEXPR const T& clamp(const T& value, const T& low, const T& high, TCompare compare) -____________________________________________________________________________________________________ -template -ETL_CONSTEXPR const T& clamp(const T& value, const T& low, const T& high ) -____________________________________________________________________________________________________ -accumulate -Reverse engineered std::accumulate - -template -ETL_CONSTEXPR14 T accumulate(TIterator first, TIterator last, T sum) - -template -ETL_CONSTEXPR14 T accumulate(TIterator first, TIterator last, T sum, TBinaryOperation operation) -____________________________________________________________________________________________________ -remove -template -TIterator remove(TIterator first, TIterator last, const T& value) -Removes all elements that are equal to value. -____________________________________________________________________________________________________ -remove_if -template -TIterator remove_if(TIterator first, TIterator last, TPredicate predicate) -Removes all elements that satisfy the predicate. - diff --git a/docs/raw/utilities/Mutex.txt b/docs/raw/utilities/Mutex.txt deleted file mode 100644 index b59af9f5..00000000 --- a/docs/raw/utilities/Mutex.txt +++ /dev/null @@ -1,13 +0,0 @@ -Mutex -This header attempts to replicate std::mutex. - -If ETL_CPP11_SUPPORTED and ETL_USING_STL are defined as 1 then etl::mutex will be defined in terms of std::mutex. -Otherwise it will be implemented in terms of the built-in support, if available, from the compiler. For example, early GCC, Clang and Arm compilers will use the __sync built-ins. - -If there is an ETL mutex type available for your platform then ETL_HAS_MUTEX will be set to 1, otherwise it will be set to 0. - -The mutex implementation will normally be selected by the compiler being used. -For FreeRTOS and CMSIS-RTOS2 you must define one of the following. -ETL_TARGET_OS_FREERTOS -ETL_TARGET_OS_CMSIS_OS2 - diff --git a/docs/raw/utilities/expected.txt b/docs/raw/utilities/expected.txt deleted file mode 100644 index acedf680..00000000 --- a/docs/raw/utilities/expected.txt +++ /dev/null @@ -1,297 +0,0 @@ -expected - -20.35.13 -STL equivalent: std::expected - -A generic result type for returning either a result or an error. -Replacement for etl::result - -template -class expected - -Specialisation for void result. -template -class expected -____________________________________________________________________________________________________ -Unexpected type -template -class unexpected -____________________________________________________________________________________________________ -A tag type for in-place construction of an unexpected value in an etl::expected object -struct unexpect_t; - -A constant of type etl::unexpect_t which is directly passed to a constructor of etl::expected to construct an unexpected value. -inline constexpr unexpect_t unexpect; >= C++17 -static const unexpect_t unexpect; < C++17 -____________________________________________________________________________________________________ -unexpected - -template -class unexpected -____________________________________________________________________________________________________ -Types -error_type TError -____________________________________________________________________________________________________ -Member functions - -ETL_CONSTEXPR -unexpected(const unexpected& other) -Copy constructor -____________________________________________________________________________________________________ -ETL_CONSTEXPR -unexpected(unexpected&& other) -Move constructor. ->= C++11 -____________________________________________________________________________________________________ -template -constexpr explicit unexpected(TError&& e) -Construct from argument. ->= C++11 -____________________________________________________________________________________________________ -template -explicit unexpected(const TError& e) -Construct from argument. -< C++11 -____________________________________________________________________________________________________ -template -constexpr explicit unexpected(etl::in_place_t, TArgs&&... args) - Construct from arguments. ->= C++11 -____________________________________________________________________________________________________ -template -constexpr explicit unexpected(etl::in_place_t, std::initializer_list init, TArgs&&... args) -Construct from initializer_list and arguments. ->= C++11 -____________________________________________________________________________________________________ -ETL_CONSTEXPR14 -etl::unexpected& operator =(const etl::unexpected& rhs) -Assign from etl::unexpected -____________________________________________________________________________________________________ -ETL_CONSTEXPR14 -etl::unexpected& operator =(etl::unexpected&& rhs) -Move assign from etl::unexpected ->= C++11 -____________________________________________________________________________________________________ -TError& error() & noexcept -Get the error. ->= C++11 -____________________________________________________________________________________________________ -constexpr const TError& error() const& noexcept -Get the error. ->= C++11 -____________________________________________________________________________________________________ -TError&& error() && noexcept -Get the error. ->= C++11 -____________________________________________________________________________________________________ -constexpr TError&& error() const&& noexcept -Get the error. ->= C++11 -____________________________________________________________________________________________________ -const TError& error() const -Get the error. -< C++11 -____________________________________________________________________________________________________ -void swap(etl::unexpected& other) -Swap with another etl::unexpected -____________________________________________________________________________________________________ -expected - -template -class expected - -Specialisation for void value type. -template -class expected -____________________________________________________________________________________________________ -Types -this_type etl::expected -value_type TValue -error_type TError -unexpected_type etl::unexpected -____________________________________________________________________________________________________ -Member functions - -ETL_CONSTEXPR14 expected() ETL_NOEXCEPT -Default constructor -____________________________________________________________________________________________________ -ETL_CONSTEXPR14 expected(const value_type& value) ETL_NOEXCEPT -Constructor -____________________________________________________________________________________________________ -ETL_CONSTEXPR14 expected(value_type&& value) ETL_NOEXCEPT -Constructor ->= C++11 -____________________________________________________________________________________________________ -ETL_CONSTEXPR14 expected(const expected& other) ETL_NOEXCEPT -Copy constructor -____________________________________________________________________________________________________ -ETL_CONSTEXPR14 expected(expected&& other) ETL_NOEXCEPT -Move constructor ->= C++11 -____________________________________________________________________________________________________ -template -ETL_CONSTEXPR14 explicit expected(const etl::unexpected& ue) -Copy construct from unexpected type. -____________________________________________________________________________________________________ -template -ETL_CONSTEXPR14 explicit expected(etl::unexpected&& ue) -Move construct from unexpected type. ->= C++11 -____________________________________________________________________________________________________ -ETL_CONSTEXPR14 explicit expected(etl::in_place_t) ETL_NOEXCEPT -Construct with default value type. -____________________________________________________________________________________________________ -template -ETL_CONSTEXPR14 explicit expected(etl::in_place_t, TArgs&&... args) -Construct value type from arguments. ->= C++11 -____________________________________________________________________________________________________ -template -ETL_CONSTEXPR14 explicit expected(etl::in_place_t, std::initializer_list il, TArgs&&... args) -Construct value type from initializer_list and arguments. -____________________________________________________________________________________________________ -template -ETL_CONSTEXPR14 explicit expected(etl::unexpect_t, TArgs&&... args) -Construct error type from arguments. ->= C++11 -____________________________________________________________________________________________________ -template -ETL_CONSTEXPR14 explicit expected(etl::unexpect_t, std::initializer_list il, TArgs&&... args) -Construct error type from initializer_list and arguments. ->= C++11 -____________________________________________________________________________________________________ -this_type& operator =(const this_type& other) -Copy assign -____________________________________________________________________________________________________ -this_type& operator =(this_type&& other) -Move assign ->= C++11 -____________________________________________________________________________________________________ -expected& operator =(const value_type& value) -Copy assign from value -____________________________________________________________________________________________________ -expected& operator =(value_type&& value) -Move assign from value ->= C++11 -____________________________________________________________________________________________________ -expected& operator =(const unexpected_type& error) -Copy assign from error -____________________________________________________________________________________________________ -expected& operator =(unexpected_type&& error) -Move assign from error ->= C++11 -____________________________________________________________________________________________________ -ETL_CONSTEXPR14 value_type& value()& -Get the value. -Undefined if has_value() returns false. -Not valid for void specialisation. ->= C++11 -____________________________________________________________________________________________________ -ETL_CONSTEXPR14 const value_type& value() const& -Get the value. -Undefined if has_value() returns false. -Not valid for void specialisation. ->= C++11 -____________________________________________________________________________________________________ -ETL_CONSTEXPR14 value_type&& value()&& -Get the value. -Undefined if has_value() returns false. -Not valid for void specialisation. ->= C++11 -____________________________________________________________________________________________________ -ETL_CONSTEXPR14 const value_type&& value() const&& -Get the value. -Undefined if has_value() returns false. -Not valid for void specialisation. ->= C++11 -____________________________________________________________________________________________________ -value_type& value() const -Get the value. -Undefined if has_value() returns false. -Not valid for void specialisation. -____________________________________________________________________________________________________ -ETL_NODISCARD -ETL_CONSTEXPR14 -bool has_value() const -Returns true if the class contains a value. -____________________________________________________________________________________________________ -ETL_NODISCARD -ETL_CONSTEXPR14 -operator bool() const -Returns true if the class contains a value. -____________________________________________________________________________________________________ -template -ETL_NODISCARD -ETL_CONSTEXPR14 -value_type value_or(U&& default_value) const& -Returns the value or default_value if has_value() returns false. ->= C++11 -____________________________________________________________________________________________________ -template -ETL_NODISCARD -ETL_CONSTEXPR14 -value_type value_or(U&& default_value)&& -Returns the value or default_value if has_value() returns false. ->= C++11 -____________________________________________________________________________________________________ -template -value_type value_or(const U& default_value) const -Returns the value or default_value if has_value() returns false. -< C++11 -____________________________________________________________________________________________________ -ETL_NODISCARD -ETL_CONSTEXPR14 -error_type& error()& ETL_NOEXCEPT -Returns the error. -Undefined if has_value() returns true. ->= C++11 -____________________________________________________________________________________________________ -ETL_NODISCARD -ETL_CONSTEXPR14 -const error_type& error() const& ETL_NOEXCEPT -Returns the error. -Undefined if has_value() returns true. ->= C++11 -____________________________________________________________________________________________________ -ETL_NODISCARD -ETL_CONSTEXPR14 -error_type&& error() && ETL_NOEXCEPT -Returns the error. -Undefined if has_value() returns true. ->= C++11 -____________________________________________________________________________________________________ -ETL_NODISCARD -ETL_CONSTEXPR14 -const error_type&& error() const&& ETL_NOEXCEPT -Returns the error. -Undefined if has_value() returns true. ->= C++11 -____________________________________________________________________________________________________ -error_type& error() const -Returns the error. -Undefined if has_value() returns true. -< C++11 -____________________________________________________________________________________________________ -template -ETL_CONSTEXPR14 value_type& emplace(TArgs&&... args) ETL_NOEXCEPT -Returns the error if has_value() returns false. -Undefined if has_value() returns true. ->= C++11 -____________________________________________________________________________________________________ -template -ETL_CONSTEXPR14 value_type& emplace(std::initializer_list& il, TArgs&&... args) ETL_NOEXCEPT -Create from arguments. ->= C++11 -____________________________________________________________________________________________________ -value_type* operator ->() -Class member access operator. -____________________________________________________________________________________________________ -const value_type* operator ->() const -Const class member access operator. -____________________________________________________________________________________________________ -value_type& operator *() -Dereference operator. -____________________________________________________________________________________________________ -const value_type& operator *() const -Dereference operator. - diff --git a/docs/raw/utilities/functional.txt b/docs/raw/utilities/functional.txt deleted file mode 100644 index 9cedf5d5..00000000 --- a/docs/raw/utilities/functional.txt +++ /dev/null @@ -1,105 +0,0 @@ -functional -Defines functional classes from the STL. -____________________________________________________________________________________________________ -reference_wrapper - -etl::reference_wrapper is a class template that wraps a reference in a copyable, assignable object. -A clone of std::reference_wrapper -____________________________________________________________________________________________________ -unary_function - -template -struct unary_function - -Typedefs -TArgumentType argument_type -TResultType result_type -____________________________________________________________________________________________________ -binary_function - -template -struct binary_function - -Typedefs -TFirstArgumentType first_argument_type -TSecondArgumentType second_argument_type -TResultType result_type -____________________________________________________________________________________________________ -bind1st - -template -class binder1st - -template -binder1st bind1st(const F& f, const T& x) -____________________________________________________________________________________________________ -bind2nd - -template -class binder2nd - -template -binder2nd bind2nd(const F& f, const T& x) -____________________________________________________________________________________________________ -Comparisons - -template -struct less - -20.21.0 -template <> -struct less -Transparent comparator. Defines is_transparent. -____________________________________________________________________________________________________ -template -struct less_equal - -20.21.0 -template <> -struct less_equal -Transparent comparator. Defines is_transparent. -____________________________________________________________________________________________________ -template -struct greater - -20.21.0 -template <> -struct greater -Transparent comparator. Defines is_transparent. -____________________________________________________________________________________________________ -template -struct greater_equal - -20.21.0 -template <> -struct greater_equal -Transparent comparator. Defines is_transparent. -____________________________________________________________________________________________________ -template -struct equal_to - -20.21.0 -template <> -struct equal_to -Transparent comparator. Defines is_transparent. -____________________________________________________________________________________________________ -template -struct not_equal_to - -20.21.0 -template <> -struct not_equal_to -Transparent comparator. Defines is_transparent. -____________________________________________________________________________________________________ -mem_fn - -20.38.11 -template - mem_fn(TReturnType(TClassType::* member_function)(TArgs...)) -Returns a functor that wraps a member function of TClassType, taking TArgs and returning TReturnType. - -20.38.11 -template - mem_fn(TReturnType(TClassType::* member_function)(TArgs...) const) -Returns a functor that wraps a const member function of TClassType, taking TArgs and returning TReturnType. - diff --git a/docs/raw/utilities/result.txt b/docs/raw/utilities/result.txt deleted file mode 100644 index 4d82dd75..00000000 --- a/docs/raw/utilities/result.txt +++ /dev/null @@ -1,81 +0,0 @@ -result - -20.17.0 -A generic result type for returning either a result or an error. -Deprecated. Use etl::expected - -template -class result - -Specialisation for void result. -template -class result -____________________________________________________________________________________________________ -result() = delete; -Cannot be default constructed - -result(const result& other) -Copy constructor - -result(result&& other) -Move constructor -____________________________________________________________________________________________________ -result(const TValue& value) -Construct from a value -Not valid for void specialisation - -result(TValue&& value) -Move construct from a value -Not valid for void specialisation -____________________________________________________________________________________________________ -result(const TError& err) -Construct from error - -result(TError&& err) -Move construct from error -____________________________________________________________________________________________________ -result& operator =(const result& other) -Copy assign - -result& operator =(result&& other) -Move assign -____________________________________________________________________________________________________ -result& operator =(const TValue& value) -Copy assign from value -Not valid for void specialisation - -result& operator =(TValue&& value) -Move assign from value -Not valid for void specialisation -____________________________________________________________________________________________________ -result& operator =(const TError& err) -Copy assign from error - -result& operator =(TError&& err) -Move assign from error -____________________________________________________________________________________________________ -bool is_value() const -true if result contains a value -____________________________________________________________________________________________________ -bool is_error() const -true if result contains an error -____________________________________________________________________________________________________ -const TValue& value() const -Returns a const reference to the value. -Undefined if the result does not contain an value. -Not valid for void specialisation - -TValue&& value() -Returns an rvalue reference to the value. -Undefined if the result does not contain an value. -Not valid for void specialisation -____________________________________________________________________________________________________ -const TError& error() const -Returns a const reference to the error. -Undefined if the result does not contain an error. - -TError&& error() -Returns an rvalue reference to the error. -Undefined if the result does not contain an error. - - diff --git a/docs/utilities/expected.md b/docs/utilities/expected.md new file mode 100644 index 00000000..07f176da --- /dev/null +++ b/docs/utilities/expected.md @@ -0,0 +1,588 @@ +--- +title: "expected" +--- + +{{< callout type="info">}} + Header: `expected.h` + Since: `20.35.13` + Similar to: `std::expected` +{{< /callout >}} + +A generic result type for returning either a result or an error. +Replacement for `etl::result`. + +```cpp +template +class expected +``` + +Specialisation for `void` result. +```cpp +template +class expected +``` + +## unexpected +template +class unexpected + +## unexpect_t +A tag type for in-place construction of an unexpected value in an `etl::expected` object. + +--- + +struct unexpect_t; + +A constant of type `etl::unexpect_t` which is directly passed to a constructor of `etl::expected` to construct an unexpected value. + +```cpp +inline constexpr unexpect_t unexpect; +``` +Since: C++17. + +```cpp +static const unexpect_t unexpect; +``` +Before: C++17. + +## unexpected + +```cpp +template +class unexpected +``` + +### Types + +`error_type = TError` + +### Member functions + +```cpp +ETL_CONSTEXPR +unexpected(const unexpected& other) +``` +**Description** +Copy constructor + +--- + +```cpp +ETL_CONSTEXPR +unexpected(unexpected&& other) +``` +**Description** +Move constructor. +Since: C++11 + +--- + +```cpp +template +constexpr explicit unexpected(TError&& e) +``` +**Description** +Construct from an argument. +Since: C++11 + +--- + +```cpp +template +explicit unexpected(const TError& e) +``` +**Description** +Construct from argument. +Before: C++11 + +--- + +```cpp +template +constexpr explicit unexpected(etl::in_place_t, TArgs&&... args) +``` +**Description** +Construct from arguments. +Since: C++11 + +--- + +```cpp +template +constexpr explicit unexpected(etl::in_place_t, std::initializer_list init, TArgs&&... args) +``` +**Description** +Construct from initializer_list and arguments. +Since: C++11 + +--- + +```cpp +ETL_CONSTEXPR14 +etl::unexpected& operator =(const etl::unexpected& rhs) +``` +**Description** +Assign from etl::unexpected + +--- + +```cpp +ETL_CONSTEXPR14 +etl::unexpected& operator =(etl::unexpected&& rhs) +``` +**Description** +Move assign from etl::unexpected +Since: C++11 + +--- + +```cpp +TError& error() & noexcept +``` +**Description** +Get the error. +Since: C++11 + +--- + +```cpp +constexpr const TError& error() const& noexcept +``` +**Description** +Get the error. +Since: C++11 + +--- + +```cpp +TError&& error() && noexcept +``` +**Description** +Get the error. +Since: C++11 + +--- + +```cpp +constexpr TError&& error() const&& noexcept +``` +**Description** +Get the error. +Since: C++11 + +--- + +```cpp +const TError& error() const +``` +**Description** +Get the error. +Before: C++11 + +--- + +```cpp +void swap(etl::unexpected& other) +``` +**Description** +Swap with another etl::unexpected + +## expected + +```cpp +template +class expected +```cpp + +Specialisation for void value type. +```cpp +template +class expected +```cpp + +### Types + +```cpp +this_type etl::expected +value_type TValue +error_type TError +unexpected_type etl::unexpected +``` + +### Member functions + +```cpp +ETL_CONSTEXPR14 expected() ETL_NOEXCEPT +``` +**Description** +Default constructor + +--- + +```cpp +ETL_CONSTEXPR14 expected(const value_type& value) ETL_NOEXCEPT +``` +**Description** +Constructor + +--- + +```cpp +ETL_CONSTEXPR14 expected(value_type&& value) ETL_NOEXCEPT +``` +**Description** +Constructor +Since: C++11 + +--- + +```cpp +ETL_CONSTEXPR14 expected(const expected& other) ETL_NOEXCEPT +``` +**Description** +Copy constructor + +--- + +```cpp +ETL_CONSTEXPR14 expected(expected&& other) ETL_NOEXCEPT +``` +**Description** +Move constructor +Since: C++11 + +--- + +```cpp +template +ETL_CONSTEXPR14 explicit expected(const etl::unexpected& ue) +``` +**Description** +Copy construct from unexpected type. + +--- + +```cpp +template +ETL_CONSTEXPR14 explicit expected(etl::unexpected&& ue) +``` +**Description** +Move construct from unexpected type. +Since: C++11 + +--- + +```cpp +ETL_CONSTEXPR14 explicit expected(etl::in_place_t) ETL_NOEXCEPT +``` +**Description** +Construct with default value type. + +--- + +```cpp +template +ETL_CONSTEXPR14 explicit expected(etl::in_place_t, TArgs&&... args) +``` +**Description** +Construct value type from arguments. +Since: C++11 + +--- + +```cpp +template +ETL_CONSTEXPR14 explicit expected(etl::in_place_t, std::initializer_list il, TArgs&&... args) +``` +**Description** +Construct value type from initializer_list and arguments. + +--- + +```cpp +template +ETL_CONSTEXPR14 explicit expected(etl::unexpect_t, TArgs&&... args) +``` +**Description** +Construct error type from arguments. +Since: C++11 + +--- + +```cpp +template +ETL_CONSTEXPR14 explicit expected(etl::unexpect_t, std::initializer_list il, TArgs&&... args) +``` +**Description** +Construct error type from initializer_list and arguments. +Since: C++11 + +--- + +```cpp +this_type& operator =(const this_type& other) +``` +**Description** +Copy assign + +--- + +```cpp +this_type& operator =(this_type&& other) +``` +**Description** +Move assign +Since: C++11 + +--- + +```cpp +expected& operator =(const value_type& value) +``` +**Description** +Copy assign from value + +--- + +```cpp +expected& operator =(value_type&& value) +``` +**Description** +Move assign from value +Since: C++11 + +--- + +```cpp +expected& operator =(const unexpected_type& error) +``` +**Description** +Copy assign from error + +--- + +```cpp +expected& operator =(unexpected_type&& error) +``` +**Description** +Move assign from error +Since: C++11 + +--- + +```cpp +ETL_CONSTEXPR14 value_type& value()& +``` +**Description** +Get the value. +Undefined if has_value() returns false. +Not valid for void specialisation. +Since: C++11 + +--- + +```cpp +ETL_CONSTEXPR14 const value_type& value() const& +``` +**Description** +Get the value. +Undefined if has_value() returns false. +Not valid for void specialisation. +Since: C++11 + +--- + +```cpp +ETL_CONSTEXPR14 value_type&& value()&& +``` +**Description** +Get the value. +Undefined if has_value() returns false. +Not valid for void specialisation. +Since: C++11 + +--- + +```cpp +ETL_CONSTEXPR14 const value_type&& value() const&& +``` +**Description** +Get the value. +Undefined if has_value() returns false. +Not valid for void specialisation. +Since: C++11 + +--- + +```cpp +value_type& value() const +``` +**Description** +Get the value. +Undefined if has_value() returns false. +Not valid for void specialisation. + +--- + +```cpp +ETL_NODISCARD +ETL_CONSTEXPR14 +bool has_value() const +``` +**Description** +Returns true if the class contains a value. + +--- + +```cpp +ETL_NODISCARD +ETL_CONSTEXPR14 +operator bool() const +``` +**Description** +Returns true if the class contains a value. + +--- + +```cpp +template +ETL_NODISCARD +ETL_CONSTEXPR14 +value_type value_or(U&& default_value) const& +``` +**Description** +Returns the value or default_value if has_value() returns false. +Since: C++11 + +--- + +```cpp +template +ETL_NODISCARD +ETL_CONSTEXPR14 +value_type value_or(U&& default_value)&& +``` +**Description** +Returns the value or default_value if has_value() returns false. +Since: C++11 + +--- + +```cpp +template +value_type value_or(const U& default_value) const +``` +**Description** +Returns the value or default_value if has_value() returns false. +Before: C++11 + +--- + +```cpp +ETL_NODISCARD +ETL_CONSTEXPR14 +error_type& error()& ETL_NOEXCEPT +``` +**Description** +Returns the error. +Undefined if has_value() returns true. +Since: C++11 + +--- + +```cpp +ETL_NODISCARD +ETL_CONSTEXPR14 +const error_type& error() const& ETL_NOEXCEPT +``` +**Description** +Returns the error. +Undefined if has_value() returns true. +Since: C++11 + +--- + +```cpp +ETL_NODISCARD +ETL_CONSTEXPR14 +error_type&& error() && ETL_NOEXCEPT +``` +**Description** +Returns the error. +Undefined if has_value() returns true. +Since: C++11 + +--- + +```cpp +ETL_NODISCARD +ETL_CONSTEXPR14 +const error_type&& error() const&& ETL_NOEXCEPT +``` +**Description** +Returns the error. +Undefined if has_value() returns true. +Since: C++11 + +--- + +```cpp +error_type& error() const +``` +**Description** +Returns the error. +Undefined if has_value() returns true. +Before: C++11 + +--- + +```cpp +template +ETL_CONSTEXPR14 value_type& emplace(TArgs&&... args) ETL_NOEXCEPT +``` +**Description** +Returns the error if has_value() returns false. +Undefined if has_value() returns true. +Since: C++11 + +--- + +```cpp +template +ETL_CONSTEXPR14 value_type& emplace(std::initializer_list& il, TArgs&&... args) ETL_NOEXCEPT +``` +**Description** +Create from arguments. +Since: C++11 + +--- + +```cpp +value_type* operator ->() +``` +**Description** +Class member access operator. + +--- + +```cpp +const value_type* operator ->() const +``` +**Description** +Const class member access operator. + +--- + +```cpp +value_type& operator *() +``` +**Description** +Dereference operator. + +--- + +```cpp +const value_type& operator *() const +``` +**Description** +Dereference operator. diff --git a/docs/utilities/functional.md b/docs/utilities/functional.md new file mode 100644 index 00000000..d290c6cc --- /dev/null +++ b/docs/utilities/functional.md @@ -0,0 +1,219 @@ +--- +title: "functional" +--- + +{{< callout type="info">}} + Header: `functional.h` +{{< /callout >}} + +Defines functional classes from the STL. + +## reference_wrapper + +`etl::reference_wrapper` is a class template that wraps a reference in a copyable, assignable object. +A clone of `std::reference_wrapper`. + +## unary_function + +```cpp +template +struct unary_function +``` + +### Typedefs +```cpp +TArgumentType argument_type +TResultType result_type +``` + +## binary_function + +```cpp +template +struct binary_function +``` + +### Typedefs +```cpp +TFirstArgumentType first_argument_type +TSecondArgumentType second_argument_type +TResultType result_type +``` + +## bind1st + +```cpp +template +class binder1st +``` + +--- + +```cpp +template +binder1st bind1st(const F& f, const T& x) +``` +**Description** +Binds a given argument to a first parameter of the given binary function object. + +## bind2nd + +```cpp +template +class binder2nd +``` + +--- + +```cpp +template +binder2nd bind2nd(const F& f, const T& x) +``` +**Description** +Binds a given argument to a second parameter of the given binary function object. + +## Less + +```cpp +template +struct less +``` +**Description** +A function object that performs a strictly less-than comparison `a < b`) between two values. + +--- + +```cpp +template <> +struct less +``` +**Description** +A function object that performs a strictly less-than comparison `a < b`) between two values. +Transparent comparator. +Defines `is_transparent`. +Since: `20.21.0` + +## less_equal + +```cpp +template +struct less_equal +``` +**Description** +A function object that performs a strictly less-than-equal comparison `a <= b`) between two values. + +--- + +```cpp +template <> +struct less_equal +``` +**Description** +A function object that performs a strictly less-than-equal comparison `a <= b`) between two values. +Transparent comparator. +Defines `is_transparent`. +Since: `20.21.0` + +## greater + +```cpp +template +struct greater +``` +**Description** +A function object that performs a strictly greater-than comparison `a > b`) between two values. + +--- + +```cpp +template <> +struct greater +``` +**Description** +A function object that performs a strictly greater-than comparison `a > b`) between two values. +Transparent comparator. +Defines `is_transparent`. +Since: `20.21.0` + +## greater_equal + +```cpp +template +struct greater_equal +``` +**Description** +A function object that performs a strictly greater-than-equal comparison `a >= b`) between two values. + +--- + +```cpp +template <> +struct greater_equal +``` +**Description** +A function object that performs a strictly greater-than-equal comparison `a >= b`) between two values. +Transparent comparator. +Defines `is_transparent`. +Since: `20.21.0` + +## equal_to + +```cpp +template +struct equal_to +``` +**Description** +A function object that performs a strictly equal-to comparison `a == b`) between two values. + +--- + +```cpp +template <> +struct equal_to +``` +**Description** +A function object that performs a strictly equal-to comparison `a == b`) between two values. +Transparent comparator. +Defines `is_transparent`. +Since: `20.21.0` + +## not_equal_to + +```cpp +template +struct not_equal_to +``` +**Description** +A function object that performs a strictly not-equal-to comparison `a !== b`) between two values. + +--- + +```cpp +template <> +struct not_equal_to +``` +**Description** +A function object that performs a strictly not-equal-to comparison `a !== b`) between two values. +Transparent comparator. +Defines `is_transparent`. +Since: `20.21.0` + +## mem_fn + +```cpp +template + mem_fn(TReturnType(TClassType::* member_function)(TArgs...)) +``` +**Description** +Returns a functor that wraps a member function of `TClassType`, taking TArgs and returning `TReturnType`. +Since: `20.38.11` + +--- + +```cpp +template + mem_fn(TReturnType(TClassType::* member_function)(TArgs...) const) +``` +**Description** +Returns a functor that wraps a const member function of `TClassType`, taking TArgs and returning `TReturnType`. +Since: `20.38.11` diff --git a/docs/raw/utilities/Memory Model.txt b/docs/utilities/memory-model.md similarity index 59% rename from docs/raw/utilities/Memory Model.txt rename to docs/utilities/memory-model.md index 8a2f060f..f3ea169e 100644 --- a/docs/raw/utilities/Memory Model.txt +++ b/docs/utilities/memory-model.md @@ -1,26 +1,39 @@ -Memory Model -This header defines enumerations and type lookups for supporting various memory models for the ETL. -These allow template classes to use optimally sized variables for the model. -For example, if a container will never have more than 256 elements then indexes and counts may be contained in an 8 bit type. +--- +title: "memory_model" +--- -memory_model -A user type that defines values for four different memory models. -MEMORY_MODEL_SMALL -MEMORY_MODEL_MEDIUM -MEMORY_MODEL_LARGE -MEMORY_MODEL_HUGE +{{< callout type="info">}} + Header: `memory_model.h` +{{< /callout >}} -Example +This header defines enumerations and type lookups for supporting various memory models for the ETL. +These allow template classes to use optimally sized variables for the model. +For example, if a container will never have more than 256 elements then indexes and counts may be contained in an 8 bit type. + +## memory_model +A user type that defines values for four different memory models. +`MEMORY_MODEL_SMALL` +`MEMORY_MODEL_MEDIUM` +`MEMORY_MODEL_LARGE` +`MEMORY_MODEL_HUGE` + +## Example +```cpp etl::memory_model::MEMORY_MODEL_LARGE -____________________________________________________________________________________________________ -size_type_lookup +``` + +## size_type_lookup A type lookup template that defines a type that equates to the size type for memory model. +```cpp using size_type = typename etl::size_type_lookup::type; +``` -The defined types are... +The defined types are: +```cpp MEMORY_MODEL_SMALL uint_least8_t MEMORY_MODEL_MEDIUM uint_least16_t MEMORY_MODEL_LARGE uint_least32_t MEMORY_MODEL_HUGE uint_least64_t +``` diff --git a/docs/utilities/mutex.md b/docs/utilities/mutex.md new file mode 100644 index 00000000..f02c4f84 --- /dev/null +++ b/docs/utilities/mutex.md @@ -0,0 +1,15 @@ +--- +title: "mutex" +--- + +This header attempts to replicate `std::mutex`. + +If `ETL_CPP11_SUPPORTED` and `ETL_USING_STL` are defined as `1` then `etl::mutex` will be defined in terms of `std::mutex`. +Otherwise it will be implemented in terms of the built-in support, if available, from the compiler. For example, early GCC, Clang and Arm compilers will use the `__sync` built-ins. + +If there is an ETL mutex type available for your platform then ETL_HAS_MUTEX will be set to `1`, otherwise it will be set to `0`. + +The mutex implementation will normally be selected by the compiler being used. +For FreeRTOS and CMSIS-RTOS2 you must define one of the following. +`ETL_TARGET_OS_FREERTOS` +`ETL_TARGET_OS_CMSIS_OS2` diff --git a/docs/raw/utilities/Parameter Pack.txt b/docs/utilities/parameter-pack.md similarity index 71% rename from docs/raw/utilities/Parameter Pack.txt rename to docs/utilities/parameter-pack.md index a8c4bbae..b35df12f 100644 --- a/docs/raw/utilities/Parameter Pack.txt +++ b/docs/utilities/parameter-pack.md @@ -1,50 +1,80 @@ -Parameter Pack -Compile time mapping of index to type and type to index for a template parameter pack. -Deprecated: Use etl::type_list -For C++11 or above -____________________________________________________________________________________________________ -parameter_pack +--- +title: "parameter_pack" +--- +{{< callout type="info">}} + Header: `parameter_pack.h` + For C++11 or above +{{< /callout >}} + +{{< callout type="warning">}} +**This class is deprecated.** +Use `etl::type_list` as a replacement. +{{< /callout >}} + +Compile time mapping of index to type and type to index for a template parameter pack. + +## parameter_pack + +```cpp template class parameter_pack +``` -Defines +## Constants +```cpp static constexpr size_t size = sizeof...(TTypes); +``` -Template alias +## Template alias + +```cpp template using parameter_pack_t = typename etl::parameter_pack::template type_from_index_t; +``` Type from index and type list. -For C++17 or above +**For C++17 or above** +```cpp template inline constexpr size_t parameter_pack_v = etl::parameter_pack::template index_of_type::value; +``` Index from type and type list. -The class contains two nested templates. -____________________________________________________________________________________________________ -index_of_type +**The class contains two nested templates.** +## index_of_type + +```cpp template class index_of_type +``` -For C++17 or above +**For C++17 or above** +```cpp template static constexpr size_t index_of_type_v = index_of_type::value; +``` -____________________________________________________________________________________________________ -type_from_index +## type_from_index +```cpp template class type_from_index +``` +--- + +```cpp template using type_from_index_t = typename type_from_index::type; -____________________________________________________________________________________________________ -Examples +``` +## Examples + +```cpp using Pack = etl::parameter_pack; constexpr size_t size = Pack::size; // size == 3 @@ -60,4 +90,4 @@ using type1 = typename Pack::type_from_index_t<1>; // type1 = short using type2 = typename Pack::type_from_index_t<2>; // type2 = int using type3 = typename Pack::type_from_index_t<3>; // Static assert // "Index out of bounds of parameter pack" - +``` diff --git a/docs/raw/utilities/parameter_type.txt b/docs/utilities/parameter-type.md similarity index 72% rename from docs/raw/utilities/parameter_type.txt rename to docs/utilities/parameter-type.md index 997f4f56..571d1c97 100644 --- a/docs/raw/utilities/parameter_type.txt +++ b/docs/utilities/parameter-type.md @@ -1,15 +1,29 @@ -parameter_type -Allows the method of passing a parameter to be determined by the type. +--- +title: "parameter_type" +--- + +{{< callout type="info">}} + Header: `parameter_type.h` +{{< /callout >}} + +Allows the method of passing a parameter to be determined by the type. By default, if the type is fundamental or a pointer, then the parameter type is 'by value', otherwise 'by const reference'. +```cpp template struct parameter_type; +``` -Defines type. +## Defines +```cpp +type +``` -The template may be specialised for specific types. +The template may be specialised for specific types. -Example +## Example + +```cpp class MyClass { }; @@ -37,5 +51,4 @@ Do_Stuff(data); // Pass by value MyClass myClass; Do_Stuff(myClass); - - +``` diff --git a/docs/utilities/result.md b/docs/utilities/result.md new file mode 100644 index 00000000..b194efb5 --- /dev/null +++ b/docs/utilities/result.md @@ -0,0 +1,195 @@ +--- +title: "result" +--- + +{{< callout type="info">}} + Header: `result.h` + Since: `20.17.0` + Similar to: `std::expected` +{{< /callout >}} + +{{< callout type="warning">}} +**This class is deprecated.** +Use `etl::expected` as a replacement. +{{< /callout >}} + +A generic result type for returning either a result or an error. +Deprecated. Use etl::expected + +## result + +```cpp +template +class result +``` + +--- + +```cpp +template +class result +``` +**Description** +Specialisation for `void` `result`. + +--- + +```c++ +result() = delete; +``` +**Description** +Cannot be default constructed. + +--- + +```cpp +result(const result& other) +``` +**Description** +Copy constructor. + +--- + +```cpp +result(result&& other) +``` +**Description** +Move constructor. + +--- + +```cpp +result(const TValue& value) +``` +**Description** +Construct from a value. +Not valid for void specialisation. + +--- + +```cpp +result(TValue&& value) +``` +**Description** +Move construct from a value. +Not valid for void specialisation. + +--- + +```cpp +result(const TError& err) +``` +**Description** +Construct from error. + +--- + +```cpp +result(TError&& err) +``` +**Description** +Move construct from error. + +--- + +```cpp +result& operator =(const result& other) +``` +**Description** +Copy assign. + +--- + +```cpp +result& operator =(result&& other) +``` +**Description** +Move assign. + +--- + +```cpp +result& operator =(const TValue& value) +``` +**Description** +Copy assign from value. +Not valid for void specialisation. + +--- + +```cpp +result& operator =(TValue&& value) +``` +**Description** +Move assign from value. +Not valid for void specialisation. + +--- + +```cpp +result& operator =(const TError& err) +``` +**Description** +Copy assign from error. + +--- + +```cpp +result& operator =(TError&& err) +``` +**Description** +Move assign from error. + +--- + +```cpp +bool is_value() const +``` +**Description** +`true` if result contains a value. + +--- + +```cpp +bool is_error() const +``` +**Description** +`true` if result contains an error. + +--- + +```cpp +const TValue& value() const +``` +**Description** +Returns a const reference to the value. +Undefined if the result does not contain an value. +Not valid for void specialisation. + +--- + +```cpp +TValue&& value() +``` +**Description** +Returns an rvalue reference to the value. +Undefined if the result does not contain an value. +Not valid for void specialisation. + +--- + +```cpp +const TError& error() const +``` +**Description** +Returns a const reference to the error. +Undefined if the result does not contain an error. + +--- + +```cpp +TError&& error() +``` +**Description** +Returns an rvalue reference to the error. +Undefined if the result does not contain an error.