byte_chisel/

lib.rs

#![doc = include_str!("docs.md")]
#![warn(missing_docs)]
/* Copyright 2025 Fayti1703
 * Licensed under the EUPL 1.2-or-later.
 * If a copy of the EUPL was not distributed with this crate,
 * you may obtain one at <https://interoperable-europe.ec.europa.eu/collection/eupl/eupl-text-eupl-12>.
 */

#[cfg(all(feature = "alloc", not(feature = "std")))]
extern crate alloc;
#[cfg(all(feature = "alloc", not(feature = "std")))]
use alloc::vec::Vec;

#[cfg(feature = "std")]
use std::vec::Vec;

pub mod prelude {
/*! `byte-chisel` prelude
 *
 * This module contains reëxports for commonly used types in this crate, for easy importing:
 * ```
 * pub use byte_chisel::prelude::*;
 * ```
 */
	pub use super::{Chisel, ChiselSource, Endianness};
	pub use super::{ChiselError, ChiselErrorData, InfallibleFormatError};
	pub use super::{ChiselResult, InfallibleFormatResult};
	pub use super::{InfalliableFormatResultExt};
}

pub mod source;
pub use source::{ChiselSource, ChiselSourceError};

mod endian;
#[doc(inline)]
pub use endian::{ChiselLittleEndian, ChiselBigEndian};

mod error;
#[doc(inline)]
pub use error::{ChiselError, ChiselErrorData};

/**
 * An object providing structured access to an underlying byte-stream.
 *
 * A `Chisel` is an abstraction over some ["source"][ChiselSource] of bytes that allows reading
 * data in a structured manner.
 *
 * See the [crate documentation](self) for more information.
 */
pub struct Chisel<S> {
	offset: usize,
	source: S
}


/** The result type of attempting to chisel a `T` from a source `S`, with format errors described by `E`. */
/* Can't use bounds here (see rust::#112792) */
pub type ChiselResult<T, E, S> = Result<T, ChiselError<E, <S as ChiselSource>::Error>>;
/**
 * The error type of attempting to chisel a value from a source `S`; where all byte sequences produce valid values ("infallible format").
 *
 * Because the format is infallible, this never contains a [`ChiselErrorData::Format`].
 */
/* Can't use bounds here (see rust::#112792) */
pub type InfallibleFormatError<S> = ChiselError<core::convert::Infallible, <S as ChiselSource>::Error>;
/** The error type of attempting to chisel a `T` from a source `S`. All byte sequences produce valid `T`s ("infallible format"). */
pub type InfallibleFormatResult<T, S> = Result<T, InfallibleFormatError<S>>;

/**
 * Used to define byte order or "endianness".
 *
 * This is used to define the order in which the bytes of datatypes are read.
 */
#[derive(Debug, Copy, Clone, PartialEq, Eq)]
pub enum Endianness {
	/** The lowest-order byte is read first. Subsequent bytes are in ascending order. */
	Little,
	/** The highest-order byte is read first. Subsequent bytes are in descending order. */
	Big,
}

/**
 * Used to indicate why a [`read_until_or_end`][Chisel::read_until_or_end] operation stopped.
 */
#[derive(Debug, Copy, Clone, PartialEq, Eq)]
pub enum ReadUntilStopReason {
	/** The operation found the provided delimiter byte. */
	Delimiter,
	/** The operation encountered an end-of-input condition. */
	EndOfInput
}

macro_rules! decode_endian {
	($endian: ident, $value: ident, $little: path, $big: path) => {
		match $endian {
			Endianness::Little => $little($value),
			Endianness::Big => $big($value)
		}
	};
}

macro_rules! ty_fn {
	($ty: ident) => {
		#[doc =
concat!(r"Reads a single [`", stringify!($ty), r"`].

The provided `endian` specifies the byte order.

## Errors

If an error is returned, the chisel [breaks][self#breaking].
")]
		pub fn $ty(&mut self, endian: Endianness) -> InfallibleFormatResult<$ty, S> {
			let mut buf = [0u8; core::mem::size_of::<$ty>()];
			self.read_buf(&mut buf)?;
			Ok(decode_endian!(endian, buf, $ty::from_le_bytes, $ty::from_be_bytes))
		}
	};
}

impl<'a> Chisel<&'a [u8]> {
	/** Create a new `Chisel`, with its source being an array of bytes. */
	pub fn from_array(buf: &'a [u8]) -> Self { Self::new(buf) }
}

#[cfg(feature = "std")]
impl<'a, T : std::io::Read> Chisel<source::ChiselSourceRead<'a, T>> {
	/**
	 * Create a new `Chisel`, with its source being a `Read` implementation.
	 *
	 * Note that typical chiseling operations involve _a lot_ of individual calls to `read`.
	 * As such, it is recommended to instead use [`from_buf_read`][Chisel::from_buf_read]
	 * whenever possible.
	 *
	 * Only use this constructor in the rare circumstance in which it is absolutely necessary 
	 * to perform direct, unbuffered reads from an I/O source.
	 */
	pub fn from_read(read: &'a mut T) -> Self { Self::new(source::ChiselSourceRead(read)) }
}

#[cfg(feature = "std")]
impl<'a, T : std::io::BufRead> Chisel<source::ChiselSourceBufRead<'a, T>> {
	/** Create a new `Chisel`, with its source being a `BufRead` implementation. */
	pub fn from_buf_read(read: &'a mut T) -> Self { Self::new(source::ChiselSourceBufRead(read)) }
}

impl<S : ChiselSource> Chisel<S> {
	/** Creates a new [Chisel] from an arbitrary source. */
	pub fn new(source: S) -> Self {
		Self { offset: 0, source }
	}

	/** Returns the current byte offset of the Chisel. */
	pub fn offset(&self) -> usize { self.offset }

	/**
	 * Returns a format error that occurred `backstep` bytes ago.
	 *
	 * This is a convenience method for manually determining the appropriate byte offset and calling [ChiselError::format].
	 */
	pub fn error<E>(&self, err: E, backstep: usize) -> ChiselError<E, S::Error> { ChiselError::format(self.offset - backstep, err) }

	/** Returns an [`Endianness::Little`]-wrapper around this chisel. The wrapper reads values in the little-endian byte order. */
	#[inline]
	pub fn little_endian(&mut self) -> ChiselLittleEndian<S> { ChiselLittleEndian(self) }
	/** Returns an [`Endianness::Big`]-wrapper around this chisel. The wrapper reads values in the big-endian byte order. */
	#[inline]
	pub fn big_endian(&mut self) -> ChiselBigEndian<S> { ChiselBigEndian(self) }

	/**
	 * Fills a provided buffer with bytes from the source.
	 *
	 * ## Errors
	 * This function returns an [`ChiselErrorData::EndOfInput`] if the end of the input is encountered
	 * before the buffer is completely filled.
	 *
	 * If an error is returned, the contents of `buf` are unspecified and the chisel [breaks][self#breaking].
	 */
	pub fn read_buf(&mut self, buf: &mut [u8]) -> InfallibleFormatResult<(), S> {
		match self.source.read_exact(buf) {
			Ok(()) => {
				self.offset += buf.len();
				Ok(())
			},
			Err(x) => Err(ChiselError::from_source(self.offset, x)),
		}
	}

	/**
	 * Reads a single byte [`u8`].
	 *
	 * As this function only reads a single byte, no endianness is required.
	 */
	pub fn u8(&mut self) -> InfallibleFormatResult<u8, S> {
		let mut buf = [0u8; 1];
		self.read_buf(&mut buf)?;
		Ok(buf[0])
	}
	ty_fn!(u16);
	ty_fn!(u32);
	ty_fn!(u64);

	/**
	* Reads a single _signed_ byte [`i8`].
	*
	* As this function only reads a single byte, no endianness is required.
	*/
	pub fn i8(&mut self) -> InfallibleFormatResult<i8, S> {
		let mut buf = [0u8; 1];
		self.read_buf(&mut buf)?;
		Ok(buf[0] as i8)
	}
	ty_fn!(i16);
	ty_fn!(i32);
	ty_fn!(i64);

	ty_fn!(f32);
	ty_fn!(f64);

	/**
	 * Skips `how_many` bytes of the underlying source.
	 *
	 * This is provided for optimization reasons. This hint is forwarded to the source.
	 *
	 * Exactly `how_many` bytes are skipped, as-if [`read_buf`][Self::read_buf] were called with a buffer
	 * of appropriate size, with the buffer being discarded.
	 *
	 * ## Errors
	 *
	 * If an end-of-input condition occurs before `how_many` bytes are skipped, an [`ChiselErrorData::EndOfInput`] error is returned.
	 *
	 * If an error is returned, the chisel [breaks][self#breaking].
	 */
	pub fn skip(&mut self, how_many: usize) -> InfallibleFormatResult<(), S> {
		match self.source.skip(how_many) {
			Ok(()) => {
				self.offset += how_many;
				Ok(())
			},
			Err(x) => Err(ChiselError::from_source(self.offset, x))
		}
	}

	#[cfg(feature = "alloc")]
	/**
	 * Reads bytes into the provided `dest` Vec until the `delimiter` byte is encountered.
	 *
	 * ## Errors
	 * If the end of the input is encountered before the delimiter is found, [`ChiselErrorData::EndOfInput`] is returned.
	 *
	 * If an error is returned, the chisel [breaks][self#breaking].
	 */
	pub fn read_until(&mut self, delimiter: u8, dest: &mut Vec<u8>) -> InfallibleFormatResult<(), S> {
		let offset = self.offset; /* backup offset before we advance it in case of EOF */
		match self.read_until_or_end(delimiter, dest) {
			Ok(x) => match x {
				ReadUntilStopReason::EndOfInput => Err(ChiselError::end_of_input(offset)),
				ReadUntilStopReason::Delimiter => Ok(())
			}
			Err(x) => Err(x)
		}
	}


	#[cfg(feature = "alloc")]
	/**
	* Reads bytes into the provided `dest` Vec until the `delimiter` byte or end-of-input is encountered.
	*
	* ## Errors
	* If an error is returned, the chisel [breaks][self#breaking].
	*/
	pub fn read_until_or_end(&mut self, delimiter: u8, dest: &mut Vec<u8>) -> InfallibleFormatResult<ReadUntilStopReason, S> {
		match self.source.read_until(delimiter, dest) {
			Ok(x) => {
				self.offset += match x {
					ReadUntilStopReason::EndOfInput => dest.len(),
					ReadUntilStopReason::Delimiter => dest.len() + 1
				};
				Ok(x)
			}
			Err(x) => Err(ChiselError::source(self.offset, x))
		}
	}
}

/** Extension trait for `InfallibleFormatResult`. */
pub trait InfalliableFormatResultExt<T, S> {
	/**
	 * Converts an [`InfallibleFormatResult`] into an arbitrary-format [`ChiselResult`].
	 *
	 * This is basically a small hack to allow easy error propagation,
	 * as `ChiselError<F, S>` cannot implement `From<ChiselError<Infallible, S>>`.
	 */
	fn forward<F>(self) -> Result<T, ChiselError<F, S>>;
}

impl<T, S> InfalliableFormatResultExt<T, S> for Result<T, ChiselError<core::convert::Infallible, S>> {
	fn forward<F>(self) -> Result<T, ChiselError<F, S>> {
		self.map_err(|x| x.forward())
	}
}