mirror of
https://github.com/ETLCPP/etl.git
synced 2026-10-28 18:07:10 +08:00
08b9c371a0
* Fix histogram test Use different Start index so skipped start_index copy would not get unnoticed in the test. * Fix several test_vector_* for valid data Instead of comparing the moved-from data which is invalid, compare with the valid initial_data. * Fix test_vector to check for the correct iterator position after erase This was done before, but a recent change dropped it. * Fix bit_stream: Guard nbits > 0 to prevent division by zero * Cleanup --------- Co-authored-by: John Wellbelove <jwellbelove@users.noreply.github.com>
267 lines
6.6 KiB
Markdown
267 lines
6.6 KiB
Markdown
---
|
|
title: "bit_stream_reader"
|
|
---
|
|
|
|
{{< callout type="info">}}
|
|
Header: `bit_stream.h`
|
|
Since: `TBC`
|
|
{{< /callout >}}
|
|
|
|
A binary streaming utility that allows values to be read from an array of char or unsigned char using custom bits widths for efficient packing. The bit order (MSB or LSB first) and the byte order (endianness) can be configured independently.
|
|
|
|
Read functions come in both checked and unchecked forms.
|
|
- Unchecked reads return a value of the specified type.
|
|
- Checked reads assert that there is enough space to read the value, and return an `etl::optional`.
|
|
|
|
## Storage Size
|
|
|
|
- `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::read` functions to stream custom types. Specialisations must be defined in the `etl` namespace.
|
|
|
|
## Types
|
|
|
|
```cpp
|
|
value_type char
|
|
const_iterator const char*
|
|
```
|
|
|
|
---
|
|
|
|
## Member functions
|
|
|
|
```cpp
|
|
bit_stream_reader(etl::span<char> span, etl::bit_order bit_order, etl::endian byte_order = etl::endian::big)
|
|
```
|
|
**Parameters**
|
|
`span` A `char` span of the read buffer.
|
|
`bit_order` The bit order of the stream. `etl::bit_order::msb_first` (MSB first) or `etl::bit_order::lsb_first` (LSB first).
|
|
`byte_order` The byte order (endianness) of the stream. `etl::endian::big` or `etl::endian::little`. Defaults to `etl::endian::big`.
|
|
|
|
---
|
|
|
|
```cpp
|
|
bit_stream_reader(etl::span<unsigned char> span, etl::bit_order bit_order, etl::endian byte_order = etl::endian::big)
|
|
```
|
|
**Parameters**
|
|
`span` `An unsigned char span` of the read buffer.
|
|
`bit_order` The bit order of the stream. `etl::bit_order::msb_first` (MSB first) or `etl::bit_order::lsb_first` (LSB first).
|
|
`byte_order` The byte order (endianness) of the stream. `etl::endian::big` or `etl::endian::little`. Defaults to `etl::endian::big`.
|
|
|
|
---
|
|
|
|
```cpp
|
|
bit_stream_reader(const void* begin, const void* end, etl::bit_order bit_order, etl::endian byte_order = etl::endian::big)
|
|
```
|
|
`begin` A const pointer to the beginning of the read buffer.
|
|
`end` A const pointer to the end of the read buffer.
|
|
`bit_order` The bit order of the stream. `etl::bit_order::msb_first` (MSB first) or `etl::bit_order::lsb_first` (LSB first).
|
|
`byte_order` The byte order (endianness) of the stream. `etl::endian::big` or `etl::endian::little`. Defaults to `etl::endian::big`.
|
|
|
|
---
|
|
|
|
```cpp
|
|
bit_stream_reader(const void* begin, size_t length, etl::bit_order bit_order, etl::endian byte_order = etl::endian::big)
|
|
```
|
|
`begin` A const pointer to the beginning of the read buffer.
|
|
`length` The length, in char, of the read buffer.
|
|
`bit_order` The bit order of the stream. `etl::bit_order::msb_first` (MSB first) or `etl::bit_order::lsb_first` (LSB first).
|
|
`byte_order` The byte order (endianness) of the stream. `etl::endian::big` or `etl::endian::little`. Defaults to `etl::endian::big`.
|
|
|
|
---
|
|
|
|
```cpp
|
|
void restart()
|
|
```
|
|
**Description**
|
|
Sets the reader back to the beginning of the stream.
|
|
|
|
---
|
|
|
|
```cpp
|
|
bool read_unchecked<bool>()
|
|
```
|
|
**Description**
|
|
Unchecked read for `bool` types.
|
|
|
|
---
|
|
|
|
```cpp
|
|
etl::optional<bool> read<bool>()
|
|
```
|
|
**Description**
|
|
Checked read for `bool` types.
|
|
|
|
---
|
|
|
|
```cpp
|
|
template <typename T>
|
|
T read_unchecked(uint_least8_t nbits = CHAR_BIT * sizeof(T))
|
|
```
|
|
**Description**
|
|
Unchecked read.
|
|
Enabled for integral types.
|
|
|
|
---
|
|
|
|
```cpp
|
|
template <typename T>
|
|
etl::optional<T> read(uint_least8_t nbits = CHAR_BIT * sizeof(T))
|
|
```
|
|
**Description**
|
|
Checked read.
|
|
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 in the stream buffer.
|
|
|
|
---
|
|
|
|
```cpp
|
|
size_t size_bits() const
|
|
```
|
|
**Description**
|
|
Returns the number of bits in the stream buffer.
|
|
|
|
---
|
|
|
|
```cpp
|
|
const_iterator begin() const
|
|
const_iterator cbegin() const
|
|
```
|
|
**Description**
|
|
Returns start of the stream buffer.
|
|
|
|
---
|
|
|
|
```cpp
|
|
const_iterator end() const
|
|
const_iterator cend() const
|
|
```
|
|
**Description**
|
|
Returns end of the stream.
|
|
|
|
---
|
|
|
|
```cpp
|
|
etl::span<const char> data() const
|
|
```
|
|
**Description**
|
|
Returns a span of whole the stream buffer.
|
|
|
|
---
|
|
|
|
## Non-member functions
|
|
|
|
```cpp
|
|
template <typename T>
|
|
T read_unchecked(etl::bit_stream_reader& stream)
|
|
```
|
|
Reads an unchecked type from a stream by calling `stream.read_unchecked<T>()`.
|
|
|
|
---
|
|
|
|
```cpp
|
|
template <typename T>
|
|
T read_unchecked(etl::bit_stream_reader& stream, uint_least8_t nbits)
|
|
```
|
|
**Description**
|
|
Reads an unchecked type from a stream by calling `stream.read_unchecked<T>(nbits)`.
|
|
|
|
---
|
|
|
|
```cpp
|
|
template <typename T>
|
|
etl::optional<T> read(etl::bit_stream_reader& stream)
|
|
```
|
|
**Description**
|
|
Reads a checked type from a stream by calling `stream.read<T>()`.
|
|
|
|
---
|
|
|
|
```cpp
|
|
template <typename T>
|
|
etl::optional<T> read(etl::bit_stream_reader& stream, uint_least8_t nbits)
|
|
```
|
|
**Description**
|
|
Reads a checked type from a stream by calling `stream.read<T>(nbits)`.
|
|
|
|
---
|
|
|
|
```cpp
|
|
template <>
|
|
bool read_unchecked<bool>(etl::bit_stream_reader& stream)
|
|
```
|
|
Specialisation for bool.
|
|
Reads an unchecked bool from a stream by calling `stream.read_unchecked<bool>()`.
|
|
|
|
---
|
|
|
|
```cpp
|
|
template <>
|
|
etl::optional<bool> read<bool>(etl::bit_stream_reader& stream)
|
|
```
|
|
Specialisation for bool.
|
|
Reads a checked bool from a stream by calling stream.read<bool>()
|
|
|
|
---
|
|
|
|
By specialisation of the templates, the user may create readers 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 <>
|
|
etl::optional<CustomType> read_unchecked<CustomType>(etl::bit_stream_reader& stream)
|
|
{
|
|
char c = stream.read_unchecked<char, 7U>();
|
|
short s = stream.read_unchecked<short>(11U);
|
|
int32_t i = stream.read_unchecked<int32_t>(25U);
|
|
|
|
return CustomType { c, s, i };
|
|
}
|
|
}
|
|
|
|
std::array<char, 100U> storage; // Assume the buffer gets filled with bit stream data.
|
|
etl::bit_stream_reader bit_stream(storage.data(), storage.size(), etl::bit_order::msb_first);
|
|
|
|
// Read unchecked values from the stream.
|
|
char c = etl::read_unchecked<char>(bit_stream, 6U);
|
|
unsigned short s = etl::read_unchecked<unsigned short>(bit_stream, 13U);
|
|
CustomType custom = etl::read_unchecked<CustomType>(bit_stream);
|
|
int32_t i = etl::read_unchecked<>(bit_stream, 23U);
|
|
```
|