Struct bitstream_io::write::BitWriter

pub struct BitWriter<'a, E: Endianness> { /* fields omitted */ }

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.

Methods

impl<'a, E: Endianness> BitWriter<'a, E>

fn new(writer: &mut Write) -> BitWriter<E>

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

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

Examples

use std::io::Write;
use bitstream_io::{BigEndian, BitWriter};
let mut data = Vec::new();
{
    let mut writer = BitWriter::<BigEndian>::new(&mut data);
    writer.write_bit(true).unwrap();
    writer.write_bit(false).unwrap();
    writer.write_bit(true).unwrap();
    writer.write_bit(true).unwrap();
    writer.write_bit(false).unwrap();
    writer.write_bit(true).unwrap();
    writer.write_bit(true).unwrap();
    writer.write_bit(true).unwrap();
}
assert_eq!(data, [0b10110111]);

use std::io::Write;
use bitstream_io::{LittleEndian, BitWriter};
let mut data = Vec::new();
{
    let mut writer = BitWriter::<LittleEndian>::new(&mut data);
    writer.write_bit(true).unwrap();
    writer.write_bit(true).unwrap();
    writer.write_bit(true).unwrap();
    writer.write_bit(false).unwrap();
    writer.write_bit(true).unwrap();
    writer.write_bit(true).unwrap();
    writer.write_bit(false).unwrap();
    writer.write_bit(true).unwrap();
}
assert_eq!(data, [0b10110111]);

fn write<U>(&mut self, bits: u32, value: U) -> Result<(), Error> where U: Numeric

Writes an unsigned value to the stream using the given number of bits. This method assumes that value's type is sufficiently large to hold those bits.

Examples

use std::io::Write;
use bitstream_io::{BigEndian, BitWriter};
let mut data = Vec::new();
{
    let mut writer = BitWriter::<BigEndian>::new(&mut data);
    writer.write(1, 0b1).unwrap();
    writer.write(2, 0b01).unwrap();
    writer.write(5, 0b10111).unwrap();
}
assert_eq!(data, [0b10110111]);

use std::io::Write;
use bitstream_io::{LittleEndian, BitWriter};
let mut data = Vec::new();
{
    let mut writer = BitWriter::<LittleEndian>::new(&mut data);
    writer.write(1, 0b1).unwrap();
    writer.write(2, 0b11).unwrap();
    writer.write(5, 0b10110).unwrap();
}
assert_eq!(data, [0b10110111]);

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

Writes the entirety of a byte buffer to the stream. If the stream is already byte-aligned, it will often map to a faster write_all call. Otherwise it will write bytes individually in 8-bit increments.

Example

use std::io::Write;
use bitstream_io::{BigEndian, BitWriter};
let mut data = Vec::new();
{
    let mut writer = BitWriter::<BigEndian>::new(&mut data);
    writer.write(8, 0x66).unwrap();
    writer.write(8, 0x6F).unwrap();
    writer.write(8, 0x6F).unwrap();
    writer.write_bytes(b"bar").unwrap();
}
assert_eq!(data, b"foobar");

fn write_huffman<T>(&mut self,
                    tree: &WriteHuffmanTree<E, T>,
                    symbol: T)
                    -> Result<(), Error> where T: Ord + Copy

Writes Huffman code for the given symbol to the stream.

Example

use std::io::Write;
use bitstream_io::{BigEndian, BitWriter};
use bitstream_io::huffman::compile_write_tree;
let tree = compile_write_tree(
    vec![('a', vec![0]),
         ('b', vec![1, 0]),
         ('c', vec![1, 1, 0]),
         ('d', vec![1, 1, 1])]).unwrap();
let mut data = Vec::new();
{
    let mut writer = BitWriter::<BigEndian>::new(&mut data);
    writer.write_huffman(&tree, 'b').unwrap();
    writer.write_huffman(&tree, 'c').unwrap();
    writer.write_huffman(&tree, 'd').unwrap();
}
assert_eq!(data, [0b10110111]);

fn write_unary0(&mut self, value: u32) -> Result<(), Error>

Writes value number of 1 bits to the stream and then writes a 0 bit. This field is variably-sized.

Examples

use std::io::Write;
use bitstream_io::{BigEndian, BitWriter};
let mut data = Vec::new();
{
    let mut writer = BitWriter::<BigEndian>::new(&mut data);
    writer.write_unary0(0).unwrap();
    writer.write_unary0(3).unwrap();
    writer.write_unary0(10).unwrap();
}
assert_eq!(data, [0b01110111, 0b11111110]);

use std::io::Write;
use bitstream_io::{LittleEndian, BitWriter};
let mut data = Vec::new();
{
    let mut writer = BitWriter::<LittleEndian>::new(&mut data);
    writer.write_unary0(0).unwrap();
    writer.write_unary0(3).unwrap();
    writer.write_unary0(10).unwrap();
}
assert_eq!(data, [0b11101110, 0b01111111]);

fn write_unary1(&mut self, value: u32) -> Result<(), Error>

Writes value number of 0 bits to the stream and then writes a 1 bit. This field is variably-sized.

Example

use std::io::Write;
use bitstream_io::{BigEndian, BitWriter};
let mut data = Vec::new();
{
    let mut writer = BitWriter::<BigEndian>::new(&mut data);
    writer.write_unary1(0).unwrap();
    writer.write_unary1(3).unwrap();
    writer.write_unary1(10).unwrap();
}
assert_eq!(data, [0b10001000, 0b00000001]);

use std::io::Write;
use bitstream_io::{LittleEndian, BitWriter};
let mut data = Vec::new();
{
    let mut writer = BitWriter::<LittleEndian>::new(&mut data);
    writer.write_unary1(0).unwrap();
    writer.write_unary1(3).unwrap();
    writer.write_unary1(10).unwrap();
}
assert_eq!(data, [0b00010001, 0b10000000]);

fn byte_aligned(&self) -> bool

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

Example

use std::io::Write;
use bitstream_io::{BigEndian, BitWriter};
let mut data = Vec::new();
let mut writer = BitWriter::<BigEndian>::new(&mut data);
assert_eq!(writer.byte_aligned(), true);
writer.write(1, 0).unwrap();
assert_eq!(writer.byte_aligned(), false);
writer.write(7, 0).unwrap();
assert_eq!(writer.byte_aligned(), true);

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

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

Example

use std::io::Write;
use bitstream_io::{BigEndian, BitWriter};
let mut data = Vec::new();
{
    let mut writer = BitWriter::<BigEndian>::new(&mut data);
    writer.write(1, 0).unwrap();
    writer.byte_align().unwrap();
    writer.write(8, 0xFF).unwrap();
}
assert_eq!(data, [0x00, 0xFF]);

impl<'a> BitWriter<'a, BigEndian>

fn write_signed<S>(&mut self, bits: u32, value: S) -> Result<(), Error> where S: SignedNumeric

Writes a twos-complement signed value to the stream with the given number of bits. This method assumes that value's type is sufficiently large to hold those bits.

Example

use std::io::Write;
use bitstream_io::{BigEndian, BitWriter};
let mut data = Vec::new();
{
    let mut writer = BitWriter::<BigEndian>::new(&mut data);
    writer.write_signed(4, -5).unwrap();
    writer.write_signed(4, 7).unwrap();
}
assert_eq!(data, [0b10110111]);

impl<'a> BitWriter<'a, LittleEndian>

fn write_signed<S>(&mut self, bits: u32, value: S) -> Result<(), Error> where S: SignedNumeric

Writes a twos-complement signed value to the stream with the given number of bits. This method assumes that value's type is sufficiently large to hold those bits.

Example

use std::io::Write;
use bitstream_io::{LittleEndian, BitWriter};
let mut data = Vec::new();
{
    let mut writer = BitWriter::<LittleEndian>::new(&mut data);
    writer.write_signed(4, 7).unwrap();
    writer.write_signed(4, -5).unwrap();
}
assert_eq!(data, [0b10110111]);