rtcm3 0.1.0

no_std, no_alloc parser and encoder for RTCM3 GNSS RTK correction messages
Documentation
//! Error types for every layer of the decode/encode pipeline.

use core::fmt;

/// Errors from the bit-level reader/writer.
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum BitError {
    /// Attempted to read past the end of the available bits.
    UnexpectedEof,
    /// A requested field width was zero or exceeded the return type's width.
    OutOfRange {
        /// Name of the field/operation that was out of range.
        field: &'static str,
    },
    /// The destination buffer has no room for more output.
    BufferFull,
}

impl fmt::Display for BitError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::UnexpectedEof => write!(f, "unexpected end of bit stream"),
            Self::OutOfRange { field } => write!(f, "field width out of range: {field}"),
            Self::BufferFull => write!(f, "output buffer is full"),
        }
    }
}

impl core::error::Error for BitError {}

/// Errors from parsing a raw RTCM3 frame.
///
/// Unlike a per-message checksum scheme, RTCM3's CRC-24Q covers the whole
/// frame (preamble through payload) with no per-message secret byte, so
/// [`crate::frame::Frame::parse`] verifies it directly - there's no
/// equivalent of a deferred checksum check here.
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FrameError {
    /// The buffer was shorter than the minimal frame this header declares
    /// (3-byte header + declared payload length + 3-byte CRC).
    TooShort {
        /// Bytes required, per the header's own declared payload length.
        needed: usize,
        /// Bytes actually available in the buffer.
        got: usize,
    },
    /// The first byte wasn't the RTCM3 preamble (`0xD3`).
    UnknownPreamble(u8),
    /// The 6 reserved bits before the length field were not all zero.
    ReservedBitsSet,
    /// The trailing 24-bit CRC-24Q did not match the one computed over the
    /// rest of the frame.
    ChecksumMismatch,
    /// A payload passed to the encoder exceeded the 1023-byte length
    /// RTCM3's 10-bit length field can represent.
    PayloadTooLong {
        /// Maximum representable payload length (always 1023).
        max: usize,
        /// Actual payload length given.
        got: usize,
    },
}

impl fmt::Display for FrameError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::TooShort { needed, got } => {
                write!(f, "frame needs {needed} bytes, buffer has {got}")
            }
            Self::UnknownPreamble(b) => write!(f, "unrecognized preamble byte: {b:#04x}"),
            Self::ReservedBitsSet => write!(f, "reserved bits before the length field were set"),
            Self::ChecksumMismatch => write!(f, "CRC-24Q checksum mismatch"),
            Self::PayloadTooLong { max, got } => {
                write!(f, "payload of {got} bytes exceeds the {max}-byte maximum")
            }
        }
    }
}

impl core::error::Error for FrameError {}

/// Errors from decoding/encoding a typed message from/to its payload.
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum MessageError {
    /// The 12-bit message type (DF002) didn't match any message this crate
    /// decodes.
    UnknownMessageType(u16),
    /// A bit-level read/write failed while decoding/encoding a message.
    Bit(BitError),
}

impl fmt::Display for MessageError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::UnknownMessageType(mt) => write!(f, "unknown/undecoded message type: {mt}"),
            Self::Bit(e) => write!(f, "{e}"),
        }
    }
}

impl core::error::Error for MessageError {}

impl From<BitError> for MessageError {
    fn from(e: BitError) -> Self {
        Self::Bit(e)
    }
}

/// Top-level error type composing every layer, for `?`-based error
/// propagation across the frame, bit, and message layers.
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Rtcm3Error {
    /// Error in the frame layer (preamble, length, CRC).
    Frame(FrameError),
    /// Error in the bit-level codec.
    Bit(BitError),
    /// Error in the message layer.
    Message(MessageError),
}

impl fmt::Display for Rtcm3Error {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Frame(e) => write!(f, "{e}"),
            Self::Bit(e) => write!(f, "{e}"),
            Self::Message(e) => write!(f, "{e}"),
        }
    }
}

impl core::error::Error for Rtcm3Error {}

impl From<FrameError> for Rtcm3Error {
    fn from(e: FrameError) -> Self {
        Self::Frame(e)
    }
}

impl From<BitError> for Rtcm3Error {
    fn from(e: BitError) -> Self {
        Self::Bit(e)
    }
}

impl From<MessageError> for Rtcm3Error {
    fn from(e: MessageError) -> Self {
        Self::Message(e)
    }
}