rtcm3 0.1.0

no_std, no_alloc parser and encoder for RTCM3 GNSS RTK correction messages
Documentation
//! MSB-first bit reader. RTCM3 packs fields at arbitrary bit widths
//! (a 12-bit message type, a 38-bit ECEF coordinate, and so on), reading
//! the most significant bit of each byte first, unlike a byte-aligned
//! protocol.

use crate::error::BitError;

/// Reads fixed-width fields from a byte slice, most-significant-bit first.
pub struct BitReader<'a> {
    data: &'a [u8],
    bit_pos: usize,
}

impl<'a> BitReader<'a> {
    /// Builds a reader starting at the first bit of `data`.
    #[must_use]
    pub const fn new(data: &'a [u8]) -> Self {
        Self { data, bit_pos: 0 }
    }

    /// How many unread bits remain.
    #[must_use]
    pub const fn remaining_bits(&self) -> usize {
        self.data.len() * 8 - self.bit_pos
    }

    /// Reads a single bit as a `bool`.
    ///
    /// # Errors
    /// Returns [`BitError::UnexpectedEof`] if no bits remain.
    pub fn read_bool(&mut self) -> Result<bool, BitError> {
        Ok(self.read_u64(1)? != 0)
    }

    /// Reads an unsigned value of `nbits` bits (`1..=64`).
    ///
    /// # Errors
    /// Returns [`BitError::OutOfRange`] if `nbits` is `0` or greater than
    /// `64`, or [`BitError::UnexpectedEof`] if fewer than `nbits` bits
    /// remain.
    pub fn read_u64(&mut self, nbits: u32) -> Result<u64, BitError> {
        if nbits == 0 || nbits > 64 {
            return Err(BitError::OutOfRange { field: "nbits" });
        }
        if (nbits as usize) > self.remaining_bits() {
            return Err(BitError::UnexpectedEof);
        }
        let mut value: u64 = 0;
        for _ in 0..nbits {
            let byte_idx = self.bit_pos / 8;
            let bit_idx = 7 - (self.bit_pos % 8);
            let bit = (self.data[byte_idx] >> bit_idx) & 1;
            value = (value << 1) | u64::from(bit);
            self.bit_pos += 1;
        }
        Ok(value)
    }

    /// Reads an unsigned value of `nbits` bits (`1..=8`).
    ///
    /// # Errors
    /// Same as [`Self::read_u64`], plus [`BitError::OutOfRange`] if
    /// `nbits > 8`.
    pub fn read_u8(&mut self, nbits: u32) -> Result<u8, BitError> {
        if nbits > 8 {
            return Err(BitError::OutOfRange { field: "nbits" });
        }
        #[allow(
            clippy::cast_possible_truncation,
            reason = "nbits <= 8 is checked above, so the value fits in a u8"
        )]
        Ok(self.read_u64(nbits)? as u8)
    }

    /// Reads an unsigned value of `nbits` bits (`1..=16`).
    ///
    /// # Errors
    /// Same as [`Self::read_u64`], plus [`BitError::OutOfRange`] if
    /// `nbits > 16`.
    pub fn read_u16(&mut self, nbits: u32) -> Result<u16, BitError> {
        if nbits > 16 {
            return Err(BitError::OutOfRange { field: "nbits" });
        }
        #[allow(
            clippy::cast_possible_truncation,
            reason = "nbits <= 16 is checked above, so the value fits in a u16"
        )]
        Ok(self.read_u64(nbits)? as u16)
    }

    /// Reads an unsigned value of `nbits` bits (`1..=32`).
    ///
    /// # Errors
    /// Same as [`Self::read_u64`], plus [`BitError::OutOfRange`] if
    /// `nbits > 32`.
    pub fn read_u32(&mut self, nbits: u32) -> Result<u32, BitError> {
        if nbits > 32 {
            return Err(BitError::OutOfRange { field: "nbits" });
        }
        #[allow(
            clippy::cast_possible_truncation,
            reason = "nbits <= 32 is checked above, so the value fits in a u32"
        )]
        Ok(self.read_u64(nbits)? as u32)
    }

    /// Reads a two's-complement signed value of `nbits` bits (`1..=32`).
    ///
    /// # Errors
    /// Same as [`Self::read_u32`].
    pub fn read_i32(&mut self, nbits: u32) -> Result<i32, BitError> {
        let raw = self.read_u32(nbits)?;
        let shift = 32 - nbits;
        #[allow(
            clippy::cast_possible_wrap,
            reason = "arithmetic (not logical) right shift sign-extends, the intended behavior"
        )]
        Ok(((raw << shift) as i32) >> shift)
    }

    /// Reads a two's-complement signed value of `nbits` bits (`1..=64`).
    ///
    /// # Errors
    /// Same as [`Self::read_u64`].
    pub fn read_i64(&mut self, nbits: u32) -> Result<i64, BitError> {
        let raw = self.read_u64(nbits)?;
        let shift = 64 - nbits;
        #[allow(
            clippy::cast_possible_wrap,
            reason = "arithmetic (not logical) right shift sign-extends, the intended behavior"
        )]
        Ok(((raw << shift) as i64) >> shift)
    }

    /// Skips `nbits` bits without interpreting them.
    ///
    /// # Errors
    /// Returns [`BitError::UnexpectedEof`] if fewer than `nbits` bits remain.
    pub fn skip(&mut self, nbits: u32) -> Result<(), BitError> {
        if (nbits as usize) > self.remaining_bits() {
            return Err(BitError::UnexpectedEof);
        }
        self.bit_pos += nbits as usize;
        Ok(())
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn reads_known_unsigned_values() {
        // 1010_1100 1111_0000
        let data = [0b1010_1100, 0b1111_0000];
        let mut r = BitReader::new(&data);
        assert_eq!(r.read_u8(4).unwrap(), 0b1010);
        assert_eq!(r.read_u8(4).unwrap(), 0b1100);
        assert_eq!(r.read_u16(8).unwrap(), 0b1111_0000);
    }

    #[test]
    fn reads_a_12_bit_message_type() {
        // DF002 = 1005: 0b0011_1110_1101 spanning a byte boundary.
        let data = [0b0011_1110, 0b1101_0000];
        let mut r = BitReader::new(&data);
        assert_eq!(r.read_u16(12).unwrap(), 1005);
    }

    #[test]
    fn sign_extends_negative_values() {
        // 6-bit two's complement -1 = 0b111111
        let data = [0b1111_1100];
        let mut r = BitReader::new(&data);
        assert_eq!(r.read_i32(6).unwrap(), -1);
    }

    #[test]
    fn sign_extends_positive_values() {
        let data = [0b0101_0000];
        let mut r = BitReader::new(&data);
        assert_eq!(r.read_i32(4).unwrap(), 0b0101);
    }

    #[test]
    fn eof_when_reading_past_end() {
        let data = [0u8; 1];
        let mut r = BitReader::new(&data);
        assert_eq!(r.read_u64(9), Err(BitError::UnexpectedEof));
    }

    #[test]
    fn rejects_out_of_range_widths() {
        let data = [0u8; 4];
        let mut r = BitReader::new(&data);
        assert_eq!(r.read_u64(0), Err(BitError::OutOfRange { field: "nbits" }));
        assert_eq!(r.read_u64(65), Err(BitError::OutOfRange { field: "nbits" }));
        assert_eq!(r.read_u8(9), Err(BitError::OutOfRange { field: "nbits" }));
    }

    #[test]
    fn skip_advances_position() {
        let data = [0b1010_1010, 0b0101_0101];
        let mut r = BitReader::new(&data);
        r.skip(8).unwrap();
        assert_eq!(r.read_u8(8).unwrap(), 0b0101_0101);
    }

    #[test]
    fn remaining_bits_counts_down() {
        let data = [0u8; 2];
        let mut r = BitReader::new(&data);
        assert_eq!(r.remaining_bits(), 16);
        r.skip(5).unwrap();
        assert_eq!(r.remaining_bits(), 11);
    }
}