fashex 0.0.12

//! ## Algorithm
//!
//! ### Encoding
//!
//! General algorithm.
//!
//! ### Decoding
//!
//! See <http://0x80.pl/notesen/2022-01-17-validating-hex-parse.html>, algorithm 3.

#![allow(unsafe_code, reason = "SIMD")]
#![allow(unsafe_op_in_unsafe_fn, reason = "SIMD")]
#![allow(clippy::cast_ptr_alignment, reason = "SIMD")]
#![allow(clippy::wildcard_imports, reason = "SIMD")]

#[cfg(any(target_arch = "aarch64", target_arch = "arm64ec"))]
pub(crate) mod aarch64;
pub(crate) mod generic;
#[cfg(all(
    feature = "experimental-loongarch-simd",
    any(target_arch = "loongarch32", target_arch = "loongarch64")
))]
pub(crate) mod loongarch;
#[cfg(feature = "portable-simd")]
pub(crate) mod portable;
#[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
pub(crate) mod x86;

use core::mem::MaybeUninit;

use crate::error::InvalidInput;

/// Encodes the input bytes to hexadecimal string and writes it to the output
/// buffer.
///
/// ## Safety
///
/// We assume that:
///
/// 1. `src.len() <= dst.len()`.
pub(crate) unsafe fn encode_unchecked<const UPPER: bool>(
    src: &[u8],
    dst: &mut [[MaybeUninit<u8>; 2]],
) {
    debug_assert!(
        src.len() <= dst.len(),
        "implementation bug: `src` should not be longer than `dst`"
    );

    unsafe { encode_unchecked_dispatch::<UPPER>(src, dst) }
}

#[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
unsafe fn encode_unchecked_dispatch<const UPPER: bool>(
    src: &[u8],
    dst: &mut [[MaybeUninit<u8>; 2]],
) {
    use crate::util::cpufeatures;

    cpufeatures::new!(cpufeature_avx512, "avx512f", "avx512bw", "avx512vl");

    if cpufeature_avx512::exist() {
        return unsafe { self::x86::encode_avx512_unchecked::<UPPER>(src, dst) };
    }

    cpufeatures::new!(cpufeature_avx2, "avx2");

    if cpufeature_avx2::exist() {
        return unsafe { self::x86::encode_avx2_unchecked::<UPPER>(src, dst) };
    }

    cpufeatures::new!(cpufeature_ssse3, "ssse3");

    if cpufeature_ssse3::exist() {
        return unsafe { self::x86::encode_ssse3_unchecked::<UPPER>(src, dst) };
    }

    unsafe { self::generic::encode_generic_unchecked::<UPPER>(src, dst) }
}

#[cfg(any(target_arch = "aarch64", target_arch = "arm64ec"))]
unsafe fn encode_unchecked_dispatch<const UPPER: bool>(
    src: &[u8],
    dst: &mut [[MaybeUninit<u8>; 2]],
) {
    use crate::util::cpufeatures;

    cpufeatures::new!(cpufeature_neon, "neon");

    if cpufeature_neon::exist() {
        return unsafe { self::aarch64::encode_neon_unchecked::<UPPER>(src, dst) };
    }

    unsafe { self::generic::encode_generic_unchecked::<UPPER>(src, dst) }
}

#[cfg(any(target_arch = "loongarch32", target_arch = "loongarch64"))]
unsafe fn encode_unchecked_dispatch<const UPPER: bool>(
    src: &[u8],
    dst: &mut [[MaybeUninit<u8>; 2]],
) {
    #[cfg(feature = "experimental-loongarch-simd")]
    {
        use crate::util::cpufeatures;

        cpufeatures::new!(cpufeature_lasx, "lasx");

        if cpufeature_lasx::exist() {
            return unsafe { self::loongarch::encode_lasx_unchecked::<UPPER>(src, dst) };
        }

        cpufeatures::new!(cpufeature_lsx, "lsx");

        if cpufeature_lsx::exist() {
            return unsafe { self::loongarch::encode_lsx_unchecked::<UPPER>(src, dst) };
        }
    }

    unsafe { self::generic::encode_generic_unchecked::<UPPER>(src, dst) }
}

#[cfg(not(any(
    target_arch = "x86",
    target_arch = "x86_64",
    target_arch = "aarch64",
    target_arch = "arm64ec",
    target_arch = "loongarch32",
    target_arch = "loongarch64",
)))]
unsafe fn encode_unchecked_dispatch<const UPPER: bool>(
    src: &[u8],
    dst: &mut [[MaybeUninit<u8>; 2]],
) {
    if cfg!(feature = "portable-simd") {
        return unsafe { self::portable::encode_simd128_unchecked::<UPPER>(src, dst) };
    }

    unsafe { self::generic::encode_generic_unchecked::<UPPER>(src, dst) }
}

#[allow(unsafe_code, reason = "XXX")]
/// Decodes the given hexadecimal string to bytes and writes it to the output
/// buffer.
///
/// ## Safety
///
/// We assume that:
///
/// 1. `src.len() <= dst.len()`.
/// 2. When `VALIDATED`, the input contains only valid hexadecimal characters.
///
/// ## Errors
///
/// When `!VALIDATED` and the input contains invalid hexadecimal characters.
pub(crate) unsafe fn decode_unchecked<const VALIDATED: bool>(
    src: *const [[u8; 2]],
    dst: *mut [MaybeUninit<u8>],
) -> Result<(), InvalidInput> {
    debug_assert!(
        src.len() <= dst.len(),
        "implementation bug: `src` should not be longer than `dst`"
    );

    unsafe { decode_unchecked_dispatch(src, dst) }
}

#[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
#[inline]
unsafe fn decode_unchecked_dispatch(
    src: *const [[u8; 2]],
    dst: *mut [MaybeUninit<u8>],
) -> Result<(), InvalidInput> {
    use crate::util::cpufeatures;

    cpufeatures::new!(cpufeature_avx512, "avx512f", "avx512bw", "avx512vl");

    if cpufeature_avx512::exist() {
        return unsafe { self::x86::decode_avx512_unchecked(src, dst) };
    }

    cpufeatures::new!(cpufeature_avx2, "avx2");

    if cpufeature_avx2::exist() {
        return unsafe { self::x86::decode_avx2_unchecked(src, dst) };
    }

    cpufeatures::new!(cpufeature_ssse3, "ssse3");

    if cpufeature_ssse3::exist() {
        return unsafe { self::x86::decode_ssse3_unchecked(src, dst) };
    }

    unsafe { self::generic::decode_generic_unchecked::<false>(src, dst) }
}

#[cfg(any(target_arch = "aarch64", target_arch = "arm64ec"))]
#[inline]
unsafe fn decode_unchecked_dispatch(
    src: *const [[u8; 2]],
    dst: *mut [MaybeUninit<u8>],
) -> Result<(), InvalidInput> {
    use crate::util::cpufeatures;

    cpufeatures::new!(cpufeature_neon, "neon");

    if cpufeature_neon::exist() {
        return unsafe { self::aarch64::decode_neon_unchecked(src, dst) };
    }

    unsafe { self::generic::decode_generic_unchecked::<false>(src, dst) }
}

#[cfg(any(target_arch = "loongarch32", target_arch = "loongarch64"))]
#[inline]
unsafe fn decode_unchecked_dispatch(
    src: *const [[u8; 2]],
    dst: *mut [MaybeUninit<u8>],
) -> Result<(), InvalidInput> {
    #[cfg(feature = "experimental-loongarch-simd")]
    {
        use crate::util::cpufeatures;

        cpufeatures::new!(cpufeature_lasx, "lasx");

        if cpufeature_lasx::exist() {
            return unsafe { self::loongarch::decode_lasx_unchecked(src, dst) };
        }

        cpufeatures::new!(cpufeature_lsx, "lsx");

        if cpufeature_lsx::exist() {
            return unsafe { self::loongarch::decode_lsx_unchecked(src, dst) };
        }
    }

    unsafe { self::generic::decode_generic_unchecked::<false>(src, dst) }
}

#[cfg(not(any(
    target_arch = "x86",
    target_arch = "x86_64",
    target_arch = "aarch64",
    target_arch = "arm64ec",
    target_arch = "loongarch32",
    target_arch = "loongarch64",
)))]
#[inline]
unsafe fn decode_unchecked_dispatch(
    src: *const [[u8; 2]],
    dst: *mut [MaybeUninit<u8>],
) -> Result<(), InvalidInput> {
    if cfg!(feature = "portable-simd") {
        return unsafe { self::portable::decode_simd128_unchecked(src, dst) };
    }

    unsafe { self::generic::decode_generic_unchecked::<false>(src, dst) }
}

#[cfg(test)]
mod tests {
    use alloc::string::String;
    use alloc::vec;
    use alloc::vec::Vec;
    use core::mem::MaybeUninit;
    use core::slice;
    use std::sync::LazyLock;

    use crate::error::InvalidInput;
    use crate::util::{HEX_CHARS_LOWER, HEX_CHARS_UPPER};

    pub(crate) const CASE: &[u8; 513] = &[
        0xBD, 0xE8, 0xAC, 0xA5, 0x82, 0x41, 0x8A, 0x10, 0x66, 0x56, 0xE4, 0xF3, 0x06, 0x13, 0xD0,
        0x06, 0x3E, 0x19, 0x4B, 0x7E, 0xE1, 0xAB, 0x24, 0x03, 0x29, 0xD0, 0x8B, 0x91, 0x06, 0x56,
        0xF4, 0x44, 0x4E, 0x7B, 0x00, 0x76, 0xFB, 0xA3, 0xB4, 0x4F, 0x9E, 0x4E, 0x3E, 0x20, 0x89,
        0x29, 0x17, 0x47, 0x4D, 0x59, 0xF7, 0x9E, 0xAE, 0x0A, 0xB4, 0x16, 0xEB, 0x2B, 0x0D, 0xA2,
        0x35, 0x99, 0x1D, 0x94, 0xA0, 0x23, 0xFF, 0x60, 0x0F, 0x67, 0xDB, 0xB5, 0xEF, 0x89, 0xC2,
        0x3C, 0x2C, 0x24, 0x0E, 0x04, 0x05, 0x35, 0x31, 0xAA, 0x88, 0xB4, 0x04, 0x82, 0x21, 0x8B,
        0x24, 0x88, 0x3F, 0x19, 0x94, 0x36, 0xDB, 0x52, 0x9E, 0x89, 0x7D, 0x53, 0x6D, 0x8D, 0xDF,
        0xF7, 0xFD, 0x2A, 0x8F, 0x4B, 0x20, 0xAB, 0xAC, 0xA4, 0x4B, 0xBB, 0x5C, 0x10, 0x0D, 0x7B,
        0xEF, 0x3A, 0x03, 0xF7, 0x4D, 0x15, 0x10, 0x8C, 0xB1, 0x0A, 0x86, 0x6A, 0x19, 0x6F, 0x25,
        0xA6, 0xE3, 0x4B, 0xA8, 0x9D, 0x78, 0xC7, 0x19, 0x19, 0x09, 0x05, 0x08, 0x9A, 0xA1, 0x67,
        0x48, 0xF7, 0x9E, 0x3C, 0xFA, 0xD3, 0xFD, 0x5E, 0x1A, 0x09, 0xD8, 0x85, 0x7F, 0xA5, 0x73,
        0x34, 0xBF, 0x93, 0xCC, 0xF4, 0x8D, 0x8A, 0x62, 0xBD, 0xD5, 0x67, 0x39, 0x0D, 0xB7, 0x41,
        0x94, 0x7D, 0xB5, 0xB3, 0x5B, 0x95, 0x1F, 0x43, 0xE4, 0x77, 0x40, 0x41, 0x9E, 0x26, 0x34,
        0x73, 0x0D, 0x93, 0x0C, 0xE9, 0xB7, 0x3C, 0x97, 0x3D, 0xA4, 0xBC, 0xAA, 0xDA, 0xA9, 0xFB,
        0x78, 0xD8, 0xE4, 0xB4, 0xE8, 0x88, 0x29, 0x9B, 0xE4, 0x5B, 0xF4, 0x56, 0xC4, 0x0D, 0x50,
        0x05, 0x0F, 0x84, 0x51, 0xD4, 0x96, 0x3E, 0xC5, 0x4F, 0xCD, 0xEF, 0x2B, 0x0F, 0x78, 0x1D,
        0xE6, 0x4A, 0x90, 0xC6, 0xD8, 0xF7, 0x88, 0x0D, 0x58, 0x2C, 0xE7, 0x37, 0x4A, 0x94, 0x5F,
        0x56, 0x68, 0x84, 0xEE, 0xD2, 0xD6, 0x8A, 0xC9, 0x8A, 0x90, 0x70, 0xF7, 0x51, 0xC9, 0xD1,
        0x86, 0x5A, 0xB2, 0xD5, 0x91, 0xDB, 0xDF, 0x36, 0xF1, 0xD3, 0x69, 0xB1, 0x7D, 0x39, 0x0E,
        0xCC, 0x86, 0xEF, 0xBD, 0xBD, 0x13, 0x52, 0x2A, 0xFC, 0x72, 0x78, 0x14, 0x28, 0xDD, 0xD5,
        0xEE, 0xF8, 0x72, 0x0F, 0x26, 0x76, 0xC6, 0x5E, 0x1B, 0x50, 0x30, 0xDB, 0x93, 0xD9, 0x20,
        0xA3, 0x07, 0x4D, 0x85, 0x50, 0x40, 0x28, 0x1E, 0x40, 0x4B, 0x96, 0xD6, 0x8C, 0xAF, 0x8E,
        0xD4, 0xD7, 0x81, 0x31, 0x97, 0x47, 0x2A, 0x95, 0xC3, 0x03, 0xA2, 0x40, 0xC9, 0x55, 0xBF,
        0x64, 0x1A, 0xAB, 0x81, 0xA1, 0x6B, 0x6A, 0x56, 0x81, 0xDD, 0xD2, 0x68, 0x1D, 0xB7, 0xDB,
        0xD6, 0x9E, 0xDA, 0x84, 0xFC, 0x5B, 0xE0, 0x34, 0xAD, 0x61, 0x5E, 0xD1, 0xF5, 0x74, 0x79,
        0xE9, 0xED, 0xB5, 0x31, 0x3C, 0x7F, 0xB1, 0x44, 0xE0, 0x23, 0xAE, 0xBD, 0x9E, 0x13, 0x8A,
        0x9D, 0xAF, 0x48, 0x75, 0x06, 0x16, 0x58, 0x4A, 0x8B, 0xD3, 0xB7, 0x06, 0x14, 0xB5, 0x92,
        0xE2, 0xA1, 0x9F, 0xCF, 0x42, 0x3E, 0x99, 0x24, 0xE4, 0x65, 0x93, 0x84, 0x83, 0x66, 0x26,
        0x28, 0xEA, 0x3F, 0x05, 0x4E, 0xAC, 0x7C, 0x96, 0xF2, 0x50, 0x22, 0xF3, 0xCD, 0x90, 0x81,
        0x73, 0xBD, 0x3D, 0xCA, 0xD1, 0x2F, 0xC2, 0x3F, 0x20, 0xF0, 0x1C, 0x41, 0x9D, 0x9A, 0x85,
        0x1A, 0xC4, 0xB1, 0xE3, 0xBA, 0x52, 0xE7, 0xE3, 0x22, 0x72, 0x98, 0x76, 0xEC, 0x0B, 0xC4,
        0x07, 0xA3, 0x05, 0x01, 0xC0, 0x40, 0xA7, 0x0E, 0x8A, 0x0F, 0xDE, 0x5F, 0x65, 0xA3, 0x89,
        0x34, 0x3B, 0xFD, 0x9F, 0xE4, 0xB1, 0x6C, 0x1B, 0x40, 0xE6, 0xC2, 0x58, 0xE3, 0x62, 0xFC,
        0xB0, 0x22, 0x02, 0xD2, 0xE2, 0xF6, 0xFD, 0x4D, 0x64, 0xF5, 0x17, 0x07, 0x04, 0x34, 0x50,
        0x04, 0xEF, 0xAB,
    ];

    static EXPECTED_ENCODED_LOWER: LazyLock<Vec<String>> = LazyLock::new(|| {
        (0..CASE.len())
            .map(|i| {
                CASE[..i]
                    .iter()
                    .flat_map(|b| {
                        [
                            HEX_CHARS_LOWER[(*b >> 4) as usize] as char,
                            HEX_CHARS_LOWER[(*b & 0b1111) as usize] as char,
                        ]
                    })
                    .collect::<String>()
            })
            .collect()
    });

    static EXPECTED_ENCODED_UPPER: LazyLock<Vec<String>> = LazyLock::new(|| {
        (0..CASE.len())
            .map(|i| {
                CASE[..i]
                    .iter()
                    .flat_map(|b| {
                        [
                            HEX_CHARS_UPPER[(*b >> 4) as usize] as char,
                            HEX_CHARS_UPPER[(*b & 0b1111) as usize] as char,
                        ]
                    })
                    .collect::<String>()
            })
            .collect()
    });

    type EncodeFn = unsafe fn(src: &[u8], dst: &mut [[MaybeUninit<u8>; 2]]);
    type DecodeFn =
        unsafe fn(src: *const [[u8; 2]], dst: *mut [MaybeUninit<u8>]) -> Result<(), InvalidInput>;

    #[track_caller]
    pub(crate) fn check_encode_decode_any_backend<const UPPER: bool>(
        encode_f: EncodeFn,
        decode_f: DecodeFn,
    ) {
        for i in 0..CASE.len() {
            let input = &CASE[..i];

            let mut encoded = vec![[MaybeUninit::<u8>::uninit(); 2]; input.len()];

            unsafe {
                encode_f(input, &mut encoded[..]);
            }

            let encoded =
                unsafe { slice::from_raw_parts(encoded.as_ptr().cast::<[u8; 2]>(), encoded.len()) }
                    .as_flattened();

            assert_eq!(
                encoded,
                if UPPER {
                    EXPECTED_ENCODED_UPPER[i].as_bytes()
                } else {
                    EXPECTED_ENCODED_LOWER[i].as_bytes()
                },
                "Invalid encoded content (input={}, upper={UPPER})",
                input.len()
            );

            let encoded = unsafe { encoded.as_chunks_unchecked() };

            let mut decoded = vec![MaybeUninit::<u8>::uninit(); input.len()];

            unsafe {
                decode_f(encoded, &mut decoded[..]).unwrap();
            }

            let decoded =
                unsafe { slice::from_raw_parts(decoded.as_ptr().cast::<u8>(), decoded.len()) };

            assert_eq!(decoded, input);
        }
    }

    #[track_caller]
    pub(crate) fn check_decode_validation_any_backend(decode_f: DecodeFn) {
        fn test(mut bytes: Vec<u8>, mid: usize, c: u8, decode_f: DecodeFn) {
            bytes[mid] = c;

            let bytes = unsafe { bytes.as_chunks_unchecked() };

            if c.is_ascii_hexdigit() {
                unsafe {
                    assert!(
                        decode_f(
                            bytes,
                            Vec::with_capacity(bytes.len() * 2).spare_capacity_mut()
                        )
                        .is_ok(),
                        "validation failed for byte {c} (mid={mid}, len={})",
                        bytes.len() * 2
                    );
                }
            } else {
                unsafe {
                    assert!(
                        decode_f(
                            bytes,
                            Vec::with_capacity(bytes.len() * 2).spare_capacity_mut()
                        )
                        .is_err(),
                        "validation failed for byte {c} (mid={mid}, len={})",
                        bytes.len() * 2
                    );
                }
            }
        }

        for (mid, bytes) in (2..256).map(|mid| (mid, vec![b'a'; mid * 2])) {
            for c in 0u8..=255 {
                test(bytes.clone(), mid - 1, c, decode_f);
                test(bytes.clone(), mid, c, decode_f);
                test(bytes.clone(), mid + 1, c, decode_f);
            }
        }
    }
}