X-Git-Url: https://git.nihav.org/?a=blobdiff_plain;f=nihav-core%2Fsrc%2Fio%2Fbitreader.rs;h=6c786228c1ecf9465e387f27ab6516e7c406891d;hb=36ce88be3f590a876fe539c8f631a58af2ea2cac;hp=faa1d8775ece2f89e05fd2e77f962695df3ee645;hpb=e243ceb4d694cc08767ad70027bb6963f4cefea3;p=nihav.git diff --git a/nihav-core/src/io/bitreader.rs b/nihav-core/src/io/bitreader.rs index faa1d87..6c78622 100644 --- a/nihav-core/src/io/bitreader.rs +++ b/nihav-core/src/io/bitreader.rs @@ -1,28 +1,74 @@ -#[derive(Debug)] +//! Bitstream reader functionality. +//! +//! Bitstream reader operates on `&[u8]` and allows to read bits from the slice in different modes. +//! +//! # Examples +//! +//! Reading 17 bits from a bitstream: +//! ``` +//! use nihav_core::io::bitreader::{BitReader,BitReaderMode}; +//! +//! # use nihav_core::io::bitreader::BitReaderResult; +//! # fn foo() -> BitReaderResult { +//! let bits: [u8; 4] = [ 42, 43, 44, 45 ]; +//! let mut br = BitReader::new(&bits, BitReaderMode::BE); +//! let value = br.read(17)?; +//! # Ok(value) +//! # } +//! ``` +//! +//! Reading some amount of bits and checking how many bits are left: +//! ``` +//! use nihav_core::io::bitreader::{BitReader,BitReaderMode}; +//! +//! # use nihav_core::io::bitreader::BitReaderResult; +//! # fn foo() -> BitReaderResult<()> { +//! let bits: [u8; 4] = [ 42, 43, 44, 45 ]; +//! let mut br = BitReader::new(&bits, BitReaderMode::BE); +//! let num_skip_bits = br.read(3)?; +//! br.skip(num_skip_bits)?; +//! println!("Now there are {} bits left to read.", br.left()); +//! # Ok(()) +//! # } +//! ``` + + + +/// Bitstream reading modes. +#[derive(Debug,Clone,Copy)] pub enum BitReaderMode { + /// The stream is big endian MSB first. BE, + /// The stream is little endian LSB first. LE, + /// The stream is packed into 16-bit little-endian words MSB first. LE16MSB, + /// The stream is packed into 32-bit little-endian words MSB first. LE32MSB, } -#[derive(Debug)] +/// A list specifying general bitstream reading errors. +#[derive(Debug,Clone,Copy)] pub enum BitReaderError { + /// The reader is at the end of bitstream. BitstreamEnd, + /// The caller tried to read too many bits at once (e.g. 128). TooManyBitsRequested, + /// Some argument is invalid. InvalidValue, } use self::BitReaderError::*; +/// A specialised `Result` type for bitstream operations. pub type BitReaderResult = Result; -#[derive(Debug)] +/// Bitstream reader. +#[derive(Debug,Clone)] pub struct BitReader<'a> { cache: u64, bits: u8, pos: usize, - end: usize, src: &'a [u8], mode: BitReaderMode, } @@ -30,17 +76,28 @@ pub struct BitReader<'a> { #[allow(clippy::identity_op)] impl<'a> BitReader<'a> { - pub fn new(src: &'a [u8], size: usize, mode: BitReaderMode) -> Self { - if src.len() < size { panic!("size is less than needed"); } - BitReader{ cache: 0, pos: 0, bits: 0, end: size, src, mode } + /// Constructs a new instance of bitstream reader. + /// + /// # Examples + /// + /// ``` + /// use nihav_core::io::bitreader::{BitReader,BitReaderMode}; + /// + /// let bits: [u8; 4] = [ 42, 43, 44, 45 ]; + /// let mut br = BitReader::new(&bits, BitReaderMode::BE); + /// ``` + pub fn new(src: &'a [u8], mode: BitReaderMode) -> Self { + BitReader{ cache: 0, pos: 0, bits: 0, src, mode } } + /// Reports the current bit position in the bitstream (usually simply the number of bits read so far). pub fn tell(&self) -> usize { self.pos * 8 - (self.bits as usize) } + /// Reports the amount of bits left until the end of the bitstream. pub fn left(&self) -> isize { - ((self.end as isize) - (self.pos as isize)) * 8 + (self.bits as isize) + ((self.src.len() as isize) - (self.pos as isize)) * 8 + (self.bits as isize) } fn fill32be(&mut self, src: &[u8]) { @@ -73,9 +130,9 @@ impl<'a> BitReader<'a> { #[inline(always)] fn refill(&mut self) -> BitReaderResult<()> { - if self.pos >= self.end { return Err(BitstreamEnd) } + if self.pos >= self.src.len() { return Err(BitstreamEnd) } while self.bits <= 32 { - if self.pos + 4 <= self.end { + if self.pos + 4 <= self.src.len() { let buf = &self.src[self.pos..]; match self.mode { BitReaderMode::BE => self.fill32be (buf), @@ -89,7 +146,7 @@ impl<'a> BitReader<'a> { let mut buf: [u8; 4] = [0, 0, 0, 0]; let mut newbits: u8 = 0; for out in buf.iter_mut().take(3) { - if self.pos < self.end { + if self.pos < self.src.len() { *out = self.src[self.pos]; self.pos += 1; newbits += 8; @@ -140,6 +197,28 @@ impl<'a> BitReader<'a> { self.cache = 0; } + /// Reads the specified amount of bits as an unsigned value. + /// + /// The amount should fit into 32 bits, if you need more then + /// you should read it as several parts. If the amount of bits + /// requested to read is larger than the amount of bits left the + /// call will return [`BitstreamEnd`]. + /// + /// # Examples + /// + /// ``` + /// use nihav_core::io::bitreader::{BitReader,BitReaderMode}; + /// + /// # use nihav_core::io::bitreader::BitReaderResult; + /// # fn foo() -> BitReaderResult { + /// let bits: [u8; 4] = [ 42, 43, 44, 45 ]; + /// let mut br = BitReader::new(&bits, BitReaderMode::BE); + /// let value = br.read(17)?; + /// # Ok(value) + /// # } + /// ``` + /// + /// [`BitstreamEnd`]: ./enum.BitReaderError.html#variant.BitstreamEnd #[inline(always)] pub fn read(&mut self, nbits: u8) -> BitReaderResult { if nbits == 0 { return Ok(0) } @@ -153,6 +232,11 @@ impl<'a> BitReader<'a> { Ok(res) } + /// Reads the specified amount of bits as a signed value. + /// + /// Beside signedness it behaves the same as [`read`]. + /// + /// [`read`]: #method.read pub fn read_s(&mut self, nbits: u8) -> BitReaderResult { if nbits == 0 || nbits > 32 { return Err(TooManyBitsRequested) } if self.bits < nbits { @@ -164,6 +248,7 @@ impl<'a> BitReader<'a> { Ok(res) } + /// Reads single bit from the stream and interprets it as a boolean value. #[inline(always)] pub fn read_bool(&mut self) -> BitReaderResult { if self.bits < 1 { @@ -175,6 +260,24 @@ impl<'a> BitReader<'a> { Ok(res == 1) } + /// Retrieves the next bits from the stream without advancing. + /// + /// If the bitstream is shorter than the amount of bits requested the result is padded with zeroes. + /// + /// # Examples + /// + /// ``` + /// use nihav_core::io::bitreader::{BitReader,BitReaderMode}; + /// + /// # use nihav_core::io::bitreader::BitReaderResult; + /// # fn foo() -> BitReaderResult { + /// let bits: [u8; 4] = [ 42, 43, 44, 45 ]; + /// let mut br = BitReader::new(&bits, BitReaderMode::BE); + /// let peek_value = br.peek(8); // this should return 42 + /// let value = br.read(8)?; // also 42 + /// # Ok(value) + /// # } + /// ``` #[inline(always)] pub fn peek(&mut self, nbits: u8) -> u32 { if nbits > 32 { return 0 } @@ -182,6 +285,13 @@ impl<'a> BitReader<'a> { self.read_cache(nbits) } + /// Skips the requested amount of bits. + /// + /// The amount of bits to skip can be arbitrary large. + /// If it skips more bits than there are actually in the stream the call will return [`BitstreamEnd`] + /// + /// [`read`]: #method.read + /// [`BitstreamEnd`]: ./enum.BitReaderError.html#variant.BitstreamEnd #[inline(always)] pub fn skip(&mut self, nbits: u32) -> BitReaderResult<()> { if u32::from(self.bits) >= nbits { @@ -199,13 +309,49 @@ impl<'a> BitReader<'a> { Ok(()) } + /// Seeks to the absolute bit position in the stream. + /// If the requested position lies after the bitstream end the function returns [`TooManyBitsRequested`]. + /// + /// # Examples + /// + /// ``` + /// use nihav_core::io::bitreader::{BitReader,BitReaderMode}; + /// + /// # use nihav_core::io::bitreader::BitReaderResult; + /// # fn foo() -> BitReaderResult { + /// let bits: [u8; 4] = [ 42, 43, 44, 45 ]; + /// let mut br = BitReader::new(&bits, BitReaderMode::BE); + /// br.seek(16)?; + /// let value = br.read(8)?; // this should return 44 + /// # Ok(value) + /// # } + /// ``` + /// + /// [`TooManyBitsRequested`]: ./enum.BitReaderError.html#variant.TooManyBitsRequested pub fn seek(&mut self, nbits: u32) -> BitReaderResult<()> { - if ((nbits + 7) >> 3) as usize > self.end { return Err(TooManyBitsRequested); } + if ((nbits + 7) >> 3) as usize > self.src.len() { return Err(TooManyBitsRequested); } self.reset_cache(); self.pos = ((nbits / 32) * 4) as usize; self.skip(nbits & 0x1F) } + /// Aligns the bit position to the next byte boundary. If already at byte boundary the function does nothing. + /// + /// # Examples + /// + /// ``` + /// use nihav_core::io::bitreader::{BitReader,BitReaderMode}; + /// + /// # use nihav_core::io::bitreader::BitReaderResult; + /// # fn foo() -> BitReaderResult<()> { + /// let bits: [u8; 4] = [ 42, 43, 44, 45 ]; + /// let mut br = BitReader::new(&bits, BitReaderMode::BE); + /// br.skip(17)?; // now reader is at bit position 17 + /// br.align(); // now reader is at bit position 24 + /// br.align(); // now reader is still at bit position 24 + /// # Ok(()) + /// # } + /// ``` pub fn align(&mut self) { let pos = self.bits & 7; if pos != 0 { @@ -214,6 +360,13 @@ impl<'a> BitReader<'a> { } } +/// Returns a variable with `len` amount of low bits in reverse order. +/// +/// # Examples +/// ``` +/// use nihav_core::io::bitreader::reverse_bits; +/// reverse_bits(0b010101, 6); // the result should be 0b101010 +/// ``` pub fn reverse_bits(inval: u32, len: u8) -> u32 { if len == 0 { return 0; } const REV_TAB: [u8; 16] = [ @@ -238,14 +391,14 @@ mod test { fn br_works() { const DATA: [u8; 18] = [0b00011011; 18]; let src = &DATA; - let mut br = BitReader::new(src, src.len(), BitReaderMode::LE16MSB); + let mut br = BitReader::new(src, BitReaderMode::LE16MSB); for _ in 0..8 { assert_eq!(br.read(16).unwrap(), 0x1B1B); } const DATA2: [u8; 1] = [ 0b00011011 ]; let src = &DATA2; - let mut br = BitReader::new(src, src.len(), BitReaderMode::LE); + let mut br = BitReader::new(src, BitReaderMode::LE); assert_eq!(br.read_s(5).unwrap(), -5); } }