slicur 0.3.0

#![doc = include_str!("../README.md")]
#![no_std]
#![allow(clippy::must_use_candidate)]

use core::num::NonZeroUsize;
use core::{fmt, slice};

pub mod error;

pub use self::error::Error;

/// Wrapper over a slice of bytes that allows reading chunks from
/// with the current position state held using a cursor.
///
/// A new reader for a sub section of the buffer can be created
/// using the `sub` function or a section of a certain length can
/// be obtained using the `read` function
pub struct Reader<'a> {
    /// The underlying buffer storing the readers content
    buffer: &'a [u8],

    /// Stores the current reading position for the buffer
    cursor: usize,
}

#[cfg(not(feature = "feat-debug-buffer"))]
impl fmt::Debug for Reader<'_> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Reader")
            .field("buffer", &"[..]")
            .field("cursor", &self.cursor)
            .finish()
    }
}

#[cfg(feature = "feat-debug-buffer")]
impl fmt::Debug for Reader<'_> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Reader")
            .field("buffer", &const_hex::encode(self.buffer))
            .field("cursor", &self.cursor)
            .finish()
    }
}

macro_rules! advance_cursor_and {
    ($this:expr, $length:expr, $($tt:tt)+) => {{
        let Some(cursor) = $this.cursor.checked_add($length) else {
            return Err(Error::Overflow);
        };

        match cursor.checked_sub($this.buffer.len()) {
            Some(0) | None => {}
            Some(insufficient) => {
                // SAFETY: insufficient is guaranteed to be non-zero here.
                return Err(Error::InsufficientData {
                    missing: unsafe { NonZeroUsize::new_unchecked(insufficient) },
                });
            }
        }

        match $($tt)+ {
            ret @ Ok(_) => {
                $this.cursor = cursor;

                ret
            }
            ret @ Err(_) => ret,
        }
    }};
}

impl<'a> Reader<'a> {
    #[inline]
    /// Creates a new [`Reader`] of the provided `bytes` slice with
    /// the initial cursor position of zero.
    ///
    /// Note that the provided slice must be network byte order (big-endian).
    pub const fn init(bytes: &'a [u8]) -> Self {
        Reader {
            buffer: bytes,
            cursor: 0,
        }
    }

    #[inline]
    /// Returns the cursor position, i.e., the number of bytes that have
    /// been read from the buffer.
    pub const fn used(&self) -> usize {
        self.cursor
    }

    #[inline]
    #[track_caller]
    /// Returns the unread bytes length.
    pub const fn left(&self) -> usize {
        let Some(left) = self
            .buffer
            .len()
            .checked_sub(self.cursor)
        else {
            // This should never happen
            unreachable!()
        };

        left
    }

    #[inline]
    #[track_caller]
    /// Returns all unread bytes of the reader without advancing the cursor.
    pub const fn unread(&self) -> &'a [u8] {
        unsafe {
            // SAFETY: The cursor is guaranteed to be within the bounds of the buffer
            slice::from_raw_parts(self.buffer.as_ptr().add(self.cursor), self.left())
        }
    }

    #[inline]
    /// Reads a slice of `length` bytes from the reader and returns it.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use slicur::Reader;
    /// let mut reader = Reader::init(&[0x12, 0x34, 0x56, 0x78]);
    /// // Read 2 bytes
    /// let bytes = reader.read(2).unwrap();
    /// assert_eq!(bytes, &[0x12, 0x34]);
    /// # assert!(reader.used() == 2);
    /// # assert!(reader.left() == 2);
    /// // Read another 2 bytes
    /// let bytes = reader.read(2).unwrap();
    /// assert_eq!(bytes, &[0x56, 0x78]);
    /// # assert!(reader.used() == 4);
    /// # assert!(reader.left() == 0);
    /// # assert!(reader.read(1).is_err());
    /// // Try to read more bytes than available.
    /// let mut reader = Reader::init(&[0x12, 0x34, 0x56, 0x78]);
    /// assert!(matches!(
    ///     reader.read(5),
    ///     Err(slicur::Error::InsufficientData { missing }) if missing.get() == 1
    /// ));
    /// # assert!(reader.used() == 0);
    /// # assert!(reader.left() == 4);
    /// ```
    ///
    /// # Errors
    ///
    /// [`Error`].
    pub const fn read(&mut self, length: usize) -> Result<&'a [u8], Error> {
        advance_cursor_and!(
            self,
            length,
            Ok(unsafe { slice::from_raw_parts(self.buffer.as_ptr().add(self.cursor), length) })
        )
    }

    #[inline]
    /// Reads an array of `N` bytes from the reader and returns it.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use slicur::Reader;
    /// let mut reader = Reader::init(&[0x12, 0x34, 0x56, 0x78]);
    /// // Read 2 bytes
    /// let bytes = reader.read_array::<2>().unwrap();
    /// assert_eq!(bytes, &[0x12, 0x34]);
    /// # assert!(reader.used() == 2);
    /// # assert!(reader.left() == 2);
    /// // Try to read more bytes than available.
    /// assert!(matches!(
    ///     reader.read_array::<3>(),
    ///     Err(slicur::Error::InsufficientData { missing }) if missing.get() == 1
    /// ));
    /// # assert!(reader.used() == 2);
    /// # assert!(reader.left() == 2);
    /// ```
    ///
    /// # Errors
    ///
    /// [`Error`].
    pub const fn read_array<const N: usize>(&mut self) -> Result<&'a [u8; N], Error> {
        advance_cursor_and!(
            self,
            N,
            Ok(unsafe {
                &*(slice::from_raw_parts(self.buffer.as_ptr().add(self.cursor), N)
                    .as_ptr()
                    .cast::<[u8; N]>())
            })
        )
    }

    #[inline]
    /// Reads all unread bytes from the reader.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use slicur::Reader;
    /// let mut reader = Reader::init(&[0x12, 0x34, 0x56, 0x78]);
    /// // Read 2 bytes
    /// let bytes = reader.read(2).unwrap();
    /// assert_eq!(bytes, &[0x12, 0x34]);
    /// # assert!(reader.used() == 2);
    /// # assert!(reader.left() == 2);
    /// // Read all remaining bytes
    /// let bytes = reader.read_all();
    /// assert_eq!(bytes, &[0x56, 0x78]);
    /// # assert!(reader.used() == 4);
    /// # assert!(reader.left() == 0);
    /// # assert!(reader.read(1).is_err());
    /// # assert!(reader.read_all().is_empty());
    /// ```
    pub const fn read_all(&mut self) -> &'a [u8] {
        let (_, unread) = self.buffer.split_at(self.cursor);
        self.cursor = self.buffer.len();
        unread
    }

    #[inline]
    /// Reads a single byte from the reader and returns it.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use slicur::Reader;
    /// let mut reader = Reader::init(&[0x12, 0x34, 0x56]);
    /// assert_eq!(reader.read_u8().unwrap(), 0x12);
    /// assert_eq!(reader.read_u8().unwrap(), 0x34);
    /// assert_eq!(reader.read_u8().unwrap(), 0x56);
    /// ```
    ///
    /// # Errors
    ///
    /// [`Error`].
    pub fn read_u8(&mut self) -> Result<u8, Error> {
        match self.read_array() {
            Ok(&[b0]) => Ok(b0),
            Err(e) => Err(e),
        }
    }

    #[inline]
    /// Reads a u16 from the reader and returns it.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use slicur::Reader;
    /// let mut reader = Reader::init(&[0x12, 0x34, 0x56, 0x78, 0x89]);
    /// assert_eq!(reader.read_u16().unwrap(), 0x1234);
    /// assert_eq!(reader.read_u16().unwrap(), 0x5678);
    /// ```
    ///
    /// # Errors
    ///
    /// [`Error`].
    pub fn read_u16(&mut self) -> Result<u16, Error> {
        match self.read_array() {
            Ok(&b) => Ok(u16::from_be_bytes(b)),
            Err(e) => Err(e),
        }
    }

    #[inline]
    /// Reads a u24 from the reader and returns it.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use slicur::Reader;
    /// let mut reader = Reader::init(&[0x12, 0x34, 0x56, 0x78, 0x9A, 0xBC, 0xCD]);
    /// assert_eq!(reader.read_u24().unwrap(), 0x123456);
    /// assert_eq!(reader.read_u24().unwrap(), 0x789ABC);
    /// ```
    ///
    /// # Errors
    ///
    /// [`Error`].
    pub fn read_u24(&mut self) -> Result<u32, Error> {
        match self.read_array() {
            Ok(&[b0, b1, b2]) => Ok(u32::from_be_bytes([0, b0, b1, b2])),
            Err(e) => Err(e),
        }
    }

    #[inline]
    /// Reads a u32 from the reader and returns it.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use slicur::Reader;
    /// let mut reader = Reader::init(&[0x12, 0x34, 0x56, 0x78, 0x9A, 0xBC, 0xDE, 0xF0, 0x11]);
    /// assert_eq!(reader.read_u32().unwrap(), 0x12345678);
    /// assert_eq!(reader.read_u32().unwrap(), 0x9ABCDEF0);
    /// ```
    ///
    /// # Errors
    ///
    /// [`Error`].
    pub fn read_u32(&mut self) -> Result<u32, Error> {
        match self.read_array() {
            Ok(&b) => Ok(u32::from_be_bytes(b)),
            Err(e) => Err(e),
        }
    }

    #[inline]
    /// Reads a u64 from the reader and returns it.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use slicur::Reader;
    /// let mut reader = Reader::init(&[0x12, 0x34, 0x56, 0x78, 0x9A, 0xBC, 0xDE, 0xF0, 0x11]);
    /// assert_eq!(reader.read_u64().unwrap(), 0x123456789ABCDEF0);
    /// ```
    ///
    /// # Errors
    ///
    /// [`Error`].
    pub fn read_u64(&mut self) -> Result<u64, Error> {
        match self.read_array() {
            Ok(&b) => Ok(u64::from_be_bytes(b)),
            Err(e) => Err(e),
        }
    }

    #[inline]
    /// Reads a u128 from the reader and returns it.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use slicur::Reader;
    /// let mut reader = Reader::init(&[
    ///     0x12, 0x34, 0x56, 0x78, 0x9A, 0xBC, 0xDE, 0xF0, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77,
    ///     0x88, 0x99,
    /// ]);
    /// assert_eq!(
    ///     reader.read_u128().unwrap(),
    ///     0x123456789ABCDEF01122334455667788
    /// );
    /// ```
    ///
    /// # Errors
    ///
    /// [`Error`].
    pub fn read_u128(&mut self) -> Result<u128, Error> {
        match self.read_array() {
            Ok(&b) => Ok(u128::from_be_bytes(b)),
            Err(e) => Err(e),
        }
    }

    #[inline]
    /// Reads a slice of `length` bytes from the reader and creates a new
    /// [`Reader`] over it, i.e., `self.read(length).map(Reader::init)`.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use slicur::Reader;
    /// let mut reader = Reader::init(&[0x12, 0x34, 0x56, 0x78, 0x9A]);
    /// let mut sub_reader = reader.sub(3).unwrap();
    /// assert_eq!(sub_reader.read_u8().unwrap(), 0x12);
    /// assert_eq!(sub_reader.read_u16().unwrap(), 0x3456);
    /// # assert!(sub_reader.read_u8().is_err());
    /// # assert_eq!(reader.used(), 3);
    /// # assert_eq!(reader.left(), 2);
    /// # assert_eq!(sub_reader.used(), 3);
    /// # assert_eq!(sub_reader.left(), 0);
    /// # assert!(reader.sub(3).is_err());
    /// # assert_eq!(reader.used(), 3);
    /// # assert_eq!(reader.left(), 2);
    /// ```
    ///
    /// # Errors
    ///
    /// [`Error`].
    pub const fn sub(&mut self, length: usize) -> Result<Self, Error> {
        match self.read(length) {
            Ok(bytes) => Ok(Reader::init(bytes)),
            Err(e) => Err(e),
        }
    }

    #[inline]
    /// Advances the cursor by the specified `length` without returning
    /// any data.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use slicur::Reader;
    /// let mut reader = Reader::init(&[0x12, 0x34, 0x56, 0x78]);
    /// assert!(reader.advance(2).is_ok());
    /// # assert_eq!(reader.used(), 2);
    /// # assert_eq!(reader.left(), 2);
    /// assert!(reader.advance(3).is_err());
    /// # assert_eq!(reader.used(), 2);
    /// # assert_eq!(reader.left(), 2);
    /// ```
    ///
    /// # Errors
    ///
    /// [`Error`].
    pub const fn advance(&mut self, length: usize) -> Result<(), Error> {
        advance_cursor_and!(self, length, Ok(()))
    }
}