Struct BitWriter 

pub struct BitWriter<W: Write, E: Endianness> { /* private fields */ }

For writing bit values to an underlying stream in a given endianness.

Because this only writes whole bytes to the underlying stream, it is important that output is byte-aligned before the bitstream writer’s lifetime ends. Partial bytes will be lost if the writer is disposed of before they can be written.

Implementations

impl<W: Write, E: Endianness> BitWriter<W, E>

pub fn new(writer: W) -> BitWriter<W, E>

Wraps a BitWriter around something that implements Write

pub fn endian(writer: W, _endian: E) -> BitWriter<W, E>

Wraps a BitWriter around something that implements Write with the given endianness.

Examples found in repository

examples/flac-metadata-write.rs (line 90)

fn main() {
    let mut flac: Vec<u8> = Vec::new();

    let mut writer = BitWriter::endian(&mut flac, BigEndian);

    // stream marker
    writer.write_bytes(b"fLaC").unwrap();

    // metadata block header
    writer
        .build(&BlockHeader {
            last_block: false,
            block_type: 0,
            block_size: 34,
        })
        .unwrap();

    // STREAMINFO block
    writer
        .build(&Streaminfo {
            minimum_block_size: 4096,
            maximum_block_size: 4096,
            minimum_frame_size: 1542,
            maximum_frame_size: 8546,
            sample_rate: 44100,
            channels: NonZero::new(2).unwrap(),
            bits_per_sample: NonZero::new(16).unwrap(),
            total_samples: 304844,
            md5: *b"\xFA\xF2\x69\x2F\xFD\xEC\x2D\x5B\x30\x01\x76\xB4\x62\x88\x7D\x92",
        })
        .unwrap();

    let comment = VorbisComment {
        vendor: "reference libFLAC 1.1.4 20070213".to_string(),
        comment: vec![
            "title=2ch 44100  16bit".to_string(),
            "album=Test Album".to_string(),
            "artist=Assorted".to_string(),
            "tracknumber=1".to_string(),
        ],
    };

    // metadata block header
    writer
        .build(&BlockHeader {
            last_block: false,
            block_type: 4,
            block_size: comment.len().try_into().unwrap(),
        })
        .unwrap();

    // VORBIS_COMMENT block (little endian)
    comment
        .write(&mut ByteWriter::new(writer.writer().unwrap()))
        .unwrap();

    assert_eq!(flac, include_bytes!("data/metadata-only.flac"));
}

pub fn into_writer(self) -> W

Unwraps internal writer and disposes of BitWriter.

Warning

Any unwritten partial bits are discarded.

pub fn writer(&mut self) -> Option<&mut W>

If stream is byte-aligned, provides mutable reference to internal writer. Otherwise returns None

Examples found in repository

examples/flac-metadata-write.rs (line 140)

fn main() {
    let mut flac: Vec<u8> = Vec::new();

    let mut writer = BitWriter::endian(&mut flac, BigEndian);

    // stream marker
    writer.write_bytes(b"fLaC").unwrap();

    // metadata block header
    writer
        .build(&BlockHeader {
            last_block: false,
            block_type: 0,
            block_size: 34,
        })
        .unwrap();

    // STREAMINFO block
    writer
        .build(&Streaminfo {
            minimum_block_size: 4096,
            maximum_block_size: 4096,
            minimum_frame_size: 1542,
            maximum_frame_size: 8546,
            sample_rate: 44100,
            channels: NonZero::new(2).unwrap(),
            bits_per_sample: NonZero::new(16).unwrap(),
            total_samples: 304844,
            md5: *b"\xFA\xF2\x69\x2F\xFD\xEC\x2D\x5B\x30\x01\x76\xB4\x62\x88\x7D\x92",
        })
        .unwrap();

    let comment = VorbisComment {
        vendor: "reference libFLAC 1.1.4 20070213".to_string(),
        comment: vec![
            "title=2ch 44100  16bit".to_string(),
            "album=Test Album".to_string(),
            "artist=Assorted".to_string(),
            "tracknumber=1".to_string(),
        ],
    };

    // metadata block header
    writer
        .build(&BlockHeader {
            last_block: false,
            block_type: 4,
            block_size: comment.len().try_into().unwrap(),
        })
        .unwrap();

    // VORBIS_COMMENT block (little endian)
    comment
        .write(&mut ByteWriter::new(writer.writer().unwrap()))
        .unwrap();

    assert_eq!(flac, include_bytes!("data/metadata-only.flac"));
}

pub fn aligned_writer(&mut self) -> Result<&mut W>

Returns byte-aligned mutable reference to internal writer.

Bytes aligns stream if it is not already aligned.

Errors

Passes along any I/O error from the underlying stream.

pub fn into_bytewriter(self) -> ByteWriter<W, E>

Converts BitWriter to ByteWriter in the same endianness.

Warning

Any written partial bits are discarded.

pub fn bytewriter(&mut self) -> Option<ByteWriter<&mut W, E>>

If stream is byte-aligned, provides temporary ByteWriter in the same endianness. Otherwise returns None

Warning

Any unwritten bits left over when ByteWriter is dropped are lost.

pub fn flush(&mut self) -> Result<()>

Flushes output stream to disk, if necessary. Any partial bytes are not flushed.

Errors

Passes along any errors from the underlying stream.

Trait Implementations

impl<W: Write, E: Endianness> BitWrite for BitWriter<W, E>

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

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

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_counted<const BITS: u32, U>( &mut self, count: 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 BITS: u32, S>( &mut self, bits: impl TryInto<SignedBitCount<BITS>>, value: S, ) -> Result<()>

where S: SignedInteger,

Writes an unsigned value to the stream with 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_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 write_checked<C: Checkable>(&mut self, value: C) -> Result<()>

Writes checked value that is known to fit a given number of bits

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

Writes the entirety of a byte buffer to the stream.

fn byte_aligned(&self) -> bool

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

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_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_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_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, _: 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_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 pad(&mut self, bits: u32) -> Result<()>

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

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 build_using<T: ToBitStreamUsing>( &mut self, build: &T, context: T::Context, ) -> Result<(), T::Error>

Builds and writes complex type with owned context

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 write_unsigned_vbr<const FIELD_SIZE: u32, U: UnsignedInteger>( &mut self, value: U, ) -> Result<()>

Writes a number using a variable using a variable width integer. This optimises the case when the number is small.

fn write_signed_vbr<const FIELD_SIZE: u32, I: SignedInteger>( &mut self, value: I, ) -> Result<()>

Writes a number using a variable using a variable width integer. This optimises the case when the number is small.

fn write_vbr<const FIELD_SIZE: u32, I: VBRInteger>( &mut self, value: I, ) -> Result<()>

Writes a signed or unsigned variable width integer to the stream

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

Creates a “by reference” adaptor for this BitWrite