diff --git a/docs/binary/Bit.md b/docs/binary/Bit.md new file mode 100644 index 00000000..7ade295d --- /dev/null +++ b/docs/binary/Bit.md @@ -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 `` header. + +## bit_cast +```cpp +template > +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 +ETL_CONSTEXPR14 T byteswap(T n) ETL_NOEXCEPT +``` +**Description** +Reverses the bytes in `n`. + +## has_single_bit +```cpp +template +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 +ETL_CONSTEXPR14 T bit_ceil(T n); +``` +**Description** +Calculates the smallest power of two, that is not smaller than `n`. + +## bit_floor +```cpp +template +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 +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 +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 +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 +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 +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 +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 +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 +ETL_NODISCARD ETL_CONSTEXPR14 int popcount(T value) ETL_NOEXCEPT +``` +**Description** +Counts the number of `1` bits in an unsigned integer. diff --git a/docs/binary/_index.md b/docs/binary/_index.md new file mode 100644 index 00000000..2e3e32da --- /dev/null +++ b/docs/binary/_index.md @@ -0,0 +1,6 @@ +--- +title: "Binary utilities" +weight: 100 +--- + +Classes and functions that define and manipulate binary data. \ No newline at end of file diff --git a/docs/binary/binary.md b/docs/binary/binary.md new file mode 100644 index 00000000..61088439 --- /dev/null +++ b/docs/binary/binary.md @@ -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 +ETL_CONSTEXPR14 T rotate_left(T value) +``` +**Return** +`value` rotated left by one bit. + +```cpp +template +ETL_CONSTEXPR14 T rotate_left(T value, size_t distance) +``` +**Return** +`value` rotated left by `distance`. + +```cpp +template +ETL_CONSTEXPR14 T rotate_right(T value) +``` +**Return** +`value` rotated right by one bit. + +```cpp +template +ETL_CONSTEXPR14 T rotate_right(T value, size_t distance) +``` +**Return** +`value` rotated right by `distance`. + +```cpp +template +ETL_CONSTEXPR14 T rotate(T value, typename etl::make_signed::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 +ETL_CONSTEXPR14 T reverse_bits(T value) +``` + +The structures below define a member constant value that is Value reversed in bits. +```cpp +template +struct reverse_bits_const +``` +```cpp +template +struct reverse_bits_const +``` +```cpp +template +struct reverse_bits_const +``` +```cpp +template +struct reverse_bits_const +``` +```cpp +template +struct reverse_bits_const +``` +```cpp +template +struct reverse_bits_const +``` +```cpp +template +struct reverse_bits_const +``` +```cpp +template +struct reverse_bits_const +``` + +Defines `value` The reversed bits. + +## reverse_bytes +Reverse the order of the bytes in a value. + +```cpp +template +ETL_CONSTEXPR T reverse_bytes(T value) +``` + +## gray_to_binary +```cpp +template +ETL_CONSTEXPR14 T gray_to_binary(T value) +``` +Converts a gray code value to binary. + +## binary_to_gray +```cpp +template +ETL_CONSTEXPR T binary_to_gray(T value) +``` +Converts a binary value to the gray code equivalent. + +## count_bits +```cpp +template +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 +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 +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 +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(0xE8C9AACCBC3D9A8F); +``` + +## sign_extend +Sign extends a binary number. + +```cpp +template +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 +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 +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 +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 +ETL_CONSTEXPR14 T count_leading_zeros(T value) +``` +**Decsription** +Counts the number of leading zeros in a binary number + +## count_trailing_zeros +```cpp +template +ETL_CONSTEXPR14 T count_trailing_zeros(T value) +``` +**Description** +Counts the number of trailing zeros in a binary number + +## count_leading_ones +```cpp +template +ETL_CONSTEXPR14 T count_leading_ones(T value) +``` +**Description** +Counts the number of leading ones in a binary number + +## count_trailing_ones +```cpp +template +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 +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 +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 +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 +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(uint8_t(0x12)); +``` + +--- + +```cpp +template +ETL_CONSTEXPR TResult binary_fill(TValue value) +``` +*Partial compile time* + +Generate `0x12121212` +```cpp +etl::binary_fill(); +``` + +## has_zero_byte +```cpp +template +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 +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 +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 +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 +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(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 +ETL_CONSTEXPR bool is_odd(T value) +``` + +```cpp +template +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 +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 +class lsb_mask; +``` +Defines the member constant value as a binary value of NBits `1` shift to the LSB. +e.g. `lsb_mask::value == 0b00000111` +Since: `20.34.0` + +--- + +```cpp +template +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(3) == 0b00000111` +Since: `20.34.0` + +--- + +```cpp +template +ETL_CONSTEXPR T make_lsb_mask() +``` +**Description** +Returns a binary value of nbits `1` shift to the LSB. +e.g. `make_lsb_mask() == 0b00000111` +Since: `20.38.7` + +--- + +```cpp +template +class msb_mask; +``` +**Return** +A binary value of nbits `1` shift to the MSB. +e.g. `msb_mask::value == 0b11100000` +Since: `20.34.0` + +--- + +```cpp +template +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(3) == 0b11100000` +20.34.0 + +--- + +```cpp +template +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() == 0b11100000` +Since: `20.38.7` + +## Bit manipulation functors +These functors are most useful where lambdas are not available. + +## binary_not +```cpp +template +struct binary_not : public etl::unary_function; +``` +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 +struct binary_and : public etl::unary_function; +``` +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 +struct binary_or : public etl::unary_function; +``` +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 +struct binary_xor : public etl::unary_function; +``` +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. diff --git a/docs/binary/byte.md b/docs/binary/byte.md new file mode 100644 index 00000000..a0f8b499 --- /dev/null +++ b/docs/binary/byte.md @@ -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 +explicit byte(T v) +``` +Constructs a byte initialised to `v`. + +## Non-member functions +```cpp +template +constexpr TInteger to_integer(etl::byte b) noexcept +``` +**Description** +Converts to an integral type. +`constexpr` and `noexcept` for C++11 and above. + +--- + +```cpp +template +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 +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 +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 +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. diff --git a/docs/raw/utilities/flags.txt b/docs/binary/flags.md similarity index 68% rename from docs/raw/utilities/flags.txt rename to docs/binary/flags.md index dd3fe920..18d70820 100644 --- a/docs/raw/utilities/flags.txt +++ b/docs/binary/flags.md @@ -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 ::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& 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& pattern) ETL_NOEXCEPT +``` +**Description** +Constructs a flag set with elements set to pattern. + +## Modifiers + +```cpp ETL_CONSTEXPR14 flags& operator =(flags other) ETL_NOEXCEPT +``` +**Description** Assigns from another flags object. -____________________________________________________________________________________________________ + +--- + +```cpp ETL_CONSTEXPR14 flags& operator =(value_type pattern) ETL_NOEXCEPT +``` +**Description** Assigns from a bit pattern. -____________________________________________________________________________________________________ + +--- + +```cpp template ETL_CONSTEXPR14 flags& set() ETL_NOEXCEPT -____________________________________________________________________________________________________ +``` + +--- + +```cpp template ETL_CONSTEXPR14 flags& set(bool value) ETL_NOEXCEPT -____________________________________________________________________________________________________ +``` + +--- + +```cpp template ETL_CONSTEXPR14 flags& set() ETL_NOEXCEPT -____________________________________________________________________________________________________ +``` + +--- + +```cpp ETL_CONSTEXPR14 flags& set(value_type pattern) ETL_NOEXCEPT -____________________________________________________________________________________________________ +``` + +--- + +```cpp ETL_CONSTEXPR14 flags& set(value_type pattern, bool value) ETL_NOEXCEPT -____________________________________________________________________________________________________ +``` + +--- + +```cpp ETL_CONSTEXPR14 flags& clear() ETL_NOEXCEPT +``` ____________________________________________________________________________________________________ template ETL_CONSTEXPR14 flags& reset() ETL_NOEXCEPT diff --git a/docs/iterators/Iterator.md b/docs/iterators/Iterator.md new file mode 100644 index 00000000..e2c25e94 --- /dev/null +++ b/docs/iterators/Iterator.md @@ -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::value +``` +**Description** +Is `T` an input iterator? + +--- + +```cpp +is_input_iterator_concept::value +``` +**Description** +Can `T` be used as an input iterator? + +## Output iterators +```cpp +is_output_iterator::value +``` +**Description** +Is `T` an output iterator? + +--- + +```cpp +is_output_iterator_concept::value +``` +**Description** +Can `T` be used as an output iterator? + +## Forward iterators + +is_forward_iterator::value +Is T a forward iterator? + +is_forward_iterator_concept::value +Can T be used as an forward iterator? + +## Bidirectional iterators +is_bidirectional_iterator::value +Is T a bidirectional iterator? + +is_bidirectional_iterator_concept::value +Can T be used as a bidirectional iterator? + +## Random iterators +is_random_iterator::value +Is T a random iterator? + +is_random_iterator_concept::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 +struct iterator_traits + +Defined types +iterator_category +value_type +difference_type +pointer +reference + + +## advance + +template +ETL_CONSTEXPR17 void advance(TIterator& itr, TDistance n) + +## prev + +template +ETL_CONSTEXPR17 TIterator prev(TIterator itr, + typename etl::iterator_traits::difference_type n = 1) + +## next + +template +ETL_CONSTEXPR17 TIterator next(TIterator itr, + typename etl::iterator_traits::difference_type n = 1) + +## distance + +template +ETL_CONSTEXPR17 typename std::iterator_traits::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 +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 +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 +class move_iterator + +Defined types +iterator_category +value_type +iterator_type +difference_type +pointer +reference + +## back_insert_iterator + +Inserts using push_back. + +template +class back_insert_iterator + +--- + +template +ETL_NODISCARD +ETL_CONSTEXPR14 +etl::back_insert_iterator back_inserter(TContainer& container) + +## front_insert_iterator + +Inserts using push_front. + +template +class front_insert_iterator + +--- + +template +ETL_NODISCARD +ETL_CONSTEXPR14 +etl::front_insert_iterator front_inserter(TContainer& container) + +## push_insert_iterator + +Inserts using push. + +template +class push_insert_iterator + +--- + +template +ETL_NODISCARD +ETL_CONSTEXPR14 +etl::push_insert_iterator push_inserter(TContainer& container) + +## begin + +template +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 +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 +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 +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 +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 +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 +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 +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 +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 +ETL_OR_STD::reverse_iterator 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 +ETL_CONSTEXPR ETL_OR_STD::reverse_iterator 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 +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 +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 +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 +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 +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 +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 +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 +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 +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 +ETL_CONSTEXPR ETL_OR_STD::reverse_iterator 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 +ETL_CONSTEXPR ETL_OR_STD::reverse_iterator 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 +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 +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 +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)) +``` diff --git a/docs/iterators/_index.md b/docs/iterators/_index.md new file mode 100644 index 00000000..c3e8f705 --- /dev/null +++ b/docs/iterators/_index.md @@ -0,0 +1,7 @@ +--- +title: "Iterators" +weight: 100 +--- + +Various classes implementing iterator types. + diff --git a/docs/raw/utilities/fixed_iterator.txt b/docs/iterators/fixed_iterator.md similarity index 68% rename from docs/raw/utilities/fixed_iterator.txt rename to docs/iterators/fixed_iterator.md index be560079..d4dfa7a5 100644 --- a/docs/raw/utilities/fixed_iterator.txt +++ b/docs/iterators/fixed_iterator.md @@ -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 etl::fixed_iterator(); +``` +```cpp template etl::fixed_iterator(TIterator it); +``` +```cpp template 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::value_type operator *() const typename etl::iterator_traits::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 buffer; const char* UART_READ = (const char*) 0x1000; @@ -47,4 +79,4 @@ std::copy_n(uart_read, 20, std::back_inserter(buffer)); // Write the buffer of characters to the port. std::copy(buffer.begin(), buffer.end(), uart_write); - +``` diff --git a/docs/raw/Macros.txt b/docs/raw/Macros.txt deleted file mode 100644 index cdaa0cf7..00000000 --- a/docs/raw/Macros.txt +++ /dev/null @@ -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 - diff --git a/docs/raw/utilities/Algorithms.txt b/docs/raw/utilities/Algorithms.txt index 511c6128..a1510427 100644 --- a/docs/raw/utilities/Algorithms.txt +++ b/docs/raw/utilities/Algorithms.txt @@ -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 diff --git a/docs/raw/utilities/Alignment.txt b/docs/raw/utilities/Alignment.txt deleted file mode 100644 index e17aecd0..00000000 --- a/docs/raw/utilities/Alignment.txt +++ /dev/null @@ -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 -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 -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 -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 -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 -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 -bool is_aligned(void* p) -Check that p has Alignment -____________________________________________________________________________________________________ -template -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. - diff --git a/docs/raw/utilities/Atomic.txt b/docs/raw/utilities/Atomic.txt deleted file mode 100644 index 3d3b8c3a..00000000 --- a/docs/raw/utilities/Atomic.txt +++ /dev/null @@ -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. - diff --git a/docs/raw/utilities/Binary.txt b/docs/raw/utilities/Binary.txt deleted file mode 100644 index 22673616..00000000 --- a/docs/raw/utilities/Binary.txt +++ /dev/null @@ -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 -ETL_CONSTEXPR14 T rotate_left(T value) - -template -ETL_CONSTEXPR14 T rotate_left(T value, size_t distance) - -template -ETL_CONSTEXPR14 T rotate_right(T value) - -template -ETL_CONSTEXPR14 T rotate_right(T value, size_t distance) - -template -ETL_CONSTEXPR14 T rotate(T value, typename etl::make_signed::type distance) -____________________________________________________________________________________________________ -Reverse bits -Reverse the order of the bits in a value. - -template -ETL_CONSTEXPR14 T reverse_bits(T value) - -The structures below define a member constant value that is Value reversed in bits. -template -struct reverse_bits_const - -template -struct reverse_bits_const - -template -struct reverse_bits_const - -template -struct reverse_bits_const - -template -struct reverse_bits_const - -template -struct reverse_bits_const - -template -struct reverse_bits_const - -template -struct reverse_bits_const - -Defines value The reversed bits. -____________________________________________________________________________________________________ -Reverse bytes -Reverse the order of the bytes in a value. - -template -ETL_CONSTEXPR T reverse_bytes(T value) -____________________________________________________________________________________________________ -Gray to binary -Converts a gray code value to binary. - -template -ETL_CONSTEXPR14 T gray_to_binary(T value) -____________________________________________________________________________________________________ -Binary to gray -Converts a binary value to the gray code equivalent. - -template -ETL_CONSTEXPR T binary_to_gray(T value) -____________________________________________________________________________________________________ -Count bits -Counts the number of set bits in a value. - -template -ETL_CONSTEXPR14 T count_bits(T value) -____________________________________________________________________________________________________ -Parity -Returns 1 if the parity of the value is odd, 0 if it is even. - -template -ETL_CONSTEXPR14 T parity(T value) -____________________________________________________________________________________________________ -Max value for N bits -Returns maximum unsigned value a particular number of bits can represent. - -template -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 -ETL_CONSTEXPR14 TReturn fold_bits(TValue value) - -Example -0xE8C9AACCBC3D9A8F folded down to 20 bits = 0x998E8 - -uint32_t result = etl::fold_bits(0xE8C9AACCBC3D9A8F); -____________________________________________________________________________________________________ -Sign extend -Sign extends a binary number. - -template -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 -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 -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 -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 -ETL_CONSTEXPR14 T count_leading_zeros(T value) -____________________________________________________________________________________________________ -Count trailing zeros -Counts the number of trailing zeros in a binary number - -template -ETL_CONSTEXPR14 T count_trailing_zeros(T value) -____________________________________________________________________________________________________ -Count leading ones -Counts the number of leading ones in a binary number - -template -ETL_CONSTEXPR14 T count_leading_ones(T value) -____________________________________________________________________________________________________ -Count trailing ones -Counts the number of trailing ones in a binary number - -template -ETL_CONSTEXPR14 T count_trailing_ones(T value) -____________________________________________________________________________________________________ -First set position -Finds the index of the first set bit from lsb. - -template -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 -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 -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 -ETL_CONSTEXPR TResult binary_fill(TValue value) - -Generate 0x12121212 -etl::binary_fill(uint8_t(0x12)); - -Partial compile time -template -ETL_CONSTEXPR TResult binary_fill(TValue value) - -Generate 0x12121212 -etl::binary_fill(); -____________________________________________________________________________________________________ -Check a binary value for a zero byte -Checks to see if a value contains a byte of value zero. - -Run time -template -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 -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 -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 -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 -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(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 -ETL_CONSTEXPR bool is_odd(T value) - -template -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 -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 -class lsb_mask; -Defines the member constant value as a binary value of NBits '1' shift to the LSB. -e.g. lsb_mask::value == 0b00000111 -20.34.0 -____________________________________________________________________________________________________ -template -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(3) == 0b00000111 -20.34.0 -____________________________________________________________________________________________________ -template -ETL_CONSTEXPR T make_lsb_mask() -Returns a binary value of nbits '1' shift to the LSB. -e.g. make_lsb_mask() == 0b00000111 -20.38.7 -____________________________________________________________________________________________________ -template -class msb_mask; -Returns a binary value of nbits '1' shift to the MSB. -msb_mask::value == 0b11100000 -20.34.0 -____________________________________________________________________________________________________ -template -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(3) == 0b11100000 -20.34.0 -____________________________________________________________________________________________________ -template -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() == 0b11100000 -20.38.7 - -____________________________________________________________________________________________________ -Bit manipulation functors -These functors are most useful where lambdas are not available. -____________________________________________________________________________________________________ -binary_not -template -struct binary_not : public etl::unary_function; -20.38.11 -____________________________________________________________________________________________________ -ETL_CONTEXPR -binary_not() -Default constructor. -____________________________________________________________________________________________________ -ETL_CONTEXPR -ETL_NODISCARD -T operator(T value) -Returns ~value. -____________________________________________________________________________________________________ -binary_and -template -struct binary_and : public etl::unary_function; -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 -struct binary_or : public etl::unary_function; -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 -struct binary_xor : public etl::unary_function; -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. - - diff --git a/docs/raw/utilities/Bit.txt b/docs/raw/utilities/Bit.txt deleted file mode 100644 index e4f338aa..00000000 --- a/docs/raw/utilities/Bit.txt +++ /dev/null @@ -1,72 +0,0 @@ -Bit -Utility functions for manipulating binary numbers. -A reverse engineered version of C++20's and C++23's header. - -ETL_CONSTEXPR14 = constexpr for C++14 or above -____________________________________________________________________________________________________ -bit_cast -template > -ETL_CONSTEXPR14 TDestination bit_cast(const TSource& source) ETL_NOEXCEPT -Returns a value of type TDestination by reinterpreting the TSource object. -____________________________________________________________________________________________________ -byteswap -template -ETL_CONSTEXPR14 T byteswap(T n) ETL_NOEXCEPT -Reverses the bytes in n. -____________________________________________________________________________________________________ -has_single_bit -template -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 -ETL_CONSTEXPR14 T bit_ceil(T n); -Calculates the smallest power of two, that is not smaller than n. -____________________________________________________________________________________________________ -bit_floor -template -ETL_CONSTEXPR14 T bit_floor(T n) ETL_NOEXCEPT -Calculates the smallest power of two, that is not greater than n. -____________________________________________________________________________________________________ -bit_width -template -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 -ETL_NODISCARD ETL_CONSTEXPR14 T rotl(T value, int n) ETL_NOEXCEPT -Computes a left circular shift of value by n. -____________________________________________________________________________________________________ -rotr -template -ETL_NODISCARD ETL_CONSTEXPR14 T rotr(T value, int n) ETL_NOEXCEPT -Computes a right circular shift of value by n. -____________________________________________________________________________________________________ -countl_zero -template -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 -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 -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 -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 -ETL_NODISCARD ETL_CONSTEXPR14 int popcount(T value) ETL_NOEXCEPT -Counts the number of 1 bits in an unsigned integer. - diff --git a/docs/raw/utilities/byte.txt b/docs/raw/utilities/byte.txt deleted file mode 100644 index 164cba73..00000000 --- a/docs/raw/utilities/byte.txt +++ /dev/null @@ -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 -explicit byte(T v) -Constructs a byte initialised to v. -____________________________________________________________________________________________________ -Non-member functions - -template -constexpr TInteger to_integer(etl::byte b) noexcept -Converts to an integral type. -constexpr and noexcept for C++11 and above. -____________________________________________________________________________________________________ -template -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 -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 -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 -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. - diff --git a/docs/raw/utilities/function_traits.txt b/docs/raw/utilities/function_traits.txt deleted file mode 100644 index 541a2b63..00000000 --- a/docs/raw/utilities/function_traits.txt +++ /dev/null @@ -1,97 +0,0 @@ -function_traits - -Allows the traits of functions to be determined. - -template -struct function_traits; - -template -struct function_traits -____________________________________________________________________________________________________ -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 -____________________________________________________________________________________________________ -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; -function_type int(int, int) -return_type int -object_type void -argument_types etl::type_list -is_function true -is_member_function false -is_const false -argument_count 2 -____________________________________________________________________________________________________ -using traits2 = etl::function_traits; -function_type int(int, int) -return_type int -object_type Object -argument_types etl::type_list -is_function false -is_member_function true -is_const false -argument_count 2 -____________________________________________________________________________________________________ -using traits3 = etl::function_traits; -function_type int(int, int) const -return_type int -object_type Object -argument_types etl::type_list -is_function false -is_member_function true -is_const true -argument_count 2 -____________________________________________________________________________________________________ -using traits4 = etl::function_traits; -function_type void(int, int) -return_type void -object_type void -argument_types etl::type_list -is_function true -is_member_function false -is_const false -argument_count 2 - - diff --git a/docs/raw/utilities/initializer_list.txt b/docs/raw/utilities/initializer_list.txt deleted file mode 100644 index cfbc8b01..00000000 --- a/docs/raw/utilities/initializer_list.txt +++ /dev/null @@ -1,29 +0,0 @@ -initializer_list -20.24.0 - -template -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 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. - diff --git a/docs/utilities/alignment.md b/docs/utilities/alignment.md new file mode 100644 index 00000000..8f548890 --- /dev/null +++ b/docs/utilities/alignment.md @@ -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 +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 +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 +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 +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 +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 +bool is_aligned(void* p) +``` +**Description** +Check that `p` has `Alignment`. + +--- + +```cpp +template +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. diff --git a/docs/utilities/atomic.md b/docs/utilities/atomic.md new file mode 100644 index 00000000..0d7e12da --- /dev/null +++ b/docs/utilities/atomic.md @@ -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. diff --git a/docs/raw/utilities/constant.txt b/docs/utilities/constant.md similarity index 53% rename from docs/raw/utilities/constant.txt rename to docs/utilities/constant.md index fd5c3383..2a0a8ccb 100644 --- a/docs/raw/utilities/constant.txt +++ b/docs/utilities/constant.md @@ -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 +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 struct sqrt { typedef typename etl::conditional<((I * I) < VALUE), @@ -19,7 +28,9 @@ struct sqrt value = type::value }; }; +``` +```cpp // Stop condition. template struct sqrt @@ -29,6 +40,7 @@ struct sqrt 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`. diff --git a/docs/utilities/endian.md b/docs/utilities/endian.md new file mode 100644 index 00000000..dd90b8fa --- /dev/null +++ b/docs/utilities/endian.md @@ -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 + `etl::endian::little = 0` + `etl::endian::big = 1` + +If `ETL_ENDIAN_NATIVE` is not defined by the user, then the ETL selects an appropriate definition. + If `ETL_CPP20_SUPPORTED == 1` and `ETL_USING_STL == 1` then +  `etl::endian::little = std::endian::little` +  `etl::endian::big = std::endian::big` +  `etl::endian::native = std::endian::native` + +else, if `__BYTE_ORDER__` is defined then + If `__ORDER_LITTLE_ENDIAN__` is defined then +  `etl::endian::little = __ORDER_LITTLE_ENDIAN__` +  `etl::endian::big = __ORDER_BIG_ENDIAN__` +  `etl::endian::native = __BYTE_ORDER__` + + else if `__LITTLE_ENDIAN__` is defined +  `etl::endian::little = __LITTLE_ENDIAN__` +  `etl::endian::big = __BIG_ENDIAN__` +  `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 +T hton(T value) +``` +**Description** +Converts `value` from host to network ordering. + +## Network to host +```cpp +template +T ntoh(T value) +``` +**Description** +Converts `value` from network to host ordering. \ No newline at end of file diff --git a/docs/utilities/function_traits.md b/docs/utilities/function_traits.md new file mode 100644 index 00000000..1b32dcdf --- /dev/null +++ b/docs/utilities/function_traits.md @@ -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 +struct function_traits +``` + +## 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` + +## 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; +``` + +```cpp +function_type int(int, int) +return_type int +object_type void +argument_types etl::type_list +is_function true +is_member_function false +is_const false +argument_count 2 +``` + +--- + +```cpp +using traits2 = etl::function_traits; +``` + +```cpp +function_type int(int, int) +return_type int +object_type Object +argument_types etl::type_list +is_function false +is_member_function true +is_const false +argument_count 2 +``` + +--- + +```cpp +using traits3 = etl::function_traits; +``` +```cpp +function_type int(int, int) const +return_type int +object_type Object +argument_types etl::type_list +is_function false +is_member_function true +is_const true +argument_count 2 +``` + +--- + +```cpp +using traits4 = etl::function_traits; +``` +```cpp +function_type void(int, int) +return_type void +object_type void +argument_types etl::type_list +is_function true +is_member_function false +is_const false +argument_count 2 +``` diff --git a/docs/utilities/initializer_list.md b/docs/utilities/initializer_list.md new file mode 100644 index 00000000..cd236c46 --- /dev/null +++ b/docs/utilities/initializer_list.md @@ -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 +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 `` 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.