coffee/etl
1
0
Fork 0
mirror of https://github.com/ETLCPP/etl.git synced 2026-06-15 08:26:04 +08:00
Code Issues Packages Projects Releases Wiki Activity

More documentation updates

Browse Source
This commit is contained in:
John Wellbelove 2026-05-14 00:05:35 +01:00
parent 0d709324bd
commit 06ccda00f6
10 changed files with 779 additions and 636 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

263
docs/raw/containers/poly_span.txt → docs/containers/Views/poly_span.md
View File

@ -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<typename TBase, size_t Extent = etl::dynamic_extent>
____________________________________________________________________________________________________
Template deduction guides
```
## Template deduction guides
C++17
```cpp
template <typename TIterator>
poly_span(const TIterator begin, const TIterator end)
->poly_span<etl::remove_pointer_t<TIterator>, etl::dynamic_extent>;
```
```cpp
template <typename TIterator, typename TSize>
poly_span(const TIterator begin, const TSize size)
->poly_span<etl::remove_pointer_t<TIterator>, etl::dynamic_extent>;
```
```cpp
template <typename T, size_t N>
poly_span(T(&)[N])
-> poly_span<T, N>;
```
```cpp
template <typename T, size_t N>
poly_span(etl::array<T, N>&)
-> poly_span<T, N>;
```
```cpp
template <typename T, size_t N>
poly_span(const etl::array<T, N>&)
-> poly_span<const T, N>;
```
```cpp
template <typename T, size_t N>
poly_span(std::array<T, N>&)
->poly_span<T, N>;
```
```cpp
template <typename T, size_t N>
poly_span(const std::array<T, N>&)
->poly_span<const T, N>;
____________________________________________________________________________________________________
Member types
```
## Member types
```cpp
element_type T
value_type remove_cv<T>::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<iterator>
____________________________________________________________________________________________________
Constructors
```
## Constructors
```cpp
ETL_CONSTEXPR poly_span() ETL_NOEXCEPT
____________________________________________________________________________________________________
```
---
```cpp
template <typename TIterator, typename TSize>
ETL_CONSTEXPR poly_span(const TIterator begin, const TSize size) ETL_NOEXCEPT
Static asserts if etl::iterator_traits<TIterator>::iterator_category is not random_access_iterator_tag
or etl::iterator_traits<TIterator>::value_type is not the same as, or not derived from TBase.
____________________________________________________________________________________________________
```
Static asserts if `etl::iterator_traits<TIterator>::iterator_category` is not `random_access_iterator_tag`
or `etl::iterator_traits<TIterator>::value_type` is not the same as, or not derived from `TBase`.
---
```cpp
template <typename TIterator>
ETL_CONSTEXPR poly_span(const TIterator begin, const TIterator end)
Static asserts if etl::iterator_traits<TIterator>::iterator_category is not random_access_iterator_tag
or etl::iterator_traits<TIterator>::value_type is not the same as, or not derived from TBase.
____________________________________________________________________________________________________
```
Static asserts if `etl::iterator_traits<TIterator>::iterator_category` is not `random_access_iterator_tag`
or `etl::iterator_traits<TIterator>::value_type` is not the same as, or not derived from `TBase`.
---
```cpp
template<typename U, size_t N>
ETL_CONSTEXPR poly_span(U(&begin_)[N]) ETL_NOEXCEPT
Static asserts if N is greater than Extent or etl::iterator_traits<TIterator>::value_type is not the same as,
or not derived from TBase.
____________________________________________________________________________________________________
```
Static asserts if `N` is greater than `Extent` or `etl::iterator_traits<TIterator>::value_type` is not the same as, or not derived from `TBase`.
---
```cpp
template <typename U, size_t N>
ETL_CONSTEXPR poly_span(etl::array<U, N>& a) ETL_NOEXCEPT
Static asserts if N is greater than Extent or etl::iterator_traits<TIterator>::value_type is not the same as,
or not derived from TBase.
____________________________________________________________________________________________________
```
Static asserts if `N` is greater than `Extent` or `etl::iterator_traits<TIterator>::value_type` is not the same as, or not derived from `TBase`.
---
```cpp
template <typename U, size_t N>
ETL_CONSTEXPR poly_span(const etl::array<U, N>& a) ETL_NOEXCEPT
Static asserts if N is greater than Extent or etl::iterator_traits<TIterator>::value_type is not the same as,
or not derived from TBase.
____________________________________________________________________________________________________
```
Static asserts if `N` is greater than `Extent` or `etl::iterator_traits<TIterator>::value_type` is not the same as, or not derived from `TBase`.
---
```cpp
template <typename U, size_t N>
ETL_CONSTEXPR poly_span(std::array<U, N>& 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<TIterator>::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<TIterator>::value_type` is not the same as, or not derived from `TBase`.
---
```cpp
template <typename U, size_t N>
ETL_CONSTEXPR poly_span(const std::array<U, N>& 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<TIterator>::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<TIterator>::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 <typename UBase>
ETL_CONSTEXPR14 poly_span& operator =(const poly_span<UBase, Extent>& other) ETL_NOEXCEPT
Assign from a other span
____________________________________________________________________________________________________
```
Assign from a other span.
---
```cpp
template <size_t COUNT>
ETL_NODISCARD ETL_CONSTEXPR etl::poly_span<element_type, COUNT> 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<element_type, etl::dynamic_extent> last(size_t count) const
```
Returns a span consisting of the last count elements of the current span.
____________________________________________________________________________________________________
---
```cpp
template <size_t COUNT>
ETL_NODISCARD ETL_CONSTEXPR etl::poly_span<element_type, COUNT> 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<element_type, etl::dynamic_extent> first(size_t count) const
```
Returns a span consisting of the first count elements of the current span.
____________________________________________________________________________________________________
---
```cpp
template <const size_t OFFSET, size_t COUNT = etl::dynamic_extent>
ETL_NODISCARD ETL_CONSTEXPR etl::poly_span<element_type, COUNT != etl::dynamic_extent ? COUNT : Extent - OFFSET> 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<element_type, etl::dynamic_extent> 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();
}
```

334
docs/raw/containers/span.txt → docs/containers/Views/span.md
View File

@ -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<typename T, size_t Extent = etl::dynamic_extent>
____________________________________________________________________________________________________
Template deduction guides
```
## Template deduction guides
C++17
```cpp
template <typename TIterator>
span(const TIterator begin, const TIterator end)
->span<etl::remove_pointer_t<TIterator>, etl::dynamic_extent>;
```
```cpp
template <typename TIterator, typename TSize>
span(const TIterator begin, const TSize size)
->span<etl::remove_pointer_t<TIterator>, etl::dynamic_extent>;
```
```cpp
template <typename T, size_t N>
span(T(&)[N])
-> span<T, N>;
```
```cpp
template <typename T, size_t N>
span(etl::array<T, N>&)
-> span<T, N>;
```
```cpp
template <typename T, size_t N>
span(const etl::array<T, N>&)
-> span<const T, N>;
```
```cpp
template <typename T, size_t N>
span(std::array<T, N>&)
->span<T, N>;
```
```cpp
template <typename T, size_t N>
span(const std::array<T, N>&)
->span<const T, N>;
```
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<T>::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 <typename TIterator>
ETL_CONSTEXPR span(TIterator begin, TIterator end)
```
**Description**
Construct from an iterator or pointer range.
____________________________________________________________________________________________________
---
```cpp
template <typename TIterator, typename TSize>
ETL_CONSTEXPR span(TIterator begin, TSize size)
```
**Description**
Construct from a start and size
___________________________________________________________________________________________________
---
```cpp
template<const size_t ARRAY_SIZE>
ETL_CONSTEXPR explicit span(element_type(&begin)[ARRAY_SIZE])
```
**Description**
Construct from a compile time sized C array.
____________________________________________________________________________________________________
---
```cpp
template <typename U, size_t N>
ETL_CONSTEXPR span(etl::array<U, N>& a) ETL_NOEXCEPT
```
**Description**
Construct from an ETL array.
____________________________________________________________________________________________________
---
```cpp
template <typename U, size_t N>
ETL_CONSTEXPR span(const etl::array<U, N>& a) ETL_NOEXCEPT
```
**Description**
Construct from a const ETL array.
____________________________________________________________________________________________________
---
```cpp
template <typename U, size_t N>
ETL_CONSTEXPR span(std::array<U, N>& 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 <typename U, size_t N>
ETL_CONSTEXPR span(const std::array<U, N>& 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 <typename U, size_t N>
ETL_CONSTEXPR span(const etl::span<U, N>& 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 <size_t COUNT>
ETL_NODISCARD ETL_CONSTEXPR etl::span<element_type, COUNT> 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 <size_t COUNT>
ETL_NODISCARD ETL_CONSTEXPR etl::span<element_type, COUNT> 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 <size_t OFFSET, size_t COUNT = etl::dynamic_extent>
ETL_NODISCARD ETL_CONSTEXPR etl::span<element_type, E> 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 <typename T1, size_t N1, typename T2, size_t N2>
ETL_NODISCARD
ETL_CONSTEXPR
bool operator ==(const etl::span<T1, N1>& lhs, const etl::span<T2, N2>& 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 <typename T1, size_t N1, typename T2, size_t N2>
ETL_NODISCARD
ETL_CONSTEXPR
bool operator !=(const etl::span<T1, N1>& lhs, const etl::span<T2, N2>& 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 <typename T1, size_t N1, typename T2, size_t N2>
bool equal(const etl::span<T1, N1>& lhs, const etl::span<T2, N2>& 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<int, 10> data = { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 };
using View = etl::span<int>;
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>()(view);
____________________________________________________________________________________________________
Looping a span.
```
**Looping a span.**
```cpp
etl::array<int, 10> data = { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 };
using View = etl::span<int>;
View view(data.begin(), data.end());
@ -235,4 +407,4 @@ for (int i; i < 1000; ++i)
{
Print(*itr++);
}
```

5
docs/containers/arrays/array.md
View File

@ -16,8 +16,9 @@ Adds additional members functions, `assign`, `insert` & `erase`.
etl::array<typename T, const size_t SIZE>
```
See also
[array_view]()
See also:
[array_view]({{< relref "array_view" >}})
[multi_array]({{< relref "multi_array" >}})
## Template deduction guides
**C++17 and above**

38
docs/containers/arrays/multi_array.md Normal file
View File

@ -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<typename T, const size_t Dx...>
```
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<int, 2, 3, 4>
```
is equivalent to
```cpp
etl::array<etl::array<etl::array<int, 4>, 3>, 2>
```
Each dimension of an `etl::multi_array` supports all of the members of an `etl::array`.

134
docs/containers/queues/priority_queue.md Normal file
View File

@ -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<typename T, const size_t SIZE>
```
Inherits from `etl::ipriority_queue<T>`
`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<typename T, const size_t SIZE>();
```
## 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.

155
docs/containers/stack.md Normal file
View File

@ -0,0 +1,155 @@
---
title: "stack"
---
{{< callout >}}
Header: `stack.h`
Similar to: `std::stack`
{{< /callout >}}
A fixed capacity stack.
```cpp
etl::stack<typename T, const size_t SIZE>
```
Inherits from `etl::istack<T>`
`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<typename T, const size_t SIZE>();
```
**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.

27
docs/raw/containers/multi_array.txt
View File

@ -1,27 +0,0 @@
multi_array
A fixed capacity multi-dimensional array.
STL equivalent: None
For C++11 or greater only.
etl::multi_array<typename T, const size_t Dx...>
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<int, 2, 3, 4>
is equivalent to
etl::array<etl::array<etl::array<int, 4>, 3>, 2>
Each dimension of an etl::multi_array supports all of the members of an etl::array.

60
docs/raw/containers/packet.txt
View File

@ -1,60 +0,0 @@
packet
A class that can contain one of several related types.
STL equivalent: none
etl::packet<typename TBase, size_t SIZE, size_t ALIGNMENT>
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 <typename T>
explicit packet(const T& value)
C++11
template <typename T>
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 <typename T>
packet& operator =(const T& value)
C++11
template <typename T>
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.

108
docs/raw/containers/stack.txt
View File

@ -1,108 +0,0 @@
stack
A fixed capacity stack.
STL equivalent: std::stack
etl::stack<typename T, const size_t SIZE>
Inherits from etl::istack<T>
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<typename T, const size_t SIZE>();
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.

291
docs/raw/containers/vector.txt
View File

@ -1,291 +0,0 @@
vector
A fixed capacity vector.
STL equivalent: std::vector
etl::vector<typename T, size_t SIZE>
etl::vector_ext<typename T>
Inherits from etl::ivector<T>
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<typename T>
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 <typename T, typename... Ts>
etl::vector(T...)
template <typename T, typename... Ts>
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<iterator>
const_reverse_iterator ETL_OR_STD::reverse_iterator<const_iterator>
____________________________________________________________________________________________________
Constructor
Internal buffer
etl::vector<typename T, const size_t SIZE>();
etl::vector<typename T, const size_t SIZE>(size_t initialSize);
etl::vector<typename T, const size_t SIZE>(size_t initialSize, const T& value);
template <typename TIterator>
etl::vector<typename T, const size_t SIZE>(TIterator begin, TIterator end);
etl::vector<typename T, const size_t SIZE>(const etl::vector<typename T, const size_t SIZE>&);
etl::vector<typename T, const size_t SIZE>(etl::vector<typename T, const size_t SIZE>&&);
External buffer
etl::vector<typename T, const size_t SIZE>(void* buffer, size_t max_size);
etl::vector<typename T, const size_t SIZE>(size_t initialSize, void* buffer, size_t max_size);
etl::vector<typename T, const size_t SIZE>(size_t initialSize, const T& value, void* buffer, size_t max_size);
template <typename TIterator>
etl::vector<typename T, const size_t SIZE>(TIterator begin, TIterator end, void* buffer, size_t max_size);
etl::vector<typename T, const size_t SIZE>(const etl::vector<typename T, const size_t SIZE>&, void* buffer, size_t max_size);
etl::vector<typename T, const size_t SIZE>(etl::vector<typename T, const size_t SIZE>&&, 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 <typename TIterator>
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 <typename… Args>
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 <typename Args...>
void emplace_back(Args&&... args);
>=20.35.10
template <typename Args...>
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 <typename TIterator>
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 <typename TIterator>
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 <typename TIterator>
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<int, 10> Data;
Data data(8, 1);
char buffer[sizeof(Data)];
memcpy(&buffer, &data, sizeof(Data));
Data& rdata(*reinterpret_cast<Data*>(buffer));
// Do not access the copied object in any way until you have called this.
rdata.repair();
____________________________________________________________________________________________________
Non-member functions
____________________________________________________________________________________________________
erase
template <typename T, typename U>
typename etl::ivector<T>::difference_type erase(etl::ivector<T>& v, const U& value)
Erases all elements that compare equal to value from the vector.
template <typename T, typename TPredicate>
typename etl::ivector<T>::difference_type erase_if(etl::ivector<T>& 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.