Struct bitter::BitGet

pub struct BitGet<'a> { /* fields omitted */ }

Reads little-endian bits platform agonistically from a slice of byte data.

Implementations

impl<'a> BitGet<'a>

pub fn new(data: &'a [u8]) -> BitGet<'a>

pub fn read_u8(&mut self) -> Option<u8>

pub fn read_i8(&mut self) -> Option<i8>

pub fn read_u16(&mut self) -> Option<u16>

pub fn read_i16(&mut self) -> Option<i16>

pub fn read_u32(&mut self) -> Option<u32>

pub fn read_i32(&mut self) -> Option<i32>

pub fn read_u8_unchecked(&mut self) -> u8

pub fn read_i8_unchecked(&mut self) -> i8

pub fn read_u16_unchecked(&mut self) -> u16

pub fn read_i16_unchecked(&mut self) -> i16

pub fn read_u32_unchecked(&mut self) -> u32

pub fn read_i32_unchecked(&mut self) -> i32

pub fn read_u64_unchecked(&mut self) -> u64

pub fn read_u64(&mut self) -> Option<u64>

pub fn read_i64(&mut self) -> Option<i64>

pub fn read_i64_unchecked(&mut self) -> i64

pub fn read_u32_bits_unchecked(&mut self, bits: i32) -> u32

pub fn read_u32_bits(&mut self, bits: i32) -> Option<u32>

pub fn read_i32_bits_unchecked(&mut self, bits: i32) -> i32

pub fn read_i32_bits(&mut self, bits: i32) -> Option<i32>

pub fn approx_bytes_remaining(&self) -> usize

Return approximately how many bytes are left in the bitstream. This can overestimate by one when the bit position is non-zero. Thus it is recommended to always compare with a greater than sign to avoid undefined behavior with unchecked reads

let mut bitter = BitGet::new(&[0xff]);
assert_eq!(bitter.approx_bytes_remaining(), 1);
assert!(bitter.read_bit().is_some());
assert_eq!(bitter.approx_bytes_remaining(), 1);
assert!(bitter.read_u32_bits(7).is_some());
assert_eq!(bitter.approx_bytes_remaining(), 0);

pub fn bits_remaining(&self) -> Option<usize>

Returns the exact number of bits remaining in the bitstream if the number of bits can fit within a usize. For large byte slices, the calculating the number of bits can cause an overflow, hence an Option is returned. See has_bits_remaining for a more performant and ergonomic alternative.

let mut bitter = BitGet::new(&[0xff]);
assert_eq!(bitter.bits_remaining(), Some(8));
assert!(bitter.read_bit().is_some());
assert_eq!(bitter.bits_remaining(), Some(7));
assert!(bitter.read_u32_bits(7).is_some());
assert_eq!(bitter.bits_remaining(), Some(0));

pub fn has_bits_remaining(&self, bits: usize) -> bool

Returns true if at least bits number of bits are left in the stream. A more performant and ergonomic way than bits_remaining.

let mut bitter = BitGet::new(&[0xff]);
assert!(bitter.has_bits_remaining(7));
assert!(bitter.has_bits_remaining(8));
assert!(!bitter.has_bits_remaining(9));

assert!(bitter.read_bit().is_some());
assert!(bitter.has_bits_remaining(7));
assert!(!bitter.has_bits_remaining(8));

assert!(bitter.read_u32_bits(7).is_some());
assert!(!bitter.has_bits_remaining(7));
assert!(bitter.has_bits_remaining(0));

pub fn is_empty(&self) -> bool

Returns if the bitstream has no bits left

let mut bitter = BitGet::new(&[0b1010_1010, 0b0101_0101]);
assert_eq!(bitter.is_empty(), false);
assert_eq!(bitter.read_u16_unchecked(), 0b0101_0101_1010_1010);
assert_eq!(bitter.is_empty(), true);

pub fn read_bit(&mut self) -> Option<bool>

Reads a bit from the bitstream if available

let mut bitter = BitGet::new(&[0b1010_1010, 0b0101_0101]);
assert_eq!(bitter.read_bit(), Some(false));

pub fn read_bit_unchecked(&mut self) -> bool

Assumes there is at least one bit left in the stream.

let mut bitter = BitGet::new(&[0b1010_1010, 0b0101_0101]);
assert_eq!(bitter.read_bit_unchecked(), false);

pub fn read_f32(&mut self) -> Option<f32>

Reads a f32 from the bitstream if available. The standard IEEE-754 binary layout float is used.

pub fn read_f32_unchecked(&mut self) -> f32

Reads a f32 from the bitstream. The standard IEEE-754 binary layout float is used.

pub fn if_get<T, F>(&mut self, f: F) -> Option<Option<T>> where
    F: FnMut(&mut Self) -> Option<T>, 

If the next bit is available and on, decode the next chunk of data (which can return None). The return value can be one of the following:

• None: Not enough data was available
• Some(None): Bit was off so data not decoded
• Some(x): Bit was on and data was decoded

let mut bitter = BitGet::new(&[0xff, 0x04]);
assert_eq!(bitter.if_get(BitGet::read_u8), Some(Some(0x7f)));
assert_eq!(bitter.if_get(BitGet::read_u8), Some(None));
assert_eq!(bitter.if_get(BitGet::read_u8), None);

pub fn if_get_unchecked<T, F>(&mut self, f: F) -> Option<T> where
    F: FnMut(&mut Self) -> T, 

If the next bit is available and on, decode the next chunk of data. The return value can be one of the following:

• Some(None): Bit was off so data not decoded
• Some(x): Bit was on and data was decoded

let mut bitter = BitGet::new(&[0xff, 0x04]);
assert_eq!(bitter.if_get_unchecked(BitGet::read_u8_unchecked), Some(0x7f));
assert_eq!(bitter.if_get_unchecked(BitGet::read_u8_unchecked), None);

Panics

Will panic if no data is left for the bit or for the data to be decoded.

pub fn read_bytes(&mut self, bytes: i32) -> Option<Cow<'_, [u8]>>

If the number of requested bytes are available return them to the client. Since the current bit position may not be byte aligned, all bytes requested may need to be shifted appropriately.

let mut bitter = BitGet::new(&[0b1010_1010, 0b0101_0101]);
assert_eq!(bitter.read_bit_unchecked(), false);
assert_eq!(bitter.read_bytes(1).map(|x| x[0]), Some(0b1101_0101));

pub fn read_bits_max(&mut self, max: u32) -> Option<u32>

Reads a value from the stream that consumes the same or fewer number of bits of a given max. The value read will always be less than the given max.

For example if one wants to read a value that is less than 20, bitter will read at least 4 bits from the stream. If the 5th bit would cause the accumulator to exceed the max, the 5th bit is not consumed. Else the 5th bit is consumed and added to accumulator. If the necessary number of bits are not available, None is returned.

let mut bitter = BitGet::new(&[0b1111_1000]);
assert_eq!(bitter.read_bits_max(20), Some(8));
assert_eq!(bitter.read_bits_max(20), Some(15));

pub fn read_bits_max_computed(&mut self, bits: i32, max: u32) -> Option<u32>

Same as read_bits_max except that this function accepts the already computed number of bits to at least read. For instance, if 20 is the max, then 4 bits are at least needed.

In general, prefer read_bits_max for ease of use

let mut bitter = BitGet::new(&[0b1111_1000]);
assert_eq!(bitter.read_bits_max_computed(4, 20), Some(8));
assert_eq!(bitter.read_bits_max_computed(4, 20), Some(15));

pub fn read_bits_max_unchecked(&mut self, max: u32) -> u32

Reads a value from the stream that consumes the same or fewer number of bits of a given max. The value read will always be less than the given max.

For example if one wants to read a value that is less than 20, bitter will read at least 4 bits from the stream. If the 5th bit would cause the accumulator to exceed the max, the 5th bit is not consumed. Else the 5th bit is consumed and added to accumulator.

let mut bitter = BitGet::new(&[0b1111_1000]);
assert_eq!(bitter.read_bits_max_unchecked(20), 8);
assert_eq!(bitter.read_bits_max_unchecked(20), 15);

pub fn read_bits_max_computed_unchecked(&mut self, bits: i32, max: u32) -> u32

Same as read_bits_max_unchecked except that this function accepts the already computed number of bits to at least read. For instance, if 20 is the max, then 4 bits are at least needed.

In general, prefer read_bits_max_unchecked for ease of use

let mut bitter = BitGet::new(&[0b1111_1000]);
assert_eq!(bitter.read_bits_max_computed_unchecked(4, 20), 8);
assert_eq!(bitter.read_bits_max_computed_unchecked(4, 20), 15);