Trait BitWrite2

pub trait BitWrite2 {
    // Required methods
    fn write<I>(&mut self, bits: u32, value: I) -> Result<()>
       where I: Integer;
    fn write_out<const BITS: u32, I>(&mut self, value: I) -> Result<()>
       where I: Integer;
    fn write_unsigned<U>(&mut self, bits: u32, value: U) -> Result<()>
       where U: UnsignedInteger;
    fn write_signed<S>(&mut self, bits: u32, value: S) -> Result<()>
       where S: SignedInteger;
    fn write_from<V>(&mut self, value: V) -> Result<()>
       where V: Primitive;
    fn write_as_from<F, V>(&mut self, value: V) -> Result<()>
       where F: Endianness,
             V: Primitive;
    fn write_unary0(&mut self, value: u32) -> Result<()>;
    fn write_unary1(&mut self, value: u32) -> Result<()>;
    fn byte_aligned(&self) -> bool;

    // Provided methods
    fn write_bit(&mut self, bit: bool) -> Result<()> { ... }
    fn write_unsigned_out<const BITS: u32, U>(&mut self, value: U) -> Result<()>
       where U: UnsignedInteger { ... }
    fn write_signed_out<const BITS: u32, S>(&mut self, value: S) -> Result<()>
       where S: SignedInteger { ... }
    fn pad(&mut self, bits: u32) -> Result<()> { ... }
    fn write_bytes(&mut self, buf: &[u8]) -> Result<()> { ... }
    fn build<T: ToBitStream>(&mut self, build: &T) -> Result<(), T::Error>
       where Self: BitWrite { ... }
    fn build_with<'a, T: ToBitStreamWith<'a>>(
        &mut self,
        build: &T,
        context: &T::Context,
    ) -> Result<(), T::Error>
       where Self: BitWrite { ... }
    fn byte_align(&mut self) -> Result<()> { ... }
    fn write_huffman<T>(&mut self, value: T::Symbol) -> Result<()>
       where T: ToBits { ... }
}

A compatibility trait for older code implementing BitWrite

This is a trait largely compatible with older code from the 2.X.X version, which one can use with a named import as needed.

New code should prefer the regular BitWrite trait.

Example

use bitstream_io::BitWrite2 as BitWrite;
use bitstream_io::{BitWriter, BigEndian};
let mut byte = vec![];
let mut writer = BitWriter::endian(byte, BigEndian);
writer.write::<u8>(4, 0b1111).unwrap();
writer.write_out::<4, u8>(0b0000).unwrap();
assert_eq!(writer.into_writer(), [0b1111_0000]);

Required Methods

fn write<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.

Errors

Passes along any I/O error from the underlying stream. Returns an error if the input type is too small to hold the given number of bits. Returns an error if the value is too large to fit the given number of bits.

fn write_out<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.

Errors

Passes along any I/O error from the underlying stream. Returns an error if the value is too large to fit the given number of bits. A compile-time error occurs if the given number of bits is larger than the output type.

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

where U: UnsignedInteger,

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

Errors

Passes along any I/O error from the underlying stream. Returns an error if the input type is too small to hold the given number of bits. Returns an error if the value is too large to fit the given number of bits.

fn write_signed<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.

Errors

Passes along any I/O error from the underlying stream. Returns an error if the input type is too small to hold the given number of bits. Returns an error if the number of bits is 0, since one bit is always needed for the sign. Returns an error if the value is too large to fit 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.

Errors

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

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.

Errors

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

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

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

Errors

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

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

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

Errors

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

fn byte_aligned(&self) -> bool

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

Provided Methods

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

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

Errors

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

fn write_unsigned_out<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.

Errors

Passes along any I/O error from the underlying stream. Returns an error if the value is too large to fit the given number of bits. A compile-time error occurs if the given number of bits is larger than the output type.

fn write_signed_out<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.

Errors

Passes along any I/O error from the underlying stream. Returns an error if the value is too large to fit the given number of bits. A compile-time error occurs if the number of bits is 0, since one bit is always needed for the sign. A compile-time error occurs if the given number of bits is larger than the output type.

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

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

Errors

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

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

Writes the entirety of a byte buffer to the stream.

Errors

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

Example

use std::io::Write;
use bitstream_io::{BigEndian, BitWriter, BitWrite};
let mut writer = BitWriter::endian(Vec::new(), BigEndian);
writer.write_var(8, 0x66u8).unwrap();
writer.write_var(8, 0x6Fu8).unwrap();
writer.write_var(8, 0x6Fu8).unwrap();
writer.write_bytes(b"bar").unwrap();
assert_eq!(writer.into_writer(), b"foobar");

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

where Self: BitWrite,

Builds and writes complex type

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

where Self: BitWrite,

Builds and writes complex type with 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.

Errors

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

Example

use std::io::Write;
use bitstream_io::{BigEndian, BitWriter, BitWrite};
let mut writer = BitWriter::endian(Vec::new(), BigEndian);
writer.write_var(1, 0u8).unwrap();
writer.byte_align().unwrap();
writer.write_var(8, 0xFFu8).unwrap();
assert_eq!(writer.into_writer(), [0x00, 0xFF]);

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.

Errors

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

Example

use std::io::Write;
use bitstream_io::{BigEndian, BitWriter, BitWrite2};
use bitstream_io::define_huffman_tree;
define_huffman_tree!(TreeName : char = ['a', ['b', ['c', 'd']]]);
let mut writer = BitWriter::endian(Vec::new(), BigEndian);
writer.write_huffman::<TreeName>('b').unwrap();
writer.write_huffman::<TreeName>('c').unwrap();
writer.write_huffman::<TreeName>('d').unwrap();
assert_eq!(writer.into_writer(), [0b10_110_111]);

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<W: BitWrite> BitWrite2 for W