rebgzf 0.2.0

Efficient gzip to BGZF transcoder using Puffin-style half-decompression
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69

use crate::error::Result;

/// Trait for bit-level reading from a data source.
///
/// Implementations provide the core bit operations needed by DEFLATE parsing
/// and Huffman decoding. This trait allows the hot path to be generic over
/// the backing store (Read-based stream vs memory-mapped slice).
pub trait BitRead {
    /// Ensure at least `n` bits are available in the buffer.
    fn fill_buffer(&mut self, n: u8) -> Result<()>;

    /// Read `n` bits (1-32) in LSB-first order (standard DEFLATE order).
    fn read_bits(&mut self, n: u8) -> Result<u32>;

    /// Peek at `n` bits without consuming them (for table-based Huffman decoding).
    fn peek_bits(&mut self, n: u8) -> Result<u32>;

    /// Consume `n` bits that were previously peeked.
    fn consume_bits(&mut self, n: u8);

    /// Read a single bit.
    #[inline]
    fn read_bit(&mut self) -> Result<bool> {
        Ok(self.read_bits(1)? != 0)
    }

    /// Discard remaining bits in current byte, align to next byte boundary.
    fn align_to_byte(&mut self);

    /// Read a complete byte (aligns to byte boundary first).
    #[inline]
    fn read_byte(&mut self) -> Result<u8> {
        self.align_to_byte();
        self.read_bits(8).map(|v| v as u8)
    }

    /// Read a 16-bit little-endian value (aligns to byte boundary first).
    #[inline]
    fn read_u16_le(&mut self) -> Result<u16> {
        self.align_to_byte();
        let lo = self.read_bits(8)? as u16;
        let hi = self.read_bits(8)? as u16;
        Ok(lo | (hi << 8))
    }

    /// Read a 32-bit little-endian value (aligns to byte boundary first).
    #[inline]
    fn read_u32_le(&mut self) -> Result<u32> {
        self.align_to_byte();
        let b0 = self.read_bits(8)?;
        let b1 = self.read_bits(8)?;
        let b2 = self.read_bits(8)?;
        let b3 = self.read_bits(8)?;
        Ok(b0 | (b1 << 8) | (b2 << 16) | (b3 << 24))
    }

    /// Read exactly `n` bytes into a buffer (aligns to byte boundary first).
    #[inline]
    fn read_bytes(&mut self, buf: &mut [u8]) -> Result<()> {
        self.align_to_byte();
        for b in buf.iter_mut() {
            *b = self.read_bits(8)? as u8;
        }
        Ok(())
    }

    /// Get approximate position in bytes (for error reporting).
    fn bytes_read(&self) -> u64;
}