X-Git-Url: https://git.nihav.org/?a=blobdiff_plain;f=nihav-core%2Fsrc%2Fio%2Fbitreader.rs;h=569330b5be59e14ab75612c14462ba18832dec0a;hb=3fae33bd60f5575e63cfb1beec82a56a036e47fb;hp=ea5f27c078d8c4e9cb3aa69bb69eeaa47e3d149e;hpb=5641dccfbf2a70d589cf094a0d4ed5a10f919f00;p=nihav.git diff --git a/nihav-core/src/io/bitreader.rs b/nihav-core/src/io/bitreader.rs index ea5f27c..569330b 100644 --- a/nihav-core/src/io/bitreader.rs +++ b/nihav-core/src/io/bitreader.rs @@ -1,80 +1,141 @@ -#[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, } +#[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: src, mode: 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 } } + /// Returns the data bitstream reader uses. + pub fn get_data(&self) -> &'a [u8] { self.src } + + /// 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]) { - let nw = (((src[0] as u32) << 24) | - ((src[1] as u32) << 16) | - ((src[2] as u32) << 8) | - ((src[3] as u32) << 0)) as u64; - self.cache |= nw << (32 - self.bits); + let nw = (u32::from(src[0]) << 24) | + (u32::from(src[1]) << 16) | + (u32::from(src[2]) << 8) | + (u32::from(src[3]) << 0); + self.cache |= u64::from(nw) << (32 - self.bits); } fn fill32le16(&mut self, src: &[u8]) { - let nw = (((src[1] as u32) << 24) | - ((src[0] as u32) << 16) | - ((src[3] as u32) << 8) | - ((src[2] as u32) << 0)) as u64; - self.cache |= nw << (32 - self.bits); + let nw = (u32::from(src[1]) << 24) | + (u32::from(src[0]) << 16) | + (u32::from(src[3]) << 8) | + (u32::from(src[2]) << 0); + self.cache |= u64::from(nw) << (32 - self.bits); } fn fill32le32(&mut self, src: &[u8], lsb: bool) { - let nw = (((src[3] as u32) << 24) | - ((src[2] as u32) << 16) | - ((src[1] as u32) << 8) | - ((src[0] as u32) << 0)) as u64; + let nw = (u32::from(src[3]) << 24) | + (u32::from(src[2]) << 16) | + (u32::from(src[1]) << 8) | + (u32::from(src[0]) << 0); if lsb { - self.cache |= nw << self.bits; + self.cache |= u64::from(nw) << self.bits; } else { - self.cache |= nw << (32 - self.bits); + self.cache |= u64::from(nw) << (32 - self.bits); } } #[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), @@ -87,10 +148,10 @@ impl<'a> BitReader<'a> { } else { let mut buf: [u8; 4] = [0, 0, 0, 0]; let mut newbits: u8 = 0; - for i in 0..3 { - if self.pos < self.end { - buf[i] = self.src[self.pos]; - self.pos = self.pos + 1; + for out in buf.iter_mut().take(3) { + if self.pos < self.src.len() { + *out = self.src[self.pos]; + self.pos += 1; newbits += 8; } } @@ -111,7 +172,7 @@ impl<'a> BitReader<'a> { fn read_cache(&mut self, nbits: u8) -> u32 { let res = match self.mode { BitReaderMode::LE => ((1u64 << nbits) - 1) & self.cache, - _ => (self.cache as u64) >> (64 - nbits), + _ => self.cache >> (64 - nbits), }; res as u32 } @@ -139,6 +200,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) } @@ -152,6 +235,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 { @@ -163,6 +251,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 { @@ -174,6 +263,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 } @@ -181,16 +288,23 @@ 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 self.bits as u32 >= nbits { + if u32::from(self.bits) >= nbits { self.skip_cache(nbits as u8); return Ok(()); } - let mut skip_bits = nbits - (self.bits as u32); + let mut skip_bits = nbits - u32::from(self.bits); self.reset_cache(); self.pos += ((skip_bits / 32) * 4) as usize; - skip_bits = skip_bits & 0x1F; + skip_bits &= 0x1F; self.refill()?; if skip_bits > 0 { self.skip_cache(skip_bits as u8); @@ -198,13 +312,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 { @@ -213,6 +363,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] = [ @@ -223,8 +380,8 @@ pub fn reverse_bits(inval: u32, len: u8) -> u32 { let mut ret = 0; let mut val = inval; for _ in 0..8 { - ret = (ret << 4) | (REV_TAB[(val & 0xF) as usize] as u32); - val = val >> 4; + ret = (ret << 4) | u32::from(REV_TAB[(val & 0xF) as usize]); + val >>= 4; } ret >> (32 - len) } @@ -237,14 +394,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); } }