Trait BitRead

pub trait BitRead<E: Endianness>: Sized {
    // Required method
    fn read(stream: &mut BitStream<E>) -> Result<Self>;

    // Provided methods
    fn skip(stream: &mut BitStream<E>) -> Result<()> { ... }
    fn bit_size() -> Option<usize> { ... }
}

Trait for types that can be read from a stream without requiring the size to be configured

The BitRead trait can be used with #[derive] on structs and enums

Structs

The implementation can be derived for a struct as long as every field in the struct implements BitRead or BitReadSized

The struct is read field by field in the order they are defined in, if the size for a field is set stream.read_sized() will be used, otherwise stream_read() will be used.

The size for a field can be set using 3 different methods

• set the size as an integer using the size attribute,
• use a previously defined field as the size using the size attribute
• read a set number of bits as an integer, using the resulting value as size using the size_bits attribute

Examples

#[derive(BitRead)]
struct TestStruct {
    foo: u8,
    str: String,
    #[size = 2] // when `size` is set, the attributed will be read using `read_sized`
    truncated: String,
    bar: u16,
    float: f32,
    #[size = 3]
    asd: u8,
    #[size_bits = 2] // first read 2 bits as unsigned integer, then use the resulting value as size for the read
    dynamic_length: u8,
    #[size = "asd"] // use a previously defined field as size
    previous_field: u8,
}

Enums

The implementation can be derived for an enum as long as every variant of the enum either has no field, or an unnamed field that implements BitRead or BitReadSized

The enum is read by first reading a set number of bits as the discriminant of the enum, then the variant for the read discriminant is read.

For details about setting the input size for fields implementing BitReadSized see the block about size in the Structs section above.

The discriminant for the variants defaults to incrementing by one for every field, starting with 0. You can overwrite the discriminant for a field, which will also change the discriminant for every following field.

Examples

#[derive(BitRead)]
#[discriminant_bits = 2]
enum TestBareEnum {
    Foo,
    Bar,
    Asd = 3, // manually set the discriminant value for a field
}

#[derive(BitRead)]
#[discriminant_bits = 2]
enum TestUnnamedFieldEnum {
    #[size = 5]
    Foo(i8),
    Bar(bool),
    #[discriminant = 3] // since rust only allows setting the discriminant on field-less enums, you can use an attribute instead
    Asd(u8),
}

Required Methods

fn read(stream: &mut BitStream<E>) -> Result<Self>

Read the type from stream

Provided Methods

fn skip(stream: &mut BitStream<E>) -> Result<()>

Skip the type

This might be faster than reading it if the size is known beforehand

fn bit_size() -> Option<usize>

The number of bits that will be read or None if the number of bits will change depending on the bit stream

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.

Implementations on Foreign Types

impl BitRead<BigEndian> for Option<NonZeroU8>

fn read(stream: &mut BitStream<BigEndian>) -> Result<Self>

fn bit_size() -> Option<usize>

impl BitRead<BigEndian> for Option<NonZeroU16>

fn read(stream: &mut BitStream<BigEndian>) -> Result<Self>

fn bit_size() -> Option<usize>

impl BitRead<BigEndian> for Option<NonZeroU32>

fn read(stream: &mut BitStream<BigEndian>) -> Result<Self>

fn bit_size() -> Option<usize>

impl BitRead<BigEndian> for Option<NonZeroU64>

fn read(stream: &mut BitStream<BigEndian>) -> Result<Self>

fn bit_size() -> Option<usize>

impl BitRead<BigEndian> for Option<NonZeroU128>

fn read(stream: &mut BitStream<BigEndian>) -> Result<Self>

fn bit_size() -> Option<usize>

impl BitRead<LittleEndian> for Option<NonZeroU8>

fn read(stream: &mut BitStream<LittleEndian>) -> Result<Self>

fn bit_size() -> Option<usize>

impl BitRead<LittleEndian> for Option<NonZeroU16>

fn read(stream: &mut BitStream<LittleEndian>) -> Result<Self>

fn bit_size() -> Option<usize>

impl BitRead<LittleEndian> for Option<NonZeroU32>

fn read(stream: &mut BitStream<LittleEndian>) -> Result<Self>

fn bit_size() -> Option<usize>

impl BitRead<LittleEndian> for Option<NonZeroU64>

fn read(stream: &mut BitStream<LittleEndian>) -> Result<Self>

fn bit_size() -> Option<usize>

impl BitRead<LittleEndian> for Option<NonZeroU128>

fn read(stream: &mut BitStream<LittleEndian>) -> Result<Self>

fn bit_size() -> Option<usize>

impl<E: Endianness> BitRead<E> for bool

fn read(stream: &mut BitStream<E>) -> Result<bool>

fn bit_size() -> Option<usize>

impl<E: Endianness> BitRead<E> for f32

fn read(stream: &mut BitStream<E>) -> Result<f32>

fn bit_size() -> Option<usize>

impl<E: Endianness> BitRead<E> for f64

fn read(stream: &mut BitStream<E>) -> Result<f64>

fn bit_size() -> Option<usize>

impl<E: Endianness> BitRead<E> for i8

fn read(stream: &mut BitStream<E>) -> Result<i8>

fn bit_size() -> Option<usize>

impl<E: Endianness> BitRead<E> for i16

fn read(stream: &mut BitStream<E>) -> Result<i16>

fn bit_size() -> Option<usize>

impl<E: Endianness> BitRead<E> for i32

fn read(stream: &mut BitStream<E>) -> Result<i32>

fn bit_size() -> Option<usize>

impl<E: Endianness> BitRead<E> for i64

fn read(stream: &mut BitStream<E>) -> Result<i64>

fn bit_size() -> Option<usize>

impl<E: Endianness> BitRead<E> for i128

fn read(stream: &mut BitStream<E>) -> Result<i128>

fn bit_size() -> Option<usize>

impl<E: Endianness> BitRead<E> for u8

fn read(stream: &mut BitStream<E>) -> Result<u8>

fn bit_size() -> Option<usize>

impl<E: Endianness> BitRead<E> for u16

fn read(stream: &mut BitStream<E>) -> Result<u16>

fn bit_size() -> Option<usize>

impl<E: Endianness> BitRead<E> for u32

fn read(stream: &mut BitStream<E>) -> Result<u32>

fn bit_size() -> Option<usize>

impl<E: Endianness> BitRead<E> for u64

fn read(stream: &mut BitStream<E>) -> Result<u64>

fn bit_size() -> Option<usize>

impl<E: Endianness> BitRead<E> for u128

fn read(stream: &mut BitStream<E>) -> Result<u128>

fn bit_size() -> Option<usize>

impl<E: Endianness> BitRead<E> for String

fn read(stream: &mut BitStream<E>) -> Result<String>

impl<E: Endianness, T1: BitRead<E>, T2: BitRead<E>> BitRead<E> for (T1, T2)

fn read(stream: &mut BitStream<E>) -> Result<Self>

fn bit_size() -> Option<usize>

impl<E: Endianness, T1: BitRead<E>, T2: BitRead<E>, T3: BitRead<E>> BitRead<E> for (T1, T2, T3)

fn read(stream: &mut BitStream<E>) -> Result<Self>

fn bit_size() -> Option<usize>

impl<E: Endianness, T1: BitRead<E>, T2: BitRead<E>, T3: BitRead<E>, T4: BitRead<E>> BitRead<E> for (T1, T2, T3, T4)

fn read(stream: &mut BitStream<E>) -> Result<Self>

fn bit_size() -> Option<usize>

impl<E: Endianness, T: BitRead<E>> BitRead<E> for Option<T>

Read a boolean, if true, read T, else return None

fn read(stream: &mut BitStream<E>) -> Result<Self>

impl<E: Endianness, T: BitRead<E>> BitRead<E> for Box<T>

fn read(stream: &mut BitStream<E>) -> Result<Self>

fn bit_size() -> Option<usize>

impl<E: Endianness, T: BitRead<E>> BitRead<E> for Rc<T>

fn read(stream: &mut BitStream<E>) -> Result<Self>

fn bit_size() -> Option<usize>

impl<E: Endianness, T: BitRead<E>> BitRead<E> for Arc<T>

fn read(stream: &mut BitStream<E>) -> Result<Self>

fn bit_size() -> Option<usize>

Implementors

impl<T: BitRead<E>, E: Endianness> BitRead<E> for LazyBitRead<T, E>