nalchi::bit_stream_reader Class Reference

Helper stream to read bits from your buffer. More...

#include <nalchi/bit_stream.hpp>

Public Types
using	size_type = bit_stream_writer::size_type
	Size type representing number of bits and bytes.
using	ssize_type = std::make_signed_t<size_type>
	Signed size type to allow negative error value.
using	scratch_type
	Internal scratch type to store the temporary scratch data.
using	word_type = bit_stream_writer::word_type
	Internal word type used to read from your buffer.

Public Member Functions
	bit_stream_reader (const bit_stream_reader &)=delete
	Deleted copy constructor.
auto	operator= (const bit_stream_reader &) -> bit_stream_reader &=delete
	Deleted copy assignment operator.
	bit_stream_reader ()
	Constructs a bit_stream_reader instance without a buffer.
	bit_stream_reader (std::span< const word_type > buffer, size_type logical_bytes_length)
	Constructs a bit_stream_reader instance with a std::span<word_type> buffer.
	bit_stream_reader (const word_type *begin, const word_type *end, size_type logical_bytes_length)
	Constructs a bit_stream_reader instance with a word range.
	bit_stream_reader (const word_type *begin, size_type words_length, size_type logical_bytes_length)
	Constructs a bit_stream_reader instance with a word begin pointer and the word length.
void	set_fail ()
	Force set the fail flag.
bool	fail () const noexcept
	Check if reading from your buffer has been failed or not.
bool	operator! () const noexcept
	Check if there was an error in the reading to your buffer. This is effectively same as fail().
	operator bool () const noexcept
	Check if there was no error in the reading to your buffer. This is effectively same as !fail().
auto	total_bytes () const -> size_type
	Gets the number of total bytes in the stream.
auto	total_bits () const -> size_type
	Gets the number of total bits in the stream.
auto	used_bytes () const -> size_type
	Gets the number of used bytes in the stream.
auto	used_bits () const -> size_type
	Gets the number of used bits in the stream.
auto	unused_bytes () const -> size_type
	Gets the number of unused bytes in the stream.
auto	unused_bits () const -> size_type
	Gets the number of unused bits in the stream.
void	restart ()
	Restarts the stream so that it can read from the beginning again.
void	reset ()
	Resets the stream so that it no longer holds your buffer anymore.
void	reset_with (std::span< const word_type > buffer, size_type logical_bytes_length)
	Resets the stream with a std::span<word_type> buffer.
void	reset_with (const word_type *begin, const word_type *end, size_type logical_bytes_length)
	Resets the stream with a word range.
void	reset_with (const word_type *begin, size_type words_length, size_type logical_bytes_length)
	Resets the stream with a word begin pointer and the word length.
auto	read (void *data, size_type size) -> bit_stream_reader &
	Reads some arbitrary data from the bit stream.
template<std::integral SInt> requires (sizeof(SInt) <= sizeof(word_type))
auto	read (SInt &data, SInt min=std::numeric_limits< SInt >::min(), SInt max=std::numeric_limits< SInt >::max()) -> bit_stream_reader &
	Reads an integral value from the bit stream.
template<std::integral BInt> requires (sizeof(BInt) > sizeof(word_type))
auto	read (BInt &data, BInt min=std::numeric_limits< BInt >::min(), BInt max=std::numeric_limits< BInt >::max()) -> bit_stream_reader &
	Reads an integral value from the bit stream.
auto	read (float &data) -> bit_stream_reader &
	Reads a float value from the bit stream.
auto	read (double &data) -> bit_stream_reader &
	Reads a double value from the bit stream.
template<character CharT, typename CharTraits , typename Allocator >
auto	read (std::basic_string< CharT, CharTraits, Allocator > &str, size_type max_length) -> bit_stream_reader &
	Reads a string from the bit stream.
template<character CharT>
auto	read (CharT *str, size_type max_length) -> bit_stream_reader &
	Reads a null-terminated string from the bit stream.
auto	peek_string_length () -> ssize_type
	Peeks the string length prefix from the current stream position.

Detailed Description

Helper stream to read bits from your buffer.

Its design is based on the articles by Glenn Fiedler, see:

• https://gafferongames.com/post/reading_and_writing_packets/
• https://gafferongames.com/post/serialization_strategies/

Member Typedef Documentation

scratch_type

using nalchi::bit_stream_reader::scratch_type

Initial value:

 
        bit_stream_writer::scratch_type

Internal scratch type to store the temporary scratch data.

Constructor & Destructor Documentation

bit_stream_reader() [1/4]

nalchi::bit_stream_reader::bit_stream_reader

(

)

Constructs a bit_stream_reader instance without a buffer.

This constructor can be useful if you want to set the buffer afterwards.
To set the buffer, call reset_with().

bit_stream_reader() [2/4]

nalchi::bit_stream_reader::bit_stream_reader	(	std::span< const word_type >	buffer,
		size_type	logical_bytes_length )

Constructs a bit_stream_reader instance with a std::span<word_type> buffer.

Parameters

buffer	Buffer to read bits from.
logical_bytes_length	Number of bytes logically. This is useful if you want to only allow partial read from the final word.

bit_stream_reader() [3/4]

nalchi::bit_stream_reader::bit_stream_reader	(	const word_type *	begin,
		const word_type *	end,
		size_type	logical_bytes_length )

Constructs a bit_stream_reader instance with a word range.

Parameters

begin	Pointer to the beginning of a buffer.
end	Pointer to the end of a buffer.
logical_bytes_length	Number of bytes logically. This is useful if you want to only allow partial read from the final word.

bit_stream_reader() [4/4]

nalchi::bit_stream_reader::bit_stream_reader	(	const word_type *	begin,
		size_type	words_length,
		size_type	logical_bytes_length )

Constructs a bit_stream_reader instance with a word begin pointer and the word length.

Parameters

begin	Pointer to the beginning of a buffer.
words_length	Number of words in the buffer.
logical_bytes_length	Number of bytes logically. This is useful if you want to only allow partial read from the final word.

Member Function Documentation

fail()

bool nalchi::bit_stream_reader::fail ( ) const

inlinenoexcept

Check if reading from your buffer has been failed or not.

If this is true, all the operations for this bit_stream_reader is no-op.

Returns

true if reading has been failed, otherwise false.

operator bool()

nalchi::bit_stream_reader::operator bool ( ) const

inlinenoexcept

Check if there was no error in the reading to your buffer.
This is effectively same as !fail().

If this is false, all the operations for this bit_stream_reader is no-op.

operator!()

bool nalchi::bit_stream_reader::operator! ( ) const

inlinenoexcept

Check if there was an error in the reading to your buffer.
This is effectively same as fail().

If this is true, all the operations for this bit_stream_reader is no-op.

peek_string_length()

auto nalchi::bit_stream_reader::peek_string_length

(

)

-> ssize_type

Peeks the string length prefix from the current stream position.

If it fails to read a string length prefix,
this function will return a negative value and set the fail flag.

Note

Be careful, if current stream position was not on the string length prefix, it might read garbage length!

Returns

Length of CharT stored in it, or a negative value if length prefix is invalid.

read() [1/7]

template<std::integral BInt>
requires (sizeof(BInt) > sizeof(word_type))

auto nalchi::bit_stream_reader::read ( BInt & data, BInt min = std::numeric_limits<BInt>::min(), BInt max = std::numeric_limits<BInt>::max() ) -> bit_stream_reader&

inline

Reads an integral value from the bit stream.

Template Parameters

BInt	Big integer type that exceeds the size of word_type.

Parameters

data	Data to read to.
min	Minimum value allowed for data.
max	Maximum value allowed for data.

Returns

The stream itself.

read() [2/7]

template<character CharT>

auto nalchi::bit_stream_reader::read ( CharT * str, size_type max_length ) -> bit_stream_reader&

inline

Reads a null-terminated string from the bit stream.

If max_length is not enough to store the string,
this function will set the fail flag and read nothing.

Note

max_length does not include null character, so your buffer must allocate additional space for it.

For example, if max_length is 4 for char16_t, you need 10 bytes.
Because you need space for 5 char16_t including null char, and char16_t is 2 bytes per char.

Template Parameters

CharT

Character type of the null-terminated string.

Parameters

str	Null-terminated string to read to.
max_length	Maximum number of CharT that can be read.

Returns

The stream itself.

read() [3/7]

auto nalchi::bit_stream_reader::read

(

double &

data

)

-> bit_stream_reader &

Reads a double value from the bit stream.

Parameters

data	Data to read to.

Returns

The stream itself.

read() [4/7]

auto nalchi::bit_stream_reader::read

(

float &

data

)

-> bit_stream_reader &

Reads a float value from the bit stream.

Parameters

data	Data to read to.

Returns

The stream itself.

read() [5/7]

template<std::integral SInt>
requires (sizeof(SInt) <= sizeof(word_type))

auto nalchi::bit_stream_reader::read ( SInt & data, SInt min = std::numeric_limits<SInt>::min(), SInt max = std::numeric_limits<SInt>::max() ) -> bit_stream_reader&

inline

Reads an integral value from the bit stream.

Template Parameters

SInt	Small integer type that doesn't exceed the size of word_type.

Parameters

data	Data to read to.
min	Minimum value allowed for data.
max	Maximum value allowed for data.

Returns

The stream itself.

read() [6/7]

template<character CharT, typename CharTraits , typename Allocator >

auto nalchi::bit_stream_reader::read ( std::basic_string< CharT, CharTraits, Allocator > & str, size_type max_length ) -> bit_stream_reader&

inline

Reads a string from the bit stream.

If the length prefix for current stream position exceeds max_length,
this function will set the fail flag and read nothing.

Template Parameters

CharT	Underlying character type of std::basic_string.
CharTraits	Char traits for CharT.
Allocator	Underlying allocator for std::basic_string.

Parameters

str	String to read to.
max_length	Maximum number of CharT that can be read. This is to prevent a huge allocation when a malicious message requests it.

Returns

The stream itself.

read() [7/7]

auto nalchi::bit_stream_reader::read	(	void *	data,
		size_type	size ) -> bit_stream_reader &

Reads some arbitrary data from the bit stream.

Note

You could read swapped bytes if the data came from the system with different endianness.
So, prefer using other overloads instead.

Parameters

data	Pointer to the arbitrary data.
size	Size in bytes of the data.

Returns

The stream itself.

reset_with() [1/3]

void nalchi::bit_stream_reader::reset_with	(	const word_type *	begin,
		const word_type *	end,
		size_type	logical_bytes_length )

Resets the stream with a word range.

Parameters

begin	Pointer to the beginning of a buffer.
end	Pointer to the end of a buffer.
logical_bytes_length	Number of bytes logically. This is useful if you want to only allow partial read from the final word.

reset_with() [2/3]

void nalchi::bit_stream_reader::reset_with	(	const word_type *	begin,
		size_type	words_length,
		size_type	logical_bytes_length )

Resets the stream with a word begin pointer and the word length.

Parameters

begin	Pointer to the beginning of a buffer.
words_length	Number of words in the buffer.
logical_bytes_length	Number of bytes logically. This is useful if you want to only allow partial read from the final word.

reset_with() [3/3]

void nalchi::bit_stream_reader::reset_with	(	std::span< const word_type >	buffer,
		size_type	logical_bytes_length )

Resets the stream with a std::span<word_type> buffer.

Parameters

buffer	Buffer to read bits from.
logical_bytes_length	Number of bytes logically. This is useful if you want to only allow partial read from the final word.

total_bits()

auto nalchi::bit_stream_reader::total_bits ( ) const -> size_type

inline

Gets the number of total bits in the stream.

Returns

Number of total bits in the stream.

total_bytes()

auto nalchi::bit_stream_reader::total_bytes ( ) const -> size_type

inline

Gets the number of total bytes in the stream.

Returns

Number of total bytes in the stream.

unused_bits()

auto nalchi::bit_stream_reader::unused_bits ( ) const -> size_type

inline

Gets the number of unused bits in the stream.

Returns

Number of unused bits in the stream.

unused_bytes()

auto nalchi::bit_stream_reader::unused_bytes ( ) const -> size_type

inline

Gets the number of unused bytes in the stream.

Returns

Number of unused bytes in the stream.

used_bits()

auto nalchi::bit_stream_reader::used_bits ( ) const -> size_type

inline

Gets the number of used bits in the stream.

Returns

Number of used bits in the stream.

used_bytes()

auto nalchi::bit_stream_reader::used_bytes

(

)

const -> size_type

Gets the number of used bytes in the stream.

Returns

Number of used bytes in the stream.

---

The documentation for this class was generated from the following file:

• bit_stream.hpp