str_array/

lib.rs

//! Provides fixed-size string types [`StrArray<N>`] and [`CStrArray<N>`].
//!
//! [`StrArray`] serves as the `str` equivalent of `[u8; N]`.
//! It provides a `Deref` to `&str` and ensures the UTF-8 invariant is
//! always upheld, but has a size known at compile time.
//!
//! This is useful in some situations:
//!
//! - Resource-constrained `no_std` and no-`alloc` environments.
//! - Defining UTF-8 strings directly in a stack array or static.
//! - Types or parameters that require `&str` of some fixed length.
//!
//! The [`str_array!`] macro provides a compile-time-checked way to
//! build [`StrArray`] values from string literals and constants.
//!
//! Similarly, [`CStrArray`] and [`cstr_array!`] can construct a
//! nul-terminated [`CStr`](core::ffi::CStr) safely on the stack.
//!
//! # Features
//!
//! - `no_std` support - disable default features to use without `std`
//! - Optional `alloc` and `std` features
//! - Full `const` support
//! - [C string](crate::CStrArray) support
//!
//! # Examples
//!
//! ```
//! use str_array::{str_array, StrArray};
//!
//! // Create from a constant using the macro. The length is inferred.
//! let s1 = str_array!("hello");
//! assert_eq!(s1.len(), 5);
//! assert_eq!(s1, "hello");
//! assert!(matches!(s1.into_bytes(), [b'h', b'e', b'l', b'l', b'o']));
//!
//! // Or create from a runtime &str with an length check.
//! let s2: StrArray<12> = StrArray::new(&format!("{s1}, world")).unwrap();
//! assert_eq!(core::mem::size_of_val(&s2), 12);
//! assert_eq!(s2, "hello, world");
//!
//! // Or create from bytes with a UTF-8 check.
//! let s3 = StrArray::from_utf8(
//!     b"\xF0\x9F\xA4\x8C\xF0\x9F\x8F\xBC"
//! ).unwrap();
//! assert_eq!(s3, "🤌🏼");
//!
//! // Or define an item with an inferred length.
//! str_array! {
//!     static S4 = "Georgia";
//! }
//! assert_eq!(S4.len(), 7);
//! ```
//!
//! # Rust feature detection
//!
//! This crate has a low Minimum Supported Rust Version (MSRV), and it achieves
//! that through `cfg` values that are enabled in the `build.rs` based on the
//! presence of existing features. This uses the `autocfg` library.
//!
//! The `build.rs` can be skipped for alternate build systems, but be sure to
//! enable the appropriate `cfg` values based on your version of `rustc`.
//! Those are:
//!
//! - `cfg(has_core_error)` is enabled when `core::error::Error` is present
//!   (stable since Rust 1.81).
//!   If it's enabled, then the error types in this crate implement `Error`
//!   with any set of features. If it's disabled, they only implement the
//!   `Error` trait when the `std` feature is enabled.
//! - `cfg(has_const_mut)` is enabled when `&mut` is usable in `const`
//!   (stable since Rust 1.83).
//!   It adds `const` to various `fn` that use `&mut` in this crate.
#![no_std]
#![deny(missing_docs, unsafe_op_in_unsafe_fn)]
#![deny(rustdoc::broken_intra_doc_links)]

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

use core::{
    fmt::{self, Debug, Display},
    ops::{Deref, DerefMut},
    str::Utf8Error,
};

mod cmp;
mod convert;
mod cstr;
pub mod error;

mod util_macros;

use error::StrLenError;
use util_macros::const_mut_fn;

pub use cstr::CStrArray;

/// Internal-only items which may change with a non-breaking release.
#[doc(hidden)]
pub mod __internal {
    pub use crate::cstr::{build_cstr, CStrArrayBytes};
}

/// Fixed-size [`str`], backed by an array.
///
/// `[u8; N]` is to `[u8]` as `StrArray<N>` is to `str`.
/// It provides a `Deref` to `&str` and ensures the UTF-8 invariant is
/// always upheld, but has a size known at compile time.
///
/// [`str_array!`] provides a convenient way to construct
/// and define `StrArray` from literals and constants.
///
/// # Examples
///
/// Small UTF-8 strings of fixed size:
///
/// ```
/// # use str_array::str_array;
/// let mut airports = [
///     str_array!("JFK"), str_array!("LAX"),
///     str_array!("LHR"), str_array!("CDG"),
///     str_array!("HND"), str_array!("PEK"),
///     str_array!("DXB"), str_array!("AMS"),
///     str_array!("FRA"), str_array!("SIN"),
/// ];
///
/// // All of the strings are contiguous in memory.
/// assert_eq!(core::mem::size_of_val(&airports), 30);
///
/// airports.sort();
/// assert_eq!(airports[0], "AMS");
/// ```
///
/// Storing `str` contents directly in a `static`:
///
/// ```
/// # use core::mem::size_of_val;
/// # use str_array::str_array;
/// str_array! {
///     static FOO = "Hello, world!";
///     static mut FOO_MUT = "utf-8 buffer";
/// }
/// assert_eq!(&FOO, "Hello, world!");
/// assert_eq!(size_of_val(&FOO), 13);
/// let foo_mut = unsafe { &mut *&raw mut FOO_MUT };
/// foo_mut.make_ascii_uppercase();
/// assert_eq!(foo_mut, "UTF-8 BUFFER");
/// assert_eq!(size_of_val(foo_mut), 12);
/// ```
#[repr(transparent)]
#[derive(PartialEq, Eq, PartialOrd, Ord, Hash, Clone, Copy)]
pub struct StrArray<const N: usize>(
    /// # Safety
    /// Must be UTF-8 encoded bytes.
    [u8; N],
);

impl<const N: usize> Debug for StrArray<N> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "StrArray<{N}>({s:?})", s = self.as_str())
    }
}

impl<const N: usize> Display for StrArray<N> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        <str as Display>::fmt(self.as_str(), f)
    }
}

impl<const N: usize> StrArray<N> {
    /// Builds a `StrArray<N>` from `val` by performing a length check.
    ///
    /// This returns an `Err` if `val.len() != N`.
    ///
    /// If `val` is a literal or `const`, consider using [`str_array!`]
    /// instead, which always builds a `StrArray` with the correct `N`.
    ///
    /// # Examples
    ///
    /// ```
    /// # use str_array::StrArray;
    /// let s = StrArray::<5>::new(&format!("he{}", "llo")).unwrap();
    /// assert_eq!(s, "hello");
    /// assert!(StrArray::<5>::new("foo").is_err());
    /// ```
    pub const fn new(val: &str) -> Result<Self, StrLenError<N>> {
        match Self::ref_from_str(val) {
            Ok(out) => Ok(*out),
            Err(e) => Err(e),
        }
    }

    /// Builds a `StrArray<N>` from `val` without a length check.
    ///
    /// # Examples
    ///
    /// ```
    /// # use str_array::StrArray;
    /// // SAFETY: "hello" has length 5
    /// let s = unsafe { StrArray::<5>::new_unchecked("hello") };
    /// assert_eq!(s, "hello");
    /// ```
    ///
    /// # Safety
    ///
    /// `val.len() >= N` or else behavior is undefined.
    pub const unsafe fn new_unchecked(val: &str) -> Self {
        // SAFETY: `val` has at least size `N` as promised by the caller.
        Self(unsafe { *(val.as_bytes() as *const [u8]).cast() })
    }

    /// Converts a `&str` to `&StrArray<N>` without copying.
    ///
    /// Returns an `Err` if `val.len() != N`.
    ///
    /// # Examples
    ///
    /// ```
    /// # use str_array::StrArray;
    /// let s = StrArray::<5>::ref_from_str("hello").unwrap();
    /// assert_eq!(s, "hello");
    ///
    /// assert!(StrArray::<5>::ref_from_str("foo").is_err());
    /// ```
    pub const fn ref_from_str(val: &str) -> Result<&Self, StrLenError<N>> {
        if val.len() != N {
            return Err(StrLenError { src_len: val.len() });
        }
        // SAFETY: val.len() == N.
        Ok(unsafe { Self::ref_from_str_unchecked(val) })
    }

    /// Converts a `&str` to `&StrArray<N>` without copying and no length check.
    ///
    /// # Examples
    ///
    /// ```
    /// # use str_array::StrArray;
    /// // SAFETY: "abc".len() == 3
    /// let s: &StrArray<3> = unsafe {
    ///     StrArray::ref_from_str_unchecked("abc")
    /// };
    /// assert_eq!(s.into_bytes(), [b'a', b'b', b'c']);
    /// ```
    ///
    /// # Safety
    ///
    /// `val.len() == N` or else behavior is undefined.
    pub const unsafe fn ref_from_str_unchecked(val: &str) -> &Self {
        // SAFETY:
        // - `StrArray<N>` is `repr(transparent)` over `[u8; N]`, as is `str`.
        // - The caller has promised that `*val` has the same size as `[u8; N]`.
        // - `val` is UTF-8, matching the requirement of `Self::0`.
        unsafe { &*val.as_ptr().cast() }
    }

    const_mut_fn! {
        /// Converts a `&mut str` to `&mut StrArray<N>` without copying.
        ///
        /// This returns an `Err` if `val.len() != N`.
        ///
        /// # Examples
        ///
        /// ```
        /// # use str_array::StrArray;
        /// let mut s = String::from("hello");
        /// let s_mut = StrArray::<5>::mut_from_str(&mut s).unwrap();
        /// s_mut.make_ascii_uppercase();
        /// assert_eq!(s, "HELLO");
        ///
        /// assert!(StrArray::<5>::mut_from_str(&mut String::from("foo")).is_err());
        /// ```
        pub fn mut_from_str(val: &mut str) -> Result<&mut Self, StrLenError<N>> {
            if val.len() != N {
                return Err(StrLenError {
                    src_len: val.len(),
                });
            }
            // SAFETY: val.len() == N.
            Ok(unsafe { Self::mut_from_str_unchecked(val) })
        }
    }

    const_mut_fn! {
        /// Converts a `&mut str` to `&mut StrArray<N>` without copying and no length check.
        ///
        /// # Examples
        ///
        /// ```
        /// # use str_array::StrArray;
        /// let mut s = String::from("abc");
        ///
        /// // SAFETY: `s.len() == 3`
        /// let m: &mut StrArray<3> = unsafe {
        ///     StrArray::mut_from_str_unchecked(&mut s)
        /// };
        /// m.make_ascii_uppercase();
        /// assert_eq!(s, "ABC");
        /// ```
        ///
        /// # Safety
        ///
        /// `val.len() == N` or else behavior is undefined.
        pub unsafe fn mut_from_str_unchecked(val: &mut str) -> &mut Self {
            // SAFETY:
            // - `StrArray<N>` is `repr(transparent)` over `[u8; N]`, as is `str`.
            // - The caller has promised that `*val` has the same size as `[u8; N]`.
            // - `val` is UTF-8.
            unsafe { &mut *val.as_mut_ptr().cast() }
        }
    }

    /// Copies UTF-8 bytes from `val` into a `StrArray<N>`.
    ///
    /// # Examples
    ///
    /// ```
    /// # use str_array::StrArray;
    /// let s = StrArray::<5>::from_utf8(b"hello").unwrap();
    /// assert_eq!(s, "hello");
    /// ```
    pub const fn from_utf8(val: &[u8; N]) -> Result<Self, Utf8Error> {
        match Self::ref_from_utf8(val) {
            Ok(&a) => Ok(a),
            Err(e) => Err(e),
        }
    }

    /// Copies UTF-8 bytes from `val` into a `StrArray<N>` without a UTF-8 check.
    ///
    /// # Examples
    ///
    /// ```
    /// # use str_array::StrArray;
    /// // SAFETY: "hello" is valid UTF-8.
    /// let s = unsafe { StrArray::<5>::from_utf8_unchecked(b"hello") };
    /// assert_eq!(s, "hello");
    /// ```
    ///
    /// # Safety
    ///
    /// `val` must contain valid UTF-8 or behavior is undefined.
    pub const unsafe fn from_utf8_unchecked(val: &[u8; N]) -> Self {
        // SAFETY: The caller guarantees `val` is valid UTF-8.
        Self(unsafe { *(val as *const [u8; N]).cast() })
    }

    /// Converts UTF-8 bytes in `val` to `&StrArray<N>` without copying.
    ///
    /// # Examples
    ///
    /// ```
    /// # use str_array::StrArray;
    /// let s = StrArray::<5>::ref_from_utf8(b"hello").unwrap();
    /// assert_eq!(s, "hello");
    /// ```
    pub const fn ref_from_utf8(val: &[u8; N]) -> Result<&Self, Utf8Error> {
        match core::str::from_utf8(val) {
            // SAFETY:
            // - `StrArray<N>` is `repr(transparent)` over `[u8; N]`.
            // - `val` is valid UTF-8.
            Ok(_) => Ok(unsafe { &*(val as *const [u8; N]).cast() }),
            Err(e) => Err(e),
        }
    }

    /// Converts UTF-8 bytes in `val` to `&StrArray<N>` without a UTF-8 check.
    ///
    /// # Examples
    ///
    /// ```
    /// # use str_array::StrArray;
    /// // SAFETY: "hello" is valid UTF-8
    /// let s: &StrArray<5> = unsafe { StrArray::ref_from_utf8_unchecked(b"hello") };
    /// assert_eq!(s, "hello");
    /// ```
    ///
    /// # Safety
    ///
    /// `val` must contain valid UTF-8 or behavior is undefined.
    pub const unsafe fn ref_from_utf8_unchecked(val: &[u8; N]) -> &Self {
        // SAFETY:
        // - `StrArray<N>` is `repr(transparent)` over `[u8; N]`.
        // - The caller guarantees `val` is valid UTF-8.
        unsafe { &*(val as *const [u8; N]).cast() }
    }

    const_mut_fn! {
        /// Converts UTF-8 bytes in `val` to `&mut StrArray<N>` without copying.
        ///
        /// # Examples
        ///
        /// ```
        /// # use str_array::StrArray;
        /// let mut bytes = *b"hello";
        /// let s = StrArray::<5>::mut_from_utf8(&mut bytes).unwrap();
        /// assert_eq!(s, "hello");
        /// ```
        pub fn mut_from_utf8(val: &mut [u8; N]) -> Result<&mut Self, Utf8Error> {
            match core::str::from_utf8(val) {
                // SAFETY:
                // - `StrArray<N>` is `repr(transparent)` over `[u8; N]`
                // - `val` is valid UTF-8
                Ok(_) => Ok(unsafe { &mut *(val as *mut [u8; N]).cast() }),
                Err(e) => Err(e),
            }
        }
    }

    const_mut_fn! {
        /// Converts UTF-8 bytes in `val` to `&mut StrArray<N>` without a UTF-8 check.
        ///
        /// # Examples
        ///
        /// ```
        /// # use str_array::StrArray;
        /// let mut bytes = *b"HELLO";
        ///
        /// // SAFETY: "HELLO" is valid UTF-8
        /// let s: &mut StrArray<5> = unsafe { StrArray::mut_from_utf8_unchecked(&mut bytes) };
        /// s.make_ascii_lowercase();
        /// assert_eq!(s, "hello");
        /// ```
        ///
        /// # Safety
        ///
        /// `val` must contain valid UTF-8 or behavior is undefined.
        pub unsafe fn mut_from_utf8_unchecked(val: &mut [u8; N]) -> &mut Self {
            // SAFETY:
            // - `StrArray<N>` is `repr(transparent)` over `[u8; N]`.
            // - The caller guarantees `val` is valid UTF-8.
            unsafe { &mut *(val as *mut [u8; N]).cast() }
        }
    }

    /// Returns a `StrArray<N>` filled with zeroes.
    ///
    /// # Examples
    ///
    /// ```
    /// # use str_array::StrArray;
    /// let s = StrArray::<4>::zeroed();
    /// assert_eq!(s, "\0\0\0\0");
    /// ```
    pub const fn zeroed() -> Self {
        Self([0; N])
    }

    /// Borrows this `StrArray<N>` as a `&str`.
    ///
    /// This is performed automatically on deref.
    ///
    /// # Examples
    ///
    /// ```
    /// # use str_array::str_array;
    /// let s = str_array!("hello");
    /// assert_eq!(s.as_str().find('l'), Some(2));
    /// assert_eq!(s.find('y'), None);  // using deref
    /// ```
    pub const fn as_str(&self) -> &str {
        // SAFETY: `self.0` is guaranteed to be UTF-8 bytes.
        unsafe { core::str::from_utf8_unchecked(&self.0) }
    }

    const_mut_fn! {
        /// Converts `&mut self` to a `&mut str`.
        ///
        /// This is performed automatically on deref.
        ///
        /// # Examples
        ///
        /// ```
        /// # use str_array::str_array;
        /// let mut s = str_array!("hello");
        /// s.as_mut_str().make_ascii_uppercase();
        /// assert_eq!(s, "HELLO");
        /// ```
        pub fn as_mut_str(&mut self) -> &mut str {
            // SAFETY: `self.0` is guaranteed to be UTF-8 bytes.
            unsafe { core::str::from_utf8_unchecked_mut(&mut self.0) }
        }
    }

    /// Borrows `self` as a byte array of the same size.
    ///
    /// Unlike [`str::as_bytes`], this returns an array reference.
    ///
    /// # Example
    ///
    /// ```
    /// # use str_array::{str_array, StrArray};
    /// let x = str_array!("Hello");
    /// let &[a, b @ .., c] = x.as_bytes();
    /// assert_eq!(a, b'H');
    /// assert_eq!(b, *b"ell");
    /// assert_eq!(c, b'o');
    /// ```
    pub const fn as_bytes(&self) -> &[u8; N] {
        &self.0
    }

    const_mut_fn! {
        /// Borrows `self` as a mutable byte array of the same size.
        ///
        /// Unlike [`str::as_bytes_mut`], this returns an array reference.
        ///
        ///
        /// # Examples
        ///
        /// ```
        /// # use str_array::str_array;
        /// let mut s = str_array!("hello");
        /// unsafe {
        ///    let bytes = s.as_mut_bytes();
        ///    bytes[0] = b'H';
        /// }
        /// assert_eq!(s, "Hello");
        /// ```
        ///
        /// # Safety
        ///
        /// This has the same non-local requirement as [`str::as_bytes_mut`]:
        ///
        /// The caller must ensure that the content of the array is valid UTF-8
        /// before the borrow ends and the underlying `StrArray` is used.
        pub unsafe fn as_mut_bytes(&mut self) -> &mut [u8; N] {
            &mut self.0
        }
    }

    /// Converts a `StrArray<N>` into a byte array.
    ///
    /// # Examples
    ///
    /// ```
    /// # use str_array::{str_array, StrArray};
    /// let x = str_array!("Fizzy");
    ///
    /// let [a, b @ .., c] = x.into_bytes();
    /// assert_eq!(a, b'F');
    /// assert_eq!(b, *b"izz");
    /// assert_eq!(c, b'y');
    /// ```
    pub const fn into_bytes(self) -> [u8; N] {
        self.0
    }
}

impl StrArray<0> {
    /// Returns an empty `StrArray`.
    ///
    /// # Examples
    ///
    /// ```
    /// # use str_array::StrArray;
    /// let s = StrArray::<0>::empty();
    /// assert!(s.is_empty());
    /// ```
    pub const fn empty() -> Self {
        Self([])
    }
}

impl<const N: usize> Deref for StrArray<N> {
    type Target = str;

    fn deref(&self) -> &Self::Target {
        self.as_str()
    }
}

impl<const N: usize> DerefMut for StrArray<N> {
    fn deref_mut(&mut self) -> &mut Self::Target {
        self.as_mut_str()
    }
}

/// Builds [`StrArray`] from constant `&str`.
///
/// # Examples
///
/// Pass a `const` expression of `&str` to build a `StrArray` with the same length.
///
/// ```
/// # use str_array::str_array;
/// let x = str_array!("Buzz");
/// assert_eq!(x.len(), 4);
///
/// const NAME: &str = "Sally";
/// let y = str_array!(NAME);
/// assert_eq!(y, "Sally");
/// ```
///
/// Define `static` or `const` items by eliding the type.
/// The length of the `StrArray` uses the length of the assigned string.
/// Note that the assignment expression currently is evaluated twice,
/// but this should have no effect due to it being in `const`.
///
/// ```
/// # use core::ptr::addr_of;
/// # use str_array::{StrArray, str_array};
/// str_array! {
///     static STATIC = "static";
///     static mut STATIC_MUT = "static_mut";
///     const CONST = "constant";
/// }
/// assert_eq!(STATIC, "static");
/// assert_eq!(unsafe { &*addr_of!(STATIC_MUT) }, "static_mut");
/// assert_eq!(CONST, "constant");
/// ```
#[macro_export]
macro_rules! str_array {
    // This rule could be moved to another utility macro, but the inability to
    // `macro_export` solely in the `mod __internal` leads me to leave this here.
    // If only I could `doc(hidden)` utility segments of a macro_rules!
    (@impl item
        ($([$attr:meta])*)
        ($($item_kind:tt)*)
        $name:ident = $val:expr; $($rest:tt)*
    ) => {
        // Is there a way to avoid the double-evaluation of `$val` for item declarations
        // without adding a dependency or proc-macro (i.e. use `paste`)?
        $(#[$attr])* $($item_kind)* $name: $crate::StrArray<{$val.len()}> = match $crate::StrArray::new($val) {
            Ok(a) => a,
            Err(e) => e.const_panic(),
        };
        $crate::str_array!($($rest)*)
    };
    ($(#[$attr:meta])* static mut $($rest:tt)*) => {
        $crate::str_array!(@impl item ($([$attr])*) (static mut) $($rest)*);
    };
    ($(#[$attr:meta])* static $($rest:tt)*) => {
        $crate::str_array!(@impl item ($([$attr])*) (static) $($rest)*);
    };
    ($(#[$attr:meta])* const $($rest:tt)*) => {
        $crate::str_array!(@impl item ($([$attr])*) (const) $($rest)*);
    };
    ($val:expr) => {{
        const VAL: &str = $val;
        const ARRAY: $crate::StrArray<{ VAL.len() }> = match $crate::StrArray::new(VAL) {
            Ok(a) => a,
            Err(e) => e.const_panic(),
        };
        ARRAY
    }};
    () => {};
}

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

    use ::alloc::format;

    trait TypeEq {
        type This;
    }

    impl<T> TypeEq for T {
        type This = Self;
    }

    fn assert_type_eq_all<T, U>(_: U)
    where
        T: TypeEq<This = U>,
        U:,
    {
    }

    #[test]
    fn test_deref_mut() {
        let mut a = str_array!("aoeu");
        a.make_ascii_uppercase();
        assert_eq!(a, "AOEU");
    }

    #[test]
    #[cfg(has_const_mut)]
    fn test_const_mut() {
        const X: StrArray<3> = {
            let mut x = str_array!("foo");
            x.as_mut_str().make_ascii_uppercase();
            x
        };
        assert_eq!(X, "FOO");
    }

    #[test]
    #[deny(non_upper_case_globals)]
    fn test_macro_declared_items() {
        str_array! {
            /// With multi-line doc string
            static STATIC = "hello";

            #[allow(non_upper_case_globals)]
            static mut StaticMut = "aoeu";
            const CONST = "constant";
        }
        assert_eq!(STATIC, "hello");
        assert_type_eq_all::<StrArray<5>, _>(STATIC);
        assert_eq!(unsafe { StaticMut }, "aoeu");
        assert_type_eq_all::<StrArray<4>, _>(unsafe { StaticMut });

        let x = unsafe { &mut *core::ptr::addr_of_mut!(StaticMut) };
        x.make_ascii_uppercase();
        assert_eq!(x, "AOEU");

        assert_eq!(CONST, "constant");
        assert_type_eq_all::<StrArray<8>, _>(CONST);
    }

    #[test]
    fn test_slice() {
        let a = str_array!("a");
        let _: &str = &a[..];
    }

    #[test]
    fn test_zeroed() {
        let s = StrArray::<4>::zeroed();
        assert_eq!(s.as_bytes(), &[0, 0, 0, 0]);
    }

    #[test]
    fn test_empty() {
        let s = StrArray::empty();
        assert!(s.is_empty());
    }

    #[test]
    fn test_display() {
        let s = str_array!("hello");
        assert_eq!(format!("{}", s), "hello");
    }

    #[test]
    fn test_debug() {
        let s = str_array!("hello");
        assert_eq!(format!("{:?}", s), "StrArray<5>(\"hello\")");
    }
}