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

More documentation

Browse Source
This commit is contained in:
John Wellbelove 2026-04-22 16:03:18 +02:00
parent b1567a52c0
commit 5e2a789b23
9 changed files with 677 additions and 960 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

90
docs/raw/utilities/ETL Traits.txt
View File

@ -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 <bool Has_Atomic = etl::traits::has_atomic>
class Controller;
template<>
class Controller<false>
{
etl::mutex lock;
};
template<>
class Controller<true>
{
etl::atomic_int lock;
};

408
docs/raw/utilities/bit_stream_writer.md
View File

@ -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<value_type>
callback_type etl::delegate<void(callback_parameter_type)>
```
## Member functions
```cpp
bit_stream_writer(etl::span<char> 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<unsigned char> 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 <typename T>
void write_unchecked(T value, uint_least8_t nbits = CHAR_BIT * sizeof(T))
```
**Description**
Enabled for integral types.
---
```cpp
template <typename T>
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 Nbits>
size_t available() const
```
**Description**
The number of multiples of Nbits available in the stream.
Compile time.
---
```cpp
template <typename T>
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<char> used_data()
```
**Description**
Returns a span of the used portion of the stream.
---
```cpp
etl::span<const char> used_data() const
```
**Description**
Returns a span of the used portion of the stream.
---
```cpp
etl::span<char> data()
```
**Description**
Returns a span of whole the stream.
---
```cpp
etl::span<const char> 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 <typename T>
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 <typename T>
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<CustomType>(etl::bit_stream_reader& stream)
{
stream.write_unchecked<char, 7U>();
stream.write_unchecked<short , 11U>();
stream.write_unchecked<int32_t, 25U>();
}
}
std::array<char, 100U> 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<char>(bit_stream, 6U);
etl::write_unchecked<unsigned short>(bit_stream, 13U);
etl::write_unchecked<Custom>(bit_stream);
etl::write_unchecked<>(bit_stream, 23U);
```

227
docs/raw/utilities/bit_stream_writer.txt
View File

@ -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<value_type>
callback_type etl::delegate<void(callback_parameter_type)>
____________________________________________________________________________________________________
Member functions
bit_stream_writer(etl::span<char> 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<unsigned char> 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 <typename T>
void write_unchecked(T value, uint_least8_t nbits = CHAR_BIT * sizeof(T))
Enabled for integral types.
____________________________________________________________________________________________________
template <typename T>
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 Nbits>
size_t available() const
The number of multiples of Nbits available in the stream.
Compile time.
____________________________________________________________________________________________________
template <typename T>
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<char> used_data()
Returns a span of the used portion of the stream.
____________________________________________________________________________________________________
etl::span<const char> used_data() const
Returns a span of the used portion of the stream.
____________________________________________________________________________________________________
etl::span<char> data()
Returns a span of whole the stream.
____________________________________________________________________________________________________
etl::span<const char> 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 <typename T>
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 <typename T>
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<CustomType>(etl::bit_stream_reader& stream)
{
stream.write_unchecked<char, 7U>();
stream.write_unchecked<short , 11U>();
stream.write_unchecked<int32_t, 25U>();
}
}
std::array<char, 100U> 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<char>(bit_stream, 6U);
etl::write_unchecked<unsigned short>(bit_stream, 13U);
etl::write_unchecked<Custom>(bit_stream);
etl::write_unchecked<>(bit_stream, 23U);

139
docs/raw/utilities/byte_stream_reader.txt
View File

@ -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<char> span, etl::endian stream_endianness)
Construct from span.
____________________________________________________________________________________________________
byte_stream_reader(etl::span<const char> 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 <typename T, size_t Size>
byte_stream_reader(T(&begin)[Size], etl::endian stream_endianness)
Construct from array.
____________________________________________________________________________________________________
template <typename T, size_t Size>
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 <typename T>
etl::optional<T> read()
Read an integral value from the stream.
____________________________________________________________________________________________________
template <typename T>
etl::optional<etl::span<T>> read(size_t n)
Read a byte range from the stream.
____________________________________________________________________________________________________
template <typename T>
etl::optional<etl::span<const T>> read(etl::span<T> range)
Read a range of T from the stream.
____________________________________________________________________________________________________
template <typename T>
etl::optional<etl::span<const T>> 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 <typename T>
etl::optional<T> read_unchecked()
Read an integral value from the stream.
____________________________________________________________________________________________________
template <typename T>
etl::optional<etl::span<T>> read_unchecked(size_t n)
Read a byte range from the stream.
____________________________________________________________________________________________________
template <typename T>
etl::optional<etl::span<const T>> read_unchecked(etl::span<T> range)
Read a range of T from the stream.
____________________________________________________________________________________________________
template <typename T>
etl::optional<etl::span<const T>> 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 <typename T>
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 <typename T>
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 <typename T>
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<char> used_data() const
Returns a span of the used portion of the stream.
____________________________________________________________________________________________________
etl::span<char> free_data() const
Returns a span of the free portion of the stream.
____________________________________________________________________________________________________
etl::span<char> 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 <typename T> 20.18.0
T read_unchecked(etl::byte_stream_reader& stream)
____________________________________________________________________________________________________
template <typename T>
etl::optional<T> read(etl::byte_stream_reader& stream)

104
docs/utilities/ETL Traits.md Normal file
View File

@ -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 <bool Has_Atomic = etl::traits::has_atomic>
class Controller;
template<>
class Controller<false>
{
etl::mutex lock;
};
template<>
class Controller<true>
{
etl::atomic_int lock;
};
```

280
docs/utilities/byte_stream_reader.md Normal file
View File

@ -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<char> span, etl::endian stream_endianness)
```
**Description**
Construct from span.
---
```cpp
byte_stream_reader(etl::span<const char> 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 <typename T, size_t Size>
byte_stream_reader(T(&begin)[Size], etl::endian stream_endianness)
```
**Description**
Construct from array.
---
```cpp
template <typename T, size_t Size>
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 <typename T>
etl::optional<T> read()
```
**Description**
Read an integral value from the stream.
---
```cpp
template <typename T>
etl::optional<etl::span<T>> read(size_t n)
```
**Description**
Read a byte range from the stream.
---
```cpp
template <typename T>
etl::optional<etl::span<const T>> read(etl::span<T> range)
```
**Description**
Read a range of `T` from the stream.
---
```cpp
template <typename T>
etl::optional<etl::span<const T>> 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 <typename T>
etl::optional<T> read_unchecked()
```
**Description**
Read an integral value from the stream.
---
```cpp
template <typename T>
etl::optional<etl::span<T>> read_unchecked(size_t n)
```
**Description**
Read a byte range from the stream.
---
```cpp
template <typename T>
etl::optional<etl::span<const T>> read_unchecked(etl::span<T> range)
```
**Description**
Read a range of `T` from the stream.
---
```cpp
template <typename T>
etl::optional<etl::span<const T>> 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 <typename T>
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 <typename T>
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 <typename T>
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<char> used_data() const
```
**Description**
Returns a span of the used portion of the stream.
---
```cpp
etl::span<char> free_data() const
```
**Description**
Returns a span of the free portion of the stream.
---
```cpp
etl::span<char> 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 <typename T> 20.18.0
T read_unchecked(etl::byte_stream_reader& stream)
```
---
```cpp
template <typename T>
etl::optional<T> read(etl::byte_stream_reader& stream)
```

339
docs/raw/utilities/byte_stream_writer.txt → docs/utilities/byte_stream_writer.md
View File

@ -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<char>
callback_type etl::delegate<void(callback_parameter_type)>
____________________________________________________________________________________________________
Constructors
Callback parameter is available from 20.29.0
```
## Constructors
```cpp
byte_stream_writer(etl::span<char> 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<unsigned char> 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 <typename T, size_t Size>
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 <typename T>
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 <typename T>
bool write(const etl::span<T>& 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 <typename T>
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 <typename T>
void write_unchecked(T value)
```
**Description**
Write an integral or floating point value to the stream.
____________________________________________________________________________________________________
---
```cpp
template <typename T>
void write_unchecked(const etl::span<T>& range)
```
**Description**
Write a range of integral or floating point values to the stream.
____________________________________________________________________________________________________
---
```cpp
template <typename T>
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 <typename T>
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<char> used_data() const
Returns a span of the used portion of the stream.
____________________________________________________________________________________________________
etl::span<char> free_data() const
Returns a span of the free portion of the stream.
____________________________________________________________________________________________________
etl::span<char> 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<char> used_data() const
```
**Description**
Returns a span of the used portion of the stream.
---
```cpp
etl::span<char> free_data() const
```
**Description**
Returns a span of the free portion of the stream.
---
```cpp
etl::span<char> 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 <typename T>
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 <typename T> 20.18.0
T write_unchecked(etl::byte_stream_writer& stream)
____________________________________________________________________________________________________
```
---
```cpp
template <typename T>
etl::optional<T> 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<char> sp)
{
for (auto itr = sp.begin(); itr != sp.end(); ++itr)
@ -193,8 +355,9 @@ for (auto i : data)
etl::span<char> 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<char> 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

24
docs/raw/utilities/enum_type.txt → docs/utilities/enum_type.md
View File

@ -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.

26
docs/utilities/static_assert.md Normal file
View File

@ -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 <typename T>
void Do_This(T value)
{
ETL_STATIC_ASSERT(etl::is_integral<T>::value, "Not an integral type");
}
```