Struct BitWriter

struct BitWriter<W: io::Write, E: Endianness> { ... }

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: io::Write, E: Endianness> BitWriter<W, E>

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

Wraps a BitWriter around something that implements Write

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

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

fn into_writer(self: Self) -> W

Unwraps internal writer and disposes of BitWriter.

Warning

Any unwritten partial bits are discarded.

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

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

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

Converts BitWriter to ByteWriter in the same endianness.

Warning

Any written partial bits are discarded.

fn bytewriter(self: &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.

fn into_unwritten(self: Self) -> (u32, u8)

Consumes writer and returns any un-written partial byte as a (bits, value) tuple.

Examples

use std::io::Write;
use bitstream_io::{BigEndian, BitWriter, BitWrite};
let mut data = Vec::new();
let (bits, value) = {
    let mut writer = BitWriter::endian(&mut data, BigEndian);
    writer.write(15, 0b1010_0101_0101_101).unwrap();
    writer.into_unwritten()
};
assert_eq!(data, [0b1010_0101]);
assert_eq!(bits, 7);
assert_eq!(value, 0b0101_101);

use std::io::Write;
use bitstream_io::{BigEndian, BitWriter, BitWrite};
let mut data = Vec::new();
let (bits, value) = {
    let mut writer = BitWriter::endian(&mut data, BigEndian);
    writer.write(8, 0b1010_0101).unwrap();
    writer.into_unwritten()
};
assert_eq!(data, [0b1010_0101]);
assert_eq!(bits, 0);
assert_eq!(value, 0);

fn flush(self: &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.

impl<T> Any for BitWriter<W, E>

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for BitWriter<W, E>

fn borrow(self: &Self) -> &T

impl<T> BorrowMut for BitWriter<W, E>

fn borrow_mut(self: &mut Self) -> &mut T

impl<T> From for BitWriter<W, E>

fn from(t: T) -> T

Returns the argument unchanged.

impl<T, U> Into for BitWriter<W, E>

fn into(self: Self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

impl<T, U> TryFrom for BitWriter<W, E>

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

impl<T, U> TryInto for BitWriter<W, E>

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>

impl<W, E> Freeze for BitWriter<W, E>

impl<W, E> RefUnwindSafe for BitWriter<W, E>

impl<W, E> Send for BitWriter<W, E>

impl<W, E> Sync for BitWriter<W, E>

impl<W, E> Unpin for BitWriter<W, E>

impl<W, E> UnsafeUnpin for BitWriter<W, E>

impl<W, E> UnwindSafe for BitWriter<W, E>

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

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

Examples

use std::io::Write;
use bitstream_io::{BigEndian, BitWriter, BitWrite};
let mut writer = BitWriter::endian(Vec::new(), BigEndian);
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!(writer.into_writer(), [0b10110111]);

use std::io::Write;
use bitstream_io::{LittleEndian, BitWriter, BitWrite};
let mut writer = BitWriter::endian(Vec::new(), LittleEndian);
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!(writer.into_writer(), [0b10110111]);

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

Examples

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

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

use std::io::{Write, sink};
use bitstream_io::{BigEndian, BitWriter, BitWrite};
let mut w = BitWriter::endian(sink(), BigEndian);
assert!(w.write(9, 0u8).is_err());    // can't write  u8 in 9 bits
assert!(w.write(17, 0u16).is_err());  // can't write u16 in 17 bits
assert!(w.write(33, 0u32).is_err());  // can't write u32 in 33 bits
assert!(w.write(65, 0u64).is_err());  // can't write u64 in 65 bits
assert!(w.write(1, 2).is_err());      // can't write   2 in 1 bit
assert!(w.write(2, 4).is_err());      // can't write   4 in 2 bits
assert!(w.write(3, 8).is_err());      // can't write   8 in 3 bits
assert!(w.write(4, 16).is_err());     // can't write  16 in 4 bits

fn write_out<BITS: u32, U>(self: &mut Self, value: U) -> Result<()>
where
    U: Numeric

Examples

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

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

use std::io::{Write, sink};
use bitstream_io::{BigEndian, BitWriter, BitWrite};
let mut w = BitWriter::endian(sink(), BigEndian);
assert!(w.write_out::<1, _>(2).is_err());      // can't write   2 in 1 bit
assert!(w.write_out::<2, _>(4).is_err());      // can't write   4 in 2 bits
assert!(w.write_out::<3, _>(8).is_err());      // can't write   8 in 3 bits
assert!(w.write_out::<4, _>(16).is_err());     // can't write  16 in 4 bits

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

Examples

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

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

fn write_signed_out<BITS: u32, S>(self: &mut Self, value: S) -> Result<()>
where
    S: SignedNumeric

Examples

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

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

fn write_from<V>(self: &mut Self, value: V) -> Result<()>
where
    V: Primitive
fn write_as_from<F, V>(self: &mut Self, value: V) -> Result<()>
where
    F: Endianness,
    V: Primitive
fn write_bytes(self: &mut Self, buf: &[u8]) -> Result<()>
fn byte_aligned(self: &Self) -> bool

Example

use std::io::{Write, sink};
use bitstream_io::{BigEndian, BitWriter, BitWrite};
let mut writer = BitWriter::endian(sink(), BigEndian);
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);

impl<W: io::Write, E: Endianness> HuffmanWrite for BitWriter<W, E>

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

Example

use std::io::Write;
use bitstream_io::{BigEndian, BitWriter, HuffmanWrite};
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 writer = BitWriter::endian(Vec::new(), BigEndian);
writer.write_huffman(&tree, 'b').unwrap();
writer.write_huffman(&tree, 'c').unwrap();
writer.write_huffman(&tree, 'd').unwrap();
assert_eq!(writer.into_writer(), [0b10110111]);