fashex/

lib.rs

#![doc = include_str!("../README.md")]
#![no_std]
#![cfg_attr(coverage_nightly, feature(coverage_attribute))]
#![cfg_attr(docsrs, feature(doc_cfg))]
#![cfg_attr(
    all(feature = "nightly", feature = "portable-simd"),
    feature(portable_simd)
)]
#![cfg_attr(
    all(
        feature = "nightly",
        feature = "experimental-loongarch-simd",
        any(target_arch = "loongarch32", target_arch = "loongarch64")
    ),
    feature(stdarch_loongarch)
)]

#[cfg(any(test, feature = "alloc"))]
extern crate alloc;

#[cfg(any(test, feature = "std"))]
extern crate std;

mod backend;
#[cfg_attr(not(docsrs), doc(hidden))]
pub mod buffer;
mod display;
mod error;
#[cfg(feature = "__internal_fuzz")]
pub mod fuzz;
mod traits;
mod util;

use core::mem::MaybeUninit;
use core::{slice, str};

pub use self::display::Display;
pub use self::error::InvalidInput;
pub use self::traits::Hex;
pub use self::util::{HEX_CHARS_LOWER, HEX_CHARS_UPPER};
use crate::buffer::MaybeUninitBuf;

/// Encodes `src` as a hexadecimal string into `dst` and returns a reference
/// to the written string.
///
/// ```rust
/// let decoded = b"Hello, world!";
///
/// let mut encoded = Vec::with_capacity(decoded.len() * 2);
///
/// assert_eq!(
///     fashex::encode::<false>(decoded, &mut encoded)
///         .expect("pre-allocated capacity is sufficient"),
///     "48656c6c6f2c20776f726c6421"
/// );
/// # assert_eq!(&*encoded, b"48656c6c6f2c20776f726c6421");
///
/// let mut encoded = Vec::with_capacity(decoded.len() * 2);
/// assert_eq!(
///     fashex::encode::<true>(decoded, &mut encoded)
///         .expect("pre-allocated capacity is sufficient"),
///     "48656C6C6F2C20776F726C6421"
/// );
/// # assert_eq!(&*encoded, b"48656C6C6F2C20776F726C6421");
/// ```
///
/// If you like, `&mut [MaybeUninit<u8>]` can also be used as the output buffer:
///
/// ```rust
/// use core::mem::MaybeUninit;
///
/// const CASE: &[u8; 13] = b"Hello, world!";
///
/// let mut encoded = [MaybeUninit::uninit(); CASE.len() * 2 + 1];
///
/// assert_eq!(
///     fashex::encode::<false>(CASE, &mut encoded)
///         .expect("the len of the uninitialized buffer is sufficient"),
///     "48656c6c6f2c20776f726c6421"
/// );
///
/// assert_eq!(
///     unsafe { &*(&raw const encoded[..CASE.len() * 2] as *const [u8] as *const str) },
///     "48656c6c6f2c20776f726c6421"
/// );
/// ```
///
/// ## Errors
///
/// 1. The len (spare capacity) of the output buffer is insufficient.
pub fn encode<const UPPER: bool>(
    src: impl AsRef<[u8]>,
    dst: &mut (impl MaybeUninitBuf + ?Sized),
) -> Result<&str, InvalidInput> {
    let src = src.as_ref();

    {
        let Some(dst) = dst.uninitialized_mut().get_mut(..2 * src.len()) else {
            return Err(InvalidInput);
        };

        #[allow(unsafe_code, reason = "The length of `dst` must be even.")]
        let dst = unsafe { dst.as_chunks_unchecked_mut() };

        #[allow(
            unsafe_code,
            reason = "The length of the input and the output buffer has been validated."
        )]
        unsafe {
            crate::backend::encode_unchecked::<UPPER>(src, dst);
        }
    }

    #[allow(
        unsafe_code,
        reason = "`src.len() * 2` bytes in `dst` have been initialized."
    )]
    let bytes = unsafe { dst.advance(2 * src.len()) };

    #[allow(
        unsafe_code,
        reason = "Hexadecimal characters must be valid UTF-8 bytes."
    )]
    unsafe {
        Ok(str::from_utf8_unchecked(bytes))
    }
}

#[cfg(feature = "__internal_cargo_asm")]
#[cfg_attr(coverage_nightly, coverage(off))]
#[doc(hidden)]
pub fn __cargo_asm_encode<'dst>(
    src: &[u8],
    dst: &'dst mut [MaybeUninit<u8>],
) -> Result<&'dst str, InvalidInput> {
    encode::<false>(src, dst)
}

/// Decodes `src` (a hexadecimal string, case insensitive) into raw bytes,
/// writes them into `dst`, and returns a reference to the written bytes.
///
/// ```rust
/// let encoded = b"48656c6c6f2c20776f726c6421";
///
/// let mut decoded = Vec::with_capacity(encoded.len() / 2);
///
/// assert_eq!(
///     fashex::decode(encoded, &mut decoded)
///         .expect("the input is valid hex and the spare capacity of the buffer is sufficient"),
///     b"Hello, world!"
/// );
/// # assert_eq!(&*decoded, b"Hello, world!");
/// ```
///
/// If you like, `&mut [MaybeUninit<u8>]` can also be used as the output buffer:
///
/// ```rust
/// use core::mem::MaybeUninit;
///
/// const CASE: &[u8; 26] = b"48656c6c6f2c20776f726c6421";
///
/// let mut decoded = [MaybeUninit::uninit(); CASE.len() / 2 + 1];
///
/// assert_eq!(
///     fashex::decode(CASE, &mut decoded)
///         .expect("the input is valid hex and the len of the uninitialized buffer is sufficient"),
///     b"Hello, world!"
/// );
///
/// assert_eq!(
///     unsafe { &*(&raw const decoded[..CASE.len() / 2] as *const [u8]) },
///     b"Hello, world!"
/// );
/// ```
///
/// ## Errors
///
/// 1. The input contains invalid characters.
/// 1. The input has an odd length.
/// 1. The len (spare capacity) of the output buffer is insufficient.
pub fn decode(
    src: impl AsRef<[u8]>,
    dst: &mut (impl MaybeUninitBuf + ?Sized),
) -> Result<&[u8], InvalidInput> {
    const EVEN: usize = 2;

    let src = src.as_ref();

    if !src.len().is_multiple_of(EVEN) {
        // Cannot have odd nibbles.
        return Err(InvalidInput);
    }

    #[allow(unsafe_code, reason = "XXX")]
    // SAFETY: the length of the input has been validated to be even.
    let src = unsafe { src.as_chunks_unchecked::<EVEN>() };

    let dst_uninitialized_mut = dst.uninitialized_mut();

    if src.len() > dst_uninitialized_mut.len() {
        // The nibble pairs cannot fit in the output buffer.
        return Err(InvalidInput);
    }

    #[allow(unsafe_code, reason = "XXX")]
    unsafe {
        // SAFETY: the length of the input and the output buffer has been validated.
        match crate::backend::decode_unchecked::<false>(src, dst_uninitialized_mut) {
            Ok(()) => Ok(dst.advance(src.len())),
            Err(e) => Err(e),
        }
    }
}

#[cfg(feature = "__internal_cargo_asm")]
#[cfg_attr(coverage_nightly, coverage(off))]
#[doc(hidden)]
pub fn __cargo_asm_decode<'dst>(
    src: &[u8],
    dst: &'dst mut [MaybeUninit<u8>],
) -> Result<&'dst [u8], InvalidInput> {
    decode(src, dst)
}

/// [`encode()`], but const-evaluable at the cost of performance.
///
/// The [`encode!`] macro wraps this function and is the preferred way to call
/// it in const contexts, such as when initializing a `const` or `static`
/// variable.
///
/// ## Errors
///
/// 1. The len of the output buffer is insufficient.
pub const fn encode_generic<'dst, const UPPER: bool>(
    src: &[u8],
    dst: &'dst mut [MaybeUninit<u8>],
) -> Result<&'dst str, InvalidInput> {
    let (dst, _) = dst.as_chunks_mut::<2>();

    if src.len() > dst.len() {
        return Err(InvalidInput);
    }

    #[allow(unsafe_code, reason = "The length is validated")]
    unsafe {
        crate::backend::generic::encode_generic_unchecked::<UPPER>(src, dst);
    };

    #[allow(
        unsafe_code,
        reason = "`src.len() * 2` bytes in `dst` have been initialized."
    )]
    let bytes = unsafe { slice::from_raw_parts(dst.as_ptr().cast(), src.len().unchecked_mul(2)) };

    #[allow(
        unsafe_code,
        reason = "Hexadecimal characters must be valid UTF-8 bytes."
    )]
    unsafe {
        Ok(str::from_utf8_unchecked(bytes))
    }
}

/// [`decode()`], but const-evaluable at the cost of performance.
///
/// The [`decode!`] macro wraps this function and is the preferred way to call
/// it in const contexts, such as when initializing a `const` or `static`
/// variable.
///
/// ## Errors
///
/// 1. The input contains invalid characters.
/// 1. The input contains an odd number of nibbles.
/// 1. The len of the output buffer is insufficient.
pub const fn decode_generic<'dst>(
    src: &[u8],
    dst: &'dst mut [MaybeUninit<u8>],
) -> Result<&'dst [u8], InvalidInput> {
    const EVEN: usize = 2;

    if !src.len().is_multiple_of(EVEN) {
        // Cannot have odd nibbles.
        return Err(InvalidInput);
    }

    #[allow(unsafe_code, reason = "XXX")]
    // SAFETY: the length of the input has been validated to be even.
    let src = unsafe { src.as_chunks_unchecked::<EVEN>() };

    if src.len() > dst.len() {
        // The nibble pairs cannot fit in the output buffer.
        return Err(InvalidInput);
    }

    #[allow(unsafe_code, reason = "The length is validated")]
    unsafe {
        match crate::backend::generic::decode_generic_unchecked::<false>(src, dst) {
            Ok(()) => Ok(slice::from_raw_parts(dst.as_ptr().cast(), src.len())),
            Err(e) => Err(e),
        }
    }
}

#[macro_export]
/// Helper macro for encoding byte arrays as hexadecimal strings in const
/// contexts.
///
/// ## Examples
///
/// ```rust
/// const HELLO_WORLD_LOWERCASE: &str = fashex::encode!(b"Hello, world!");
/// assert_eq!(HELLO_WORLD_LOWERCASE, "48656c6c6f2c20776f726c6421");
/// const HELLO_WORLD_UPPERCASE: &str = fashex::encode!(b"Hello, world!", true);
/// assert_eq!(HELLO_WORLD_UPPERCASE, "48656C6C6F2C20776F726C6421");
/// # const HELLO_WORLD_STR: &str = fashex::encode!("Hello, world!");
/// # assert_eq!(HELLO_WORLD_STR, "48656c6c6f2c20776f726c6421");
/// # const FROM_BYTES_LOWERCASE: &str = fashex::encode!([0x12, 0x34, 0xab, 0xcd]);
/// # assert_eq!(FROM_BYTES_LOWERCASE, "1234abcd");
/// ```
macro_rules! encode {
    ($bytes:expr) => {
        $crate::encode!($bytes, false)
    };
    ($bytes:expr, $uppercase:expr) => {{
        const ENCODED: [u8; $bytes.len() * 2] = {
            let buf: &mut [::core::mem::MaybeUninit<u8>; const { $bytes.len() * 2 }] =
                &mut [::core::mem::MaybeUninit::uninit(); _];

            #[allow(unsafe_code, reason = "XXX")]
            let bytes = unsafe { ::core::slice::from_raw_parts($bytes.as_ptr(), $bytes.len()) };

            match $crate::encode_generic::<{ $uppercase }>(bytes, buf) {
                Ok(_) => {}
                Err(_) => unreachable!(),
            };

            #[allow(unsafe_code, reason = "XXX")]
            unsafe {
                ::core::mem::transmute::<_, _>(*buf)
            }
        };

        #[allow(unsafe_code, reason = "XXX")]
        unsafe {
            ::core::str::from_utf8_unchecked(&ENCODED)
        }
    }};
}

#[macro_export]
/// Helper macro for decoding hexadecimal strings to byte arrays in const
/// contexts.
///
/// ## Examples
///
/// ```rust
/// const FOOBAR: &[u8] = fashex::decode!("48656c6c6f2c20776f726c6421");
/// assert_eq!(FOOBAR, b"Hello, world!");
/// # const FOOBAR_ARRAY: &[u8; 13] = fashex::decode!("48656c6c6f2c20776f726c6421");
/// # assert_eq!(FOOBAR_ARRAY, b"Hello, world!");
/// # const FOOBAR_RIG: &[u8; 13] = fashex::decode!("48656c6c6f2C20776F726c6421");
/// # assert_eq!(FOOBAR_RIG, b"Hello, world!");
/// ```
macro_rules! decode {
    ($bytes:expr) => {{
        const DECODED: [u8; $bytes.len() / 2] = {
            assert!(
                $bytes.len() % 2 == 0,
                "the length of the input must be even"
            );

            let buf: &mut [::core::mem::MaybeUninit<u8>; const { $bytes.len() / 2 }] =
                &mut [::core::mem::MaybeUninit::uninit(); _];

            #[allow(unsafe_code, reason = "XXX")]
            let bytes = unsafe { ::core::slice::from_raw_parts($bytes.as_ptr(), $bytes.len()) };

            match $crate::decode_generic(bytes, buf) {
                Ok(_) => {}
                Err(_) => panic!("invalid hexadecimal string"),
            };

            #[allow(unsafe_code, reason = "XXX")]
            unsafe {
                ::core::mem::transmute::<_, _>(*buf)
            }
        };

        &DECODED
    }};
}