nalchi::bit_stream_writer Class Reference

Helper stream to write bits to your buffer. More...

#include <nalchi/bit_stream.hpp>

Public Types
using	size_type = std::uint32_t
	Size type representing number of bits and bytes.
using	scratch_type = std::uint64_t
	Internal scratch type to store the temporary scratch data.
using	word_type = std::uint32_t
	Internal word type used to write to your buffer.

Public Member Functions
	bit_stream_writer (const bit_stream_writer &)=delete
	Deleted copy constructor.
auto	operator= (const bit_stream_writer &) -> bit_stream_writer &=delete
	Deleted copy assignment operator.
	bit_stream_writer ()
	Constructs a bit_stream_writer instance without a buffer.
	bit_stream_writer (shared_payload buffer, size_type logical_bytes_length)
	Constructs a bit_stream_writer instance with a shared_payload buffer.
	bit_stream_writer (std::span< word_type > buffer, size_type logical_bytes_length)
	Constructs a bit_stream_writer instance with a std::span<word_type> buffer.
	bit_stream_writer (word_type *begin, word_type *end, size_type logical_bytes_length)
	Constructs a bit_stream_writer instance with a word range.
	bit_stream_writer (word_type *begin, size_type words_length, size_type logical_bytes_length)
	Constructs a bit_stream_writer instance with a word begin pointer and the word length.
void	set_fail ()
	Force set the fail flag.
bool	fail () const noexcept
	Check if writing to your buffer has been failed or not.
bool	operator! () const noexcept
	Check if there was an error in the writing to your buffer. This is effectively same as fail().
	operator bool () const noexcept
	Check if there was no error in the writing 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 write from the beginning again.
void	reset ()
	Resets the stream so that it no longer holds your buffer anymore.
void	reset_with (shared_payload buffer, size_type logical_bytes_length)
	Resets the stream with a shared_payload buffer.
void	reset_with (std::span< word_type > buffer, size_type logical_bytes_length)
	Resets the stream with a std::span<word_type> buffer.
void	reset_with (word_type *begin, word_type *end, size_type logical_bytes_length)
	Resets the stream with a word range.
void	reset_with (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	flush_final () -> bit_stream_writer &
	Flushes the last remaining bytes on the internal scratch buffer to your buffer.
bool	flushed () const
	Checks if flush_final() has been called or not.
auto	write (const void *data, size_type size) -> bit_stream_writer &
	Writes some arbitrary data to the bit stream.
template<std::integral SInt> requires (sizeof(SInt) <= sizeof(word_type))
auto	write (SInt data, SInt min=std::numeric_limits< SInt >::min(), SInt max=std::numeric_limits< SInt >::max()) -> bit_stream_writer &
	Writes an integral value to the bit stream.
template<std::integral BInt> requires (sizeof(BInt) > sizeof(word_type))
auto	write (BInt data, BInt min=std::numeric_limits< BInt >::min(), BInt max=std::numeric_limits< BInt >::max()) -> bit_stream_writer &
	Writes an integral value to the bit stream.
auto	write (float data) -> bit_stream_writer &
	Writes a float value to the bit stream.
auto	write (double data) -> bit_stream_writer &
	Writes a double value to the bit stream.
template<character CharT, typename CharTraits >
auto	write (std::basic_string_view< CharT, CharTraits > str) -> bit_stream_writer &
	Writes a string view to the bit stream.
template<character CharT, typename CharTraits , typename Allocator >
auto	write (const std::basic_string< CharT, CharTraits, Allocator > &str) -> bit_stream_writer &
	Writes a string to the bit stream.
template<character CharT>
auto	write (const CharT *str) -> bit_stream_writer &
	Writes a null-terminated string to the bit stream.

Static Public Attributes
static constexpr size_type	STR_LEN_PREFIX_PREFIX_BITS = 2u
static constexpr size_type	MIN_STR_LEN_PREFIX_PREFIX = 0u
static constexpr size_type	MAX_STR_LEN_PREFIX_PREFIX = 3u

Detailed Description

Helper stream to write bits to 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/

Note

bit_stream_writer uses an internal scratch buffer, so the final few bytes might not be flushed to your buffer yet when you're done writing.
So, after writing everything, you must call flush_final() to flush the remaining bytes to your buffer.
(Destroying the bit_stream_writer instance won't flush them, either.)

Constructor & Destructor Documentation

bit_stream_writer() [1/5]

nalchi::bit_stream_writer::bit_stream_writer

(

)

Constructs a bit_stream_writer 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_writer() [2/5]

nalchi::bit_stream_writer::bit_stream_writer	(	shared_payload	buffer,
		size_type	logical_bytes_length )

Constructs a bit_stream_writer instance with a shared_payload buffer.

Parameters

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

bit_stream_writer() [3/5]

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

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

Parameters

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

bit_stream_writer() [4/5]

nalchi::bit_stream_writer::bit_stream_writer	(	word_type *	begin,
		word_type *	end,
		size_type	logical_bytes_length )

Constructs a bit_stream_writer 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 write to the final word.

bit_stream_writer() [5/5]

nalchi::bit_stream_writer::bit_stream_writer	(	word_type *	begin,
		size_type	words_length,
		size_type	logical_bytes_length )

Constructs a bit_stream_writer 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 write to the final word.

Member Function Documentation

fail()

bool nalchi::bit_stream_writer::fail ( ) const

inlinenoexcept

Check if writing to your buffer has been failed or not.

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

Returns

true if writing has been failed, otherwise false.

flush_final()

auto nalchi::bit_stream_writer::flush_final

(

)

-> bit_stream_writer &

Flushes the last remaining bytes on the internal scratch buffer to your buffer.

Note

This function must be only called when you're done writing.
Any attempt to write more data after calling this function will set the fail flag and write nothing.

Returns

The stream itself.

flushed()

bool nalchi::bit_stream_writer::flushed ( ) const

inline

Checks if flush_final() has been called or not.

Returns

Whether the flush_final() has been called or not.

operator bool()

nalchi::bit_stream_writer::operator bool ( ) const

inlinenoexcept

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

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

operator!()

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

inlinenoexcept

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

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

reset()

void nalchi::bit_stream_writer::reset

(

)

Resets the stream so that it no longer holds your buffer anymore.

Note

This function removes reference to your buffer without flushing,
so if you need flushing, you should call flush_final() beforehand.

reset_with() [1/4]

void nalchi::bit_stream_writer::reset_with	(	shared_payload	buffer,
		size_type	logical_bytes_length )

Resets the stream with a shared_payload buffer.

Note

This function resets to the new buffer without flushing to your previous buffer,
so if you need flushing, you should call flush_final() beforehand.

Parameters

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

reset_with() [2/4]

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

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

Note

This function resets to the new buffer without flushing to your previous buffer,
so if you need flushing, you should call flush_final() beforehand.

Parameters

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

reset_with() [3/4]

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

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

Note

This function resets to the new buffer without flushing to your previous buffer,
so if you need flushing, you should call flush_final() beforehand.

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 write to the final word.

reset_with() [4/4]

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

Resets the stream with a word range.

Note

This function resets to the new buffer without flushing to your previous buffer,
so if you need flushing, you should call flush_final() beforehand.

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 write to the final word.

restart()

void nalchi::bit_stream_writer::restart

(

)

Restarts the stream so that it can write from the beginning again.

Note

This function resets internal states without flushing, so if you need flushing, you should call flush_final() beforehand.

total_bits()

auto nalchi::bit_stream_writer::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_writer::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_writer::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_writer::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_writer::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_writer::used_bytes

(

)

const -> size_type

Gets the number of used bytes in the stream.

Returns

Number of used bytes in the stream.

write() [1/8]

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

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

inline

Writes an integral value to the bit stream.

Template Parameters

BInt	Big integer type that exceeds the size of word_type.

Parameters

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

Returns

The stream itself.

write() [2/8]

template<character CharT>

auto nalchi::bit_stream_writer::write ( const CharT * str ) -> bit_stream_writer&

inline

Writes a null-terminated string to the bit stream.

Template Parameters

CharT

Character type of the null-terminated string.

Parameters

str	String to write.

Returns

The stream itself.

write() [3/8]

template<character CharT, typename CharTraits , typename Allocator >

auto nalchi::bit_stream_writer::write ( const std::basic_string< CharT, CharTraits, Allocator > & str ) -> bit_stream_writer&

inline

Writes a string to the bit stream.

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

Returns

The stream itself.

write() [4/8]

auto nalchi::bit_stream_writer::write	(	const void *	data,
		size_type	size ) -> bit_stream_writer &

Writes some arbitrary data to the bit stream.

Note

Bytes in your data could be read swapped if it is sent to 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.

write() [5/8]

auto nalchi::bit_stream_writer::write

(

double

data

)

-> bit_stream_writer &

Writes a double value to the bit stream.

Parameters

data	Data to write.

Returns

The stream itself.

write() [6/8]

auto nalchi::bit_stream_writer::write

(

float

data

)

-> bit_stream_writer &

Writes a float value to the bit stream.

Parameters

data	Data to write.

Returns

The stream itself.

write() [7/8]

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

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

inline

Writes an integral value to the bit stream.

Template Parameters

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

Parameters

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

Returns

The stream itself.

write() [8/8]

template<character CharT, typename CharTraits >

auto nalchi::bit_stream_writer::write ( std::basic_string_view< CharT, CharTraits > str ) -> bit_stream_writer&

inline

Writes a string view to the bit stream.

Template Parameters

CharT	Underlying character type of std::basic_string_view.
CharTraits	Char traits for CharT.

Parameters

str	String to write.

Returns

The stream itself.

---

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

• bit_stream.hpp