diff --git a/docs/raw/containers/poly_span.txt b/docs/containers/Views/poly_span.md similarity index 50% rename from docs/raw/containers/poly_span.txt rename to docs/containers/Views/poly_span.md index fdc9c294..16555eba 100644 --- a/docs/raw/containers/poly_span.txt +++ b/docs/containers/Views/poly_span.md @@ -1,43 +1,66 @@ -poly_span -20.31.0 +--- +title: "poly_span" +--- -This class implements a view in to a contiguous range through a base type. +{{< callout >}} + Header: `priority_queue.h` + Since: `20.31.0` +{{< /callout >}} +This class implements a view in to a contiguous range through a base type. + +```cpp etl::poly_span -____________________________________________________________________________________________________ -Template deduction guides +``` + +## Template deduction guides C++17 +```cpp template poly_span(const TIterator begin, const TIterator end) ->poly_span, etl::dynamic_extent>; +``` +```cpp template poly_span(const TIterator begin, const TSize size) ->poly_span, etl::dynamic_extent>; +``` +```cpp template poly_span(T(&)[N]) -> poly_span; +``` +```cpp template poly_span(etl::array&) -> poly_span; +``` +```cpp template poly_span(const etl::array&) -> poly_span; +``` +```cpp template poly_span(std::array&) ->poly_span; +``` +```cpp template poly_span(const std::array&) ->poly_span; -____________________________________________________________________________________________________ -Member types +``` +## Member types + +```cpp element_type T value_type remove_cv::type size_type size_t @@ -48,129 +71,235 @@ pointer value_type* const_pointer const value_type* iterator Random access iterator reverse_iterator ETL_OR_STD::reverse_iterator -____________________________________________________________________________________________________ -Constructors +``` +## Constructors + +```cpp ETL_CONSTEXPR poly_span() ETL_NOEXCEPT -____________________________________________________________________________________________________ +``` + +--- + +```cpp template ETL_CONSTEXPR poly_span(const TIterator begin, const TSize size) ETL_NOEXCEPT -Static asserts if etl::iterator_traits::iterator_category is not random_access_iterator_tag -or etl::iterator_traits::value_type is not the same as, or not derived from TBase. -____________________________________________________________________________________________________ +``` +Static asserts if `etl::iterator_traits::iterator_category` is not `random_access_iterator_tag` +or `etl::iterator_traits::value_type` is not the same as, or not derived from `TBase`. + +--- + +```cpp template ETL_CONSTEXPR poly_span(const TIterator begin, const TIterator end) -Static asserts if etl::iterator_traits::iterator_category is not random_access_iterator_tag -or etl::iterator_traits::value_type is not the same as, or not derived from TBase. -____________________________________________________________________________________________________ +``` +Static asserts if `etl::iterator_traits::iterator_category` is not `random_access_iterator_tag` +or `etl::iterator_traits::value_type` is not the same as, or not derived from `TBase`. + +--- + +```cpp template ETL_CONSTEXPR poly_span(U(&begin_)[N]) ETL_NOEXCEPT -Static asserts if N is greater than Extent or etl::iterator_traits::value_type is not the same as, -or not derived from TBase. -____________________________________________________________________________________________________ +``` +Static asserts if `N` is greater than `Extent` or `etl::iterator_traits::value_type` is not the same as, or not derived from `TBase`. + +--- + +```cpp template ETL_CONSTEXPR poly_span(etl::array& a) ETL_NOEXCEPT -Static asserts if N is greater than Extent or etl::iterator_traits::value_type is not the same as, -or not derived from TBase. -____________________________________________________________________________________________________ +``` +Static asserts if `N` is greater than `Extent` or `etl::iterator_traits::value_type` is not the same as, or not derived from `TBase`. + +--- + +```cpp template ETL_CONSTEXPR poly_span(const etl::array& a) ETL_NOEXCEPT -Static asserts if N is greater than Extent or etl::iterator_traits::value_type is not the same as, -or not derived from TBase. -____________________________________________________________________________________________________ +``` +Static asserts if `N` is greater than `Extent` or `etl::iterator_traits::value_type` is not the same as, or not derived from `TBase`. + +--- + +```cpp template ETL_CONSTEXPR poly_span(std::array& a) ETL_NOEXCEPT -Enabled if ETL_USING_CPP11 and ETL_USING_STL are true. -Static asserts if N is greater than Extent or etl::iterator_traits::value_type is not the same as, -or not derived from TBase. -____________________________________________________________________________________________________ +``` +Enabled if `ETL_USING_CPP11` and `ETL_USING_STL` are `true`. +Static asserts if `N` is greater than `Extent` or `etl::iterator_traits::value_type` is not the same as, or not derived from `TBase`. + +--- + +```cpp template ETL_CONSTEXPR poly_span(const std::array& a) ETL_NOEXCEPT -Enabled if ETL_USING_CPP11 and ETL_USING_STL are true. -Static asserts if N is greater than Extent or etl::iterator_traits::value_type is not the same as, -or not derived from TBase. -____________________________________________________________________________________________________ -ETL_CONSTEXPR poly_span(const poly_span& other) -Copy constructor. -____________________________________________________________________________________________________ -Access +``` +Enabled if `ETL_USING_CPP11` and `ETL_USING_STL` are `true`. +Static asserts if `N` is greater than `Extent` or `etl::iterator_traits::value_type` is not the same as, or not derived from `TBase`. +--- + +```cpp +ETL_CONSTEXPR poly_span(const poly_span& other) +``` +Copy constructor. + +## Access + +```cpp ETL_CONSTEXPR reference operator[](size_t i) const -Returns a reference to the indexed element. +``` +Returns a reference to the indexed element. Index out of range results in undefined behaviour. -____________________________________________________________________________________________________ + +--- + +```cpp ETL_NODISCARD ETL_CONSTEXPR reference front() const ETL_NOEXCEPT +``` Returns a reference to the first element. -____________________________________________________________________________________________________ + +--- + +```cpp ETL_NODISCARD ETL_CONSTEXPR reference back() const ETL_NOEXCEPT +``` Returns a reference to the last element. -____________________________________________________________________________________________________ + +--- + +```cpp ETL_NODISCARD ETL_CONSTEXPR pointer data() const ETL_NOEXCEPT +``` Returns a pointer to the first element. -____________________________________________________________________________________________________ + +--- + +```cpp ETL_CONSTEXPR14 poly_span& operator =(const poly_span& other) ETL_NOEXCEPT +``` Assign from a other span +--- + +```cpp template ETL_CONSTEXPR14 poly_span& operator =(const poly_span& other) ETL_NOEXCEPT -Assign from a other span -____________________________________________________________________________________________________ +``` +Assign from a other span. + +--- + +```cpp template ETL_NODISCARD ETL_CONSTEXPR etl::poly_span first() const -Returns a span consisting of the first COUNT elements of the current span. +``` +Returns a span consisting of the first `COUNT` elements of the current span. +--- + +```cpp ETL_NODISCARD ETL_CONSTEXPR etl::poly_span last(size_t count) const +``` Returns a span consisting of the last count elements of the current span. -____________________________________________________________________________________________________ + +--- + +```cpp template ETL_NODISCARD ETL_CONSTEXPR etl::poly_span last() const -Returns a span consisting of the last COUNT elements of the current span +```cpp +Returns a span consisting of the last `COUNT` elements of the current span +--- + +```cpp ETL_NODISCARD ETL_CONSTEXPR etl::poly_span first(size_t count) const +``` Returns a span consisting of the first count elements of the current span. -____________________________________________________________________________________________________ + +--- + +```cpp template ETL_NODISCARD ETL_CONSTEXPR etl::poly_span subspan() const -Returns a subspan consisting of the range starting at OFFSET for COUNT elements of the current span. +``` +Returns a subspan consisting of the range starting at `OFFSET` for `COUNT` elements of the current span. +--- + +```cpp ETL_NODISCARD ETL_CONSTEXPR etl::poly_span subspan(size_t offset, size_t count = etl::dynamic_extent) const -Returns a subspan consisting of the range starting at offset for count elements of the current span. -____________________________________________________________________________________________________ -Iterators +``` +Returns a subspan consisting of the range starting at `offset` for `count` elements of the current span. +## Iterators + +```cpp ETL_NODISCARD ETL_CONSTEXPR iterator begin() const ETL_NOEXCEPT +``` Returns an iterator to the beginning of the span. -____________________________________________________________________________________________________ + +--- + +```cpp ETL_NODISCARD ETL_CONSTEXPR iterator end() const ETL_NOEXCEPT +``` Returns an iterator to the end of the span. -____________________________________________________________________________________________________ + +--- + +```cpp ETL_NODISCARD ETL_CONSTEXPR iterator rbegin() const ETL_NOEXCEPT +``` Returns a reverse iterator to the beginning of the span. -____________________________________________________________________________________________________ + +--- + +```cpp ETL_NODISCARD ETL_CONSTEXPR iterator rend() const ETL_NOEXCEPT +``` Returns a reverse iterator to the end of the span. -____________________________________________________________________________________________________ -Capacity +## Capacity + +```cpp ETL_NODISCARD ETL_CONSTEXPR bool empty() const ETL_NOEXCEPT +``` Returns true if the size of the span is zero, otherwise false. -____________________________________________________________________________________________________ + +--- + +```cpp ETL_NODISCARD ETL_CONSTEXPR size_t size() const ETL_NOEXCEPT +``` Returns the size of the span. -____________________________________________________________________________________________________ + +--- + +```cpp ETL_NODISCARD ETL_CONSTEXPR size_t size_bytes() const ETL_NOEXCEPT +``` Returns the size of the span in bytes. -____________________________________________________________________________________________________ + +--- + +```cpp ETL_NODISCARD ETL_CONSTEXPR size_t size_of_element() const ETL_NOEXCEPT +``` Returns the size of the elements pointed to by the span, in bytes. -____________________________________________________________________________________________________ -Non-member functions -Hash -There is a specialisation of etl::hash for etl::poly_span -____________________________________________________________________________________________________ -Example +## Non-member functions +### Hash +There is a specialisation of `etl::hash` for `etl::poly_span`. + +--- + +### Example +```cpp struct Base { virtual ~Base() {} @@ -200,4 +329,4 @@ for (const Base& b : ps) { b.Print(); } - +``` diff --git a/docs/raw/containers/span.txt b/docs/containers/Views/span.md similarity index 54% rename from docs/raw/containers/span.txt rename to docs/containers/Views/span.md index d9a71166..fe4b30ed 100644 --- a/docs/raw/containers/span.txt +++ b/docs/containers/Views/span.md @@ -1,45 +1,69 @@ -span +--- +title: "span" +--- -This class implements a view in to a range of a C array, etl::array, std::array, etl::vector and std::vector. It will support construction from any class that supports data() and size() member functions as well as plain C arrays. +{{< callout >}} + Header: `span.h` + Similar to: `std::span` +{{< /callout >}} -The ETL's span adds the ability to access circular iterators that will loop through the span when the beginning or end is reached. 20.34.0 +This class implements a view in to a range of a C array, `etl::array`, `std::array`, `etl::vector` and `std::vector`. +It will support construction from any class that supports `data()` and `size()` member functions as well as plain C arrays. -STL equivalent: std::span. +Since: `20.34.0` +The ETL's span adds the ability to access circular iterators that will loop through the span when the beginning or end is reached. +```cpp etl::span -____________________________________________________________________________________________________ -Template deduction guides +``` + +## Template deduction guides C++17 +```cpp template span(const TIterator begin, const TIterator end) ->span, etl::dynamic_extent>; +``` +```cpp template span(const TIterator begin, const TSize size) ->span, etl::dynamic_extent>; +``` +```cpp template span(T(&)[N]) -> span; +``` +```cpp template span(etl::array&) -> span; +``` +```cpp template span(const etl::array&) -> span; +``` +```cpp template span(std::array&) ->span; +``` +```cpp template span(const std::array&) ->span; +``` -Examples +### Examples +```cpp etl::array data{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 }; etl::span span1{ data }; @@ -49,9 +73,11 @@ etl::span span4{ span1 }; int c_array[] = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 }; etl::span span5{ c_array }; -____________________________________________________________________________________________________ -Member types +``` +## Member types + +```cpp element_type T value_type remove_cv::type size_type size_t @@ -64,145 +90,288 @@ iterator A random access iterator reverse_iterator A reverse random access iterator circular_iterator A circular random access iterator 20.34.0 circular_reverse_iterator A reverse circular random access iterator 20.34.0 -____________________________________________________________________________________________________ -Constructors +``` +## Constructors + +```cpp ETL_CONSTEXPR span() +``` +**Description** Default constructor. -____________________________________________________________________________________________________ + +--- + +```cpp template ETL_CONSTEXPR span(TIterator begin, TIterator end) +``` +**Description** Construct from an iterator or pointer range. -____________________________________________________________________________________________________ + +--- + +```cpp template ETL_CONSTEXPR span(TIterator begin, TSize size) +``` +**Description** Construct from a start and size -___________________________________________________________________________________________________ + +--- + +```cpp template ETL_CONSTEXPR explicit span(element_type(&begin)[ARRAY_SIZE]) +``` +**Description** Construct from a compile time sized C array. -____________________________________________________________________________________________________ + +--- + +```cpp template ETL_CONSTEXPR span(etl::array& a) ETL_NOEXCEPT +``` +**Description** Construct from an ETL array. -____________________________________________________________________________________________________ + +--- + +```cpp template ETL_CONSTEXPR span(const etl::array& a) ETL_NOEXCEPT +``` +**Description** Construct from a const ETL array. -____________________________________________________________________________________________________ + +--- + +```cpp template ETL_CONSTEXPR span(std::array& a) ETL_NOEXCEPT -Enabled if ETL_USING_CPP11 and ETL_USING_STL are true. +``` +**Description** +Enabled if `ETL_USING_CPP11` and `ETL_USING_STL` are `true`. Construct from an STL array. -____________________________________________________________________________________________________ + +--- + +```cpp template ETL_CONSTEXPR span(const std::array& a) ETL_NOEXCEPT -Enabled if ETL_USING_CPP11 and ETL_USING_STL are true. +``` +**Description** +Enabled if `ETL_USING_CPP11` and `ETL_USING_STL` are `true`. Construct from a const STL array. -____________________________________________________________________________________________________ + +--- + +```cpp ETL_CONSTEXPR span(const span& other) ETL_NOEXCEPT +``` +**Description** Copy constructor. -____________________________________________________________________________________________________ + +--- + +```cpp template ETL_CONSTEXPR span(const etl::span& other) ETL_NOEXCEPT -____________________________________________________________________________________________________ -Access +``` +## Access + +```cpp ETL_CONSTEXPR reference operator[](size_t i) const -Returns a reference to the indexed element. +``` +**Description** +Returns a reference to the indexed element. Index out of range results in undefined behaviour. -____________________________________________________________________________________________________ + +--- + +```cpp ETL_NODISCARD ETL_CONSTEXPR reference front() const ETL_NOEXCEPT +``` +**Description** Returns a reference to the first element. -____________________________________________________________________________________________________ + +--- + +```cpp ETL_NODISCARD ETL_CONSTEXPR reference back() const ETL_NOEXCEPT +``` +**Description** Returns a reference to the last element. -____________________________________________________________________________________________________ + +--- + +```cpp ETL_NODISCARD ETL_CONSTEXPR pointer data() const ETL_NOEXCEPT +``` +**Description** Returns a pointer to the first element. -____________________________________________________________________________________________________ + +--- + +```cpp ETL_CONSTEXPR14 span& operator =(const span& other) ETL_NOEXCEPT +``` +**Description** Assign from a other span -____________________________________________________________________________________________________ + +--- + +```cpp template ETL_NODISCARD ETL_CONSTEXPR etl::span first() const -Returns a span consisting of the first COUNT elements of the current span -____________________________________________________________________________________________________ +``` +**Description** +Returns a span consisting of the first `COUNT` elements of the current span + +--- + +```cpp template ETL_NODISCARD ETL_CONSTEXPR etl::span last() const -Returns a span consisting of the last COUNT elements of the current span -____________________________________________________________________________________________________ +``` +**Description** +Returns a span consisting of the last `COUNT` elements of the current span + +--- + +```cpp template ETL_NODISCARD ETL_CONSTEXPR etl::span subspan() const -Returns a subspan consisting of the range starting at OFFSET for COUNT elements of the current span -____________________________________________________________________________________________________ -Iterators +``` +**Description** +Returns a subspan consisting of the range starting at `OFFSET` for `COUNT` elements of the current span +## Iterators + +```cpp ETL_NODISCARD ETL_CONSTEXPR iterator begin() const ETL_NOEXCEPT +``` +**Description** Returns an iterator to the beginning of the span. -____________________________________________________________________________________________________ + +--- + +```cpp ETL_NODISCARD ETL_CONSTEXPR circular_iterator begin_circular() const ETL_NOEXCEPT -Returns a circular iterator to the beginning of the span. -20.34.0 -____________________________________________________________________________________________________ +``` +**Description** +Returns a circular iterator to the beginning of the span. +Since: `20.34.0` + +--- + +```cpp ETL_NODISCARD ETL_CONSTEXPR iterator end() const ETL_NOEXCEPT +``` +**Description** Returns an iterator to the end of the span. -____________________________________________________________________________________________________ + +--- + +```cpp ETL_NODISCARD ETL_CONSTEXPR iterator rbegin() const ETL_NOEXCEPT +``` +**Description** Returns a reverse iterator to the beginning of the span. -____________________________________________________________________________________________________ + +--- + +```cpp ETL_NODISCARD ETL_CONSTEXPR reverse_circular_iterator rbegin_circular() const ETL_NOEXCEPT -Returns a reverse circular iterator to the beginning of the span. -20.34.0 -____________________________________________________________________________________________________ +``` +**Description** +Returns a reverse circular iterator to the beginning of the span. +Since: `20.34.0` + +--- + +```cpp ETL_NODISCARD ETL_CONSTEXPR iterator rend() const ETL_NOEXCEPT +``` +**Description** Returns a reverse iterator to the end of the span. -____________________________________________________________________________________________________ -Capacity +## Capacity + +```cpp ETL_NODISCARD ETL_CONSTEXPR bool empty() const ETL_NOEXCEPT -Returns true if the size of the span is zero, otherwise false. -____________________________________________________________________________________________________ -ETL_NODISCARD ETL_CONSTEXPR size_t size() const ETL_NOEXCEPT -Returns the size of the span. -____________________________________________________________________________________________________ -ETL_NODISCARD ETL_CONSTEXPR size_t size_bytes() const ETL_NOEXCEPT -Returns the size of the span in bytes. -____________________________________________________________________________________________________ -Non-member functions +``` +**Description** +Returns `true` if the size of the span is zero, otherwise `false`. +--- + +```cpp +ETL_NODISCARD ETL_CONSTEXPR size_t size() const ETL_NOEXCEPT +``` +**Description** +Returns the size of the span. + +--- + +```cpp +ETL_NODISCARD ETL_CONSTEXPR size_t size_bytes() const ETL_NOEXCEPT +``` +**Description** +Returns the size of the span in bytes. + +## Non-member functions + +```cpp template ETL_NODISCARD ETL_CONSTEXPR bool operator ==(const etl::span& lhs, const etl::span& rhs) ETL_NOEXCEPT -20.35.12 -Compare two spans for equality. -Returns true if they both point to the same range of data. -____________________________________________________________________________________________________ +``` +**Description** +Compare two spans for equality. +Returns true if they both point to the same range of data. +Since: `20.35.12` + +--- + +```cpp template ETL_NODISCARD ETL_CONSTEXPR bool operator !=(const etl::span& lhs, const etl::span& rhs) ETL_NOEXCEPT -20.35.12 -Compare two spans for inequality. -Returns true if they don't both point to the same range of data. -____________________________________________________________________________________________________ +``` +**Description** +Compare two spans for inequality. +Returns true if they don't both point to the same range of data. +Since: `20.35.12` + +--- + +```cpp template bool equal(const etl::span& lhs, const etl::span& rhs) -20.35.12 -Equality function. -Performs a comparision of the range values. -Returns true if one of the following are true -1. Both spans are empty. -2. They both point to the same range of data. -3. The values in the two ranges are equal. -____________________________________________________________________________________________________ -Hash -There is a specialisation of etl::hash for etl::span -____________________________________________________________________________________________________ -Example +``` +**Description** +Equality function. +Performs a comparision of the range values. +Returns `true` if one of the following are `true` +1. Both spans are empty. +2. They both point to the same range of data. +3. The values in the two ranges are equal. -Iterating through a span and subspan. +Since: `20.35.12` + +## Hash +There is a specialisation of etl::hash for etl::span + +### Example + +**Iterating through a span and subspan.** + +```cpp etl::array data = { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 }; using View = etl::span; View view(data.begin() + 2, data.end() - 2); @@ -222,8 +391,11 @@ auto subview = view.subspan<2, 3>(); Print(subview); // Prints "5 6 7" size_t hashvalue = etl::hash()(view); -____________________________________________________________________________________________________ -Looping a span. +``` + +**Looping a span.** + +```cpp etl::array data = { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 }; using View = etl::span; View view(data.begin(), data.end()); @@ -235,4 +407,4 @@ for (int i; i < 1000; ++i) { Print(*itr++); } - +``` diff --git a/docs/containers/arrays/array.md b/docs/containers/arrays/array.md index bcb83946..540c2e4f 100644 --- a/docs/containers/arrays/array.md +++ b/docs/containers/arrays/array.md @@ -16,8 +16,9 @@ Adds additional members functions, `assign`, `insert` & `erase`. etl::array ``` -See also -[array_view]() +See also: +[array_view]({{< relref "array_view" >}}) +[multi_array]({{< relref "multi_array" >}}) ## Template deduction guides **C++17 and above** diff --git a/docs/containers/arrays/multi_array.md b/docs/containers/arrays/multi_array.md new file mode 100644 index 00000000..c052a1ba --- /dev/null +++ b/docs/containers/arrays/multi_array.md @@ -0,0 +1,38 @@ +--- +title: "multi_array" +--- + +{{< callout >}} + Header: `multi_array.h` +{{< /callout >}} + +A fixed capacity multi-dimensional array. + +For C++11 or greater only. + +```cpp +etl::multi_array +``` + +See also: +[array]({{< relref "array" >}}) +[array_view]({{< relref "array_view" >}}) + +## Description + +The `etl::multi_array` class is defined as a recursive variadic template. +It defines a multi-dimensional array class based on nested etl::array definitions. + +## Example + +```cpp +etl::multi_array +``` + +is equivalent to + +```cpp +etl::array, 3>, 2> +``` + +Each dimension of an `etl::multi_array` supports all of the members of an `etl::array`. diff --git a/docs/containers/queues/priority_queue.md b/docs/containers/queues/priority_queue.md new file mode 100644 index 00000000..4f9cb271 --- /dev/null +++ b/docs/containers/queues/priority_queue.md @@ -0,0 +1,134 @@ +--- +title: "priority_queue" +--- + +{{< callout >}} + Header: `priority_queue.h` + Similar to: `std::priority_queue` +{{< /callout >}} + +A fixed capacity priority queue. + +```cpp +etl::priority_queue +``` + +Inherits from `etl::ipriority_queue` +`etl::ipriority_queue` may be used as a size independent pointer or reference type for any `etl::priority_queue` instance. + +## Member types +```cpp +value_type T +size_type std::size_t +``` + +## Constructor + +```cpp +etl::priority_queue(); +``` + +## Element access + +```cpp +T& top() +const T& top() const +``` +**Description** +Returns a reference or const reference to the first element. +Undefined behaviour if the queue is empty. + +## Capacity +```cpp +bool empty() const +``` +**Description** +Returns `true` if the size of the queue is zero, otherwise `false`. + +--- + +```cpp +bool full() const +``` +**Description** +Returns `true` if the size of the queue is SIZE, otherwise `false`. + +--- + +```cpp +size_t size() const +``` +**Description** +Returns the size of the queue. + +--- + +```cpp +size_t available() const +``` +**Description** +Returns the remaining available capacity in the queue. + +--- + +```cpp +size_t max_size() const +``` +**Description** +Returns the maximum possible size of the queue. + +--- + +```cpp +size_t capacity() const +``` +**Description** +Returns the maximum possible size of the queue. + +## Modifiers + +```cpp +void push(const T& value); +void push(T&& value); +``` +**Description** +Pushes a value to the queue. +If the queue is full then emits an `etl::queue_full error`. +If asserts or exceptions are not enabled then undefined behaviour occurs. + +--- + +**C++03** +```cpp +void emplace(const T1& value1); +void emplace(const T1& value1, const T2& value2); +void emplace(const T1& value1, const T2& value2, const T3& value3); +void emplace(const T1& value1, const T2& value2, const T3& value3, const T4& value4); +``` + +**C++11** +```cpp +void emplace(Args&&… args); +``` +**Description** +Constructs an item in the the queue 'in place'. +C++03: Supports up to four constructor parameters. +Emits an `etl::queue_full` if the queue is full and `ETL_CHECK_PUSH_POP` is defined. +If asserts or exceptions are not enabled then undefined behaviour occurs. + +--- + +```cpp +void pop(); +``` +**Description** +Pop a value from the front of the list. +Undefined behaviour if the queue is empty. + +--- + +```cpp +void clear(); +``` +**Description** +Clears the queue to a size of zero. diff --git a/docs/containers/stack.md b/docs/containers/stack.md new file mode 100644 index 00000000..42216a11 --- /dev/null +++ b/docs/containers/stack.md @@ -0,0 +1,155 @@ +--- +title: "stack" +--- + +{{< callout >}} + Header: `stack.h` + Similar to: `std::stack` +{{< /callout >}} + +A fixed capacity stack. + +```cpp +etl::stack +``` + +Inherits from `etl::istack` +`etl::istack` may be used as a size independent pointer or reference type for any `etl::stack` instance. + +## Member types + +```cpp +value_type T +size_type std::size_t +``` + +## Constructor + +```cpp +etl::stack(); +``` +**Description** +Default constructs `SIZE` elements. + +## Element access + +```cpp +T& top() +const T& top() const +``` +**Description** +Returns a reference or const reference to the element at the top of the stack. +Undefined behaviour if the stack is empty. + +## Capacity +```cpp +bool empty() const +``` +**Description** +Returns `true` if the size of the stack is zero, otherwise `false`. + +--- + +```cpp +bool full() const +``` +**Description** +Returns `true` if the size of the stack is `SIZE`, otherwise `false`. + +--- + +```cpp +size_t size() const +``` +**Description** +Returns the size of the stack. + +--- + +```cpp +size_t available() const +``` +**Description** +Returns the remaining available capacity in the stack. + +--- + +```cpp +size_t max_size() const +``` +**Description** +Returns the maximum possible size of the stack. + +--- + +```cpp +size_t capacity() const +``` +**Description** +Returns the maximum possible size of the stack. + +## Modifiers + +```cpp +void push(parameter_t value); +``` +**Description** +Pushes a value to the top of the stack. +Emits an `etl::stack_full` if the stack is full and `ETL_CHECK_PUSH_POP` is defined. +If asserts or exceptions are not enabled undefined behaviour occurs. + +--- + +C++03 +```cpp +void emplace(const T1& value1); +void emplace(const T1& value1, const T2& value2); +void emplace(const T1& value1, const T2& value2, const T3& value3); +void emplace(const T1& value1, const T2& value2, const T3& value3, const T4& value4); +``` + +C++11 +```cpp +void emplace(Args&&… args); +``` +**Description** +Constructs an item in the the stack 'in place'. +Supports up to four constructor parameters. +Emits an `etl::stack_full` if the stack is full and `ETL_CHECK_PUSH_POP` is defined. +If asserts or exceptions are not enabled undefined behaviour occurs. + +--- + +```cpp +void pop(); +``` +**Description** +Pop a value from the top of the stack. +Emits an `etl::stack_empty` if the stack is empty and `ETL_CHECK_PUSH_POP` is defined. +If asserts or exceptions are not enabled undefined behaviour occurs. + +--- + +```cpp +void pop_into(const T& destination); +``` +**Description** +Pop a value from the top of the stack and places it in destination. +Emits an `etl::stack_empty` if the queue is empty and `ETL_CHECK_PUSH_POP` is defined. +If asserts or exceptions are not enabled undefined behaviour occurs. + +--- + +```cpp +void reverse(); +``` +**Description** +Reverses the stack order. + +--- + +```cpp +void clear(); +``` +**Description** +Clears the stack to a size of zero. diff --git a/docs/raw/containers/multi_array.txt b/docs/raw/containers/multi_array.txt deleted file mode 100644 index 2d7bb2df..00000000 --- a/docs/raw/containers/multi_array.txt +++ /dev/null @@ -1,27 +0,0 @@ -multi_array - -A fixed capacity multi-dimensional array. -STL equivalent: None - -For C++11 or greater only. - -etl::multi_array - -See also -array -____________________________________________________________________________________________________ -Description - -The etl::multi_array class is defined as a recursive variadic template. -It defines a multi-dimensional array class based on nested etl::array definitions. - -Example - -etl::multi_array - -is equivalent to - -etl::array, 3>, 2> - -Each dimension of an etl::multi_array supports all of the members of an etl::array. - diff --git a/docs/raw/containers/packet.txt b/docs/raw/containers/packet.txt deleted file mode 100644 index 0995b661..00000000 --- a/docs/raw/containers/packet.txt +++ /dev/null @@ -1,60 +0,0 @@ -packet - -A class that can contain one of several related types. -STL equivalent: none - -etl::packet - -TBase The base class for all objects. The destructor must be virtual. -SIZE The size of the largest type. -ALIGNMENT The largest alignment of all of the types. - -____________________________________________________________________________________________________ -Member types - -base_t TBase - -____________________________________________________________________________________________________ -Contructor - -C++03 -template -explicit packet(const T& value) - -C++11 -template -explicit packet(T&& value) - -Constructs an object of type T with the supplied value. -Static asserts on any type that does not derive from TBase. -Static asserts on any type that does not conform to the maximum size and alignment. - -____________________________________________________________________________________________________ -Destructor - -~packet() - -Destructs the contained object - -____________________________________________________________________________________________________ -Operator - -C++03 -template -packet& operator =(const T& value) - -C++11 -template -packet& operator =(T&& value) - -Assigns a new object to the packet. -The previous object is destructed. - -____________________________________________________________________________________________________ -Access - -const TBase& get() const - -Returns a const reference to the contained object. - - diff --git a/docs/raw/containers/stack.txt b/docs/raw/containers/stack.txt deleted file mode 100644 index 116b87c6..00000000 --- a/docs/raw/containers/stack.txt +++ /dev/null @@ -1,108 +0,0 @@ -stack - -A fixed capacity stack. -STL equivalent: std::stack - -etl::stack - -Inherits from etl::istack -etl::istack may be used as a size independent pointer or reference type for any etl::stack instance. - -____________________________________________________________________________________________________ -Member types - -value_type T -size_type std::size_t - -____________________________________________________________________________________________________ -Constructor - -etl::stack(); - -Default constructs SIZE elements. - -____________________________________________________________________________________________________ -Element access - -T& top() -const T& top() const - -Returns a reference or const reference to the element at the top of the stack. -Undefined behaviour if the stack is empty. - -____________________________________________________________________________________________________ -Capacity - -bool empty() const - -Returns true if the size of the stack is zero, otherwise false. -____________________________________________________________________________________________________ - -bool full() const - -Returns true if the size of the stack is SIZE, otherwise false. -____________________________________________________________________________________________________ - -size_t size() const - -Returns the size of the stack. -____________________________________________________________________________________________________ - -size_t available() const - -Returns the remaining available capacity in the stack. -____________________________________________________________________________________________________ - -size_t max_size() const - -Returns the maximum possible size of the stack. -____________________________________________________________________________________________________ - -size_t capacity() const - -Returns the maximum possible size of the stack. - -____________________________________________________________________________________________________ -Modifiers - -void push(parameter_t value); - -Pushes a value to the top of the stack. -Emits an etl::stack_full if the stack is full and ETL_CHECK_PUSH_POP is defined. If asserts or exceptions are not enabled undefined behaviour occurs. -____________________________________________________________________________________________________ - -C++03 -void emplace(const T1& value1); -void emplace(const T1& value1, const T2& value2); -void emplace(const T1& value1, const T2& value2, const T3& value3); -void emplace(const T1& value1, const T2& value2, const T3& value3, const T4& value4); - -C++11 -void emplace(Args&&… args); - -Constructs an item in the the stack 'in place'. -Supports up to four constructor parameters. -Emits an etl::stack_full if the stack is full and ETL_CHECK_PUSH_POP is defined. If asserts or exceptions are not enabled undefined behaviour occurs. -____________________________________________________________________________________________________ - -void pop(); - -Pop a value from the top of the stack. -Emits an etl::stack_empty if the stack is empty and ETL_CHECK_PUSH_POP is defined. If asserts or exceptions are not enabled undefined behaviour occurs. -____________________________________________________________________________________________________ - -void pop_into(const T& destination); - -Pop a value from the top of the stack and places it in destination. -Emits an etl::stack_empty if the queue is empty and ETL_CHECK_PUSH_POP is defined. If asserts or exceptions are not enabled undefined behaviour occurs. -____________________________________________________________________________________________________ - -void reverse(); - -Reverses the stack order. -____________________________________________________________________________________________________ - -void clear(); - -Clears the stack to a size of zero. - diff --git a/docs/raw/containers/vector.txt b/docs/raw/containers/vector.txt deleted file mode 100644 index fe9f4891..00000000 --- a/docs/raw/containers/vector.txt +++ /dev/null @@ -1,291 +0,0 @@ -vector - -A fixed capacity vector. -STL equivalent: std::vector - -etl::vector -etl::vector_ext - -Inherits from etl::ivector -etl::ivector may be used as a size independent pointer or reference type for any etl::vector instance. - -There is a specialisation for pointers that means that just one instantiation of code for all pointer types. -The one caveat is that etl::vector cannot directly store pointers to member functions. They must be wrapped in either a custom struct, one of the etl::function or etl::deletgate templates, or std::function. - -Has the ability to be copied by low level functions such as memcpy by use of a repair() function. -See the function reference for an example of use. - -Unlike std::vector, An iterator to an etl::vector element is never invalidated by a call to resize(). - -The size of the instance will be (SIZE * sizeof(T)) + (2 * sizeof(size_t)) + sizeof(T*) -For a 32 bit environment the overhead (compared to an array) will usually be 12 bytes. -____________________________________________________________________________________________________ -External buffer - -etl::vector_ext -With this template the constructor expects pointer and size parameters to the externally provided buffer. This buffer must not be shared concurrently with any other vector. -When a vector with an external buffer is moved, the data is moved, not the pointer to the buffer. -____________________________________________________________________________________________________ -Template deduction guides -C++17 and above - -template -etl::vector(T...) - -template -etl::vector(T*...) - -Example -etl::vector data{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 }; - -Defines data as an vector of int, of length 10, containing the supplied data. -____________________________________________________________________________________________________ -Member types - -value_type T -size_type size_t -difference_type ptrdiff_t -reference value_type& -const_reference const value_type& -rvalue_reference value_type&& -pointer value_type* -const_pointer const value_type* -iterator Random access iterator -const_iterator Constant random access iterator -reverse_iterator ETL_OR_STD::reverse_iterator -const_reverse_iterator ETL_OR_STD::reverse_iterator -____________________________________________________________________________________________________ -Constructor - -Internal buffer -etl::vector(); -etl::vector(size_t initialSize); -etl::vector(size_t initialSize, const T& value); - -template -etl::vector(TIterator begin, TIterator end); - -etl::vector(const etl::vector&); -etl::vector(etl::vector&&); - -External buffer -etl::vector(void* buffer, size_t max_size); -etl::vector(size_t initialSize, void* buffer, size_t max_size); -etl::vector(size_t initialSize, const T& value, void* buffer, size_t max_size); - -template -etl::vector(TIterator begin, TIterator end, void* buffer, size_t max_size); - -etl::vector(const etl::vector&, void* buffer, size_t max_size); - -etl::vector(etl::vector&&, void* buffer, size_t max_size); -If the vector is full then emits an etl::vector_full. If asserts or exceptions are not enabled then undefined behaviour occurs. -____________________________________________________________________________________________________ -Element access - -T& at(size_t i) -const T& at(size_t i) const -Returns a reference or const reference to the indexed element. Emits an etl::vector_out_of_range if the index is out of range of the array. If asserts or exceptions are not enabled then undefined behaviour occurs. -____________________________________________________________________________________________________ -T& operator[](size_t i) -const T& operator[](size_t i) const -Returns a reference or const reference to the indexed element. -if the index is out of range of the array then undefined behaviour occurs. -____________________________________________________________________________________________________ -T& front() -const T& front() const -Returns a reference or const reference to the first element. -Undefined behaviour if the vector is empty. -____________________________________________________________________________________________________ -T& back() -const T& back() const -Returns a reference or const reference to the last element. -Undefined behaviour if the vector is empty. -____________________________________________________________________________________________________ -T* data() -const T* data() const -Returns a pointer or const pointer to the internal buffer. -____________________________________________________________________________________________________ -Iterators - -iterator begin() -const_iterator begin() const -const_iterator cbegin() const -Returns an iterator to the beginning of the vector. -____________________________________________________________________________________________________ -iterator end() -const_iterator end() const -const_iterator cend() const -Returns an iterator to the end of the vector. -____________________________________________________________________________________________________ -iterator rbegin() -const_reverse_iterator rbegin() const -const_reverse_iterator crbegin() const -Returns a reverse iterator to the beginning of the vector. -____________________________________________________________________________________________________ -iterator rend() -const_reverse_iterator rend() const -const_reverse_iterator crend() const -Returns a reverse iterator to the end of the vector. -____________________________________________________________________________________________________ -Capacity - -bool empty() const -Returns true if the size of the vector is zero, otherwise false. -____________________________________________________________________________________________________ -bool full() const -Returns true if the size of the vector is SIZE, otherwise false. -____________________________________________________________________________________________________ -size_t size() const -Returns the size of the vector. -____________________________________________________________________________________________________ -void resize(size_t new_size, const_reference value = T()) -Resizes the vector, up to the maximum capacity. Emits an etl::vector_full if the vector does not have the capacity. -____________________________________________________________________________________________________ -void uninitialized_resize(size_t new_size) -20.4.0 -Resizes the vector, up to the maximum capacity, without initialising the new elements. -____________________________________________________________________________________________________ -size_t max_size() const -Returns the maximum possible size of the vector. -____________________________________________________________________________________________________ -size_t capacity() const -Returns the maximum possible size of the vector. -____________________________________________________________________________________________________ -size_t available() const -Returns the remaining available capacity in the vector. -____________________________________________________________________________________________________ -Modifiers - -template -void assign(TIterator begin, TIterator end); - -void assign(size_t n, const T& value); -Fills the vector with the values. Emits etl::vector_iterator if the distance between begin and end is illegal. -(debug mode only). If asserts or exceptions are not enabled undefined behaviour occurs. -____________________________________________________________________________________________________ -void push_back(const T& value); -void push_back(T&& value); -Pushes a value to the back of the vector. -If the vector is full then emits an etl::vector_full. If asserts or exceptions are not enabled undefined behaviour occurs. -____________________________________________________________________________________________________ -C++03 -void emplace(); 20.38.0 -void emplace(const T1& value1); -void emplace(const T1& value1, const T2& value2); -void emplace(const T1& value1, const T2& value2, const T3& value3); -void emplace(const T1& value1, const T2& value2, const T3& value3, const T4& value4); - -C++11 -template -void emplace(Args&&… args); -Constructs an item at the back of the the vector 'in place'. -Supports up to four constructor parameters. -Pushes a value to the back of the vector. The first pushes a value, the second allocates the new element but does not initialise it. -If the vector is full then emits an etl::vector_full. If asserts or exceptions are not enabled undefined behaviour occurs. -____________________________________________________________________________________________________ -C++03 -<=20.35.9 -void emplace_back(const T1& value1); -void emplace_back(const T1& value1, const T2& value2); -void emplace_back(const T1& value1, const T2& value2, const T3& value3); -void emplace_back(const T1& value1, const T2& value2, const T3& value3, const T4& value4); - ->=20.35.10 -reference emplace_back(); 20.38.0 -reference emplace_back(const T1& value1); -reference emplace_back(const T1& value1, const T2& value2); -reference emplace_back(const T1& value1, const T2& value2, const T3& value3); -reference emplace_back(const T1& value1, const T2& value2, const T3& value3, const T4& value4); - -C++11 -<=20.35.9 -template -void emplace_back(Args&&... args); ->=20.35.10 -template -reference emplace_back(Args&&... args); -Constructs an item at the back of the the vector 'in place'. -Supports up to four constructor parameters. -Pushes a value to the back of the vector. -If the vector is full then emits an etl::vector_full. If asserts or exceptions are not enabled undefined behaviour occurs. -____________________________________________________________________________________________________ -void pop_back(); -Pop a value from the back of the vector. -If the vector is empty and ETL_CHECK_PUSH_POP is defined then emits an etl::vector_empty. If asserts or exceptions are not enabled undefined behaviour occurs. -____________________________________________________________________________________________________ -<=20.19.0 -template -void insert(iterator position, TIterator begin, TIterator end); - -iterator insert(iterator position, const T& value); -iterator insert(iterator position, T&& value); -void insert(iterator position, size_t n, const T& value); - ->=20.20.0 -template -iterator insert(const_iterator position, TIterator begin, TIterator end); - -iterator insert(const_iterator position, const T& value); -iterator insert(const_iterator position, T&& value); -iterator insert(const_iterator position, size_t n, const T& value); -Inserts values in to the vector. -If the vector is full then emits an etl::vector_full exception. If asserts or exceptions are not enabled undefined behaviour occurs. -____________________________________________________________________________________________________ -template -iterator erase(TIterator begin, TIterator end); - -iterator erase(iterator position); -Erases values in the vector. -Iterators are not checked. -____________________________________________________________________________________________________ -void clear() -Clears the vector to a size of zero. -____________________________________________________________________________________________________ -void fill(value_type value) -Fill the current size of the buffer with value -20.24.0 -____________________________________________________________________________________________________ -void repair() -This function must be called if the vector has been copied via a low level method such as memcpy. -This can only be called from an etl::vector instance, unless ETL_IVECTOR_REPAIR_ENABLE is defined. Be aware that doing so introduces a virtual function to the class. - -Has no effect if the object has not been copied in this way. - -NOTE: -The contained type must be trivially copyable. -Compilers that satisfy the C++11 type traits support check in platform.h will generate an assert if the type is incompatible. - -Example: -typedef etl::vector Data; - -Data data(8, 1); -char buffer[sizeof(Data)]; - -memcpy(&buffer, &data, sizeof(Data)); - -Data& rdata(*reinterpret_cast(buffer)); - -// Do not access the copied object in any way until you have called this. -rdata.repair(); -____________________________________________________________________________________________________ -Non-member functions -____________________________________________________________________________________________________ -erase -template -typename etl::ivector::difference_type erase(etl::ivector& v, const U& value) -Erases all elements that compare equal to value from the vector. - -template -typename etl::ivector::difference_type erase_if(etl::ivector& v, TPredicate predicate) -Erases all elements that satisfy the predicate from the vector. -____________________________________________________________________________________________________ -Operators -== true if the contents of the vectors are equal, otherwise false. -!= true if the contents of the vectors are not equal, otherwise false. -< true if the contents of the lhs are lexicographically less than the contents of the rhs, otherwise false. -<= true if the contents of the lhs are lexicographically less than or equal to the contents of the rhs, otherwise false. -> true if the contents of the lhs are lexicographically greater than the contents of the rhs, otherwise ffalsealse. ->= true if the contents of the lhs are lexicographically greater than or equal to the contents of the rhs, otherwise false. - -