mirror of
https://github.com/ETLCPP/etl.git
synced 2026-11-10 15:19:50 +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>
414 lines
9.0 KiB
Markdown
414 lines
9.0 KiB
Markdown
---
|
|
title: "bit_stream_writer"
|
|
---
|
|
|
|
{{< callout type="info">}}
|
|
Header: `bit_stream.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. The bit order (MSB or LSB first) and the byte order (endianness) can be configured independently.
|
|
|
|
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::bit_order bit_order, callback_type callback = callback_type(), etl::endian byte_order = etl::endian::big)
|
|
```
|
|
**Description**
|
|
Construct from span.
|
|
**Parameters**
|
|
`span` A char span of the write buffer.
|
|
`bit_order` The bit order of the stream. `etl::bit_order::msb_first` (MSB first) or `etl::bit_order::lsb_first` (LSB first).
|
|
`callback` An optional callback.
|
|
`byte_order` The byte order (endianness) of the stream. `etl::endian::big` or `etl::endian::little`. Defaults to `etl::endian::big`.
|
|
|
|
---
|
|
|
|
```cpp
|
|
bit_stream_writer(etl::span<unsigned char> span, etl::bit_order bit_order, callback_type callback = callback_type(), etl::endian byte_order = etl::endian::big)
|
|
```
|
|
**Description**
|
|
Construct from span.
|
|
**Parameters**
|
|
`span` An unsigned char span of the write buffer.
|
|
`bit_order` The bit order of the stream. `etl::bit_order::msb_first` (MSB first) or `etl::bit_order::lsb_first` (LSB first).
|
|
`callback` An optional callback.
|
|
`byte_order` The byte order (endianness) of the stream. `etl::endian::big` or `etl::endian::little`. Defaults to `etl::endian::big`.
|
|
|
|
---
|
|
|
|
```cpp
|
|
bit_stream_writer(void* begin, void* end, etl::bit_order bit_order, callback_type callback = callback_type(), etl::endian byte_order = etl::endian::big)
|
|
```
|
|
**Description**
|
|
Construct from range.
|
|
**Parameters**
|
|
`begin` A pointer to the beginning of the write buffer.
|
|
`end` A pointer to the end of the write buffer.
|
|
`bit_order` The bit order of the stream. `etl::bit_order::msb_first` (MSB first) or `etl::bit_order::lsb_first` (LSB first).
|
|
`callback` An optional callback.
|
|
`byte_order` The byte order (endianness) of the stream. `etl::endian::big` or `etl::endian::little`. Defaults to `etl::endian::big`.
|
|
|
|
---
|
|
|
|
```cpp
|
|
bit_stream_writer(void* begin, size_t length_chars, etl::bit_order bit_order, callback_type callback = callback_type(), etl::endian byte_order = etl::endian::big)
|
|
```
|
|
**Description**
|
|
Construct from begin and length.
|
|
**Parameters**
|
|
`begin` A pointer to the beginning of the write buffer.
|
|
`length` The length, in char, of the write buffer.
|
|
`bit_order` The bit order of the stream. `etl::bit_order::msb_first` (MSB first) or `etl::bit_order::lsb_first` (LSB first).
|
|
`callback` An optional callback.
|
|
`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 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 after every write.
|
|
|
|
---
|
|
|
|
```cpp
|
|
callback_type get_callback() const
|
|
```
|
|
**Description**
|
|
Gets the function to call after 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_writer bit_stream(storage.data(), storage.size(), etl::bit_order::msb_first);
|
|
|
|
// 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);
|
|
```
|