n3_lib/

binary.rs

//! Bounded little-endian binary primitives.

use std::fmt;

/// A malformed record or an invalid edited value, with its byte offset.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Error {
    /// Byte position where the failure was detected.
    pub offset: usize,
    /// Human-readable field or validation context.
    pub message: String,
}

impl fmt::Display for Error {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(formatter, "{} at byte {}", self.message, self.offset)
    }
}
impl std::error::Error for Error {}

/// Result returned by bounded parsing and writing operations.
pub type Result<T> = std::result::Result<T, Error>;

/// Sequential reader borrowing a byte slice.
pub struct Reader<'a> {
    bytes: &'a [u8],
    /// Current byte offset.
    pub offset: usize,
}

impl<'a> Reader<'a> {
    /// Borrow input without copying or mutating it.
    pub fn new(bytes: &'a [u8]) -> Self {
        Self { bytes, offset: 0 }
    }
    /// Unconsumed byte count.
    pub fn remaining(&self) -> usize {
        self.bytes.len() - self.offset
    }
    /// Read a bounded range, returning an error rather than panicking.
    pub fn raw(&mut self, size: usize) -> Result<&'a [u8]> {
        if size > self.remaining() {
            return self.fail("Truncated record");
        }
        let start = self.offset;
        self.offset += size;
        Ok(&self.bytes[start..self.offset])
    }
    /// Construct a diagnostic at the current position.
    pub fn fail<T>(&self, message: impl Into<String>) -> Result<T> {
        Err(Error {
            offset: self.offset,
            message: message.into(),
        })
    }
    /// Read an unsigned byte.
    pub fn u8(&mut self) -> Result<u8> {
        Ok(self.raw(1)?[0])
    }
    /// Read a signed byte.
    pub fn i8(&mut self) -> Result<i8> {
        Ok(self.u8()? as i8)
    }
    /// Read an unsigned 16-bit word.
    pub fn u16(&mut self) -> Result<u16> {
        let bytes = self.raw(2)?;
        Ok(u16::from_le_bytes([bytes[0], bytes[1]]))
    }
    /// Read a signed 16-bit word.
    pub fn i16(&mut self) -> Result<i16> {
        Ok(self.u16()? as i16)
    }
    /// Read an unsigned word, also usable for exact f32 storage bits.
    pub fn u32(&mut self) -> Result<u32> {
        let bytes = self.raw(4)?;
        Ok(u32::from_le_bytes([bytes[0], bytes[1], bytes[2], bytes[3]]))
    }
    /// Read a signed 32-bit word.
    pub fn i32(&mut self) -> Result<i32> {
        Ok(self.u32()? as i32)
    }
    /// Read an IEEE-754 single-precision value.
    pub fn f32(&mut self) -> Result<f32> {
        Ok(f32::from_bits(self.u32()?))
    }
    /// Read a nonnegative count bounded by both policy and available storage.
    pub fn count(&mut self, maximum: usize, stride: usize) -> Result<usize> {
        let value = self.i32()?;
        if value < 0 {
            return self.fail("Negative count");
        }
        let count = value as usize;
        if count > maximum
            || count
                .checked_mul(stride)
                .is_none_or(|size| size > self.remaining())
        {
            return self.fail("Invalid count or truncated array");
        }
        Ok(count)
    }
    /// Read an original length-prefixed byte string.
    pub fn string(&mut self, maximum: usize) -> Result<Vec<u8>> {
        let size = self.count(maximum, 1)?;
        Ok(self.raw(size)?.to_vec())
    }
    /// Require exact record consumption.
    pub fn end(&self) -> Result<()> {
        if self.remaining() == 0 {
            Ok(())
        } else {
            self.fail("Trailing bytes")
        }
    }
}

/// Output builder with a byte budget; integer ranges are enforced by Rust types.
pub struct Writer {
    bytes: Vec<u8>,
    maximum: usize,
}

impl Default for Writer {
    fn default() -> Self {
        Self::new(256 * 1024 * 1024)
    }
}

impl Writer {
    /// Construct a writer with a maximum encoded length.
    pub fn new(maximum: usize) -> Self {
        Self {
            bytes: Vec::new(),
            maximum,
        }
    }
    /// Append bytes without exceeding the configured budget.
    pub fn raw(&mut self, bytes: &[u8]) -> Result<()> {
        if bytes.len() > self.maximum.saturating_sub(self.bytes.len()) {
            return Err(Error {
                offset: self.bytes.len(),
                message: "Output byte budget exceeded".into(),
            });
        }
        self.bytes.try_reserve(bytes.len()).map_err(|_| Error {
            offset: self.bytes.len(),
            message: "Allocation failed".into(),
        })?;
        self.bytes.extend_from_slice(bytes);
        Ok(())
    }
    /// Write an unsigned byte.
    pub fn u8(&mut self, value: u8) -> Result<()> {
        self.raw(&[value])
    }
    /// Write a signed byte.
    pub fn i8(&mut self, value: i8) -> Result<()> {
        self.u8(value as u8)
    }
    /// Write an unsigned 16-bit word.
    pub fn u16(&mut self, value: u16) -> Result<()> {
        self.raw(&value.to_le_bytes())
    }
    /// Write a signed 16-bit word.
    pub fn i16(&mut self, value: i16) -> Result<()> {
        self.raw(&value.to_le_bytes())
    }
    /// Write an unsigned word or original f32 bits.
    pub fn u32(&mut self, value: u32) -> Result<()> {
        self.raw(&value.to_le_bytes())
    }
    /// Write a signed 32-bit word.
    pub fn i32(&mut self, value: i32) -> Result<()> {
        self.raw(&value.to_le_bytes())
    }
    /// Write an IEEE-754 single-precision value.
    pub fn f32(&mut self, value: f32) -> Result<()> {
        self.u32(value.to_bits())
    }
    /// Write a length-prefixed original or newly encoded string.
    pub fn string(&mut self, bytes: &[u8]) -> Result<()> {
        let length = i32::try_from(bytes.len()).map_err(|_| Error {
            offset: self.bytes.len(),
            message: "String too long".into(),
        })?;
        self.i32(length)?;
        self.raw(bytes)
    }
    /// Consume the writer and return its bytes.
    pub fn finish(self) -> Vec<u8> {
        self.bytes
    }
}

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

    #[test]
    fn bit_exact_and_bounded() -> Result<()> {
        let mut writer = Writer::default();
        writer.i32(-17)?;
        writer.u32(0x7fa12345)?;
        writer.string(&[0, 255, 128])?;
        let bytes = writer.finish();
        let mut reader = Reader::new(&bytes);
        assert_eq!(reader.i32()?, -17);
        assert_eq!(reader.u32()?, 0x7fa12345);
        assert_eq!(reader.string(100)?, [0, 255, 128]);
        reader.end()?;
        assert!(reader.u8().is_err());
        assert!(Reader::new(&[255; 4]).count(100, 1).is_err());
        assert!(Writer::new(2).u32(1).is_err());
        Ok(())
    }
}