X-Git-Url: https://git.nihav.org/?a=blobdiff_plain;f=nihav-core%2Fsrc%2Fio%2Fcodebook.rs;h=9882610ab0d102d2be487b56ca5abc4494fd4a4a;hb=fd47a9b679a723f08a76a7f83e3be18f87cef63c;hp=78ef5ae0d142164106696f478916905da2514477;hpb=5641dccfbf2a70d589cf094a0d4ed5a10f919f00;p=nihav.git

diff --git a/nihav-core/src/io/codebook.rs b/nihav-core/src/io/codebook.rs
index 78ef5ae..9882610 100644
--- a/nihav-core/src/io/codebook.rs
+++ b/nihav-core/src/io/codebook.rs
@@ -1,40 +1,130 @@
+//! Codebook support for bitstream reader.
+//!
+//! Codebook is a set of unique bit strings and values assigned to them.
+//! Since there are many ways to define codebook, this implementation employs [`CodebookDescReader`] trait to provide codebook generator with the codes.
+//! Please also pay attention to the codebook creation mode: if bitstream reader reads bits starting from most significant bit first then you should use [`MSB`] mode and [`LSB`] mode otherwise.
+//!
+//! # Examples
+//!
+//! Create a codebook from arrays with codeword descriptions:
+//! ```
+//! use nihav_core::io::codebook::{ShortCodebookDesc, ShortCodebookDescReader, Codebook, CodebookMode};
+//!
+//! let cb_desc: Vec<ShortCodebookDesc> = vec!(
+//!             ShortCodebookDesc { code: 0b00,   bits: 2 },
+//!             ShortCodebookDesc { code: 0,      bits: 0 },
+//!             ShortCodebookDesc { code: 0b01,   bits: 2 },
+//!             ShortCodebookDesc { code: 0b1,    bits: 1 });
+//! let mut cr = ShortCodebookDescReader::new(cb_desc);
+//! let cb = Codebook::new(&mut cr, CodebookMode::LSB).unwrap();
+//! ```
+//!
+//! Create a codebook using more flexible [`TableCodebookDescReader`] approach.
+//! This will create a codebook for the following set: `1` -> -2, `01` -> -1, `001` -> 0, `0001` -> 1, `00001` -> 2.
+//! ```
+//! use nihav_core::io::codebook::{TableCodebookDescReader, Codebook, CodebookMode};
+//!
+//! fn map_cb_index(index: usize) -> i16 { (index as i16) - 2 }
+//! const CB_BITS:  [u8; 5] = [ 1, 2, 3, 4, 5 ];
+//! const CB_CODES: [u8; 5] = [ 1, 1, 1, 1, 1 ];
+//!
+//! let mut tcr = TableCodebookDescReader::new(&CB_CODES, &CB_BITS, map_cb_index);
+//! let cb = Codebook::new(&mut tcr, CodebookMode::MSB).unwrap();
+//! ```
+//!
+//! Read value using a codebook:
+//! ```no_run
+//! use nihav_core::io::bitreader::BitReader;
+//! use nihav_core::io::codebook::{Codebook, CodebookReader, CodebookMode};
+//! # use nihav_core::io::codebook::{ShortCodebookDesc, ShortCodebookDescReader, CodebookDescReader, CodebookResult};
+//!
+//! # fn foo(br: &mut BitReader) -> CodebookResult<()> {
+//! # let mut cr = ShortCodebookDescReader::new(vec![ShortCodebookDesc { code: 0b00,   bits: 2 }]);
+//! let cb = Codebook::new(&mut cr, CodebookMode::MSB).unwrap();
+//! let value = br.read_cb(&cb)?;
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! [`MSB`]: ./enum.CodebookMode.html#variant.MSB
+//! [`LSB`]: ./enum.CodebookMode.html#variant.LSB
+//! [`CodebookDescReader`]: ./trait.CodebookDescReader.html
+//! [`TableCodebookDescReader`]: ./struct.TableCodebookDescReader.html
+
 use std::collections::HashMap;
 use std::cmp::{max, min};
 use super::bitreader::BitReader;
 
+/// A list specifying general codebook operations errors.
 #[derive(Debug)]
 pub enum CodebookError {
+    /// Codebook description contains errors.
     InvalidCodebook,
+    /// Could not allocate memory for codebook.
     MemoryError,
+    /// Bitstream contains a sequence not present in codebook.
     InvalidCode,
 }
 
+/// Codebook operation modes.
 #[derive(Debug, Copy, Clone)]
 pub enum CodebookMode {
+    /// Codes in the codebook should be read most significant bit first.
     MSB,
+    /// Codes in the codebook should be read least significant bit first.
     LSB,
 }
 
-type CodebookResult<T> = Result<T, CodebookError>;
+/// A specialised `Result` type for codebook operations.
+pub type CodebookResult<T> = Result<T, CodebookError>;
 
+/// Codebook description for `(code bits, code length, code value)` triplet.
+///
+/// This should be used to create a list of codeword definitions for [`FullCodebookDescReader`].
+///
+/// [`FullCodebookDescReader`]: ./struct.FullCodebookDescReader.html
+#[derive(Clone,Copy)]
 pub struct FullCodebookDesc<S> {
-    code: u32,
-    bits: u8,
-    sym:  S,
+    /// Codeword bits.
+    pub code: u32,
+    /// Codeword length.
+    pub bits: u8,
+    /// Codeword value (symbol).
+    pub sym:  S,
 }
 
+/// Codebook description for `(code bits, code length)` pair with array index being used as codeword value.
+///
+/// This should be used to create a list of codeword definitions for [`ShortCodebookDescReader`].
+///
+/// [`ShortCodebookDescReader`]: ./struct.ShortCodebookDescReader.html
+#[derive(Clone,Copy)]
 pub struct ShortCodebookDesc {
-    code: u32,
-    bits: u8,
+    /// Codeword bits.
+    pub code: u32,
+    /// Codeword length.
+    pub bits: u8,
 }
 
+/// The interface for providing a list of codeword definitions to the codebook creator.
+///
+/// The structure implementing this trait should be able to provide the total number of defined codewords and their bits and values. [`ShortCodebookDescReader`] or [`TableCodebookDescReader`] are some examples of such implementation.
+/// Codeword definitions with zero length are ignored (those may be used to create sparse codebook definitions though).
+///
+/// [`ShortCodebookDescReader`]: ./struct.ShortCodebookDescReader.html
+/// [`TableCodebookDescReader`]: ./struct.TableCodebookDescReader.html
 pub trait CodebookDescReader<S> {
+    /// Returns the codeword length for the provided index.
     fn bits(&mut self, idx: usize) -> u8;
+    /// Returns the codeword bits for the provided index.
     fn code(&mut self, idx: usize) -> u32;
+    /// Returns the codeword value (aka codeword symbol) for the provided index.
     fn sym (&mut self, idx: usize) -> S;
+    /// Returns the total number of defined codewords.
     fn len (&mut self)             -> usize;
 }
 
+/// The codebook structure for code reading.
 #[allow(dead_code)]
 pub struct Codebook<S> {
     table: Vec<u32>,
@@ -42,7 +132,11 @@ pub struct Codebook<S> {
     lut_bits: u8,
 }
 
+/// Trait allowing bitreader to use codebook for decoding bit sequences.
 pub trait CodebookReader<S> {
+    /// Reads the codeword from the bitstream and returns its value (or [`InvalidCode`] on error).
+    ///
+    /// [`InvalidCode`]: ./enum.CodebookError.html#variant.InvalidCode
     fn read_cb(&mut self, cb: &Codebook<S>) -> CodebookResult<S>;
 }
 
@@ -55,14 +149,14 @@ fn fill_lut_msb(table: &mut Vec<u32>, off: usize,
         let fill_len  = lut_bits - bits;
         let fill_size = 1 << fill_len;
         let fill_code = code << (lut_bits - bits);
-        let lut_value = (symidx << 8) | (bits as u32);
+        let lut_value = (symidx << 8) | u32::from(bits);
         for j in 0..fill_size {
             let idx = (fill_code + j) as usize;
             table[idx + off] = lut_value;
         }
     } else {
         let idx = (code as usize) + off;
-        table[idx] = (symidx << 8) | 0x80 | (bits as u32);
+        table[idx] = (symidx << 8) | 0x80 | u32::from(bits);
     }
 }
 
@@ -75,11 +169,11 @@ fn fill_lut_lsb(table: &mut Vec<u32>, off: usize,
         let step = lut_bits - fill_len;
         for j in 0..fill_size {
             let idx = (fill_code + (j << step)) as usize;
-            table[idx + off] = (symidx << 8) | (bits as u32);
+            table[idx + off] = (symidx << 8) | u32::from(bits);
         }
     } else {
         let idx = (code as usize) + off;
-        table[idx] = (symidx << 8) | 0x80 | (bits as u32);
+        table[idx] = (symidx << 8) | 0x80 | u32::from(bits);
     }
 }
 
@@ -143,10 +237,10 @@ impl CodeBucket {
 type EscapeCodes = HashMap<u32, CodeBucket>;
 
 fn add_esc_code(cc: &mut EscapeCodes, key: u32, code: u32, bits: u8, idx: usize) {
-    if !cc.contains_key(&key) { cc.insert(key, CodeBucket::new()); }
+    cc.entry(key).or_insert_with(CodeBucket::new);
     let b = cc.get_mut(&key);
     if let Some(bucket) = b {
-        bucket.add_code(Code {code: code, bits: bits, idx: idx });
+        bucket.add_code(Code {code, bits, idx });
     } else { panic!("no bucket when expected!"); }
 }
 
@@ -178,7 +272,7 @@ fn build_esc_lut(table: &mut Vec<u32>,
         sec_bucket.offset = new_off as usize;
     }
 
-    for (_, sec_bucket) in &escape_list {
+    for sec_bucket in escape_list.values() {
         build_esc_lut(table, mode, sec_bucket)?;
     }
 
@@ -187,6 +281,7 @@ fn build_esc_lut(table: &mut Vec<u32>,
 
 impl<S: Copy> Codebook<S> {
 
+    /// Constructs a new `Codebook` instance using provided codebook description and mode.
     pub fn new(cb: &mut CodebookDescReader<S>, mode: CodebookMode) -> CodebookResult<Self> {
         let mut maxbits = 0;
         let mut nnz = 0;
@@ -196,7 +291,7 @@ impl<S: Copy> Codebook<S> {
         for i in 0..cb.len() {
             let bits = cb.bits(i);
             if bits > 0 {
-                nnz = nnz + 1;
+                nnz += 1;
                 if cb.code(i) >= (1 << bits) {
                     return Err(CodebookError::InvalidCodebook);
                 }
@@ -208,7 +303,7 @@ impl<S: Copy> Codebook<S> {
                 let cval = extract_esc_part(code, bits, MAX_LUT_BITS, mode);
                 add_esc_code(&mut escape_list, ckey, cval, bits - MAX_LUT_BITS, symidx);
             }
-            if bits > 0 { symidx = symidx + 1; }
+            if bits > 0 { symidx += 1; }
         }
         if maxbits == 0 { return Err(CodebookError::InvalidCodebook); }
 
@@ -240,10 +335,10 @@ impl<S: Copy> Codebook<S> {
                     }
                 }
             }
-            symidx = symidx + 1;
+            symidx += 1;
         }
 
-        for (_, bucket) in &escape_list {
+        for bucket in escape_list.values() {
             build_esc_lut(&mut table, mode, &bucket)?;
         }
 
@@ -253,7 +348,7 @@ impl<S: Copy> Codebook<S> {
             }
         }
 
-        Ok(Codebook { table: table, syms: syms, lut_bits: maxbits })
+        Ok(Codebook { table, syms, lut_bits: maxbits })
     }
 }
 
@@ -272,21 +367,23 @@ impl<'a, S: Copy> CodebookReader<S> for BitReader<'a> {
             if (bits as isize) > self.left() {
                 return Err(CodebookError::InvalidCode);
             }
-            let skip_bits = if esc { lut_bits as u32 } else { bits };
-            if let Err(_) = self.skip(skip_bits as u32) {}
+            let skip_bits = if esc { u32::from(lut_bits) } else { bits };
+            self.skip(skip_bits as u32).unwrap();
             lut_bits = bits as u8;
         }
         Ok(cb.syms[idx])
     }
 }
 
+/// Codebook description that stores a list of codewords and their values.
 pub struct FullCodebookDescReader<S> {
     data: Vec<FullCodebookDesc<S>>,
 }
 
 impl<S> FullCodebookDescReader<S> {
+    /// Constructs a new `FullCodebookDescReader` instance.
     pub fn new(data: Vec<FullCodebookDesc<S>>) -> Self {
-        FullCodebookDescReader { data: data }
+        FullCodebookDescReader { data }
     }
 }
 
@@ -297,13 +394,15 @@ impl<S: Copy> CodebookDescReader<S> for FullCodebookDescReader<S> {
     fn len(&mut self) -> usize { self.data.len() }
 }
 
+/// Codebook description that stores a list of codewords and their value is equal to the index.
 pub struct ShortCodebookDescReader {
     data: Vec<ShortCodebookDesc>,
 }
 
 impl ShortCodebookDescReader {
+    /// Constructs a new `ShortCodebookDescReader` instance.
     pub fn new(data: Vec<ShortCodebookDesc<>>) -> Self {
-        ShortCodebookDescReader { data: data }
+        ShortCodebookDescReader { data }
     }
 }
 
@@ -314,18 +413,20 @@ impl CodebookDescReader<u32> for ShortCodebookDescReader {
     fn len(&mut self) -> usize { self.data.len() }
 }
 
-pub struct TableCodebookDescReader<CodeType:'static, IndexType:'static> {
-    bits:       &'static [u8],
-    codes:      &'static [CodeType],
+/// Flexible codebook description that uses two separate arrays for codeword bits and lengths and a function that maps codeword index into its symbol.
+pub struct TableCodebookDescReader<'a, CodeType:'static, IndexType:'static> {
+    bits:       &'a [u8],
+    codes:      &'a [CodeType],
     idx_map:    fn(usize) -> IndexType,
 }
 
-impl<'a, CodeType, IndexType> TableCodebookDescReader<CodeType, IndexType> {
-    pub fn new(codes: &'static [CodeType], bits: &'static [u8], idx_map: fn(usize) -> IndexType) -> Self {
+impl<'a, CodeType, IndexType> TableCodebookDescReader<'a, CodeType, IndexType> {
+    /// Constructs a new `TableCodebookDescReader` instance.
+    pub fn new(codes: &'a [CodeType], bits: &'a [u8], idx_map: fn(usize) -> IndexType) -> Self {
         Self { bits, codes, idx_map }
     }
 }
-impl<CodeType: Copy+Into<u32>, IndexType> CodebookDescReader<IndexType> for TableCodebookDescReader<CodeType, IndexType>
+impl<'a, CodeType: Copy+Into<u32>, IndexType> CodebookDescReader<IndexType> for TableCodebookDescReader<'a, CodeType, IndexType>
 {
     fn bits(&mut self, idx: usize) -> u8  { self.bits[idx] }
     fn code(&mut self, idx: usize) -> u32 { self.codes[idx].into() }
@@ -348,7 +449,7 @@ mod test {
             FullCodebookDesc { code: 0b1110, bits: 4, sym: -42 }
         );
         let buf = &BITS;
-        let mut br = BitReader::new(buf, buf.len(), BitReaderMode::BE);
+        let mut br = BitReader::new(buf, BitReaderMode::BE);
         let mut cfr = FullCodebookDescReader::new(cb_desc);
         let cb = Codebook::new(&mut cfr, CodebookMode::MSB).unwrap();
         assert_eq!(br.read_cb(&cb).unwrap(),  16);
@@ -377,7 +478,7 @@ mod test {
             ShortCodebookDesc { code: 0b1111110, bits: 7 },
             ShortCodebookDesc { code: 0b11111111, bits: 8 }
         );
-        let mut br2 = BitReader::new(buf, buf.len(), BitReaderMode::BE);
+        let mut br2 = BitReader::new(buf, BitReaderMode::BE);
         let mut cfr = ShortCodebookDescReader::new(scb_desc);
         let cb = Codebook::new(&mut cfr, CodebookMode::MSB).unwrap();
         assert_eq!(br2.read_cb(&cb).unwrap(), 0);
@@ -404,7 +505,7 @@ mod test {
             ShortCodebookDesc { code: 0b0111111, bits: 7 },
             ShortCodebookDesc { code: 0b1011101111, bits: 10 }
         );
-        let mut brl = BitReader::new(buf, buf.len(), BitReaderMode::LE);
+        let mut brl = BitReader::new(buf, BitReaderMode::LE);
         let mut cfr = ShortCodebookDescReader::new(scble_desc);
         let cb = Codebook::new(&mut cfr, CodebookMode::LSB).unwrap();
         assert_eq!(brl.read_cb(&cb).unwrap(), 11);