byte_stream_writer

byte_stream_reader

20.17.0

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

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

const_iterator const char*

byte_stream_writer

____________________________________________________________________________________________________

Constructors

byte_stream_writer(etl::span<char> span, etl::endian buffer_endianness = etl::endian::big)

Construct from span.

byte_stream_writer(char* begin, char* end, etl::endian buffer_endianness = etl::endian::big)

Construct from range.

byte_stream_writer(char* begin, size_t length, etl::endian buffer_endianness = etl::endian::big)

Construct from begin and length.

template <typename T, size_t Size>

byte_stream_writer(T(&begin)[Size], etl::endian buffer_endianness = etl::endian::big)

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.

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

____________________________________________________________________________________________________

byte_stream_reader

____________________________________________________________________________________________________

Constructors

byte_stream_reader(etl::span<char> span, etl::endian buffer_endianness = etl::endian::big)

Construct from span.

byte_stream_reader(etl::span<const char> span, etl::endian buffer_endianness = etl::endian::big)

Construct from span.

byte_stream_reader(const void* begin, const void* end, etl::endian buffer_endianness = etl::endian::big)

Construct from range.

byte_stream_reader(const void* begin, size_t length, etl::endian buffer_endianness = etl::endian::big)

Construct from begin and length.

template <typename T, size_t Size>

byte_stream_reader(T(&begin)[Size], etl::endian buffer_endianness = etl::endian::big)

Construct from array.

template <typename T, size_t Size>

byte_stream_reader(const T(&begin)[Size], etl::endian buffer_endianness = etl::endian::big)

Construct from const array.

___________________________________________________________________________________________________

Read

Checked

The following function 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.

____________________________________________________________________________________________________

template <typename T>

bool skip(size_t n)

Skip n items of T, up to the maximum space available.

____________________________________________________________________________________________________

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.

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.write functions.

For integral and floating point types only.

Specialise these to support custom types.

template <typename T> 20.18.0

void write_unchecked(etl::byte_stream_writer& stream, const T& value)

template <typename T>

bool write(etl::byte_stream_writer& stream, const T& value)

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();

}

byte_stream.h