diff --git a/docs/raw/utilities/ETL Traits.txt b/docs/raw/utilities/ETL Traits.txt deleted file mode 100644 index 9f98023a..00000000 --- a/docs/raw/utilities/ETL Traits.txt +++ /dev/null @@ -1,90 +0,0 @@ -ETL Traits - -A set of traits that reflect the platform settings. It gives a C++ style interface to the library macros. -The traits are accessed under the etl::traits namespace. -All traits are constexpr for C++11 and above, const for C++03 and below. -____________________________________________________________________________________________________ -Trait Type Defined Macro -using_stl bool platform.h ETL_USING_STL -using_stlport bool platform.h ETL_USING_STLPORT -using_cpp11 bool platform.h ETL_USING_CPP11 -using_cpp14 bool platform.h ETL_USING_CPP14 -using_cpp17 bool platform.h ETL_USING_CPP17 -using_cpp20 bool platform.h ETL_USING_CPP20 -using_cpp23 bool platform.h ETL_USING_CPP23 -cplusplus long builtin __cplusplus -language_standard int platform.h ETL_LANGUAGE_STANDARD -using_exceptions bool platform.h ETL_USING_EXCEPTIONS -using_gcc_compiler bool platform.h ETL_USING_GCC_COMPILER -using_microsoft_compiler bool platform.h ETL_USING_MICROSOFT_COMPILER -using_arm5_compiler bool platform.h ETL_USING_ARM5_COMPILER -using_arm6_compiler bool platform.h ETL_USING_ARM6_COMPILER -using_arm7_compiler bool platform.h ETL_USING_ARM7_COMPILER -using_clang_compiler bool platform.h ETL_USING_CLANG_COMPILER -using_green_hills_compiler bool platform.h ETL_USING_GREEN_HILLS_COMPILER -using_iar_compiler bool platform.h ETL_USING_IAR_COMPILER -using_intel_compiler bool platform.h ETL_USING_INTEL_COMPILER -using_texas_instruments_compiler bool platform.h ETL_USING_TEXAS_INSTRUMENTS_COMPILER -using_builtin_is_assignable bool platform.h ETL_USING_BUILTIN_IS_ASSIGNABLE -using_builtin_is_constructible bool platform.h ETL_USING_BUILTIN_IS_CONSTRUCTIBLE -using_builtin_is_trivially_constructible bool platform.h ETL_USING_BUILTIN_IS_TRIVIALLY_CONSTRUCTIBLE -using_builtin_is_trivially_destructible bool platform.h ETL_USING_BUILTIN_IS_TRIVIALLY_DESTRUCTIBLE -using_builtin_is_trivially_copyable bool platform.h ETL_USING_BUILTIN_IS_TRIVIALLY_COPYABLE -using_builtin_underlying_type bool platform.h ETL_USING_BUILTIN_UNDERLYING_TYPE -using_builtin_memcpy bool platform.h ETL_USING_BUILTIN_MEMCPY -using_builtin_memmove bool platform.h ETL_USING_BUILTIN_MEMMOVE -using_builtin_memset bool platform.h ETL_USING_BUILTIN_MEMSET -using_builtin_memcmp bool platform.h ETL_USING_BUILTIN_MEMCMP -using_builtin_memchr bool platform.h ETL_USING_BUILTIN_MEMCHR -using_generic_compiler bool platform.h ETL_USING_GENERIC_COMPILER -has_8bit_types bool platform.h ETL_USING_8BIT_TYPES -has_64bit_types bool platform.h ETL_USING_64BIT_TYPES -has_atomic bool platform.h ETL_HAS_ATOMIC -has_mutex bool mutex.h ETL_HAS_MUTEX -has_nullptr bool platform.h ETL_HAS_NULLPTR -has_char8_t bool platform.h ETL_HAS_CHAR8_T -has_native_char8_t bool platform.h ETL_HAS_NATIVE_CHAR8_T -has_native_char16_t bool platform.h ETL_HAS_NATIVE_CHAR16_T -has_native_char32_t bool platform.h ETL_HAS_NATIVE_CHAR32_T -has_string_truncation_checks bool platform.h ETL_HAS_STRING_TRUNCATION_CHECKS -has_error_on_string_truncation bool platform.h ETL_HAS_ERROR_ON_STRING_TRUNCATION -has_string_clear_after_use bool platform.h ETL_HAS_STRING_CLEAR_AFTER_USE -has_istring_repair bool platform.h ETL_HAS_ISTRING_REPAIR -has_ivector_repair bool platform.h ETL_HAS_IVECTOR_REPAIR -has_mutable_array_view bool platform.h ETL_HAS_MUTABLE_ARRAY_VIEW -has_ideque_repair bool platform.h ETL_HAS_IDEQUE_REPAIR -has_initializer_list bool platform.h ETL_HAS_INITIALIZER_LIST -is_debug_build bool platform.h ETL_IS_DEBUG_BUILD -version long version.h ETL_VERSION_VALUE -version_major long version.h ETL_VERSION_MAJOR -version_minor long version.h ETL_VERSION_MINOR -version_patch long version.h ETL_VERSION_PATCH -version_string const char* version.h ETL_VERSION -version_wstring const wchar_t* version.h ETL_VERSION_W -version_u8string const char8_t* version.h ETL_VERSION_U8 if has_native_char8_t -version_u16string const char16_t* version.h ETL_VERSION_U16 -version_u32string const char32_t* version.h ETL_VERSION_U32 -____________________________________________________________________________________________________ -Examples - -if constexpr(etl::traits::is_debug_build) -{ - std::cerr << etl::traits::version_string; -} -____________________________________________________________________________________________________ - -template -class Controller; - -template<> -class Controller -{ - etl::mutex lock; -}; - -template<> -class Controller -{ - etl::atomic_int lock; -}; - diff --git a/docs/raw/utilities/bit_stream_writer.md b/docs/raw/utilities/bit_stream_writer.md deleted file mode 100644 index 79f9662d..00000000 --- a/docs/raw/utilities/bit_stream_writer.md +++ /dev/null @@ -1,408 +0,0 @@ ---- -title: "bit_stream_writer" ---- - -{{< callout type="info">}} - Header: `bit_stream_writer.h` - Since: `TBC` -{{< /callout >}} - -A binary streaming utility that allows values to be written to an array of char or unsigned char using custom bits widths for efficient packing. Values may be streamed in either msb or lsb format. - -Write functions come in both checked and unchecked forms. -- Unchecked writes return `void`. -- Checked writes assert that there is enough space to store the value, and return a `bool` indicating success or failure. - -A callback delegate can be assigned that will be called with a span of filled bytes. -If the callback is used then the stream is reset to empty or the last unfilled byte after each callback. This allows a very small buffer to be assigned. - -## Storage -`bool` -Stored as 1 bit. - -Integrals -By default, stored using full bit width, otherwise uses the specified width. - -Custom types -The user may create specializations of the non-member etl::write functions to stream custom types. Specialisations must be defined in the `etl` namespace. - -## Types - -```cpp -value_type char -iterator value_type* -const_iterator const value_type* -callback_parameter_type etl::span -callback_type etl::delegate -``` - -## Member functions -```cpp -bit_stream_writer(etl::span span, etl::endian stream_endianness, callback_type callback = callback_type()) -``` -**Description** -Construct from span. -**Parameters** -`span` A char span of the read buffer. -`stream_endianness` The endianness of the stream. `etl::endian::little` or `etl::endian::big`. -`callback` An optional callback. - ---- - -```cpp -bit_stream_writer(etl::span span, etl::endian stream_endianness, callback_type callback = callback_type()) -``` -**Description** -Construct from span. -**Parameters** -`span` A char span of the read buffer. -`stream_endianness` The endianness of the stream. etl::endian::little or etl::endian::big. -`callback` An optional callback. - ---- - -```cpp -bit_stream_writer(void* begin, void* end, etl::endian stream_endianness, callback_type callback = callback_type()) -``` -**Description** -Construct from range. -**Parameters** -`begin` A pointer to the beginning of the read buffer. -`end` A pointer to the beginning of the read buffer. -`stream_endianness` The endianness of the stream. `etl::endian::little` or `etl::endian::big`. -`callback` An optional callback. - ---- - -```cpp -bit_stream_writer(void* begin, size_t length_chars, etl::endian stream_endianness, callback_type callback = callback_type()) -``` -**Description** -Construct from begin and length. -**Parameters** -`begin` A pointer to the beginning of the read buffer. -`length` The length, in char, of the read buffer. -`stream_endianness` The endianness of the stream. `etl::endian::little` or `etl::endian::big`. - ---- - -```cpp -void restart() -``` -**Description** -Sets the indexes back to the beginning of the stream. - ---- - -```cpp -size_t capacity_bytes() const -``` -**Description** -Returns the maximum capacity in bytes. - ---- - -```cpp -size_t capacity_bits() const -``` -**Description** -Returns the maximum capacity in bits. - ---- - -```cpp -bool empty() const -``` -**Description** -Returns true if the bitsteam indexes have been reset - ---- - -```cpp -bool full() const -``` -**Description** -Returns true if the bitsteam indexes have reached the end - ---- - -```cpp -void write_unchecked(bool value) -``` -**Description** -Writes a boolean to the stream. - ---- - -```cpp -bool write(bool value) -``` -**Description** -Writes a boolean to the stream. - ---- - -```cpp -template -void write_unchecked(T value, uint_least8_t nbits = CHAR_BIT * sizeof(T)) -``` -**Description** -Enabled for integral types. - ---- - -```cpp -template -bool write(T value, uint_least8_t nbits = CHAR_BIT * sizeof(T)) -``` -**Description** -Enabled for integral types. - ---- - -```cpp -bool skip(size_t nbits) -``` -**Description** -Skip forward in the stream by nbits. -If there are not enough bits remaining in the stream it assert an etl::bit_stream_overflow and return false. - ---- - -```cpp -size_t size_bytes() const -``` -**Description** -Returns the number of bytes used in the stream. - ---- - -```cpp -size_t size_bits() const -``` -**Description** -Returns the number of bits used in the stream. - ---- - -```cpp -template -size_t available() const -``` -**Description** -The number of multiples of Nbits available in the stream. -Compile time. - ---- - -```cpp -template -size_t available() const -``` -**Description** -The number of T available in the stream. -Compile time. - ---- - -```cpp -size_t available(size_t nbits) const -``` -**Description** -The number of 'bit width' available in the stream. -Run time. - ---- - -```cpp -size_t available_bits() const -``` -**Description** -The number of bits left in the stream. - ---- - -```cpp -iterator begin() -``` -**Description** -Returns start of the stream. - ---- - -```cpp -const_iterator begin() const -``` -**Description** -Returns start of the stream. - ---- - -```cpp -const_iterator cbegin() const -``` -**Description** -Returns start of the stream. - ---- - -```cpp -iterator end() -``` -**Description** -Returns end of the stream. - ---- - -```cpp -const_iterator end() const -``` -**Description** -Returns end of the stream. - ---- - -```cpp -const_iterator cend() const -``` -**Description** -Returns end of the stream. - ---- - -```cpp -etl::span used_data() -``` -**Description** -Returns a span of the used portion of the stream. - ---- - -```cpp -etl::span used_data() const -``` -**Description** -Returns a span of the used portion of the stream. - ---- - -```cpp -etl::span data() -``` -**Description** -Returns a span of whole the stream. - ---- - -```cpp -etl::span data() const -``` -**Description** -Returns a span of whole the stream. - ---- - -```cpp -void flush() -``` -**Description** -Flush the last byte, if partially filled, to the callback. -This is only required when a callback delegate has been set. - ---- - -```cpp -void set_callback(callback_type callback_) -``` -**Description** -Sets the delegate to call afer every write. - ---- - -```cpp -callback_type get_callback() const -``` -**Description** -Gets the function to call afer every write. - ---- - -## Non-member functions - -```cpp -void write_unchecked(etl::bit_stream_writer& stream, bool value) -``` -**Description** -Implementation of the write unchecked function. -For bool types only. - ---- - -```cpp -bool write(etl::bit_stream_writer& stream, bool value) -``` -**Description** -Implementation of the write function. -For bool types only. - ---- - -```cpp -template -void write_unchecked(etl::bit_stream_writer& stream, const T& value, uint_least8_t nbits = CHAR_BIT * sizeof(T)) -``` -**Description** - Default implementation of the write function. - For integral types only (but not bool). - Overload this to support custom types. - ---- - -```cpp -template -bool write(etl::bit_stream_writer& stream, const T& value, uint_least8_t nbits = CHAR_BIT * sizeof(T)) -``` -**Description** -Default implementation of the write function. -For integral types only (but not bool). -Overload this to support custom types. - ---- - -By specialisation of the templates, the user may create writers for custom types. - -## Example -```cpp -char c = 26; // 6 bits -unsigned short s = 6742; // 13 bits -int32_t i = 2448037; // 23 bits - -struct CustomType -{ -char c = -10; // 7 bits -unsigned short s = 1878; // 11 bits -int32_t i = -10836646; // 25 bits -}; - -namespace etl -{ - // Specialisation for Custom. - // Must be defined in the etl namespace. - template <> - void write_unchecked(etl::bit_stream_reader& stream) - { - stream.write_unchecked(); - stream.write_unchecked(); - stream.write_unchecked(); - } -} - -std::array storage; // Assume the buffer gets filled with bit stream data. -etl::bit_stream_reader bit_stream(storage.data(), storage.size()); - -// Write unchecked values to the stream. -etl::write_unchecked(bit_stream, 6U); -etl::write_unchecked(bit_stream, 13U); -etl::write_unchecked(bit_stream); -etl::write_unchecked<>(bit_stream, 23U); -``` diff --git a/docs/raw/utilities/bit_stream_writer.txt b/docs/raw/utilities/bit_stream_writer.txt deleted file mode 100644 index b8e9a464..00000000 --- a/docs/raw/utilities/bit_stream_writer.txt +++ /dev/null @@ -1,227 +0,0 @@ -bit_stream_writer - -A binary streaming utility that allows values to be written to an array of char or unsigned char using custom bits widths for efficient packing. Values may be streamed in either msb or lsb format. - -Write functions come in both checked and unchecked forms. -Unchecked writes return void. -Checked writes assert that there is enough space to store the value, and return a bool indicating success or failure. - -A callback delegate can be assigned that will be called with a span of filled bytes. -If the callback is used then the stream is reset to empty or the last unfilled byte after each callback. This allows a very small buffer to be assigned. - -bool -Stored as 1 bit. - -Integrals -By default, stored using full bit width, otherwise uses the specified width. - -Custom types -The user may create specializations of the non-member etl::write functions to stream custom types. Specialisations must be defined in the etl namespace. -____________________________________________________________________________________________________ -Types - -value_type char -iterator value_type* -const_iterator const value_type* -callback_parameter_type etl::span -callback_type etl::delegate -____________________________________________________________________________________________________ -Member functions - -bit_stream_writer(etl::span span, etl::endian stream_endianness, callback_type callback = callback_type()) -Construct from span. -span -A char span of the read buffer. -stream_endianness -The endianness of the stream. -etl::endian::little or etl::endian::big -callback -An optional callback. -____________________________________________________________________________________________________ -bit_stream_writer(etl::span span, etl::endian stream_endianness, callback_type callback = callback_type()) -Construct from span. -span -A char span of the read buffer. -stream_endianness -The endianness of the stream. -etl::endian::little or etl::endian::big -callback -An optional callback. -____________________________________________________________________________________________________ -bit_stream_writer(void* begin, void* end, etl::endian stream_endianness, callback_type callback = callback_type()) -Construct from range. -begin -A pointer to the beginning of the read buffer. -end -A pointer to the beginning of the read buffer. -stream_endianness -The endianness of the stream. -etl::endian::little or etl::endian::big -callback -An optional callback. -____________________________________________________________________________________________________ -bit_stream_writer(void* begin, size_t length_chars, etl::endian stream_endianness, callback_type callback = callback_type()) -Construct from begin and length. -begin -A pointer to the beginning of the read buffer. -length -The length, in char, of the read buffer. -stream_endianness -The endianness of the stream. -etl::endian::little or etl::endian::big -____________________________________________________________________________________________________ -void restart() -Sets the indexes back to the beginning of the stream. -____________________________________________________________________________________________________ -size_t capacity_bytes() const -Returns the maximum capacity in bytes. -____________________________________________________________________________________________________ -size_t capacity_bits() const -Returns the maximum capacity in bits. -____________________________________________________________________________________________________ -bool empty() const -Returns true if the bitsteam indexes have been reset -____________________________________________________________________________________________________ -bool full() const -Returns true if the bitsteam indexes have reached the end -____________________________________________________________________________________________________ -void write_unchecked(bool value) -Writes a boolean to the stream. -____________________________________________________________________________________________________ -bool write(bool value) -Writes a boolean to the stream. -____________________________________________________________________________________________________ -template -void write_unchecked(T value, uint_least8_t nbits = CHAR_BIT * sizeof(T)) -Enabled for integral types. -____________________________________________________________________________________________________ -template -bool write(T value, uint_least8_t nbits = CHAR_BIT * sizeof(T)) -Enabled for integral types. -____________________________________________________________________________________________________ -bool skip(size_t nbits) -Skip forward in the stream by nbits. -If there are not enough bits remaining in the stream it assert an etl::bit_stream_overflow and return false. -____________________________________________________________________________________________________ -size_t size_bytes() const -Returns the number of bytes used in the stream. -____________________________________________________________________________________________________ -size_t size_bits() const -Returns the number of bits used in the stream. -____________________________________________________________________________________________________ -template -size_t available() const -The number of multiples of Nbits available in the stream. -Compile time. -____________________________________________________________________________________________________ -template -size_t available() const -The number of T available in the stream. -Compile time. -____________________________________________________________________________________________________ -size_t available(size_t nbits) const -The number of 'bit width' available in the stream. -Run time. -____________________________________________________________________________________________________ -size_t available_bits() const -The number of bits left in the stream. -____________________________________________________________________________________________________ -iterator begin() -Returns start of the stream. -____________________________________________________________________________________________________ -const_iterator begin() const -Returns start of the stream. -____________________________________________________________________________________________________ -const_iterator cbegin() const -Returns start of the stream. -____________________________________________________________________________________________________ -iterator end() -Returns end of the stream. -____________________________________________________________________________________________________ -const_iterator end() const -Returns end of the stream. -____________________________________________________________________________________________________ -const_iterator cend() const -Returns end of the stream. -____________________________________________________________________________________________________ -etl::span used_data() -Returns a span of the used portion of the stream. -____________________________________________________________________________________________________ -etl::span used_data() const -Returns a span of the used portion of the stream. -____________________________________________________________________________________________________ -etl::span data() -Returns a span of whole the stream. -____________________________________________________________________________________________________ -etl::span data() const -Returns a span of whole the stream. -____________________________________________________________________________________________________ -void flush() -Flush the last byte, if partially filled, to the callback. -This is only required when a callback delegate has been set. -____________________________________________________________________________________________________ -void set_callback(callback_type callback_) -Sets the delegate to call afer every write. -____________________________________________________________________________________________________ -callback_type get_callback() const -Gets the function to call afer every write. -____________________________________________________________________________________________________ -Non-member functions - -void write_unchecked(etl::bit_stream_writer& stream, bool value) -Implementation of the write unchecked function. -For bool types only. - -bool write(etl::bit_stream_writer& stream, bool value) -Implementation of the write function. -For bool types only. -____________________________________________________________________________________________________ -template -void write_unchecked(etl::bit_stream_writer& stream, const T& value, uint_least8_t nbits = CHAR_BIT * sizeof(T)) - Default implementation of the write function. - For integral types only (but not bool). - Overload this to support custom types. - -template -bool write(etl::bit_stream_writer& stream, const T& value, uint_least8_t nbits = CHAR_BIT * sizeof(T)) -Default implementation of the write function. -For integral types only (but not bool). -Overload this to support custom types. -____________________________________________________________________________________________________ -By specialisation of the templates, the user may create writers for custom types. -____________________________________________________________________________________________________ -Example - -char c = 26; // 6 bits -unsigned short s = 6742; // 13 bits -int32_t i = 2448037; // 23 bits - -struct CustomType -{ -char c = -10; // 7 bits -unsigned short s = 1878; // 11 bits -int32_t i = -10836646; // 25 bits -}; - -namespace etl -{ - // Specialisation for Custom. - // Must be defined in the etl namespace. - template <> - void write_unchecked(etl::bit_stream_reader& stream) - { - stream.write_unchecked(); - stream.write_unchecked(); - stream.write_unchecked(); - } -} - -std::array storage; // Assume the buffer gets filled with bit stream data. -etl::bit_stream_reader bit_stream(storage.data(), storage.size()); - -// Write unchecked values to the stream. -etl::write_unchecked(bit_stream, 6U); -etl::write_unchecked(bit_stream, 13U); -etl::write_unchecked(bit_stream); -etl::write_unchecked<>(bit_stream, 23U); - diff --git a/docs/raw/utilities/byte_stream_reader.txt b/docs/raw/utilities/byte_stream_reader.txt deleted file mode 100644 index a07a0e3c..00000000 --- a/docs/raw/utilities/byte_stream_reader.txt +++ /dev/null @@ -1,139 +0,0 @@ -byte_stream_reader -20.17.0 -A binary streaming utility that allows boolean, integral and floating point values to be read from an array of char or unsigned char. By default, values are stored in the byte stream in network order (Big Endian). This can be changed by specifying in the constructor. - -class byte_stream_reader - -Note for floating point -Be aware that floating point representations can change between platforms. -For example long double is 8 bytes for MS compilers and 12 for GCC. -____________________________________________________________________________________________________ -Types - -iterator char* -const_iterator const char* -____________________________________________________________________________________________________ -Constructors - -byte_stream_reader(etl::span span, etl::endian stream_endianness) -Construct from span. -____________________________________________________________________________________________________ -byte_stream_reader(etl::span span, etl::endian stream_endianness) -Construct from span. -____________________________________________________________________________________________________ -byte_stream_reader(const void* begin, const void* end, etl::endian stream_endianness) -Construct from range. -____________________________________________________________________________________________________ -byte_stream_reader(const void* begin, size_t length, etl::endian stream_endianness) -Construct from begin and length. -____________________________________________________________________________________________________ -template -byte_stream_reader(T(&begin)[Size], etl::endian stream_endianness) -Construct from array. -____________________________________________________________________________________________________ -template -byte_stream_reader(const T(&begin)[Size], etl::endian stream_endianness) -Construct from const array. -___________________________________________________________________________________________________ -Read -Checked -The following functions will only read from the buffer if there is enough room to do so. - -template -etl::optional read() -Read an integral value from the stream. -____________________________________________________________________________________________________ -template -etl::optional> read(size_t n) -Read a byte range from the stream. -____________________________________________________________________________________________________ -template -etl::optional> read(etl::span range) -Read a range of T from the stream. -____________________________________________________________________________________________________ -template -etl::optional> read(const T* start, size_t length) -Read a range of T from the stream. - -Unchecked 20.18.0 -The following functions will always read from the buffer. They do not check for free space. - -template -etl::optional read_unchecked() -Read an integral value from the stream. -____________________________________________________________________________________________________ -template -etl::optional> read_unchecked(size_t n) -Read a byte range from the stream. -____________________________________________________________________________________________________ -template -etl::optional> read_unchecked(etl::span range) -Read a range of T from the stream. -____________________________________________________________________________________________________ -template -etl::optional> read_unchecked(T* start, size_t length) -Read a range of T from the stream. -____________________________________________________________________________________________________ -Status - -bool empty() const -Returns true if the byte stream is empty. -____________________________________________________________________________________________________ -size_t size_bytes() const -Returns the number of bytes used in the stream. -____________________________________________________________________________________________________ -template -size_t available() const -The number of T left in the stream. -____________________________________________________________________________________________________ -Access - -void restart(size_t n = 0U) -Sets the index back to position n in the stream. Default = 0. -____________________________________________________________________________________________________ -template -bool skip(size_t n) -Skip n items of T, if the total space is available. -Returns true if the skip was possible. -Returns false if the full skip size was not possible. - -20.29.1 -template -bool skip(size_t n) -Skip n items of T, if the total space is available. -Returns true if the skip was possible. -Asserts etl::byte_stream_overflow and returns false if the skip size was not possible. -____________________________________________________________________________________________________ -const_iterator begin() const -Returns start of the stream. -____________________________________________________________________________________________________ -const_iterator end() const -Returns end of the stream. -____________________________________________________________________________________________________ -const_iterator cbegin() const -Returns start of the stream. -____________________________________________________________________________________________________ -const_iterator cend() const -Returns end of the stream. -____________________________________________________________________________________________________ -etl::span used_data() const -Returns a span of the used portion of the stream. -____________________________________________________________________________________________________ -etl::span free_data() const -Returns a span of the free portion of the stream. -____________________________________________________________________________________________________ -etl::span data() const -Returns a span of whole the stream. -____________________________________________________________________________________________________ -Non-member functions - -Default implementation of the read functions. -For integral and floating point types only. -Specialise these to support custom types. - -template 20.18.0 -T read_unchecked(etl::byte_stream_reader& stream) -____________________________________________________________________________________________________ -template -etl::optional read(etl::byte_stream_reader& stream) - diff --git a/docs/utilities/ETL Traits.md b/docs/utilities/ETL Traits.md new file mode 100644 index 00000000..fe183149 --- /dev/null +++ b/docs/utilities/ETL Traits.md @@ -0,0 +1,104 @@ +--- +title: "ETL Traits" +--- + +{{< callout type="info">}} + Header: `various` + Since: `TBC` +{{< /callout >}} + +A set of traits that reflect the platform settings. It gives a C++ style interface to the library macros. +The traits are accessed under the etl::traits namespace. +All traits are constexpr for C++11 and above, const for C++03 and below. + +## Traits + +| Trait | Type | Defined by | Macro | +| ---------------------------------------- | --------------- | ---------- | --------| +| using_stl | bool | platform.h | ETL_USING_STL | +| using_stlport | bool | platform.h | ETL_USING_STLPORT | +| using_cpp11 | bool | platform.h | ETL_USING_CPP11 | +| using_cpp14 | bool | platform.h | ETL_USING_CPP14 | +| using_cpp17 | bool | platform.h | ETL_USING_CPP17 | +| using_cpp20 | bool | platform.h | ETL_USING_CPP20 | +| using_cpp23 | bool | platform.h | ETL_USING_CPP23 | +| cplusplus | long | builtin | __cplusplus | +| language_standard | int | platform.h | ETL_LANGUAGE_STANDARD | +| using_exceptions | bool | platform.h | ETL_USING_EXCEPTIONS | +| using_gcc_compiler | bool | platform.h | ETL_USING_GCC_COMPILER | +| using_microsoft_compiler | bool | platform.h | ETL_USING_MICROSOFT_COMPILER | +| using_arm5_compiler | bool | platform.h | ETL_USING_ARM5_COMPILER | +| using_arm6_compiler | bool | platform.h | ETL_USING_ARM6_COMPILER | +| using_arm7_compiler | bool | platform.h | ETL_USING_ARM7_COMPILER | +| using_clang_compiler | bool | platform.h | ETL_USING_CLANG_COMPILER | +| using_green_hills_compiler | bool | platform.h | ETL_USING_GREEN_HILLS_COMPILER | +| using_iar_compiler | bool | platform.h | ETL_USING_IAR_COMPILER | +| using_intel_compiler | bool | platform.h | ETL_USING_INTEL_COMPILER | +| using_texas_instruments_compiler | bool | platform.h | ETL_USING_TEXAS_INSTRUMENTS_COMPILER | +| using_builtin_is_assignable | bool | platform.h | ETL_USING_BUILTIN_IS_ASSIGNABLE | +| using_builtin_is_constructible | bool | platform.h | ETL_USING_BUILTIN_IS_CONSTRUCTIBLE | +| using_builtin_is_trivially_constructible | bool | platform.h | ETL_USING_BUILTIN_IS_TRIVIALLY_CONSTRUCTIBLE | +| using_builtin_is_trivially_destructible | bool | platform.h | ETL_USING_BUILTIN_IS_TRIVIALLY_DESTRUCTIBLE | +| using_builtin_is_trivially_copyable | bool | platform.h | ETL_USING_BUILTIN_IS_TRIVIALLY_COPYABLE | +| using_builtin_underlying_type | bool | platform.h | ETL_USING_BUILTIN_UNDERLYING_TYPE | +| using_builtin_memcpy | bool | platform.h | ETL_USING_BUILTIN_MEMCPY | +| using_builtin_memmove | bool | platform.h | ETL_USING_BUILTIN_MEMMOVE | +| using_builtin_memset | bool | platform.h | ETL_USING_BUILTIN_MEMSET | +| using_builtin_memcmp | bool | platform.h | ETL_USING_BUILTIN_MEMCMP | +| using_builtin_memchr | bool | platform.h | ETL_USING_BUILTIN_MEMCHR | +| using_generic_compiler | bool | platform.h | ETL_USING_GENERIC_COMPILER | +| has_8bit_types | bool | platform.h | ETL_USING_8BIT_TYPES | +| has_64bit_types | bool | platform.h | ETL_USING_64BIT_TYPES | +| has_atomic | bool | platform.h | ETL_HAS_ATOMIC | +| has_mutex | bool | mutex.h | ETL_HAS_MUTEX | +| has_nullptr | bool | platform.h | ETL_HAS_NULLPTR | +| has_char8_t | bool | platform.h | ETL_HAS_CHAR8_T | +| has_native_char8_t | bool | platform.h | ETL_HAS_NATIVE_CHAR8_T | +| has_native_char16_t | bool | platform.h | ETL_HAS_NATIVE_CHAR16_T | +| has_native_char32_t | bool | platform.h | ETL_HAS_NATIVE_CHAR32_T | +| has_string_truncation_checks | bool | platform.h | ETL_HAS_STRING_TRUNCATION_CHECKS | +| has_error_on_string_truncation | bool | platform.h | ETL_HAS_ERROR_ON_STRING_TRUNCATION | +| has_string_clear_after_use | bool | platform.h | ETL_HAS_STRING_CLEAR_AFTER_USE | +| has_istring_repair | bool | platform.h | ETL_HAS_ISTRING_REPAIR | +| has_ivector_repair | bool | platform.h | ETL_HAS_IVECTOR_REPAIR | +| has_mutable_array_view | bool | platform.h | ETL_HAS_MUTABLE_ARRAY_VIEW | +| has_ideque_repair | bool | platform.h | ETL_HAS_IDEQUE_REPAIR | +| has_initializer_list | bool | platform.h | ETL_HAS_INITIALIZER_LIST | +| is_debug_build | bool | platform.h | ETL_IS_DEBUG_BUILD | +| version | long | version.h | ETL_VERSION_VALUE | +| version_major | long | version.h | ETL_VERSION_MAJOR | +| version_minor | long | version.h | ETL_VERSION_MINOR | +| version_patch | long | version.h | ETL_VERSION_PATCH | +| version_string | const char* | version.h | ETL_VERSION | +| version_wstring | const wchar_t * | version.h | ETL_VERSION_W | +| version_u8string | const char8_t* | version.h | ETL_VERSION_U8 if `has_native_char8_t` | +| version_u16string | const char16_t* | version.h | ETL_VERSION_U16 | +| version_u32string | const char32_t* | version.h | ETL_VERSION_U32 | + +## Examples + +```cpp +if constexpr(etl::traits::is_debug_build) +{ + std::cerr << etl::traits::version_string; +} +``` + +--- + +```cpp +template +class Controller; + +template<> +class Controller +{ + etl::mutex lock; +}; + +template<> +class Controller +{ + etl::atomic_int lock; +}; +``` diff --git a/docs/utilities/byte_stream_reader.md b/docs/utilities/byte_stream_reader.md new file mode 100644 index 00000000..d77c2daa --- /dev/null +++ b/docs/utilities/byte_stream_reader.md @@ -0,0 +1,280 @@ +--- +title: "byte_stream_reader" +--- + +{{< callout type="info">}} + Header: `byte_stream_reader.h` + Since: `20.17.0` +{{< /callout >}} + +A binary streaming utility that allows boolean, integral and floating point values to be read from an array of char or unsigned char. By default, values are stored in the byte stream in network order (Big Endian). This can be changed by specifying in the constructor. + +```cpp +class byte_stream_reader +``` + +>Note for floating point: +>Be aware that floating point representations can change between platforms. +>For example, `long double` is 8 bytes for MS compilers and 12 for GCC. + +## Types + +```cpp +iterator char* +const_iterator const char* +``` + +## Constructors + +```cpp +byte_stream_reader(etl::span span, etl::endian stream_endianness) +``` +**Description** +Construct from span. + +--- + +```cpp +byte_stream_reader(etl::span span, etl::endian stream_endianness) +``` +**Description** +Construct from span. + +--- + +```cpp +byte_stream_reader(const void* begin, const void* end, etl::endian stream_endianness) +``` +**Description** +Construct from range. + +--- + +```cpp +byte_stream_reader(const void* begin, size_t length, etl::endian stream_endianness) +``` +**Description** +Construct from begin and length. + +--- + +```cpp +template +byte_stream_reader(T(&begin)[Size], etl::endian stream_endianness) +``` +**Description** +Construct from array. + +--- + +```cpp +template +byte_stream_reader(const T(&begin)[Size], etl::endian stream_endianness) +``` +**Description** +Construct from const array. + +## Read +**Checked** +The following functions will only read from the buffer if there is enough room to do so. + +```cpp +template +etl::optional read() +``` +**Description** +Read an integral value from the stream. + +--- + +```cpp +template +etl::optional> read(size_t n) +``` +**Description** +Read a byte range from the stream. + +--- + +```cpp +template +etl::optional> read(etl::span range) +``` +**Description** +Read a range of `T` from the stream. + +--- + +```cpp +template +etl::optional> read(const T* start, size_t length) +``` +**Description** +Read a range of `T` from the stream. + +**Unchecked** +Since: `20.18.0` +The following functions will always read from the buffer. They do not check for free space. + +```cpp +template +etl::optional read_unchecked() +``` +**Description** +Read an integral value from the stream. + +--- + +```cpp +template +etl::optional> read_unchecked(size_t n) +``` +**Description** +Read a byte range from the stream. + +--- + +```cpp +template +etl::optional> read_unchecked(etl::span range) +``` +**Description** +Read a range of `T` from the stream. + +--- + +```cpp +template +etl::optional> read_unchecked(T* start, size_t length) +``` +**Description** +Read a range of `T` from the stream. + +## Status + +```cpp +bool empty() const +``` +**Description** +Returns `true` if the byte stream is empty. + +--- + +```cpp +size_t size_bytes() const +``` +**Description** +Returns the number of bytes used in the stream. + +--- + +```cpp +template +size_t available() const +``` +**Description** +The number of `T` left in the stream. + +## Access + +```cpp +void restart(size_t n = 0U) +``` +**Description** +Sets the index back to position n in the stream. Default = 0. + +--- + +```cpp +template +bool skip(size_t n) +``` +**Description** +Skip `n` items of `T`, if the total space is available. +Returns `true` if the skip was possible. +Returns `false` if the full skip size was not possible. + +--- + +```cpp +template +bool skip(size_t n) +``` +**Description** +Skip `n` items of `T`, if the total space is available. +Returns `true` if the skip was possible. +Asserts `etl::byte_stream_overflow` and returns `false` if the skip size was not possible. +Since: `20.29.1` + +--- + +```cpp +const_iterator begin() const +``` +**Description** +Returns start of the stream. + +--- + +```cpp +const_iterator end() const +``` +**Description** +Returns end of the stream. + +--- + +```cpp +const_iterator cbegin() const +``` +**Description** +Returns start of the stream. + +--- + +```cpp +const_iterator cend() const +``` +**Description** +Returns end of the stream. + +--- + +```cpp +etl::span used_data() const +``` +**Description** +Returns a span of the used portion of the stream. + +--- + +```cpp +etl::span free_data() const +``` +**Description** +Returns a span of the free portion of the stream. + +--- + +```cpp +etl::span data() const +``` +**Description** +Returns a span of whole the stream. + +## Non-member functions +Default implementation of the read functions. +For integral and floating point types only. +Specialise these to support custom types. + +```cpp +template 20.18.0 +T read_unchecked(etl::byte_stream_reader& stream) +``` + +--- + +```cpp +template +etl::optional read(etl::byte_stream_reader& stream) +``` diff --git a/docs/raw/utilities/byte_stream_writer.txt b/docs/utilities/byte_stream_writer.md similarity index 53% rename from docs/raw/utilities/byte_stream_writer.txt rename to docs/utilities/byte_stream_writer.md index 4c9b238d..cdf18ba8 100644 --- a/docs/raw/utilities/byte_stream_writer.txt +++ b/docs/utilities/byte_stream_writer.md @@ -1,177 +1,339 @@ -byte_stream_writer -20.17.0 +--- +title: "byte_stream_writer" +--- + +{{< callout type="info">}} + Header: `byte_stream_writer.h` + Since: `20.17.0` +{{< /callout >}} + A binary streaming utility that allows boolean, integral and floating point values to be written to an array of char or unsigned char. Values may be stored in the byte stream in big or little endian format. This is specified in the constructor. -20.29.0 -If a callback delegate is set, then this will be called after each write. The stream buffer indexes will be reset after every write, allowing a small buffer to be used. +If a callback delegate is set, then this will be called after each write. The stream buffer indexes will be reset after every write, allowing a small buffer to be used. +Since: `20.29.0` +```cpp class byte_stream_writer +``` -Note for floating point -Be aware that floating point representations can change between platforms. -For example long double is 8 bytes for MS compilers and 12 for GCC. -____________________________________________________________________________________________________ -Types +>Note for floating point +>Be aware that floating point representations can change between platforms. +>For example, `long double` is 8 bytes for MS compilers and 12 for GCC. +## Types + +```cpp iterator char* const_iterator const char* callback_parameter_type etl::span callback_type etl::delegate -____________________________________________________________________________________________________ -Constructors -Callback parameter is available from 20.29.0 +``` +## Constructors +```cpp byte_stream_writer(etl::span span, etl::endian stream_endianness, callback_type callback = callback_type()) +``` +**Description** Construct from span. -____________________________________________________________________________________________________ +Callback parameter is available from `20.29.0` + +--- + +```cpp byte_stream_writer(etl::span span, etl::endian stream_endianness, callback_type callback = callback_type()) +``` +**Description** Construct from span. -____________________________________________________________________________________________________ + +--- + +```cpp byte_stream_writer(char* begin, char* end, etl::endian stream_endianness, callback_type callback = callback_type()) +``` +**Description** Construct from range. -____________________________________________________________________________________________________ + +--- + +```cpp byte_stream_writer(char* begin, size_t length, etl::endian stream_endianness, callback_type callback = callback_type()) +``` +**Description** Construct from begin and length. -____________________________________________________________________________________________________ + +--- + +```cpp template byte_stream_writer(T(&begin)[Size], etl::endian stream_endianness, callback_type callback = callback_type()) +``` +**Description** Construct from array. -___________________________________________________________________________________________________ -Write -Checked + +## Write +**Checked** The following function will only write to the buffer if there is enough room to do so. +```cpp bool write(bool value) +``` +**Description** Write a boolean value to the stream. -Returns true if successful, otherwise false. -____________________________________________________________________________________________________ +Returns `true` if successful, otherwise `false`. + +--- + +```cpp template bool write(T value) +``` +**Description** Write an integral or floating point value to the stream. -Returns true if successful, otherwise false. -____________________________________________________________________________________________________ +Returns `true` if successful, otherwise `false`. + +--- + +```cpp template bool write(const etl::span& range) +``` +**Description** Write a range of integral or floating point values to the stream. -Returns true if successful, otherwise false. -____________________________________________________________________________________________________ +Returns `true` if successful, otherwise `false`. + +--- + +```cpp template bool write(const T* start, size_t length) +``` +**Description** Write a range of integral or floating point values to the stream. -Returns true if successful, otherwise false. -____________________________________________________________________________________________________ -Unchecked 20.18.0 +Returns `true` if successful, otherwise `false`. + +## Unchecked +Since: `20.18.0` The following functions will always write to the buffer. They do not check for free space. +```cpp bool write_unchecked(bool value) +``` +**Description** Write a boolean value to the stream. -Returns true if successful, otherwise false. -____________________________________________________________________________________________________ +Returns `true` if successful, otherwise `false`. + +--- + +```cpp template void write_unchecked(T value) +``` +**Description** Write an integral or floating point value to the stream. -____________________________________________________________________________________________________ + +--- + +```cpp template void write_unchecked(const etl::span& range) +``` +**Description** Write a range of integral or floating point values to the stream. -____________________________________________________________________________________________________ + +--- + +```cpp template void write_unchecked(const T* start, size_t length) +``` +**Description** Write a range of integral or floating point values to the stream. -____________________________________________________________________________________________________ -Access +## Access + +```cpp void restart(size_t n = 0U) +``` +**Description** Sets the index back to position n in the stream. Default = 0. -____________________________________________________________________________________________________ -20.29.0 + +--- + +```cpp template bool skip(size_t n) -Skip n items of T, if the total space is available. -Returns true if the skip was possible. -Asserts etl::byte_stream_overflow and returns false if the skip size was not possible. -____________________________________________________________________________________________________ -const_iterator begin() const -Returns start of the stream. -____________________________________________________________________________________________________ -const_iterator end() const -Returns end of the stream. -____________________________________________________________________________________________________ -const_iterator cbegin() const -Returns start of the stream. -____________________________________________________________________________________________________ -const_iterator cend() const -Returns end of the stream. -____________________________________________________________________________________________________ -etl::span used_data() const -Returns a span of the used portion of the stream. -____________________________________________________________________________________________________ -etl::span free_data() const -Returns a span of the free portion of the stream. -____________________________________________________________________________________________________ -etl::span data() const -Returns a span of whole the stream. -____________________________________________________________________________________________________ -Status +``` +**Description** +Skip `n` items of `T`, if the total space is available. +Returns `true` if the skip was possible. +Asserts `etl::byte_stream_overflow` and returns `false` if the skip size was not possible. +Since: `20.29.0` +--- + +```cpp +const_iterator begin() const +``` +**Description** +Returns start of the stream. + +--- + +```cpp +const_iterator end() const +``` +**Description** +Returns end of the stream. + +--- + +```cpp +const_iterator cbegin() const +``` +**Description** +Returns start of the stream. + +--- + +```cpp +const_iterator cend() const +``` +**Description** +Returns end of the stream. + +--- + +```cpp +etl::span used_data() const +``` +**Description** +Returns a span of the used portion of the stream. + +--- + +```cpp +etl::span free_data() const +``` +**Description** +Returns a span of the free portion of the stream. + +--- + +```cpp +etl::span data() const +``` +**Description** +Returns a span of whole the stream. + +## Status + +```cpp bool full() const -Returns true if the byte stream writer has reached the end. -____________________________________________________________________________________________________ +``` +**Description** +Returns `true` if the byte stream writer has reached the end. + +--- + +```cpp bool empty() const -Returns true if the byte stream is empty. -____________________________________________________________________________________________________ +``` +**Description** +Returns `true` if the byte stream is empty. + +--- + +```cpp size_t size_bytes() const +``` +**Description** Returns the number of bytes used in the stream. -____________________________________________________________________________________________________ + +--- + +```cpp size_t capacity() const +``` +**Description** Returns the maximum number of bytes in the stream. -____________________________________________________________________________________________________ + +--- + +```cpp template size_t available() const -The number of T left in the stream. -____________________________________________________________________________________________________ +``` +**Description** +The number of `T` left in the stream. + +--- + +```cpp size_t available_bytes() const +``` +**Description** The number of bytes left in the stream. -____________________________________________________________________________________________________ + +--- + +```cpp etl::endian get_endianness() const +``` +**Description** Gets the endianness of the stream. -____________________________________________________________________________________________________ -Callback -20.29.0 + +## Callback + +```cpp void set_callback(callback_type callback_) -Sets the delegate that is called after every write. -____________________________________________________________________________________________________ +``` +**Description** +Sets the delegate that is called after every write. +Since: `20.29.0` + +--- + +```cpp callback_type get_callback() const +``` +**Description** Gets the delegate that is called after every write. -____________________________________________________________________________________________________ -Non-member functions + +## Non-member functions Default implementation of the write functions. For integral and floating point types only. Specialise these to support custom types. +```cpp template 20.18.0 T write_unchecked(etl::byte_stream_writer& stream) -____________________________________________________________________________________________________ +``` + +--- + +```cpp template etl::optional write(etl::byte_stream_writer& stream) -____________________________________________________________________________________________________ -Examples -____________________________________________________________________________________________________ -Using a large buffer and processing the bytes at the end +``` +## Examples + +**Using a large buffer and processing the bytes at the end** + +```cpp void WriteBytesToConsole(etl::span sp) { for (auto itr = sp.begin(); itr != sp.end(); ++itr) @@ -193,8 +355,9 @@ for (auto i : data) etl::span sp = writer.used_data(); WriteBytesToConsole(sp); -____________________________________________________________________________________________________ -Using a small buffer and processing the bytes after every write +```cpp + +**Using a small buffer and processing the bytes after every write** void WriteBytesToConsole(etl::span sp) { @@ -218,9 +381,9 @@ for (auto i : data) writer.restart(); } -____________________________________________________________________________________________________ -Using a small buffer and processing the bytes after every write with a callback +**Using a small buffer and processing the bytes after every write with a callback** +```cpp void WriteBytesToConsole(etl::byte_stream_writer::callback_parameter_type sp) { for (auto itr = sp.begin(); itr != sp.end(); ++itr) @@ -243,4 +406,4 @@ for (auto i : data) { writer.write(i); // Sends the bytes to WriteBytesToConsole } - +```cpp diff --git a/docs/raw/utilities/enum_type.txt b/docs/utilities/enum_type.md similarity index 71% rename from docs/raw/utilities/enum_type.txt rename to docs/utilities/enum_type.md index 21b0f891..a445c5f7 100644 --- a/docs/raw/utilities/enum_type.txt +++ b/docs/utilities/enum_type.md @@ -1,12 +1,20 @@ -enum_type -Smart enumerations. +--- +title: "enum_type" +--- -A method of declaring enumerations that allow grouping within a structure. -Avoids the problem of clashing names that can occur with standard enumerations. +{{< callout type="info">}} + Header: `enum_type.h` +{{< /callout >}} -One way to think of the code is as a type with built-in constants and an optional conversion to a string +Smart enumerations. -Example +A method of declaring enumerations that allow grouping within a structure. +Avoids the problem of clashing names that can occur with standard enumerations. + +One way to think of the code is as a type with built-in constants and an optional conversion to a string. + +## Example +```cpp struct CompassDirection { enum enum_type @@ -40,6 +48,6 @@ direction = CompassDirection(3); // Explicit conversion from an invalid valu direction = value; // **** Compilation error **** std::cout << "Direction = " << direction.c_str(); // Prints "Direction = North" +``` -If a conversion to a string is not required then the ENUM_TYPE declarations may be omitted. In that case the c_str() function will return a "?". This will also be the case for any enumeration value that does not have an ENUM_TYPE entry. - +If a conversion to a string is not required then the `ETL_ENUM_TYPE` declarations may be omitted. In that case the `c_str()` function will return a `"?"`. This will also be the case for any enumeration value that does not have an `ETL_ENUM_TYPE` entry. diff --git a/docs/utilities/static_assert.md b/docs/utilities/static_assert.md new file mode 100644 index 00000000..6309800b --- /dev/null +++ b/docs/utilities/static_assert.md @@ -0,0 +1,26 @@ +--- +title: "static assert" +--- + +{{< callout type="info">}} + Header: `static_assert.h` +{{< /callout >}} + +## Macro +```cpp +ETL_STATIC_ASSERT +``` +Either maps on to the built-in `static_assert` or supplies a suitable definition. + +```cpp +ETL_STATIC_ASSERT(condition, message); +``` + +## Example +```cpp +template +void Do_This(T value) +{ + ETL_STATIC_ASSERT(etl::is_integral::value, "Not an integral type"); +} +```