Bit writer state, its arguments, and the bitio dispatch table. More...

#include "mmgr.h"

Data Structures
struct	mmgr_bitor
	Bit writer state: the buffer, how much is written, and the partial byte. More...
struct	BitorumCfg
	Arguments for the bitor calls, where each call reads only the members it needs. More...
struct	BitorumIntroitusExitusNs
	Type of the bitio dispatch table. More...

Functions
mmgr_bitor	mmgr_bitor_init (const BitorumCfg *args)
	Builds a bit writer over args->out with capacity args->cap.
void	mmgr_bitor_put (const BitorumCfg *args)
	Appends the low args->bit_count bits of args->val to args->writer.
void	mmgr_bitor_align (const BitorumCfg *args)
	Writes the partial byte the writer still holds, padded with zeros above its bits.

Variables
static const BitorumIntroitusExitusNs	bitio
	Dispatch table instance named bitio, with each member set to its mmgr_bitor_ function.

Detailed Description

Bit writer state, its arguments, and the bitio dispatch table.

Author: dstroy0 (Douglas Quigg) dquig.nosp@m.g123.nosp@m.@gmai.nosp@m.l.co.nosp@m.m

Note: Packs bit fields of any width into a byte buffer without a bit ever crossing a call. The writer holds the partial byte. A caller states widths and values and never does its own shifting or masking.; The writer is a value the caller owns and not state this module keeps. Two streams are two writers, and neither module state nor a lock is involved.

Warning: put writes whole bytes only, and so bits that do not fill one stay in the writer's residue and align puts that last partial byte out. A stream whose length is not a multiple of eight and that never calls align ends one byte short, with no flag raised and nothing to notice at the call.

Function Documentation

mmgr_bitor mmgr_bitor_init ( const BitorumCfg * args )

Builds a bit writer over args->out with capacity args->cap.

Parameters

[in] args Buffer and capacity [BORROWS].

Warning: args->out must not be null and args->cap must not be zero. Neither is checked outside a MMGR_DEBUG_CHECKS build, and a null out is not noticed here: mmgr_bitor_put writes through it on the first whole byte.

void mmgr_bitor_put ( const BitorumCfg * args )

Appends the low args->bit_count bits of args->val to args->writer.

Parameters

[in,out] args Writer, value and bit count [BORROWS].

Note: Writes whole bytes only. Leftover bits stay in the writer's residue.; Does nothing when the writer's overflow is already set. A caller may write a whole stream and test overflow once at the end and not after every call.; Sets the writer's overflow and clears its residue when the bytes would pass its cap.

Warning: args->bit_count must not exceed 64, and nothing holds it there outside a MMGR_DEBUG_CHECKS build. A larger count writes zeros past the sixty-fourth bit and advances the writer as though they were data.

void mmgr_bitor_align ( const BitorumCfg * args )

Writes the partial byte the writer still holds, padded with zeros above its bits.

Parameters

[in,out] args Writer to finish [BORROWS].

Note: mmgr_bitor_put writes whole bytes only. Without this call the residue is never written.; Does nothing when the residue is empty. A second call writes nothing.; Does nothing when the writer's overflow is already set.; Only args->writer is read.