pixie::BinaryWriter Class Reference

Bounded-buffer writer for canonical little-endian binary data. More...

#include <serialization.h>

Public Member Functions
template<SeekableBinaryOutputSink Sink>
	BinaryWriter (Sink &sink, std::size_t buffer_bytes=kDefaultBufferBytes)
	Construct a writer with an owned, fixed-size staging buffer.
template<SeekableBinaryOutputSink Sink>
	BinaryWriter (Sink &sink, std::span< std::byte > buffer)
	Construct a writer over a caller-owned staging buffer.
	BinaryWriter (const BinaryWriter &)=delete
BinaryWriter &	operator= (const BinaryWriter &)=delete
	BinaryWriter (BinaryWriter &&)=delete
BinaryWriter &	operator= (BinaryWriter &&)=delete
bool	empty () const noexcept
	Return whether no bytes have been written.
std::size_t	size_bytes () const noexcept
	Return the logical number of bytes written.
std::size_t	buffer_size_bytes () const noexcept
	Return the maximum staging-buffer size.
void	write_u8 (std::uint8_t value)
	Write an unsigned eight-bit integer.
void	write_u16 (std::uint16_t value)
	Write an unsigned 16-bit integer in little-endian order.
void	write_u32 (std::uint32_t value)
	Write an unsigned 32-bit integer in little-endian order.
void	write_u64 (std::uint64_t value)
	Write an unsigned 64-bit integer in little-endian order.
void	write_i8 (std::int8_t value)
	Write a signed eight-bit integer.
void	write_i16 (std::int16_t value)
	Write a signed 16-bit integer in little-endian order.
void	write_i32 (std::int32_t value)
	Write a signed 32-bit integer in little-endian order.
void	write_i64 (std::int64_t value)
	Write a signed 64-bit integer in little-endian order.
void	write_size (std::size_t value)
	Write a platform size as an unsigned 64-bit integer.
void	write_bytes (std::span< const std::byte > bytes)
	Append bytes without interpretation.
void	write_zeros (std::size_t count)
	Append count zero bytes.
void	align_to (std::size_t alignment)
	Pad with zero bytes to the next multiple of alignment.
std::size_t	write_u64_placeholder ()
	Write a zero 64-bit field and return its byte position.
void	patch_u64 (std::size_t position, std::uint64_t value)
	Replace an existing 64-bit field with value.
void	flush ()
	Deliver currently buffered bytes while keeping the writer open.
void	finish ()
	Deliver all bytes and complete the sink.

Static Public Attributes
static constexpr std::size_t	kDefaultBufferBytes = 64 * 1024
	Default bounded staging-buffer size.

Detailed Description

Bounded-buffer writer for canonical little-endian binary data.

The writer does not own its sink. Small fields are accumulated in a fixed-size staging buffer; large caller-owned byte spans may be sent directly to the sink. Integer methods encode a fixed number of bytes, independent of the host ABI. Call finish() to report output errors and deliver the final buffered bytes before inspecting or consuming the sink. Destruction does not perform I/O.

Constructor & Destructor Documentation

BinaryWriter() [1/2]

template<SeekableBinaryOutputSink Sink>

pixie::BinaryWriter::BinaryWriter ( Sink & sink, std::size_t buffer_bytes = kDefaultBufferBytes )

inlineexplicit

Construct a writer with an owned, fixed-size staging buffer.

Parameters

sink	Empty sink that remains alive and unmoved until finish().
buffer_bytes	Maximum staging-buffer memory owned by the writer.

Exceptions

std::invalid_argument

if buffer_bytes is zero.

BinaryWriter() [2/2]

template<SeekableBinaryOutputSink Sink>

pixie::BinaryWriter::BinaryWriter ( Sink & sink, std::span< std::byte > buffer )

inline

Construct a writer over a caller-owned staging buffer.

Parameters

sink	Empty sink that remains alive and unmoved until finish().
buffer	Writable staging memory that remains alive and unmoved until finish().

Exceptions

std::invalid_argument

if buffer is empty.

Member Function Documentation

align_to()

void pixie::BinaryWriter::align_to ( std::size_t alignment )

inline

Pad with zero bytes to the next multiple of alignment.

Exceptions

std::invalid_argument

if alignment is zero.

finish()

void pixie::BinaryWriter::finish ( )

inline

Deliver all bytes and complete the sink.

This operation is idempotent after success. A sink failure is propagated and leaves the writer unusable; already-written output is not rolled back.

flush()

void pixie::BinaryWriter::flush ( )

inline

Deliver currently buffered bytes while keeping the writer open.

Exceptions

Any	exception reported by the sink. A failed writer is unusable.

patch_u64()

void pixie::BinaryWriter::patch_u64 ( std::size_t position, std::uint64_t value )

inline

Replace an existing 64-bit field with value.

Exceptions

std::out_of_range

if the field is outside the current output.

write_size()

void pixie::BinaryWriter::write_size ( std::size_t value )

inline

Write a platform size as an unsigned 64-bit integer.

Exceptions

std::length_error

if size_t is wider than the wire type.

write_u64_placeholder()

std::size_t pixie::BinaryWriter::write_u64_placeholder ( )

inline

Write a zero 64-bit field and return its byte position.

Use patch_u64() to fill framed lengths after writing a payload.

---

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

• include/pixie/serialization.h