A C++ template library for embedded applications
Designed and maintained by
Aster Consulting Ltd
Join the ETL community

bit_stream

A binary streaming utility that allows boolean, integral and floating point values to be written and read from an array of
char or unsigned char using custom bits widths for efficient packing. Values are stored in the bit stream in network order.

bool

Stored as 1 bit.

Integrals

By default, stored using full bit width, otherwise uses the specified width.

Floating Point

Always stored using full bit width.
Be aware that floating point representation can change between platforms.
For example long double is 8 bytes for MS compilers and 12 for GCC.

____________________________________________________________________________________________________

Constructors


bit_stream()

Default constructor. No stream storage defined.
____________________________________________________________________________________________________
bit_stream(char* begin, char* end)
bit_stream(unsigned char* begin, unsigned char* end)

Construct from range.
____________________________________________________________________________________________________
bit_stream(char* begin, size_t length)
bit_stream(unsigned char* begin, size_t length)

Construct from begin and length.
____________________________________________________________________________________________________

Setup


void set_stream(char* begin, char* end)
void set_stream(unsigned char* begin, unsigned char* end)

Set stream from range.
____________________________________________________________________________________________________
void set_stream(char* begin, size_t length)
void set_stream(unsigned char* begin, size_t length)

Set stream from begin and length.
____________________________________________________________________________________________________

Utility


void restart()


Resets the bit stream indexes to the start.
____________________________________________________________________________________________________
bool at_end() const

Returns true if the bit stream indexes have reached the end of the stream.
____________________________________________________________________________________________________
size_t size() const

Returns the number of char used in the stream.
____________________________________________________________________________________________________
size_t bits() const

Returns the number of bits used in the stream.
____________________________________________________________________________________________________
const_iterator begin() const

Returns a const iterator to the first char in the stream.
____________________________________________________________________________________________________
const_iterator end() const

Returns a const iterator to one past the last char in the stream.
____________________________________________________________________________________________________

Put to stream


bool put(bool value)

Puts a boolean to the stream.
Returns true if the stream has enough remaining capacity to add the value.
____________________________________________________________________________________________________

template <typename T>
bool put(T value, uint_least8_t width = CHAR_BIT * sizeof(T))

Puts an integral (up to 32 bits) to the stream. The actual bit width used can be specified.
Automatically selected by the compiler for integral types.
Returns true if the stream has enough remaining capacity to add the value.
____________________________________________________________________________________________________
bool put(int64_t value, uint_least8_t width = CHAR_BIT * sizeof(int64_t))
bool put(uint64_t value, uint_least8_t width = CHAR_BIT * sizeof(uint64_t))

Puts a 64 bit integral to the stream.
Returns true if the stream has enough remaining capacity to add the value.
____________________________________________________________________________________________________
template <typename T>
bool put(T value)

Puts a floating point to the stream.
Automatically selected by the compiler for floating point types.
Returns true if the stream has enough remaining capacity to add the value.

____________________________________________________________________________________________________

Get from stream


bool get(bool& value)

Gets a boolean from the stream.
Returns true if the stream has enough remaining bits to get the value.
____________________________________________________________________________________________________
template <typename T>
bool get(T& value, uint_least8_t width = CHAR_BIT * sizeof(T))

Gets an integral from the stream. The number of bits to use can be specified.
Automatically selected by the compiler for integral types.
Returns true if the stream has enough remaining bits to get the value.
____________________________________________________________________________________________________
template <typename T>
bool get(T& value)

Gets a floating point from the stream.
Automatically selected by the compiler for floating point types.
Returns true if the stream has enough remaining bits to get the value.

____________________________________________________________________________________________________

Example


char c1           = 26;                // 6 bits
char c2           = -10;               // 7 bits
unsigned short s1 = 6742;              // 13 bits
unsigned short s2 = 1878;              // 11 bits
int32_t i1        = 2448037;           // 23 bits
int32_t i2        = -10836646;         // 25 bits
float f           = 3.1415927f;        // Possibly 32 bits
double d          = 3.1415927;         // Possibly 32 or 64 bits
long double ld    = 3.1414927L;        // Possibly 32, 64, 96 or 128 bits
int64_t ll        = 140737488355327LL; // 64 bits

std::array<unsigned char, 100> storage;

etl::bit_stream bit_stream(storage.data(), storage.size());

// Insert into the stream.
bit_stream.put(c1, 6);
bit_stream.put(s1, 13);
bit_stream.put(i1, 23);
bit_stream.put(f);
bit_stream.put(i2, 25);
bit_stream.put(d);
bit_stream.put(s2, 11);
bit_stream.put(ld);
bit_stream.put(c2, 7);
bit_stream.put(ll, 47);

bit_stream.restart();

// Read them all back.
bit_stream.get(c1, 6);
bit_stream.get(s1, 13);
bit_stream.get(i1, 23);
bit_stream.get(f);
bit_stream.get(i2, 25);
bit_stream.get(d);
bit_stream.get(s2, 11);
bit_stream.get(ld);
bit_stream.get(c2, 7);
bit_stream.get(ll, 47);
bit_stream.h