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

Added multiple documentation files

Browse Source
This commit is contained in:
John Wellbelove 2026-04-18 12:45:45 +02:00
parent 0527e4a3c0
commit 4504d96cd6
23 changed files with 1835 additions and 1105 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

117
docs/binary/Bit.md Normal file
View File

@ -0,0 +1,117 @@
---
title: "Bit"
---
{{< callout type="info">}}
Header: `bit.h`
Since: `TBC`
Similar to: [STL bit header](https://en.cppreference.com/cpp/header/bit)
{{< /callout >}}
Utility functions for manipulating binary numbers.
A reverse engineered version of C++20's and C++23's `<bit>` header.
## bit_cast
```cpp
template <typename TDestination, typename TSource>>
ETL_CONSTEXPR14 TDestination bit_cast(const TSource& source) ETL_NOEXCEPT
```
**Description**
Returns a value of type `TDestination` by reinterpreting the `TSource` object.
## byteswap
```cpp
template <typename T>
ETL_CONSTEXPR14 T byteswap(T n) ETL_NOEXCEPT
```
**Description**
Reverses the bytes in `n`.
## has_single_bit
```cpp
template <typename T>
ETL_CONSTEXPR14 bool has_single_bit(T n) ETL_NOEXCEPT
```
**Description**
Checks if `n` is a power of two, or has one bit set.
## bit_ceil
```cpp
template <typename T>
ETL_CONSTEXPR14 T bit_ceil(T n);
```
**Description**
Calculates the smallest power of two, that is not smaller than `n`.
## bit_floor
```cpp
template <typename T>
ETL_CONSTEXPR14 T bit_floor(T n) ETL_NOEXCEPT
```
**Description**
Calculates the smallest power of two, that is not greater than `n`.
## bit_width
```cpp
template <typename T>
ETL_CONSTEXPR14 T bit_width(T n) ETL_NOEXCEPT
```
**Description**
If `n` is not `0`, calculates the number of bits needed to store it.
If `n` is `0`, then the result is `0`.
## rotl
```cpp
template <typename T>
ETL_NODISCARD ETL_CONSTEXPR14 T rotl(T value, int n) ETL_NOEXCEPT
```
**Description**
Computes a left circular shift of value by `n`.
## rotr
```cpp
template <typename T>
ETL_NODISCARD ETL_CONSTEXPR14 T rotr(T value, int n) ETL_NOEXCEPT
```
**Description**
Computes a right circular shift of value by `n`.
## countl_zero
```cpp
template <typename T>
ETL_NODISCARD ETL_CONSTEXPR14 int countl_zero(T value) ETL_NOEXCEPT
```
**Description**
Returns the number of consecutive `0` bits in `n`, starting from the most significant bit (left).
## countl_one
```cpp
template <typename T>
ETL_NODISCARD ETL_CONSTEXPR14 int countl_one(T value) ETL_NOEXCEPT
```
**Description**
Returns the number of consecutive `1` bits in `n`, starting from the most significant bit (left).
## countr_zero
```cpp
template <typename T>
ETL_NODISCARD ETL_CONSTEXPR14 int countr_zero(T value) ETL_NOEXCEPT
```
**Description**
Returns the number of consecutive `0` bits in `n`, starting from the least significant bit (right).
## countr_one
```cpp
template <typename T>
ETL_NODISCARD ETL_CONSTEXPR14 int countr_one(T value) ETL_NOEXCEPT
```
**Description**
Returns the number of consecutive `1` bits in `n`, starting from the least significant bit (right).
## popcount
```cpp
template <typename T>
ETL_NODISCARD ETL_CONSTEXPR14 int popcount(T value) ETL_NOEXCEPT
```
**Description**
Counts the number of `1` bits in an unsigned integer.

6
docs/binary/_index.md Normal file
View File

@ -0,0 +1,6 @@
---
title: "Binary utilities"
weight: 100
---
Classes and functions that define and manipulate binary data.

568
docs/binary/binary.md Normal file
View File

@ -0,0 +1,568 @@
---
title: binary
---
{{< callout type="info">}}
Header: `binary.h`
Since: `TBC`
{{< /callout >}}
Utility functions for manipulating binary numbers.
## Rotate
Rotate the bits in the value left or right.
```cpp
template <typename T>
ETL_CONSTEXPR14 T rotate_left(T value)
```
**Return**
`value` rotated left by one bit.
```cpp
template <typename T>
ETL_CONSTEXPR14 T rotate_left(T value, size_t distance)
```
**Return**
`value` rotated left by `distance`.
```cpp
template <typename T>
ETL_CONSTEXPR14 T rotate_right(T value)
```
**Return**
`value` rotated right by one bit.
```cpp
template <typename T>
ETL_CONSTEXPR14 T rotate_right(T value, size_t distance)
```
**Return**
`value` rotated right by `distance`.
```cpp
template <typename T>
ETL_CONSTEXPR14 T rotate(T value, typename etl::make_signed<size_t>::type distance)
```
**Parameters**
`distance` Positive is left, negative is right.
**Return**
`value` rotated left or right by `distance`.
## reverse_bits
Reverse the order of the bits in a value.
```cpp
template <typename T>
ETL_CONSTEXPR14 T reverse_bits(T value)
```
The structures below define a member constant value that is Value reversed in bits.
```cpp
template <int8_t Value>
struct reverse_bits_const<int8_t, Value>
```
```cpp
template <uint8_t Value>
struct reverse_bits_const<uint8_t, Value>
```
```cpp
template <int16_t Value>
struct reverse_bits_const<int16_t, Value>
```
```cpp
template <uint16_t Value>
struct reverse_bits_const<uint16_t, Value>
```
```cpp
template <int32_t Value>
struct reverse_bits_const<int32_t, Value>
```
```cpp
template <uint32_t Value>
struct reverse_bits_const<uint32_t, Value>
```
```cpp
template <int64_t Value>
struct reverse_bits_const<int64_t, Value>
```
```cpp
template <uint64_t Value>
struct reverse_bits_const<uint64_t, Value>
```
Defines `value` The reversed bits.
## reverse_bytes
Reverse the order of the bytes in a value.
```cpp
template <typename T>
ETL_CONSTEXPR T reverse_bytes(T value)
```
## gray_to_binary
```cpp
template <typename T>
ETL_CONSTEXPR14 T gray_to_binary(T value)
```
Converts a gray code value to binary.
## binary_to_gray
```cpp
template <typename T>
ETL_CONSTEXPR T binary_to_gray(T value)
```
Converts a binary value to the gray code equivalent.
## count_bits
```cpp
template <typename T>
ETL_CONSTEXPR14 T count_bits(T value)
```
**Return**
`1` if the parity of the value is odd, `0` if it is even.
## parity
```cpp
template <typename T>
ETL_CONSTEXPR14 T parity(T value)
```
**Return**
`1` if the parity of the value is odd, `0` if it is even.
## max_value_for_nbits
```cpp
template <size_t NBits>
struct max_value_for_nbits
```
**Return**
Maximum unsigned value a particular number of bits can represent.
`value_type` The type for the value.
`value` The maximum value.
## fold_bits
```cpp
template <typename TReturn, size_t NBits, typename TValue>
ETL_CONSTEXPR14 TReturn fold_bits(TValue value)
```
**Decsription**
Fold a binary number down to a set number of bits using XOR.
**Example**
`0xE8C9AACCBC3D9A8F` folded down to 20 bits = `0x998E8`
```cpp
uint32_t result = etl::fold_bits<uint32_t, 20>(0xE8C9AACCBC3D9A8F);
```
## sign_extend
Sign extends a binary number.
```cpp
template <typename TReturn, const size_t NBits, typename TValue>
ETL_CONSTEXPR14 TReturn sign_extend(TValue value)
```
**Description**
Converts an N bit binary number, where bit N-1 is the sign bit, to a signed integral type.
---
```cpp
template <typename TReturn, const size_t NBits, const size_t Shift, typename TValue>
ETL_CONSTEXPR14 TReturn sign_extend(TValue value)
```
**Description**
Converts an N bit binary number, where bit N-1 is the sign bit, and `Shift` is the right shift amount, to a signed integral type.
---
```cpp
template <typename TReturn, typename TValue>
ETL_CONSTEXPR14 TReturn sign_extend(TValue value, size_t nbits)
```
**Description**
Converts an N bit binary number, where bit N-1 is the sign bit, to a signed integral type.
---
```cpp
template <typename TReturn, typename TValue>
ETL_CONSTEXPR14 TReturn sign_extend(TValue value, size_t nbits, size_t shift)
```
**Description**
Converts an N bit binary number, where bit N-1 is the sign bit, and shift is the right shift amount, to a signed integral type.
## count_leading_zeros
```cpp
template <typename T>
ETL_CONSTEXPR14 T count_leading_zeros(T value)
```
**Decsription**
Counts the number of leading zeros in a binary number
## count_trailing_zeros
```cpp
template <typename T>
ETL_CONSTEXPR14 T count_trailing_zeros(T value)
```
**Description**
Counts the number of trailing zeros in a binary number
## count_leading_ones
```cpp
template <typename T>
ETL_CONSTEXPR14 T count_leading_ones(T value)
```
**Description**
Counts the number of leading ones in a binary number
## count_trailing_ones
```cpp
template <typename T>
ETL_CONSTEXPR14 T count_trailing_ones(T value)
```
**Description**
Counts the number of trailing ones in a binary number
## first_set_bit_position
```cpp
template <typename T>
ETL_CONSTEXPR14 uint_least8_t first_set_bit_position(T value)
```
**Description**
Finds the index of the first set bit from lsb.
## first_clear_position
```cpp
template <typename T>
ETL_CONSTEXPR14 uint_least8_t first_clear_bit_position(T value)
```
**Description**
Finds the index of the first clear bit from lsb.
## first_bit_position
```cpp
template <typename T>
ETL_CONSTEXPR14 uint_least8_t first_bit_position(bool state, T value)
```
**Description**
Finds the index of the first bit in the specified state, from lsb.
## binary_fill
```cpp
template <typename TResult, typename TValue>
ETL_CONSTEXPR TResult binary_fill(TValue value)
```
Fills a value of the specified width with a repeating binary pattern.
*Run time*
Generate `0x12121212`
```cpp
etl::binary_fill<uint32_t>(uint8_t(0x12));
```
---
```cpp
template <typename TResult, typename TValue, TValue N>
ETL_CONSTEXPR TResult binary_fill(TValue value)
```
*Partial compile time*
Generate `0x12121212`
```cpp
etl::binary_fill<uint32_t, uint8_t, 0x12>();
```
## has_zero_byte
```cpp
template <typename TValue>
ETL_CONSTEXPR14 bool has_zero_byte(const TValue value)
```
*Run time*
Checks to see if a value contains a byte of value zero.
**Example**
`etl::has_zero_byte(uint32_t(0x01234567)) == false`
`etl::has_zero_byte(uint32_t(0x01230067)) == true`
## has_byte_n
Checks to see if a value contains a byte of a particular value.
```cpp
template <typename TValue>
ETL_CONSTEXPR14 bool has_byte_n(TValue value, uint8_t n)
```
*Run time*
```cpp
etl::has_byte_n(uint32_t(0x01234567), 0x12) == false
etl::has_byte_n(uint32_t(0x01234567), 0x45) == true
```
---
```cpp
template <typename TValue, TValue N>
ETL_CONSTEXPR14 bool has_byte_n(TValue value)
```
*Partial compile time*
```cpp
etl::has_byte_n<0x12>(uint32_t(0x01234567)) == false
etl::has_byte_n<0x45>(uint32_t(0x01234567)) == true
```
## binary_merge
Merges two binary values according to a mask.
Bits set in the mask select bits in the first value, clear bits select those in the second.
```cpp
template <typename T>
ETL_CONSTEXPR T binary_merge(T first, T second, T mask)
```
```cpp
uint8_t first = 0x12;
uint8_t second = 0x34;
const uint8_t mask = 0xF0;
etl::binary_merge(first, second, mask) Equals 0x14
```
---
```cpp
template <typename T, T Mask>
ETL_CONSTEXPR T binary_merge(T first, T second)
```
```cpp
uint8_t first = 0x12;
uint8_t second = 0x34;
const uint8_t mask = 0xF0;
etl::binary_merge<uint8_t, mask>(first, second) Equals 0x14
```
## binary_interleave
Interleaves two values such that bits abcd and efgh will result in eafbgchd.
```cpp
ETL_CONSTEXPR14 uint16_t binary_interleave(uint8_t first, uint8_t second);
ETL_CONSTEXPR14 int16_t binary_interleave(int8_t first, int8_t second);
ETL_CONSTEXPR14 uint32_t binary_interleave(uint16_t first, uint16_t second);
ETL_CONSTEXPR14 int32_t binary_interleave(int16_t first, int16_t second);
ETL_CONSTEXPR14 uint64_t binary_interleave(uint32_t first, uint32_t second);
ETL_CONSTEXPR14 int64_t binary_interleave(int32_t first, int32_t second);
```
## Odd / Even
Determines the odd or evenness of a value.
```cpp
template <typename T>
ETL_CONSTEXPR bool is_odd(T value)
```
```cpp
template <typename T>
ETL_CONSTEXPR bool is_even(T value);
```
## Constants
```cpp
enum binary_constant
```
An enumeration of 256 constants from `b00000000` to `b11111111` (`0` to `255`)
---
```cpp
enum bit_constant
```
An enumeration of 32 constants from `b0` to `b31` (`1` to `4294967296`)
---
```cpp
template <size_t Position>
struct bit
```
`value_type` The type of the value.
`value` The value of the bit at `Position`.
## Creating bit masks
These classes and constexpr functions help create lsb and msb masks.
```cpp
template <typename T, size_t NBits>
class lsb_mask;
```
Defines the member constant value as a binary value of NBits `1` shift to the LSB.
e.g. `lsb_mask<int8_t, 3>::value == 0b00000111`
Since: `20.34.0`
---
```cpp
template <typename T>
ETL_CONSTEXPR T make_lsb_mask(size_t nbits)
```
Returns a binary value of nbits `1` shift to the LSB.
e.g. `make_lsb_mask<int8_t>(3) == 0b00000111`
Since: `20.34.0`
---
```cpp
template <typename T, size_t NBits>
ETL_CONSTEXPR T make_lsb_mask()
```
**Description**
Returns a binary value of nbits `1` shift to the LSB.
e.g. `make_lsb_mask<int8_t, 3>() == 0b00000111`
Since: `20.38.7`
---
```cpp
template <typename T, size_t NBits>
class msb_mask;
```
**Return**
A binary value of nbits `1` shift to the MSB.
e.g. `msb_mask<int8_t, 3>::value == 0b11100000`
Since: `20.34.0`
---
```cpp
template <typename T>
ETL_CONSTEXPR T make_msb_mask(size_t nbits)
```
**Description**
Defines the member constant value as a binary value of NBits `1` shift to the MSB.
e.g. `make_msb_mask<int8_t>(3) == 0b11100000`
20.34.0
---
```cpp
template <typename T, size_t NBits>
ETL_CONSTEXPR T make_msb_mask()
```
**Description**
Defines the member constant value as a binary value of NBits `1` shift to the MSB.
e.g. `make_msb_mask<int8_t, 3>() == 0b11100000`
Since: `20.38.7`
## Bit manipulation functors
These functors are most useful where lambdas are not available.
## binary_not
```cpp
template <typename T>
struct binary_not : public etl::unary_function<T, T>;
```
Since: `20.38.11`
---
```cpp
ETL_CONTEXPR
binary_not()
```
**Description**
Default constructor.
---
```cpp
ETL_CONTEXPR
ETL_NODISCARD
T operator(T value)
```
**Return**
~value.
## binary_and
```cpp
template <typename T>
struct binary_and : public etl::unary_function<T, T>;
```
Since: `20.38.11`
---
```cpp
ETL_CONTEXPR
binary_and(T and_value)
```
**Description**
Constructor.
---
```cpp
ETL_CONTEXPR
ETL_NODISCARD
T operator(T value)
```
**Return**
`value & and_value`.
## binary_or
```cpp
template <typename T>
struct binary_or : public etl::unary_function<T, T>;
```
Since: `20.38.11`
---
```cpp
ETL_CONTEXPR
binary_and(T or_value)
```
**Description**
Constructor.
---
``cpp
ETL_CONTEXPR
ETL_NODISCARD
T operator(T value)
``
**Return**
`value | or_value`.
## binary_xor
```cpp
template <typename T>
struct binary_xor : public etl::unary_function<T, T>;
```
Since: `20.38.11`
---
```cpp
ETL_CONTEXPR
binary_xor(T xor_value)
```
**Description**
Constructor.
---
```cpp
ETL_CONTEXPR
ETL_NODISCARD
T operator(T value)
```
**Return**
value ^ xor_value.

149
docs/binary/byte.md Normal file
View File

@ -0,0 +1,149 @@
---
title: "byte"
---
{{< callout type="info">}}
Header: `byte.h`
Since: `20.24.0`
Similar to: [std::byte](https://en.cppreference.com/cpp/types/byte)
{{< /callout >}}
A type that implements the concept of byte
**C++03**
Implemented as a class.
Cannot be cast using `static_cast`.
**C++11 or above**
Implemented as enum class.
All functions are `constexpr`.
## Constructors
```cpp
byte()
```
**Description**
Constructs a default initialised byte.
C++03
---
```cpp
template <typename T>
explicit byte(T v)
```
Constructs a byte initialised to `v`.
## Non-member functions
```cpp
template <typename TInteger>
constexpr TInteger to_integer(etl::byte b) noexcept
```
**Description**
Converts to an integral type.
`constexpr` and `noexcept` for C++11 and above.
---
```cpp
template <typename TInteger>
constexpr etl::byte operator <<(etl::byte b, TInteger shift) noexcept
```
**Description**
Shifts the value of the byte to the left and returns the new byte.
`constexpr` and `noexcept` for C++11 and above.
---
```cpp
template <typename TInteger>
constexpr etl::byte operator >>(etl::byte b, TInteger shift) noexcept
```
**Description**
Shifts the value of the byte to the right and returns the new byte.
`constexpr` and `noexcept` for C++11 and above.
---
```cpp
template <typename TInteger>
constexpr etl::byte& operator <<=(etl::byte& b, TInteger shift) noexcept
```
**Description**
Shifts the value of the byte to the left and returns a reference to the byte.
`constexpr` and `noexcept` for C++11 and above.
---
```cpp
template <typename TInteger>
constexpr etl::byte& operator >>=(etl::byte& b, TInteger shift) noexcept
```
**Description**
Shifts the value of the byte to the right and returns a reference to the byte.
`constexpr` and `noexcept` for C++11 and above.
---
```cpp
constexpr etl::byte operator |(etl::byte lhs, etl::byte rhs) noexcept
```
ORs the two bytes returns the new byte.
`constexpr` and `noexcept` for C++11 and above.
---
```cpp
constexpr etl::byte operator &(etl::byte lhs, etl::byte rhs) noexcept
```
**Description**
ANDs the two bytes returns the new byte.
`constexpr` and `noexcept` for C++11 and above.
---
```cpp
constexpr etl::byte operator ^(etl::byte lhs, etl::byte rhs) noexcept
```
**Description**
Exclusive ORs the two bytes returns the new byte.
`constexpr` and `noexcept` for C++11 and above.
---
```cpp
constexpr etl::byte& operator |=(etl::byte& lhs, etl::byte rhs) noexcept
```
**Description**
ORs the two bytes returns and a reference to the first parameter.
`constexpr` for C++14 and above.
`noexcept` for C++11 and above.
---
```cpp
constexpr etl::byte& operator &=(etl::byte& lhs, etl::byte rhs) noexcept
```
**Description**
ANDs the two bytes returns and a reference to the first parameter.
`constexpr` for C++14 and above.
`noexcept` for C++11 and above.
---
```cpp
constexpr etl::byte& operator ^=(etl::byte& lhs, etl::byte rhs) noexcept
```
**Description**
Exclusive ORs the two bytes and returns a reference to the first parameter.
`constexpr` for C++14 and above.
`noexcept` for C++11 and above.
---
```cpp
constexpr etl::byte operator ~(etl::byte b) noexcept
```
**Description**
Negates the value of the byte and returns the new value.
`constexpr` and `noexcept` for C++11 and above.

105
docs/raw/utilities/flags.txt → docs/binary/flags.md
View File

@ -1,49 +1,104 @@
flags
Provides a wrapper around a set of binary flags.
Supports compile time and runtime variants
---
title: "flags"
---
{{< callout type="info">}}
Header: `flags.h`
Since: `TBC`
{{< /callout >}}
Provides a wrapper around a set of binary flags.
Supports compile time and runtime variants
```cpp
template <typename T, T MASK = etl::integral_limits<T>::max>
class flags
```
`T` must be an unsigned integral type.
`MASK` is used to exclude unused or undefine bits from operations of the flags. By default, all bits are included.
T must be an unsigned integral type.
MASK is used to exclude unused or undefine bits from operations of the flags. By default, all bits are included.
Most member functions may be chained.
Most member functions may be chained.
```cpp
bool isF5Set = flags.set(bitPattern, true).flip().test(F5);
____________________________________________________________________________________________________
Constructor
```
## Constructor
```cpp
ETL_CONSTEXPR flags() ETL_NOEXCEPT
Constructs a flag set with all elements set to 0 (false).
____________________________________________________________________________________________________
ETL_CONSTEXPR flags(value_type pattern) ETL_NOEXCEPT
Constructs a flag set with elements set to pattern.
____________________________________________________________________________________________________
ETL_CONSTEXPR flags(const flags<T, MASK>& pattern) ETL_NOEXCEPT
Constructs a flag set with elements set to pattern.
____________________________________________________________________________________________________
Modifiers
```
**Description**
Constructs a flag set with all elements set to `0` (`false`).
---
```cpp
ETL_CONSTEXPR flags(value_type pattern) ETL_NOEXCEPT
```
**Description**
Constructs a flag set with elements set to pattern.
---
```cpp
ETL_CONSTEXPR flags(const flags<T, MASK>& pattern) ETL_NOEXCEPT
```
**Description**
Constructs a flag set with elements set to pattern.
## Modifiers
```cpp
ETL_CONSTEXPR14 flags<T, MASK>& operator =(flags<T, MASK> other) ETL_NOEXCEPT
```
**Description**
Assigns from another flags object.
____________________________________________________________________________________________________
---
```cpp
ETL_CONSTEXPR14 flags<T, MASK>& operator =(value_type pattern) ETL_NOEXCEPT
```
**Description**
Assigns from a bit pattern.
____________________________________________________________________________________________________
---
```cpp
template <value_type pattern, bool value>
ETL_CONSTEXPR14 flags<T, MASK>& set() ETL_NOEXCEPT
____________________________________________________________________________________________________
```
---
```cpp
template <value_type pattern>
ETL_CONSTEXPR14 flags<T, MASK>& set(bool value) ETL_NOEXCEPT
____________________________________________________________________________________________________
```
---
```cpp
template <value_type pattern>
ETL_CONSTEXPR14 flags<T, MASK>& set() ETL_NOEXCEPT
____________________________________________________________________________________________________
```
---
```cpp
ETL_CONSTEXPR14 flags<T, MASK>& set(value_type pattern) ETL_NOEXCEPT
____________________________________________________________________________________________________
```
---
```cpp
ETL_CONSTEXPR14 flags<T, MASK>& set(value_type pattern, bool value) ETL_NOEXCEPT
____________________________________________________________________________________________________
```
---
```cpp
ETL_CONSTEXPR14 flags<T, MASK>& clear() ETL_NOEXCEPT
```
____________________________________________________________________________________________________
template <value_type pattern>
ETL_CONSTEXPR14 flags<T, MASK>& reset() ETL_NOEXCEPT

379
docs/iterators/Iterator.md Normal file
View File

@ -0,0 +1,379 @@
---
title: iterator
---
{{< callout type="info">}}
Header: `iterator.h`
Since: `TBC`
{{< /callout >}}
A set of templates to more easily determine the properties of iterator types.
## Input iterators
```cpp
is_input_iterator<T>::value
```
**Description**
Is `T` an input iterator?
---
```cpp
is_input_iterator_concept<T>::value
```
**Description**
Can `T` be used as an input iterator?
## Output iterators
```cpp
is_output_iterator<T>::value
```
**Description**
Is `T` an output iterator?
---
```cpp
is_output_iterator_concept<T>::value
```
**Description**
Can `T` be used as an output iterator?
## Forward iterators
is_forward_iterator<T>::value
Is T a forward iterator?
is_forward_iterator_concept<T>::value
Can T be used as an forward iterator?
## Bidirectional iterators
is_bidirectional_iterator<T>::value
Is T a bidirectional iterator?
is_bidirectional_iterator_concept<T>::value
Can T be used as a bidirectional iterator?
## Random iterators
is_random_iterator<T>::value
Is T a random iterator?
is_random_iterator_concept<T>::value
Can T be used as a random iterator?
## Iterator tags
struct input_iterator_tag
struct output_iterator_tag
struct forward_iterator_tag
struct bidirectional_iterator_tag
struct random_access_iterator_tag
## Iterator traits
template <typename TIterator>
struct iterator_traits
Defined types
iterator_category
value_type
difference_type
pointer
reference
## advance
template <typename TIterator, typename TDistance>
ETL_CONSTEXPR17 void advance(TIterator& itr, TDistance n)
## prev
template<typename TIterator>
ETL_CONSTEXPR17 TIterator prev(TIterator itr,
typename etl::iterator_traits<TIterator>::difference_type n = 1)
## next
template<typename TIterator>
ETL_CONSTEXPR17 TIterator next(TIterator itr,
typename etl::iterator_traits<TIterator>::difference_type n = 1)
## distance
template<typename TIterator>
ETL_CONSTEXPR17 typename std::iterator_traits<TIterator>::difference_type
distance(TIterator first, TIterator last)
## iterator
A base class provided to simplify definitions of the required types for iterators.
https://en.cppreference.com/w/cpp/iterator/iterator
template <typename TCategory,
typename T,
typename TDistance = ptrdiff_t,
typename TPointer = T* ,
typename TReference = T&>
struct iterator
Defined types
value_type
difference_type
pointer
reference
iterator_category
## reverse_iterator
An iterator adaptor that reverses the direction of a given iterator
template <typename TIterator>
class reverse_iterator
Defined types
iterator_category
value_type
iterator_type
difference_type
pointer
reference
## move_iterator
An iterator adaptor that converts the value returned by the underlying iterator into an rvalue.
C++11 or above.
template <typename TIterator>
class move_iterator
Defined types
iterator_category
value_type
iterator_type
difference_type
pointer
reference
## back_insert_iterator
Inserts using push_back.
template <typename TContainer>
class back_insert_iterator
---
template <typename TContainer>
ETL_NODISCARD
ETL_CONSTEXPR14
etl::back_insert_iterator<TContainer> back_inserter(TContainer& container)
## front_insert_iterator
Inserts using push_front.
template <typename TContainer>
class front_insert_iterator
---
template <typename TContainer>
ETL_NODISCARD
ETL_CONSTEXPR14
etl::front_insert_iterator<TContainer> front_inserter(TContainer& container)
## push_insert_iterator
Inserts using push.
template <typename TContainer>
class push_insert_iterator
---
template <typename TContainer>
ETL_NODISCARD
ETL_CONSTEXPR14
etl::push_insert_iterator<TContainer> push_inserter(TContainer& container)
## begin
template <typename TContainer>
ETL_CONSTEXPR typename TContainer::iterator begin(TContainer& container)
Get the 'begin' iterator of container.
Enabled if ETL_NOT_USING_STL or ETL_CPP11_NOT_SUPPORTED.
---
template <typename TContainer>
ETL_CONSTEXPR typename TContainer::const_iterator begin(const TContainer& container)
Get the 'begin' const_iterator of container.
Enabled if ETL_NOT_USING_STL or ETL_CPP11_NOT_SUPPORTED.
---
template <typename TContainer>
ETL_CONSTEXPR typename TContainer::const_iterator cbegin(const TContainer& container)
Get the 'begin' const_iterator of container.
Enabled if ETL_NOT_USING_STL or ETL_CPP11_NOT_SUPPORTED.
---
template <typename TValue, size_t Array_Size>
ETL_CONSTEXPR TValue* begin(TValue(&data)[Array_Size])
Get the 'begin' pointer for an array.
Enabled if ETL_NOT_USING_STL or ETL_CPP11_NOT_SUPPORTED.
---
template <typename TValue, size_t Array_Size>
ETL_CONSTEXPR const TValue* begin(const TValue(&data)[Array_Size])
Get the 'begin' const pointer for an array.
Enabled if ETL_NOT_USING_STL or ETL_CPP11_NOT_SUPPORTED.
---
template <typename TValue, size_t Array_Size>
ETL_CONSTEXPR const TValue* cbegin(const TValue(&data)[Array_Size])
Get the 'begin' const pointer for an array.
Enabled if ETL_NOT_USING_STL or ETL_CPP11_NOT_SUPPORTED.
---
template <typename TContainer>
ETL_CONSTEXPR typename TContainer::reverse_iterator rbegin(TContainer& container)
Get the 'begin' reverse_iterator of container.
Enabled if ETL_NOT_USING_STL or ETL_CPP14_NOT_SUPPORTED.
---
template <typename TContainer>
ETL_CONSTEXPR typename TContainer::const_reverse_iterator rbegin(const TContainer& container)
Get the 'begin' const_reverse_iterator of container.
Enabled if ETL_NOT_USING_STL or ETL_CPP14_NOT_SUPPORTED.
---
template <typename TContainer>
ETL_CONSTEXPR typename TContainer::const_reverse_iterator crbegin(const TContainer& container)
Get the 'begin' const_reverse_iterator of container.
Enabled if ETL_NOT_USING_STL or ETL_CPP14_NOT_SUPPORTED.
---
template <typename TValue, size_t Array_Size>
ETL_OR_STD::reverse_iterator<TValue*> rbegin(TValue(&data)[Array_Size])
Get the 'begin' reverse_iterator for an array.
Enabled if ETL_NOT_USING_STL or ETL_CPP14_NOT_SUPPORTED.
---
template <typename TValue, size_t Array_Size>
ETL_CONSTEXPR ETL_OR_STD::reverse_iterator<const TValue*> crbegin(const TValue(&data)[Array_Size])
Get the 'begin' const_reverse_iterator for an array.
Enabled if ETL_NOT_USING_STL or ETL_CPP14_NOT_SUPPORTED.
## end
template <typename TContainer>
ETL_CONSTEXPR typename TContainer::iterator end(TContainer& container)
Get the 'end' iterator of container.
Enabled if ETL_NOT_USING_STL or ETL_CPP11_NOT_SUPPORTED.
---
template <typename TContainer>
ETL_CONSTEXPR typename TContainer::const_iterator end(const TContainer& container)
Get the 'end' const_iterator of container.
Enabled if ETL_NOT_USING_STL or ETL_CPP11_NOT_SUPPORTED.
---
template <typename TContainer>
ETL_CONSTEXPR typename TContainer::const_iterator cend(const TContainer& container)
Get the 'end' const_iterator of container.
Enabled if ETL_NOT_USING_STL or ETL_CPP11_NOT_SUPPORTED.
---
template <typename TValue, size_t Array_Size>
ETL_CONSTEXPR TValue* end(TValue(&data)[Array_Size])
Get the 'end' pointer for an array.
Enabled if ETL_NOT_USING_STL or ETL_CPP11_NOT_SUPPORTED.
---
template <typename TValue, size_t Array_Size>
ETL_CONSTEXPR const TValue* end(const TValue(&data)[Array_Size])
Get the 'end' const pointer of an array.
Enabled if ETL_NOT_USING_STL or ETL_CPP11_NOT_SUPPORTED
---
template <typename TValue, size_t Array_Size>
ETL_CONSTEXPR const TValue* cend(const TValue(&data)[Array_Size])
Get the 'end' const pointer of an array.
Enabled if ETL_NOT_USING_STL or ETL_CPP11_NOT_SUPPORTED
---
template <typename TContainer>
ETL_CONSTEXPR typename TContainer::reverse_iterator rend(TContainer& container)
Get the 'end' reverse_iterator of container.
Enabled if ETL_NOT_USING_STL or ETL_CPP14_NOT_SUPPORTED.
---
template <typename TContainer>
ETL_CONSTEXPR typename TContainer::const_reverse_iterator rend(TContainer& container)
Get the 'end' const_reverse_iterator of container.
Enabled if ETL_NOT_USING_STL or ETL_CPP14_NOT_SUPPORTED.
---
template <typename TContainer>
ETL_CONSTEXPR typename TContainer::const_reverse_iterator crend(const TContainer& container)
Get the 'end' const_reverse_iterator of container.
Enabled if ETL_NOT_USING_STL or ETL_CPP14_NOT_SUPPORTED.
---
template <typename TValue, size_t Array_Size>
ETL_CONSTEXPR ETL_OR_STD::reverse_iterator<TValue*> rend(TValue(&data)[Array_Size])
Get the 'end' reverse_iterator for an array.
Enabled if ETL_NOT_USING_STL or ETL_CPP14_NOT_SUPPORTED.
---
template <typename TValue, size_t Array_Size>
ETL_CONSTEXPR ETL_OR_STD::reverse_iterator<const TValue*> crend(const TValue(&data)[Array_Size])
Get the 'end' const_reverse_iterator for an array.
Enabled if ETL_NOT_USING_STL or ETL_CPP14_NOT_SUPPORTED.
## size
template <typename TContainer>
ETL_CONSTEXPR typename TContainer::size_type size(const TContainer& container)
Get the size of a container.
Expects the container to have defined size_type.
Enabled if ETL_NOT_USING_STL or ETL_CPP17_NOT_SUPPORTED.
---
template <typename TValue, size_t Array_Size>
ETL_CONSTEXPR size_t size(TValue(&)[Array_Size])
Get the size of an array in elements at run time, or compile time if C++11 or above.
Enabled if ETL_NOT_USING_STL or ETL_CPP17_NOT_SUPPORTED.
---
template <typename T, size_t Array_Size>
char(&array_size(T(&array)[Array_Size]))[Array_Size];
Get the size of an array in elements at compile time for C++03
Usage:- sizeof(array_size(array))
Enabled if ETL_NOT_USING_STL or ETL_CPP17_NOT_SUPPORTED.
---
```cpp
ETL_ARRAY_SIZE(a) calls sizeof(etl::array_size(a))
```

7
docs/iterators/_index.md Normal file
View File

@ -0,0 +1,7 @@
---
title: "Iterators"
weight: 100
---
Various classes implementing iterator types.

58
docs/raw/utilities/fixed_iterator.txt → docs/iterators/fixed_iterator.md
View File

@ -1,39 +1,71 @@
fixed_iterator
An iterator where increments and decrements are null operations.
---
title: fixed_iterator
---
{{< callout type="info">}}
Header: `fixed_iterator.h`
Since: `TBC`
{{< /callout >}}
An iterator where increments and decrements are null operations.
Can be used to copy to or from a fixed address such as a register.
See also: circular_iterator
____________________________________________________________________________________________________
Constructor
## Constructor
```cpp
template <typename TIterator>
etl::fixed_iterator();
```
```cpp
template <typename TIterator>
etl::fixed_iterator(TIterator it);
```
```cpp
template <typename TIterator>
etl::fixed_iterator(const etl::fixed_iterator&);
____________________________________________________________________________________________________
Access
```
## Access
```cpp
Titerator get() const;
```
**Decscription**
Get the internal iterator.
```cpp
void get(TIterator it);
```
**Decscription**
Set the iterator.
____________________________________________________________________________________________________
Operators
## Operators
```cpp
typename etl::iterator_traits<TIterator>::value_type operator *()
const typename etl::iterator_traits<TIterator>::value_type operator *() const
```
**Decscription**
Dereference operators
---
```cpp
TIterator operator ->()
const TIterator operator ->() const
Member dereference operators
```
**Decscription**
Member dereference operators
---
```cpp
operator TIterator() const
```
**Decscription**
Conversion operator
____________________________________________________________________________________________________
Example
## Example
```cpp
etl::vector<char, 32> buffer;
const char* UART_READ = (const char*) 0x1000;
@ -47,4 +79,4 @@ std::copy_n(uart_read, 20, std::back_inserter<char>(buffer));
// Write the buffer of characters to the port.
std::copy(buffer.begin(), buffer.end(), uart_write);
```

279
docs/raw/Macros.txt
View File

@ -1,279 +0,0 @@
Macros
Many of the features or options in the ETL can be selected by defining the appropriate macros.
Some macros are defined by the ETL.
Some of the following macros are presented as C++ constants.
See ETL Traits
____________________________________________________________________________________________________
User defined
These may be defined in the project settings or the user created etl_profile.h.
ETL_NO_CHECKS ETL_ASSERT has no effect.
ETL_THROW_EXCEPTIONS ETL_ASSERT throws the specified exception.
ETL_THROW_EXCEPTIONS + ETL_LOG_ERRORS ETL_ASSERT calls the error handler then
throws an exception.
ETL_LOG_ERRORS ETL_ASSERT calls the error handler then asserts.
ETL_LOG_ERRORS + NDEBUG ETL_ASSERT calls the error handler.
ETL_CHECK_PUSH_POP Pushes and pops to containers are checked for bounds.
ETL_VERBOSE_ERRORS If this is defined then error messages and ouput in their
long form.
ETL_BITSET_ELEMENT_TYPE If this is defined, then it will become the type used for
elements in the bitset class.
Default is uint_least8_t
ETL_FSM_STATE_ID_TYPE If this is defined, then it will become the type used for FSM
state id numbers.
Default is uint_least8_t
ETL_MESSAGE_ID_TYPE If this is defined, then it will become the type used for
message id numbers.
Default is uint_least8_t
ETL_TIMER_SEMAPHORE_TYPE If this is defined, then it will become the type used for the
type for the timer guard variable. This must be a type that
cannot be interrupted during a read/modify/write cycle.
Default is etl::atomic_uint32_t
ETL_ISTRING_REPAIR_ENABLE Define this if you wish to memcpy ETL strings and repair them
via an istring pointer or reference.
Warning: This will make the container a virtual class.
ETL_IVECTOR_REPAIR_ENABLE Define this if you wish to memcpy ETL vectors and repair them
via an ivector pointer or reference.
Warning: This will make the container a virtual class.
ETL_IDEQUE_REPAIR_ENABLE Define this if you wish to memcpy ETL deques and repair them
via an ideque pointer or reference.
Warning: This will make the container a virtual class.
ETL_STLPORT This must be defined in the user library profile when using
STLPort as the standard library implementation.
ETL_NO_STL If defined, the ETL will not use definitions from the STL.
Instead it will use its own reverse engineered versions .
ETL_FORCE_EXPLICIT_STRING_CONVERSION_FROM_CHAR If defined, the ETL will force string, wstring, u16string,
u32string and string_view to have explicit construction
from a character pointer.
ETL_STRING_TRUNCATION_IS_ERROR If defined, then a string truncation will result in an
before 20.26.0 etl::string_truncation error being emitted.
ETL_ENABLE_ERROR_ON_STRING_TRUNCATION See above.
after 20.26.0
ETL_ARRAY_VIEW_IS_MUTABLE If defined, then etl::array_view is mutable.
ETL_POLYMORPHIC_BITSET Defining any one of these will make the corresponding
ETL_POLYMORPHIC_DEQUE container polymorphic, turning the protected non-virtual
ETL_POLYMORPHIC_FLAT_MAP destructor to public virtual.
ETL_POLYMORPHIC_FLAT_MULTIMAP
ETL_POLYMORPHIC_FLAT_SET
ETL_POLYMORPHIC_FLAT_MULTISET
ETL_POLYMORPHIC_FORWARD_LIST
ETL_POLYMORPHIC_LIST
ETL_POLYMORPHIC_MAP
ETL_POLYMORPHIC_MULTIMAP
ETL_POLYMORPHIC_SET
ETL_POLYMORPHIC_MULTISET
ETL_POLYMORPHIC_QUEUE
ETL_POLYMORPHIC_STACK
ETL_POLYMORPHIC_REFERENCE_FLAT_MAP
ETL_POLYMORPHIC_REFERENCE_FLAT_MULTIMAP
ETL_POLYMORPHIC_REFERENCE_FLAT_SET
ETL_POLYMORPHIC_REFERENCE_FLAT_MULTISET
ETL_POLYMORPHIC_UNORDERED_MAP
ETL_POLYMORPHIC_UNORDERED_MULTIMAP
ETL_POLYMORPHIC_UNORDERED_SET
ETL_POLYMORPHIC_UNORDERED_MULTISET
ETL_POLYMORPHIC_STRINGS
ETL_POLYMORPHIC_POOL
ETL_POLYMORPHIC_VECTOR
ETL_POLYMORPHIC_CONTAINERS If defined then all containers are polymorphic.
ETL_POLYMORPHIC_MESSAGES If defined then etl::imessage is virtual.
ETL_MESSAGES_ARE_VIRTUAL ETL_MESSAGES_ARE_VIRTUAL is deprecated and may be removed.
Only valid before 19.4.1 Messages are virtual, by default, from 19.4.1
ETL_USE_TYPE_TRAITS_BUILTINS Forces the ETL to use calls compiler built-ins.
Sets all of them to be 1 if not already defined.
If not defined ETL_USE_BUILTIN_IS_ASSIGNABLE then
ETL_USE_BUILTIN_IS_ASSIGNABLE = 1
If not defined ETL_USE_BUILTIN_IS_CONSTRUCTIBLE then
ETL_USE_BUILTIN_IS_CONSTRUCTIBLE = 1
If not ETL_USE_BUILTIN_IS_TRIVIALLY_CONSTRUCTIBLE then
ETL_USE_BUILTIN_IS_TRIVIALLY_CONSTRUCTIBLE = 1
If not defined ETL_USE_BUILTIN_IS_TRIVIALLY_DESTRUCTIBLE then
ETL_USE_BUILTIN_IS_TRIVIALLY_DESTRUCTIBLE = 1
If not defined ETL_USE_BUILTIN_IS_TRIVIALLY_COPYABLE then
ETL_USE_BUILTIN_IS_TRIVIALLY_COPYABLE = 1
ETL_TARGET_DEVICE_GENERIC Only ETL_TARGET_DEVICE_ARM_CORTEX_M0 and
ETL_TARGET_DEVICE_ARM ETL_TARGET_DEVICE_ARM_CORTEX_M0_PLUS are currently used in
ETL_TARGET_DEVICE_ARM_CORTEX_M0 the ETL code to disable etl::atomic.
ETL_TARGET_DEVICE_ARM_CORTEX_M0_PLUS
ETL_NO_LIBC_WCHAR_H Define if the libc++ used has not been compiled for wchar_t
support.
____________________________________________________________________________________________________
ETL defined
Defined in platform.h
ETL_DEBUG This is defined as 1 if DEBUG or _DEBUG is defined. Otherwise 0.
ETL_8BIT_SUPPORT This is defined as 1 if the platform supports 8 bit char types.
Otherwise 0. Deprecated.
ETL_CONSTEXPR If ETL_CPP11_SUPPORTED is defined as 1 then this macro is
defined as constexpr, otherwise defined as blank.
ETL_CONSTEXPR14 If ETL_CPP14_SUPPORTED is defined as 1 then this macro is
defined as constexpr, otherwise defined as blank.
ETL_CONSTEXPR17 If ETL_CPP17_SUPPORTED is defined as 1 then this macro is
defined as constexpr, otherwise defined as blank.
ETL_IF_CONSTEXPR If ETL_CPP17_SUPPORTED is defined as 1 then this macro is
defined as constexpr, otherwise defined as blank.
ETL_CONSTANT If ETL_CPP11_SUPPORTED is defined as 1 then this macro is
defined as constexpr, otherwise defined as const.
ETL_NOEXCEPT If ETL_CPP11_SUPPORTED is defined as 1 then this macro is
defined as noexcept, otherwise defined as blank.
ETL_NOEXCEPT_EXPR(expression) If ETL_CPP11_SUPPORTED is defined as 1 then this macro is
defined as noexcept(expression), otherwise defined as blank.
ETL_NODISCARD If ETL_CPP11_SUPPORTED is defined as 1 then this macro is
defined as [[nodiscard]], otherwise defined as blank.
ETL_DEPRECATED If ETL_CPP14_SUPPORTED is defined as 1 then this macro is
defined as [[deprecated]], otherwise defined as blank.
ETL_DEPRECATED_REASON(reason) If ETL_CPP14_SUPPORTED is defined as 1 then this macro is
defined as [[deprecated(reason)]], otherwise defined as blank.
ETL_FALLTHROUGH If ETL_CPP17_SUPPORTED is defined as 1 then this macro is
defined as [[falltrough]], otherwise defined as blank.
ETL_NORETURN If ETL_CPP11_SUPPORTED is defined as 1 then this macro is
defined as [[noreturn]], otherwise defined as blank.
ETL_OR_STD If ETL_NO_STL is defined and ETL_IN_UNIT_TEST is not then
ETL_OR_STD is defined as etl, otherwise it is defined as std.
ETL_IN_UNIT_TEST If defined, then the code is being compiled in the unit tests.
For internal ETL use only.
ETL_HAS_ATOMIC This is defined as 1 if the compiler supplies an atomic class.
Otherwise 0.
ETL_INLINE_VAR If ETL_CPP17_SUPPORTED is defined as 1 then this macro is
defined as inline, otherwise defined as blank.
ETL_USING_STL These macros will be defined as 0 & 1 dependant of whether
ETL_NOT_USING_STL ETL_NO_STL is defined or not.
ETL_USING_STLPORT These macros will be defined as 0 & 1 dependant of whether
ETL_NOT_USING_STLPORT ETL_STLPORT is defined or not.
ETL_USING_8BIT_TYPES These macros will be defined as 0 & 1 dependant of whether
ETL_NOT_USING_8BIT_TYPES CHAR_BIT == 8 or not.
ETL_USING_64BIT_TYPES These macros will be defined as 0 & 1 dependant of whether
ETL_NOT_USING_64BIT_TYPES ETL_NO_64BIT_TYPES is defined or not.
ETL_HAS_ISTRING_REPAIR Set to 1 if the repair functionality is enabled, otherwise 0.
ETL_HAS_IVECTOR_REPAIR
ETL_HAS_IDEQUE_REPAIR
ETL_IS_DEBUG_BUILD Set to 1 if in a debug build, otherwise 0.
ETL_HAS_POLYMORPHIC_MESSAGES Set to 1 if messages are polymorphic, otherwise 0.
ETL_HAS_ERROR_ON_STRING_TRUNCATION Set to 1 if truncated strings are an error, otherwise 0.
ETL_USING_LIBC_WCHAR_H These macros will be defined as 0 & 1 dependant of whether
ETL_NOT_USING_LIBC_WCHAR_H ETL_NO_LIBC_WCHAR_H is defined or not.
ETL_USING_CPP11 This is defined as 1 if the compiler supports C++11.
Otherwise 0.
ETL_USING_CPP14 This is defined as 1 if the compiler supports C++14.
Otherwise 0.
ETL_USING_CPP17 This is defined as 1 if the compiler supports C++17.
Otherwise 0.
ETL_USING_CPP20 This is defined as 1 if the compiler supports C++20.
Otherwise 0.
ETL_USING_CPP23 This is defined as 1 if the compiler supports C++23.
Otherwise 0.
____________________________________________________________________________________________________
These may be user defined in etl_profile.h, or automatically determined in platform.h
ETL_CPP11_SUPPORTED This is defined as 1 if the compiler supports C++11.
Otherwise 0.
ETL_CPP14_SUPPORTED This is defined as 1 if the compiler supports C++14.
Otherwise 0.
ETL_CPP17_SUPPORTED This is defined as 1 if the compiler supports C++17.
Otherwise 0.
ETL_CPP20_SUPPORTED This is defined as 1 if the compiler supports C++20.
Otherwise 0.
ETL_CPP23_SUPPORTED This is defined as 1 if the compiler supports C++23.
Otherwise 0.
ETL_NO_NULLPTR_SUPPORT This is defined as 1 if compiler does not support nullptr.
Otherwise 0.
ETL_NO_LARGE_CHAR_SUPPORT This is defined as 1 if the compiler does not support char16_t
or char32_t types. Otherwise 0.
ETL_CPP11_TYPE_TRAITS_IS_TRIVIAL_SUPPORTED This is defined as 1 if compiler supports the
std::is_trivially_xxx set of traits. Otherwise 0.
ETL_COMPILER_IAR One of these will be defined.
ETL_COMPILER_GREEN_HILLS
ETL_COMPILER_INTEL
ETL_COMPILER_MICROSOFT
ETL_COMPILER_GCC
ETL_COMPILER_CLANG
ETL_COMPILER_ARM
ETL_COMPILER_TEXAS_INSTRUMENTS
ETL_COMPILER_GENERIC
ETL_COMPILER_VERSION These will be defined as the compiler version numbers,
ETL_COMPILER_FULL_VERSION if available.
ETL_DEVELOPMENT_OS_WINDOWS One of these will be defined.
ETL_DEVELOPMENT_OS_LINUX
ETL_DEVELOPMENT_OS_UNIX
ETL_DEVELOPMENT_OS_APPLE
ETL_DEVELOPMENT_OS_BSD
ETL_DEVELOPMENT_OS_GENERIC
ETL_NO_CPP_NAN_SUPPORT If defined, indicates that the compiler does not support nan(),
nanf() or nanl().
Automatically defined if using CodeWorks for ARM

5
docs/raw/utilities/Algorithms.txt
View File

@ -9,9 +9,6 @@ Functions returning pair will either use std::pair or, if ETL_NO_STL is defined,
Constexpr
Some algorithms will be constexpr, dependent on the compiler support and ETL setup.
ETL_FORCE_CONSTEXPR_ALGORITHMS
If this macro is defined, then certain algorithms will be always be constexpr, regardless of STL setting or availability of compiler built-ins. The downside, if the STL is not use, is that some copy algorithms may be less efficient when used at run-time.
See the descriptions below.
____________________________________________________________________________________________________
swap
Only defined if ETL_NO_STL is defined.
@ -134,7 +131,6 @@ https://en.cppreference.com/w/cpp/algorithm/reverse_copy
Constexpr
This function is constexpr under the following conditions.
⦁ The STL is in use and C++20 is supported.
⦁ The STL is in use and ETL_FORCE_CONSTEXPR_ALGORITHMS is defined as 1.
⦁ The STL is not in use.
____________________________________________________________________________________________________
copy_backward
@ -147,7 +143,6 @@ https://en.cppreference.com/w/cpp/algorithm/copy_backward
Constexpr
This function is constexpr under the following conditions.
⦁ The STL is in use and C++20 is supported.
⦁ The STL is in use and ETL_FORCE_CONSTEXPR_ALGORITHMS is defined as 1.
⦁ The STL is not in use.
____________________________________________________________________________________________________
count

103
docs/raw/utilities/Alignment.txt
View File

@ -1,103 +0,0 @@
Alignment
A way of aligning memory storage through template parameters.
____________________________________________________________________________________________________
type_with_alignment
Returns a fundamental type that has the same alignment as that specified in the template parameter.
template <const size_t ALIGNMENT>
class type_with_alignment
Example
typedef etl::type_with_alignment<4>::type type_t;
____________________________________________________________________________________________________
aligned_storage
Creates a memory store of the specified length at the specified alignment.
template <const size_t LENGTH, const size_t ALIGNMENT>
struct aligned_storage;
Example
// Creates aligned storage of length 100 at an alignment of 8.
etl::aligned_storage<100, 8>::type storage;
The class defines various conversion operators for ease of use.
Conversions are supplied to T&, const T&, T*, const T*, plus explicit get_address and get_reference member functions.
____________________________________________________________________________________________________
aligned_storage_as
Creates a memory store of the specified length at the same alignment as the specified type.
template <const size_t LENGTH, typename T>
struct aligned_storage_as;
Example
// Creates aligned storage of length 100 at an alignment of a double.
etl::aligned_storage_as<100, double>::type storage;
____________________________________________________________________________________________________
typed_storage
20.40.1
template <typename T>
class typed_storage;
Wrapper class that provides a memory area and lets the user create an instance of T in this memory at runtime.
This class also erases the destructor call of T, i.e. if typed_storage goes out of scope, the destructor if the wrapped type will not be called. This can be done explicitly by calling destroy().
T value_type
T& reference
const T& const_reference
T* pointer
const T* const_pointer
typed_storage()
Constructor
~typed_storage() = default;
Defaulted destructor which will NOT call the destructor of the object which was created by calling create().
____________________________________________________________________________________________________
void destroy()
Calls the destructor of the wrapped object and asserts if has_value() is false.
____________________________________________________________________________________________________
bool has_value() const
Returns true if object has been constructed using create().
Returns false otherwise.
____________________________________________________________________________________________________
template <typename... Args>
reference create(Args&&... args)
Constructs the instance of T forwarding the given args to its constructor and asserts etl::typed_storage_error if has_value() is false.
Returns the instance of T which has been constructed in the internal byte array.
____________________________________________________________________________________________________
pointer operator->()
Returns a pointer of type T and asserts etl::typed_storage_error if has_value() is false.
const_pointer operator->() const
Returns a const pointer of type T and asserts etl::typed_storage_error if has_value() is false.
____________________________________________________________________________________________________
reference operator*()
Returns reference of type T and asserts if etl::typed_storage_error if has_value() is false.
const_reference operator*() const
Returns const reference of type T and asserts etl::typed_storage_error if has_value() is false.
____________________________________________________________________________________________________
is_aligned
20.35.12
bool is_aligned(void* p, size_t alignment)
Check that p has alignment
____________________________________________________________________________________________________
template <size_t Alignment>
bool is_aligned(void* p)
Check that p has Alignment
____________________________________________________________________________________________________
template <typename T>
bool is_aligned(void* p)
Check that p has the alignment of T
____________________________________________________________________________________________________
alignment_exception
20.35.12
Exception base for alignment
____________________________________________________________________________________________________
alignment_error
20.35.12
Memory misalignment exception.

13
docs/raw/utilities/Atomic.txt
View File

@ -1,13 +0,0 @@
Atomic
This header attempts to replicate some of the types from std::atomic.
If ETL_CPP11_SUPPORTED is defined as 1 in the profile then etl::atomic will be defined in terms of std::atomic.
Otherwise it will be implemented in terms of the built-in support, if available, from the compiler. For example, early GCC and Arm compilers will use the __sync built-ins.
If a type cannot be handled by the built-ins then the types are wrapped by etl::mutex.
If there is an ETL atomic type available for your platform then ETL_HAS_ATOMIC will be set to 1, otherwise
it will be set to 0.
From 20.40.0 etl::atomic supports the is_always_lock_free property.

380
docs/raw/utilities/Binary.txt
View File

@ -1,380 +0,0 @@
Binary
Utility functions for manipulating binary numbers.
ETL_CONSTEXPR = constexpr for C++11 or above
ETL_CONSTEXPR14 = constexpr for C++14 or above
____________________________________________________________________________________________________
Rotate
Rotate the bits in the value left or right.
template <typename T>
ETL_CONSTEXPR14 T rotate_left(T value)
template <typename T>
ETL_CONSTEXPR14 T rotate_left(T value, size_t distance)
template <typename T>
ETL_CONSTEXPR14 T rotate_right(T value)
template <typename T>
ETL_CONSTEXPR14 T rotate_right(T value, size_t distance)
template <typename T>
ETL_CONSTEXPR14 T rotate(T value, typename etl::make_signed<size_t>::type distance)
____________________________________________________________________________________________________
Reverse bits
Reverse the order of the bits in a value.
template <typename T>
ETL_CONSTEXPR14 T reverse_bits(T value)
The structures below define a member constant value that is Value reversed in bits.
template <int8_t Value>
struct reverse_bits_const<int8_t, Value>
template <uint8_t Value>
struct reverse_bits_const<uint8_t, Value>
template <int16_t Value>
struct reverse_bits_const<int16_t, Value>
template <uint16_t Value>
struct reverse_bits_const<uint16_t, Value>
template <int32_t Value>
struct reverse_bits_const<int32_t, Value>
template <uint32_t Value>
struct reverse_bits_const<uint32_t, Value>
template <int64_t Value>
struct reverse_bits_const<int64_t, Value>
template <uint64_t Value>
struct reverse_bits_const<uint64_t, Value>
Defines value The reversed bits.
____________________________________________________________________________________________________
Reverse bytes
Reverse the order of the bytes in a value.
template <typename T>
ETL_CONSTEXPR T reverse_bytes(T value)
____________________________________________________________________________________________________
Gray to binary
Converts a gray code value to binary.
template <typename T>
ETL_CONSTEXPR14 T gray_to_binary(T value)
____________________________________________________________________________________________________
Binary to gray
Converts a binary value to the gray code equivalent.
template <typename T>
ETL_CONSTEXPR T binary_to_gray(T value)
____________________________________________________________________________________________________
Count bits
Counts the number of set bits in a value.
template <typename T>
ETL_CONSTEXPR14 T count_bits(T value)
____________________________________________________________________________________________________
Parity
Returns 1 if the parity of the value is odd, 0 if it is even.
template <typename T>
ETL_CONSTEXPR14 T parity(T value)
____________________________________________________________________________________________________
Max value for N bits
Returns maximum unsigned value a particular number of bits can represent.
template <size_t NBits>
struct max_value_for_nbits
value_type The type for the value.
value The maximum value.
____________________________________________________________________________________________________
Fold bits
Fold a binary number down to a set number of bits using XOR.
template <typename TReturn, size_t NBits, typename TValue>
ETL_CONSTEXPR14 TReturn fold_bits(TValue value)
Example
0xE8C9AACCBC3D9A8F folded down to 20 bits = 0x998E8
uint32_t result = etl::fold_bits<uint32_t, 20>(0xE8C9AACCBC3D9A8F);
____________________________________________________________________________________________________
Sign extend
Sign extends a binary number.
template <typename TReturn, const size_t NBits, typename TValue>
ETL_CONSTEXPR14 TReturn sign_extend(TValue value)
Converts an N bit binary number, where bit N-1 is the sign bit, to a signed integral type.
____________________________________________________________________________________________________
template <typename TReturn, const size_t NBits, const size_t Shift, typename TValue>
ETL_CONSTEXPR14 TReturn sign_extend(TValue value)
Converts an N bit binary number, where bit N-1 is the sign bit, and SHIFT is the right shift amount, to a signed integral type.
____________________________________________________________________________________________________
template <typename TReturn, typename TValue>
ETL_CONSTEXPR14 TReturn sign_extend(TValue value, size_t nbits)
Converts an N bit binary number, where bit N-1 is the sign bit, to a signed integral type.
____________________________________________________________________________________________________
template <typename TReturn, typename TValue>
ETL_CONSTEXPR14 TReturn sign_extend(TValue value, size_t nbits, size_t shift)
Converts an N bit binary number, where bit N-1 is the sign bit, and shift is the right shift amount, to a signed integral type.
____________________________________________________________________________________________________
Count leading zeros
Counts the number of leading zeros in a binary number
template <typename T>
ETL_CONSTEXPR14 T count_leading_zeros(T value)
____________________________________________________________________________________________________
Count trailing zeros
Counts the number of trailing zeros in a binary number
template <typename T>
ETL_CONSTEXPR14 T count_trailing_zeros(T value)
____________________________________________________________________________________________________
Count leading ones
Counts the number of leading ones in a binary number
template <typename T>
ETL_CONSTEXPR14 T count_leading_ones(T value)
____________________________________________________________________________________________________
Count trailing ones
Counts the number of trailing ones in a binary number
template <typename T>
ETL_CONSTEXPR14 T count_trailing_ones(T value)
____________________________________________________________________________________________________
First set position
Finds the index of the first set bit from lsb.
template <typename T>
ETL_CONSTEXPR14 uint_least8_t first_set_bit_position(T value)
____________________________________________________________________________________________________
First clear position
Finds the index of the first clear bit from lsb.
template <typename T>
ETL_CONSTEXPR14 uint_least8_t first_clear_bit_position(T value)
____________________________________________________________________________________________________
First position of bit in the specified state
Finds the index of the first bit in the specified state, from lsb.
template <typename T>
ETL_CONSTEXPR14 uint_least8_t first_bit_position(bool state, T value)
____________________________________________________________________________________________________
Fill a binary value with a pattern
Fills a value of the specified width with a repeating binary pattern.
Run time
template <typename TResult, typename TValue>
ETL_CONSTEXPR TResult binary_fill(TValue value)
Generate 0x12121212
etl::binary_fill<uint32_t>(uint8_t(0x12));
Partial compile time
template <typename TResult, typename TValue, TValue N>
ETL_CONSTEXPR TResult binary_fill(TValue value)
Generate 0x12121212
etl::binary_fill<uint32_t, uint8_t, 0x12>();
____________________________________________________________________________________________________
Check a binary value for a zero byte
Checks to see if a value contains a byte of value zero.
Run time
template <typename TValue>
ETL_CONSTEXPR14 bool has_zero_byte(const TValue value)
etl::has_zero_byte(uint32_t(0x01234567)) == false
etl::has_zero_byte(uint32_t(0x01230067)) == true
____________________________________________________________________________________________________
Check a binary value for a particular value byte
Checks to see if a value contains a byte of a particular value.
Run time
template <typename TValue>
ETL_CONSTEXPR14 bool has_byte_n(TValue value, uint8_t n)
etl::has_byte_n(uint32_t(0x01234567), 0x12) == false
etl::has_byte_n(uint32_t(0x01234567), 0x45) == true
Partial compile time
template <typename TValue, TValue N>
ETL_CONSTEXPR14 bool has_byte_n(TValue value)
etl::has_byte_n<0x12>(uint32_t(0x01234567)) == false
etl::has_byte_n<0x45>(uint32_t(0x01234567)) == true
____________________________________________________________________________________________________
Merge two values
Merges two binary values according to a mask.
Bits set in the mask select bits in the first value, clear bits select those in the second.
template <typename T>
ETL_CONSTEXPR T binary_merge(T first, T second, T mask)
uint8_t first = 0x12;
uint8_t second = 0x34;
const uint8_t mask = 0xF0;
etl::binary_merge(first, second, mask) Equals 0x14
____________________________________________________________________________________________________
template <typename T, T Mask>
ETL_CONSTEXPR T binary_merge(T first, T second)
uint8_t first = 0x12;
uint8_t second = 0x34;
const uint8_t mask = 0xF0;
etl::binary_merge<uint8_t, mask>(first, second) Equals 0x14
____________________________________________________________________________________________________
Interleave two values
Interleaves two values such that bits abcd and efgh will result in eafbgchd.
ETL_CONSTEXPR14 uint16_t binary_interleave(uint8_t first, uint8_t second);
ETL_CONSTEXPR14 int16_t binary_interleave(int8_t first, int8_t second);
ETL_CONSTEXPR14 uint32_t binary_interleave(uint16_t first, uint16_t second);
ETL_CONSTEXPR14 int32_t binary_interleave(int16_t first, int16_t second);
ETL_CONSTEXPR14 uint64_t binary_interleave(uint32_t first, uint32_t second);
ETL_CONSTEXPR14 int64_t binary_interleave(int32_t first, int32_t second);
____________________________________________________________________________________________________
Odd / Even
Determines the odd or evenness of a value.
template <typename T>
ETL_CONSTEXPR bool is_odd(T value)
template <typename T>
ETL_CONSTEXPR bool is_even(T value);
____________________________________________________________________________________________________
Constants
enum binary_constant
An enumeration of 256 constants from b00000000 to b11111111 (0 to 255)
enum bit_constant
An enumeration of 32 constants from b0 to b31 (1 to 4294967296)
template <size_t Position>
struct bit
value_type The type of the value.
value The value of the bit at POSITION.
____________________________________________________________________________________________________
Creating bit masks
These classes and constexpr functions help create lsb and msb masks.
template <typename T, size_t NBits>
class lsb_mask;
Defines the member constant value as a binary value of NBits '1' shift to the LSB.
e.g. lsb_mask<int8_t, 3>::value == 0b00000111
20.34.0
____________________________________________________________________________________________________
template <typename T>
ETL_CONSTEXPR T make_lsb_mask(size_t nbits)
Returns a binary value of nbits '1' shift to the LSB.
e.g. make_lsb_mask<int8_t>(3) == 0b00000111
20.34.0
____________________________________________________________________________________________________
template <typename T, size_t NBits>
ETL_CONSTEXPR T make_lsb_mask()
Returns a binary value of nbits '1' shift to the LSB.
e.g. make_lsb_mask<int8_t, 3>() == 0b00000111
20.38.7
____________________________________________________________________________________________________
template <typename T, size_t NBits>
class msb_mask;
Returns a binary value of nbits '1' shift to the MSB.
msb_mask<int8_t, 3>::value == 0b11100000
20.34.0
____________________________________________________________________________________________________
template <typename T>
ETL_CONSTEXPR T make_msb_mask(size_t nbits)
Defines the member constant value as a binary value of NBits '1' shift to the MSB.
e.g. make_msb_mask<int8_t>(3) == 0b11100000
20.34.0
____________________________________________________________________________________________________
template <typename T, size_t NBits>
ETL_CONSTEXPR T make_msb_mask()
Defines the member constant value as a binary value of NBits '1' shift to the MSB.
e.g. make_msb_mask<int8_t, 3>() == 0b11100000
20.38.7
____________________________________________________________________________________________________
Bit manipulation functors
These functors are most useful where lambdas are not available.
____________________________________________________________________________________________________
binary_not
template <typename T>
struct binary_not : public etl::unary_function<T, T>;
20.38.11
____________________________________________________________________________________________________
ETL_CONTEXPR
binary_not()
Default constructor.
____________________________________________________________________________________________________
ETL_CONTEXPR
ETL_NODISCARD
T operator(T value)
Returns ~value.
____________________________________________________________________________________________________
binary_and
template <typename T>
struct binary_and : public etl::unary_function<T, T>;
20.38.11
____________________________________________________________________________________________________
ETL_CONTEXPR
binary_and(T and_value)
Constructor.
Uses and_value as the second parameter in operator().
____________________________________________________________________________________________________
ETL_CONTEXPR
ETL_NODISCARD
T operator(T value)
Returns value & and_value.
____________________________________________________________________________________________________
binary_or
template <typename T>
struct binary_or : public etl::unary_function<T, T>;
20.38.11
____________________________________________________________________________________________________
ETL_CONTEXPR
binary_and(T or_value)
Constructor.
Uses or_value as the second parameter in operator().
____________________________________________________________________________________________________
ETL_CONTEXPR
ETL_NODISCARD
T operator(T value)
Returns value | or_value.
____________________________________________________________________________________________________
binary_xor
template <typename T>
struct binary_xor : public etl::unary_function<T, T>;
20.38.11
____________________________________________________________________________________________________
ETL_CONTEXPR
binary_xor(T xor_value)
Constructor.
Uses xor_value as the second parameter in operator().
____________________________________________________________________________________________________
ETL_CONTEXPR
ETL_NODISCARD
T operator(T value)
Returns value ^ xor_value.

72
docs/raw/utilities/Bit.txt
View File

@ -1,72 +0,0 @@
Bit
Utility functions for manipulating binary numbers.
A reverse engineered version of C++20's and C++23's <bit> header.
ETL_CONSTEXPR14 = constexpr for C++14 or above
____________________________________________________________________________________________________
bit_cast
template <typename TDestination, typename TSource>>
ETL_CONSTEXPR14 TDestination bit_cast(const TSource& source) ETL_NOEXCEPT
Returns a value of type TDestination by reinterpreting the TSource object.
____________________________________________________________________________________________________
byteswap
template <typename T>
ETL_CONSTEXPR14 T byteswap(T n) ETL_NOEXCEPT
Reverses the bytes in n.
____________________________________________________________________________________________________
has_single_bit
template <typename T>
ETL_CONSTEXPR14 bool has_single_bit(T n) ETL_NOEXCEPT
Checks if n is a power of two, or has one bit set.
____________________________________________________________________________________________________
bit_ceil
template <typename T>
ETL_CONSTEXPR14 T bit_ceil(T n);
Calculates the smallest power of two, that is not smaller than n.
____________________________________________________________________________________________________
bit_floor
template <typename T>
ETL_CONSTEXPR14 T bit_floor(T n) ETL_NOEXCEPT
Calculates the smallest power of two, that is not greater than n.
____________________________________________________________________________________________________
bit_width
template <typename T>
ETL_CONSTEXPR14 T bit_width(T n) ETL_NOEXCEPT
If n is not 0, calculates the number of bits needed to store it.
If n is 0, then the result is 0.
____________________________________________________________________________________________________
rotl
template <typename T>
ETL_NODISCARD ETL_CONSTEXPR14 T rotl(T value, int n) ETL_NOEXCEPT
Computes a left circular shift of value by n.
____________________________________________________________________________________________________
rotr
template <typename T>
ETL_NODISCARD ETL_CONSTEXPR14 T rotr(T value, int n) ETL_NOEXCEPT
Computes a right circular shift of value by n.
____________________________________________________________________________________________________
countl_zero
template <typename T>
ETL_NODISCARD ETL_CONSTEXPR14 int countl_zero(T value) ETL_NOEXCEPT
Returns the number of consecutive 0 bits in n, starting from the most significant bit (left).
____________________________________________________________________________________________________
countl_one
template <typename T>
ETL_NODISCARD ETL_CONSTEXPR14 int countl_one(T value) ETL_NOEXCEPT
Returns the number of consecutive 1 bits in n, starting from the most significant bit (left).
____________________________________________________________________________________________________
countr_zero
template <typename T>
ETL_NODISCARD ETL_CONSTEXPR14 int countr_zero(T value) ETL_NOEXCEPT
Returns the number of consecutive 0 bits in n, starting from the least significant bit (right).
____________________________________________________________________________________________________
countr_one
template <typename T>
ETL_NODISCARD ETL_CONSTEXPR14 int countr_one(T value) ETL_NOEXCEPT
Returns the number of consecutive 1 bits in n, starting from the least significant bit (right).
____________________________________________________________________________________________________
popcount
template <typename T>
ETL_NODISCARD ETL_CONSTEXPR14 int popcount(T value) ETL_NOEXCEPT
Counts the number of 1 bits in an unsigned integer.

80
docs/raw/utilities/byte.txt
View File

@ -1,80 +0,0 @@
byte
20.24.0
A type that implements the concept of byte
C++03
Implemented as a class.
Cannot be cast using static_cast.
C++11 or above
Implemented as enum class.
All functions are constexpr.
____________________________________________________________________________________________________
Constructors
C++03
byte()
Constructs a default initialised byte.
____________________________________________________________________________________________________
template <typename T>
explicit byte(T v)
Constructs a byte initialised to v.
____________________________________________________________________________________________________
Non-member functions
template <typename TInteger>
constexpr TInteger to_integer(etl::byte b) noexcept
Converts to an integral type.
constexpr and noexcept for C++11 and above.
____________________________________________________________________________________________________
template <typename TInteger>
constexpr etl::byte operator <<(etl::byte b, TInteger shift) noexcept
Shifts the value of the byte to the left and returns the new byte.
constexpr and noexcept for C++11 and above.
____________________________________________________________________________________________________
template <typename TInteger>
constexpr etl::byte operator >>(etl::byte b, TInteger shift) noexcept
Shifts the value of the byte to the right and returns the new byte.
constexpr and noexcept for C++11 and above.
____________________________________________________________________________________________________
template <typename TInteger>
constexpr etl::byte& operator <<=(etl::byte& b, TInteger shift) noexcept
Shifts the value of the byte to the left and returns a reference to the byte.
constexpr and noexcept for C++11 and above.
____________________________________________________________________________________________________
template <typename TInteger>
constexpr etl::byte& operator >>=(etl::byte& b, TInteger shift) noexcept
Shifts the value of the byte to the right and returns a reference to the byte.
constexpr and noexcept for C++11 and above.
____________________________________________________________________________________________________
constexpr etl::byte operator |(etl::byte lhs, etl::byte rhs) noexcept
ORs the two bytes returns the new byte.
constexpr and noexcept for C++11 and above.
____________________________________________________________________________________________________
constexpr etl::byte operator &(etl::byte lhs, etl::byte rhs) noexcept
ANDs the two bytes returns the new byte.
constexpr and noexcept for C++11 and above.
____________________________________________________________________________________________________
constexpr etl::byte operator ^(etl::byte lhs, etl::byte rhs) noexcept
Exclusive ORs the two bytes returns the new byte.
constexpr and noexcept for C++11 and above.
____________________________________________________________________________________________________
constexpr etl::byte& operator |=(etl::byte& lhs, etl::byte rhs) noexcept
ORs the two bytes returns and a reference to the first parameter.
constexpr for C++14 and above.
noexcept for C++11 and above.
____________________________________________________________________________________________________
constexpr etl::byte& operator &=(etl::byte& lhs, etl::byte rhs) noexcept
ANDs the two bytes returns and a reference to the first parameter.
constexpr for C++14 and above.
noexcept for C++11 and above.
____________________________________________________________________________________________________
constexpr etl::byte& operator ^=(etl::byte& lhs, etl::byte rhs) noexcept
Exclusive ORs the two bytes and returns a reference to the first parameter.
constexpr for C++14 and above.
noexcept for C++11 and above.
____________________________________________________________________________________________________
constexpr etl::byte operator ~(etl::byte b) noexcept
Negates the value of the byte and returns the new value.
constexpr and noexcept for C++11 and above.

97
docs/raw/utilities/function_traits.txt
View File

@ -1,97 +0,0 @@
function_traits
Allows the traits of functions to be determined.
template <typename T>
struct function_traits;
template <typename TReturn, typename... TArgs>
struct function_traits<TReturn(*)(TArgs...)>
____________________________________________________________________________________________________
Member types
function_type
The signature of the function.
TReturn(TArgs...)
____________________________________________________________________________________________________
return_type
The return type.
TReturn
____________________________________________________________________________________________________
object_type
The object type, if a member function.
Otherwise void.
____________________________________________________________________________________________________
argument_types
An etl::type_list of the arguments.
etl::type_list<TArgs...>
____________________________________________________________________________________________________
is_function
true if a free or static member function.
bool
____________________________________________________________________________________________________
is_member_function
true if a member function.
bool
____________________________________________________________________________________________________
is_const
true if a const member function.
bool
____________________________________________________________________________________________________
argument_count
The number of arguments.
size_t
____________________________________________________________________________________________________
Example
int free_int(int i, int j);
class Object
{
public:
int member_int(int i, int j);
int member_int_const(int i, int j) const;
static void member_static(int i, int j);
};
____________________________________________________________________________________________________
using traits1 = etl::function_traits<decltype(&free_int)>;
function_type int(int, int)
return_type int
object_type void
argument_types etl::type_list<int, int>
is_function true
is_member_function false
is_const false
argument_count 2
____________________________________________________________________________________________________
using traits2 = etl::function_traits<decltype(&Object::member_int)>;
function_type int(int, int)
return_type int
object_type Object
argument_types etl::type_list<int, int>
is_function false
is_member_function true
is_const false
argument_count 2
____________________________________________________________________________________________________
using traits3 = etl::function_traits<decltype(&Object::member_int_const)>;
function_type int(int, int) const
return_type int
object_type Object
argument_types etl::type_list<int, int>
is_function false
is_member_function true
is_const true
argument_count 2
____________________________________________________________________________________________________
using traits4 = etl::function_traits<decltype(&Object::member_static)>;
function_type void(int, int)
return_type void
object_type void
argument_types etl::type_list<int, int>
is_function true
is_member_function false
is_const false
argument_count 2

29
docs/raw/utilities/initializer_list.txt
View File

@ -1,29 +0,0 @@
initializer_list
20.24.0
template <typename T>
class initializer_list
The initializer_list template class is a special case in that it must have a definition that is compatible with what the compiler expects. It must also be defined under the std namespace.
This header will either include the standard <initializer_list> header, or attempt to define a std::initializer_list template class that is compatible with the current compiler.
The header will define ETL_USING_INITIALIZER_LIST to either 1 or 0 dependant of whether std::initializer_list is available or not.
The ETL will select the STL version if you are using the STL and ETL_FORCE_ETL_INITIALIZER_LIST is not defined or,
ETL_FORCE_STD_INITIALIZER_LIST is defined.
The ETL's version will be selected if you are not using the STL or ETL_FORCE_ETL_INITIALIZER_LIST is defined.
____________________________________________________________________________________________________
What issues might I come across?
If you are not using the STL, and one of the system headers or libraries that you include reference the standard initializer_list definition then the compiler will complain of duplicate definitions. In this case you will have to force the ETL to use the STL definition. There are two macros that force selection of one or other definition.
Define one of these macros to force the selection.
ETL_FORCE_ETL_INITIALIZER_LIST
ETL_FORCE_STD_INITIALIZER_LIST
Defining ETL_NO_INITIALIZER_LIST will disable the use of std::initializer_list for the ETL.
____________________________________________________________________________________________________
If you get "No definition for initializer_list is currently available for your compiler. Visit https://github.com/ETLCPP/etl/issues to request support", it may be that neither of the ETL definitions of initializer_list are compatible with your compiler. In that case please raise an issue here. Alternatively, your compiler may be compatible with GCC/clang. Try adding the compiler's Identifier macro to the conditional compilation directive.

178
docs/utilities/alignment.md Normal file
View File

@ -0,0 +1,178 @@
---
title: alignment
---
A way of aligning memory storage through template parameters.
## type_with_alignment
Returns a fundamental type that has the same alignment as that specified in the template parameter.
```cpp
template <const size_t ALIGNMENT>
class type_with_alignment
```
**Example**
```cpp
using type_t = etl::type_with_alignment<4>::type;
```
## aligned_storage
Creates a memory store of the specified length at the specified alignment.
```cpp
template <const size_t LENGTH, const size_t ALIGNMENT>
struct aligned_storage;
```
**Example**
```cpp
// Creates aligned storage of length 100 at an alignment of 8.
etl::aligned_storage<100, 8>::type storage;
```
The class defines various conversion operators for ease of use.
Conversions are supplied to `T&`, `const T&`, `T*`, `const T*`, plus explicit get_address and get_reference member functions.
```cpp
aligned_storage_as
```
Creates a memory store of the specified length at the same alignment as the specified type.
```cpp
template <const size_t LENGTH, typename T>
struct aligned_storage_as;
```
**Example**
```cpp
// Creates aligned storage of length 100 at an alignment of a double.
etl::aligned_storage_as<100, double>::type storage;
```
## typed_storage
Since: `20.40.1`
```cpp
template <typename T>
class typed_storage;
```
Wrapper class that provides a memory area and lets the user create an instance of `T` in this memory at runtime.
This class also erases the destructor call of `T`, i.e. if typed_storage goes out of scope, the destructor if the wrapped type will not be called. This can be done explicitly by calling `destroy()`.
```cpp
T value_type
T& reference
const T& const_reference
T* pointer
const T* const_pointer
```
---
```cpp
typed_storage()
```
**Description**
Constructor
---
```cpp
~typed_storage() = default;
```
**Description**
Defaulted destructor which will NOT call the destructor of the object which was created by calling `create()`.
---
```cpp
void destroy()
```
**Description**
Calls the destructor of the wrapped object and asserts if `has_value()` is `false`.
---
```cpp
bool has_value() const
```
**Returns**
`true` if object has been constructed using `create()`, otherwise `false`.
---
```cpp
template <typename... Args>
reference create(Args&&... args)
```
**Description**
Constructs the instance of `T` forwarding the given args to its constructor and asserts `etl::typed_storage_error` if `has_value()` is `false`.
Returns the instance of `T` which has been constructed in the internal byte array.
---
```cpp
pointer operator->()
```
**Return**
A pointer of type `T` and asserts `etl::typed_storage_error` if `has_value()` is `false`.
---
```cpp
const_pointer operator->() const
```
**Return**
A const pointer of type `T` and asserts `etl::typed_storage_error` if `has_value()` is `false`.
---
```cpp
reference operator*()
```
**Return**
Reference of type `T` and asserts if `etl::typed_storage_error` if `has_value()` is `false`.
---
```cpp
const_reference operator*() const
```
**Return**
Const reference of type `T` and asserts `etl::typed_storage_error` if `has_value()` is `false`.
## is_aligned
Since: `20.35.12`
```cpp
bool is_aligned(void* p, size_t alignment)
```
**Description**
Check that `p` has `alignment`.
```cpp
template <size_t Alignment>
bool is_aligned(void* p)
```
**Description**
Check that `p` has `Alignment`.
---
```cpp
template <typename T>
bool is_aligned(void* p)
```
**Description**
Check that `p` has the alignment of `T`.
## alignment_exception
Since: `20.35.12`
Exception base for alignment
---
## alignment_error
Since: `20.35.12`
Memory misalignment exception.

21
docs/utilities/atomic.md Normal file
View File

@ -0,0 +1,21 @@
---
title: atomic
---
{{< callout type="info">}}
Header: `atomic.h`
Since: `TBC`
Similar to: [atomic](https://en.cppreference.com/cpp/atomic/atomic)
{{< /callout >}}
This header attempts to replicate some of the types from `std::atomic`.
If `ETL_CPP11_SUPPORTED` is defined as `1` in the profile then `etl::atomic` will be defined in terms of `std::atomic`.
Otherwise it will be implemented in terms of the built-in support, if available, from the compiler. For example, early GCC and Arm compilers will use the `__sync` built-ins.
If a type cannot be handled by the built-ins then the types are wrapped by `etl::mutex`.
If there is an ETL atomic type available for your platform then `ETL_HAS_ATOMIC` will be set to `1`, otherwise
it will be set to `0`.
Since: `20.40.0` `etl::atomic` supports the `is_always_lock_free` property.

30
docs/raw/utilities/constant.txt → docs/utilities/constant.md
View File

@ -1,13 +1,22 @@
constant
A helper class for templates that require constants and classes that declare value and value_type members.
---
title: "constant"
---
The class allows constants to be wrapped in a template that defines value and value_type.
This can be particularly useful in recursively defined templates where the value is defined as either a constant or a further invocation of the template.
{{< callout type="info">}}
Header: `constants.h`
Since: `TBC`
{{< /callout >}}
Example
Take the example of etl::sqrt.
A helper class for templates that require constants and classes that declare value and value_type members.
template <const intmax_t VALUE, const intmax_t I = 1>
The class allows constants to be wrapped in a template that defines value and value_type.
This can be particularly useful in recursively defined templates where the value is defined as either a constant or a further invocation of the template.
**Example**
Take the example of `etl::sqrt`.
```cpp
template <intmax_t VALUE, const intmax_t I = 1>
struct sqrt
{
typedef typename etl::conditional<((I * I) < VALUE),
@ -19,7 +28,9 @@ struct sqrt
value = type::value
};
};
```
```cpp
// Stop condition.
template <const intmax_t I>
struct sqrt<I, I>
@ -29,6 +40,7 @@ struct sqrt<I, I>
value = I
};
};
```
etl::conditional will select one of the two types based on the boolean template parameter. The types are expected to have a value member. This is achieved for the constant by wrapping it in etl::constant.
`etl::conditional` will select one of the two types based on the boolean template parameter.
The types are expected to have a value member. This is achieved for the constant by wrapping it in `etl::constant`.

83
docs/utilities/endian.md Normal file
View File

@ -0,0 +1,83 @@
---
title: "Endian"
---
{{< callout type="info">}}
Header: `endian.h`
Since: `TBC`
{{< /callout >}}
Constants & utilities for endianess.
For endian specific integral types, see `unaligned_type`.
The values for endianness are dependant on the platform setup.
If `ETL_ENDIAN_NATIVE` is defined by the user, then
&emsp;`etl::endian::little = 0`
&emsp;`etl::endian::big = 1`
If `ETL_ENDIAN_NATIVE` is not defined by the user, then the ETL selects an appropriate definition.
&emsp;If `ETL_CPP20_SUPPORTED == 1` and `ETL_USING_STL == 1` then
&emsp;&emsp;`etl::endian::little = std::endian::little`
&emsp;&emsp;`etl::endian::big = std::endian::big`
&emsp;&emsp;`etl::endian::native = std::endian::native`
else, if `__BYTE_ORDER__` is defined then
&emsp;If `__ORDER_LITTLE_ENDIAN__` is defined then
&emsp;&emsp;`etl::endian::little = __ORDER_LITTLE_ENDIAN__`
&emsp;&emsp;`etl::endian::big = __ORDER_BIG_ENDIAN__`
&emsp;&emsp;`etl::endian::native = __BYTE_ORDER__`
&emsp;else if `__LITTLE_ENDIAN__` is defined
&emsp;&emsp;`etl::endian::little = __LITTLE_ENDIAN__`
&emsp;&emsp;`etl::endian::big = __BIG_ENDIAN__`
&emsp;&emsp;`etl::endian::native = __BYTE_ORDER__`
else
The user needs to define `ETL_ENDIAN_NATIVE` either as `0` for little endian or `1` for big endian.
## endian
A smart enumeration defining little and big members.
```cpp
etl::endian::little;
etl::endian::big;
```
## endianness
Interrogates the endianness of the platform.
```cpp
etl::endian operator ()() const
```
`constexpr` if `ETL_CPP11_SUPPORTED == 1` and `ETL_ENDIAN_NATIVE` is defined.
---
```cpp
operator etl::endian() const
```
`constexpr` if `ETL_CPP11_SUPPORTED == 1` and `ETL_ENDIAN_NATIVE` is defined.
---
```cpp
static etl::endian value()
```
`constexpr` if `ETL_CPP11_SUPPORTED == 1` and `ETL_ENDIAN_NATIVE` is defined.
## Host to network
```cpp
template <typename T>
T hton(T value)
```
**Description**
Converts `value` from host to network ordering.
## Network to host
```cpp
template <typename T>
T ntoh(T value)
```
**Description**
Converts `value` from network to host ordering.

140
docs/utilities/function_traits.md Normal file
View File

@ -0,0 +1,140 @@
---
title: "function_traits"
---
{{< callout type="info">}}
Header: `function_traits.h`
Since: `TBC`
{{< /callout >}}
Allows the traits of functions to be determined.
```cpp
template <typename TReturn, typename... TArgs>
struct function_traits<TReturn(*)(TArgs...)>
```
## Member types
`function_type`
The signature of the function.
`TReturn(TArgs...)`
---
`return_type`
The return type.
`TReturn`
---
`object_type`
The object type, if a member function, otherwise `void`.
---
`argument_types`
An `etl::type_list` of the arguments.
`etl::type_list<TArgs...>`
## Member constants
`is_function`
`true` if a free or static member function.
`bool`
---
`is_member_function`
`true` if a member function.
`bool`
---
`is_const`
`true` if a const member function.
`bool`
---
`argument_count`
The number of arguments.
`size_t`
---
**Example**
```cpp
int free_int(int i, int j);
class Object
{
public:
int member_int(int i, int j);
int member_int_const(int i, int j) const;
static void member_static(int i, int j);
};
using traits1 = etl::function_traits<decltype(&free_int)>;
```
```cpp
function_type int(int, int)
return_type int
object_type void
argument_types etl::type_list<int, int>
is_function true
is_member_function false
is_const false
argument_count 2
```
---
```cpp
using traits2 = etl::function_traits<decltype(&Object::member_int)>;
```
```cpp
function_type int(int, int)
return_type int
object_type Object
argument_types etl::type_list<int, int>
is_function false
is_member_function true
is_const false
argument_count 2
```
---
```cpp
using traits3 = etl::function_traits<decltype(&Object::member_int_const)>;
```
```cpp
function_type int(int, int) const
return_type int
object_type Object
argument_types etl::type_list<int, int>
is_function false
is_member_function true
is_const true
argument_count 2
```
---
```cpp
using traits4 = etl::function_traits<decltype(&Object::member_static)>;
```
```cpp
function_type void(int, int)
return_type void
object_type void
argument_types etl::type_list<int, int>
is_function true
is_member_function false
is_const false
argument_count 2
```

41
docs/utilities/initializer_list.md Normal file
View File

@ -0,0 +1,41 @@
---
title: "initializer_list"
---
{{< callout type="info">}}
Header: `initializer_list.h`
Since: `20.24.0`
Similar to: [initializer_list](https://en.cppreference.com/cpp/utility/initializer_list)
{{< /callout >}}
```cpp
template <typename T>
class initializer_list
```
## Special case
The `initializer_list` template class is a special case in that it *must* have a definition that is compatible with what the compiler expects. It *must* also be defined under the `std` namespace.
This header will either include the standard `<initializer_list>` header, or attempt to define a `std::initializer_list` template class that is compatible with the current compiler.
The header will define `ETL_USING_INITIALIZER_LIST` to either `1` or `0` dependant of whether `std::initializer_list` is available or not.
The ETL will select the STL version if you are using the STL and `ETL_FORCE_ETL_INITIALIZER_LIST` is not defined or,
`ETL_FORCE_STD_INITIALIZER_LIST` is defined.
The ETL's version will be selected if you are not using the STL or `ETL_FORCE_ETL_INITIALIZER_LIST` is defined.
## What issues might I come across?
If you are not using the STL, and one of the system headers or libraries that you include reference the standard initializer_list definition then the compiler will complain of duplicate definitions. In this case you will have to force the ETL to use the STL definition. There are two macros that force selection of one or other definition.
Define one of these macros to force the selection.
`ETL_FORCE_ETL_INITIALIZER_LIST`
`ETL_FORCE_STD_INITIALIZER_LIST`
Defining `ETL_NO_INITIALIZER_LIST` will disable the use of `std::initializer_list` for the ETL.
---
If you get "No definition for initializer_list is currently available for your compiler", visit [https://github.com/ETLCPP/etl/issues](https://github.com/ETLCPP/etl/issues) to request support, it may be that neither of the ETL definitions of `initializer_list` are compatible with your compiler. In that case please raise an issue here.
Alternatively, your compiler may be compatible with GCC/clang. Try adding the compiler's Identifier macro to the conditional compilation directive.