Struct BitRecorder

pub struct BitRecorder<N, E: Endianness> { /* private fields */ }

For recording writes in order to play them back on another writer

Example

use std::io::Write;
use bitstream_io::{BigEndian, BitWriter, BitWrite, BitRecorder};
let mut recorder: BitRecorder<u32, BigEndian> = BitRecorder::new();
recorder.write_var(1, 0b1u8).unwrap();
recorder.write_var(2, 0b01u8).unwrap();
recorder.write_var(5, 0b10111u8).unwrap();
assert_eq!(recorder.written(), 8);
let mut writer = BitWriter::endian(Vec::new(), BigEndian);
recorder.playback(&mut writer);
assert_eq!(writer.into_writer(), [0b10110111]);

Implementations

impl<N: Counter, E: Endianness> BitRecorder<N, E>

pub fn new() -> Self

Creates new recorder

pub fn with_capacity(bytes: usize) -> Self

Creates new recorder sized for the given number of bytes

pub fn endian(endian: E) -> Self

Creates new recorder with the given endianness

pub fn written(&self) -> N

Returns number of bits written

Panics

Panics if the number of bits written is larger than the maximum supported by the counter type. Use BitRecorder::written_checked for a non-panicking alternative.

pub fn written_checked(&self) -> Result<N, Overflowed>

Returns number of bits written

Errors

Returns an error if the number of bits written overflows our counter type.

pub fn playback<W: BitWrite>(&self, writer: &mut W) -> Result<()>

Plays recorded writes to the given writer

pub fn clear(&mut self)

Clears recorder, removing all values

impl<N: PartialOrd + Counter + Copy, E: Endianness> BitRecorder<N, E>

pub fn best<F>( self, candidate: &mut Self, f: impl FnOnce(&mut Self) -> Result<(), F>, ) -> Result<Self, F>

Returns shortest option between ourself and candidate

Executes fallible closure on emptied candidate recorder, compares the lengths of ourself and the candidate, and returns the shorter of the two.

If the new candidate is shorter, we swap ourself and the candidate so any recorder capacity can be reused.

Example

use bitstream_io::{BitRecorder, BitWrite, BigEndian};

let mut best = BitRecorder::<u8, BigEndian>::new();
let mut candidate = BitRecorder::new();

// write an 8 bit value to our initial candidate
best.write::<8, u8>(0);
assert_eq!(best.written(), 8);

// try another candidate which writes 4 bits
best = best.best(&mut candidate, |w| {
    w.write::<4, u8>(0)
}).unwrap();

// which becomes our new best candidate
assert_eq!(best.written(), 4);

// finally, try a not-so-best candidate
// which writes 10 bits
best = best.best(&mut candidate, |w| {
    w.write::<10, u16>(0)
}).unwrap();

// so our best candidate remains 4 bits
assert_eq!(best.written(), 4);

Trait Implementations

impl<N, E> BitWrite for BitRecorder<N, E>

where E: Endianness, N: Counter,

fn write_bit(&mut self, bit: bool) -> Result<()>

Writes a single bit to the stream. true indicates 1, false indicates 0

fn write<const BITS: u32, I>(&mut self, value: I) -> Result<()>

where I: Integer,

Writes a signed or unsigned value to the stream using the given const number of bits.

fn write_const<const BITS: u32, const VALUE: u32>(&mut self) -> Result<()>

Writes the given constant value to the stream with the given number of bits.

fn write_var<I>(&mut self, bits: u32, value: I) -> Result<()>

where I: Integer,

Writes a signed or unsigned value to the stream using the given number of bits.

fn write_unsigned<const BITS: u32, U>(&mut self, value: U) -> Result<()>

where U: UnsignedInteger,

Writes an unsigned value to the stream using the given const number of bits.

fn write_unsigned_var<U>(&mut self, bits: u32, value: U) -> Result<()>

where U: UnsignedInteger,

Writes an unsigned value to the stream using the given number of bits.

fn write_signed<const BITS: u32, S>(&mut self, value: S) -> Result<()>

where S: SignedInteger,

Writes a twos-complement signed value to the stream with the given const number of bits.

fn write_signed_var<S>(&mut self, bits: u32, value: S) -> Result<()>

where S: SignedInteger,

Writes a twos-complement signed value to the stream with the given number of bits.

fn write_count<const MAX: u32>(&mut self, count: BitCount<MAX>) -> Result<()>

Writes the given bit count to the stream with the necessary maximum number of bits.

fn write_counted<const MAX: u32, I>( &mut self, bits: BitCount<MAX>, value: I, ) -> Result<()>

where I: Integer + Sized,

Writes a signed or unsigned value to the stream with the given number of bits.

fn write_unsigned_counted<const BITS: u32, U>( &mut self, bits: BitCount<BITS>, value: U, ) -> Result<()>

where U: UnsignedInteger,

Writes a signed value to the stream with the given number of bits.

fn write_signed_counted<const MAX: u32, S>( &mut self, bits: impl TryInto<SignedBitCount<MAX>>, value: S, ) -> Result<()>

where S: SignedInteger,

Writes an unsigned value to the stream with the given number of bits.

fn write_from<V>(&mut self, value: V) -> Result<()>

where V: Primitive,

Writes whole value to the stream whose size in bits is equal to its type’s size.

fn write_as_from<F, V>(&mut self, value: V) -> Result<()>

where F: Endianness, V: Primitive,

Writes whole value to the stream whose size in bits is equal to its type’s size in an endianness that may be different from the stream’s endianness.

fn pad(&mut self, bits: u32) -> Result<()>

Pads the stream by writing 0 over the given number of bits.

fn write_bytes(&mut self, buf: &[u8]) -> Result<()>

Writes the entirety of a byte buffer to the stream.

fn write_unary<const STOP_BIT: u8>(&mut self, value: u32) -> Result<()>

Writes value number of non STOP_BIT bits to the stream and then writes a STOP_BIT. This field is variably-sized. STOP_BIT must be 0 or 1.

fn build<T: ToBitStream>(&mut self, build: &T) -> Result<(), T::Error>

Builds and writes complex type

fn build_with<'a, T: ToBitStreamWith<'a>>( &mut self, build: &T, context: &T::Context, ) -> Result<(), T::Error>

Builds and writes complex type with context

fn byte_aligned(&self) -> bool

Returns true if the stream is aligned at a whole byte.

fn byte_align(&mut self) -> Result<()>

Pads the stream with 0 bits until it is aligned at a whole byte. Does nothing if the stream is already aligned.

fn write_huffman<T>(&mut self, value: T::Symbol) -> Result<()>

where T: ToBits,

Given a symbol, writes its representation to the output stream as bits. Generates no output if the symbol isn’t defined in the Huffman tree.

fn by_ref(&mut self) -> &mut Self

Creates a “by reference” adaptor for this BitWrite

impl<N: Counter, E: Endianness> Default for BitRecorder<N, E>

fn default() -> Self

Returns the “default value” for a type.