A C++ template library for embedded applications
MIT licensed
Designed and
maintained by
John Wellbelove

byte_stream_writer

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

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

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

byte_stream_writer(etl::span<char> span,
                   etl::endian stream_endianness,
                   callback_type callback = callback_type())
Construct from span.
____________________________________________________________________________________________________
byte_stream_writer(etl::span<unsigned char> span,
                   etl::endian stream_endianness,
                   callback_type callback = callback_type())
Construct from span.
____________________________________________________________________________________________________
byte_stream_writer(char* begin,
                   char* end,
                   etl::endian stream_endianness,
                   callback_type callback = callback_type())
Construct from range.
____________________________________________________________________________________________________
byte_stream_writer(char* begin,
                   size_t length,
                   etl::endian stream_endianness,
                   callback_type callback = callback_type())
Construct from begin and length.
____________________________________________________________________________________________________
template <typename T, size_t Size>
byte_stream_writer(T(&begin)[Size],
                   etl::endian stream_endianness,
                   callback_type callback = callback_type())
Construct from array.
___________________________________________________________________________________________________
Write

Checked

The following function will only write to the buffer if there is enough room to do so.

bool write(bool value)
Write a boolean value to the stream.
Returns true if successful, otherwise false.
____________________________________________________________________________________________________
template <typename T>
bool write(T value)
Write an integral or floating point value to the stream.
Returns true if successful, otherwise false.
____________________________________________________________________________________________________
template <typename T>
bool write(const etl::span<T>& range)
Write a range of integral or floating point values to the stream.
Returns true if successful, otherwise false.
____________________________________________________________________________________________________
template <typename T>
bool write(const T* start, size_t length)
Write a range of integral or floating point values to the stream.
Returns true if successful, otherwise false.
____________________________________________________________________________________________________

Unchecked

20.18.0

The following functions will always write to the buffer. They do not check for free space.



bool write_unchecked(bool value)
Write a boolean value to the stream.
Returns true if successful, otherwise false.
____________________________________________________________________________________________________
template <typename T>
void  write_unchecked(T value)
Write an integral or floating point value to the stream.
____________________________________________________________________________________________________
template <typename T>
void write_unchecked(const etl::span<T>& range)
Write a range of integral or floating point values to the stream.
____________________________________________________________________________________________________
template <typename T>
void write_unchecked(const T* start, size_t length)
Write a range of integral or floating point values to the stream.
____________________________________________________________________________________________________
Access

void restart(size_t n = 0U)
Sets the index back to position n in the stream. Default = 0.
____________________________________________________________________________________________________
20.29.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.
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

bool full() const
Returns true if the byte stream writer has reached the end.
____________________________________________________________________________________________________
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.
____________________________________________________________________________________________________
size_t capacity() const
Returns the maximum number of bytes in the stream.
____________________________________________________________________________________________________
template <typename T>
size_t available() const
The number of T left in the stream.
____________________________________________________________________________________________________
size_t available_bytes() const
The number of bytes left in the stream.
____________________________________________________________________________________________________
etl::endian get_endianness() const
Gets the endianness of the stream.
____________________________________________________________________________________________________

Callback

20.29.0
void set_callback(callback_type callback_)
Sets the delegate that is called after every write.
____________________________________________________________________________________________________
callback_type get_callback() const
Gets the delegate that is called after every write.
____________________________________________________________________________________________________
Non-member functions

Default implementation of the write 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)
____________________________________________________________________________________________________

Examples

____________________________________________________________________________________________________

Using a large buffer and processing the bytes at the end


void WriteBytesToConsole(etl::span<char> sp)
{
  for (auto itr = sp.begin(); itr != sp.end(); ++itr)
  {
    putc(*itr);
  }
}

std::array<int32_t, 4> data = { int32_t(0x00000001), int32_t(0xA55AA55A),
                                int32_t(0x5AA55AA5), int32_t(0xFFFFFFFF) };

std::array<char, 4 * sizeof(int32_t)> storage;
etl::byte_stream_writer writer(storage.data(), storage.size(), etl::endian::big);

for (auto i : data)
{
  writer.write(i);
}

etl::span<char> sp = writer.used_data();
WriteBytesToConsole(sp);
____________________________________________________________________________________________________

Using a small buffer and processing the bytes after every write


void WriteBytesToConsole(etl::span<char> sp)
{
  for (auto itr = sp.begin(); itr != sp.end(); ++itr)
  {
    putc(*itr);
  }
}

std::array<int32_t, 4> data = { int32_t(0x00000001), int32_t(0xA55AA55A),
                                int32_t(0x5AA55AA5), int32_t(0xFFFFFFFF) };

std::array<char, sizeof(int32_t)> storage;
etl::byte_stream_writer writer(storage.data(), storage.size(), etl::endian::big);

for (auto i : data)
{
  writer.write(i);
  etl::span<char> sp = writer.used_data();
  WriteBytesToConsole(sp);
  writer.restart();
}

____________________________________________________________________________________________________

Using a small buffer and processing the bytes after every write with a callback


void WriteBytesToConsole(etl::byte_stream_writer::callback_parameter_type sp)
{
  for (auto itr = sp.begin(); itr != sp.end(); ++itr)
  {
    putc(*itr);
  }
}

std::array<int32_t, 4> data = { int32_t(0x00000001), int32_t(0xA55AA55A),
                                int32_t(0x5AA55AA5), int32_t(0xFFFFFFFF) };

std::array<char, sizeof(int32_t)> storage;

auto callback =
  etl::delegate<void<etl::byte_stream_writer::callback_parameter_type>>::create<WriteBytesToConsole>();

etl::byte_stream_writer writer(storage.data(), storage.size(), etl::endian::big, callback);

for (auto i : data)
{
  writer.write(i); // Sends the bytes to WriteBytesToConsole
}
byte_stream.h