devela 0.27.0

// devela::text::str::u
//
//! `String` backed by an array.
//
// TOC
// - impl_str_u!
//   - definitions
//   - trait impls
// - tests

use crate::{
    CharIter, ConstInit, Debug, Deref, Display, FmtError, FmtResult, FmtWrite, Formatter, Hash,
    Hasher, InvalidText, InvalidUtf8, MismatchedCapacity, NotEnoughElements, NotEnoughSpace, Str,
    is, paste, slice, text::char::*, whilst,
};
#[allow(unused, reason = "±unsafe")]
use crate::{Cmp, unwrap};

macro_rules! impl_str_u {
    // in sync with devela::code::const_init % _stringu
    () => { impl_str_u![u8, u16, u32, usize]; };
    (
    // $t: the length type. E.g.: u8.
    $($t:ty),+ $(,)?) => { $( paste! { impl_str_u![@[<String $t:camel>], $t]; } )+ };
    (
    // $name: the name of the type. E.g.: StringU8.
    @$name:ty, $t:ty) => { paste! {
        /* definitions */

        #[allow(rustdoc::broken_intra_doc_links, reason = "±unsafe")]
        #[doc = crate::_tags!(text)]
        /// A UTF-8 string with fixed capacity that stores length explicitly.
        #[doc = crate::_doc_location!("text/str")]
        ///
        /// Suited for frequently inspected or manipulated text where constant-time
        /// length access is important. Uses extra space to provide O(1) length operations.
        /// For the opposite trade-off see [`StringNonul`][crate::StringNonul].
        ///
        #[doc = "Internally, the current length is stored as a [`" $t "`]."]
        ///
        /// ## Methods
        ///
        /// - [Constructors](#constructors):
        ///   [`new`][Self::new],
        ///     *([_checked][Self::new_checked])*.
        ///   [`from_str`][Self::from_str],
        ///     *([_truncate][Self::from_str_truncate],
        ///       [_unchecked][Self::from_str_unchecked])*,
        ///   [`from_char`][Self::from_char]
        ///     *([7][Self::from_char7],
        ///       [8][Self::from_char8],
        ///       [16](Self::from_char16),
        ///       [utf8](Self::from_charu))*.
        ///   [`from_array`][Self::from_array] *(
        #[cfg_attr(feature = "unsafe_str", doc =
            "[_unchecked][Self::from_array_unchecked]<sup title='unsafe function'>⚠</sup>,")]
        ///     [_nleft][Self::from_array_nleft],
        #[cfg_attr(feature = "unsafe_str", doc =
            "[_nleft_unchecked][Self::from_array_nleft_unchecked]<sup title='unsafe function'>⚠</sup>,")]
        ///       [_nright][Self::from_array_nleft]
        // IMPROVE comma list, maybe _doc macro to concat method links with optional unsafe items
        #[cfg_attr(feature = "unsafe_str", doc =
            ", [_nright_unchecked][Self::from_array_nright_unchecked]<sup title='unsafe function'>⚠</sup>")]
        /// )*.
        ///
        /// - [Deconstructors](#deconstructors):
        ///   [`into_array`][Self::into_array],
        ///   [`as_array`][Self::as_array],
        ///   [`as_bytes`][Self::as_bytes]
        #[cfg_attr(feature = "unsafe_str", doc =
            "*([mut][Self::as_bytes_mut]<sup title='unsafe function'>⚠</sup>)*.")]
        ///   [`as_str`][Self::as_str]
        #[cfg_attr(feature = "unsafe_str", doc =
            "*([mut][Self::as_mut_str]<sup title='unsafe function'>⚠</sup>)*.")]
        ///   [`chars`][Self::chars].
        ///
        /// - [Queries](#queries):
        ///   [`len`][Self::len],
        ///   [`is_empty`][Self::is_empty],
        ///   [`is_full`][Self::is_full],
        ///   [`capacity`][Self::capacity],
        ///   [`remaining_capacity`][Self::remaining_capacity].
        ///
        /// - [Modifiers](#modifiers):
        ///   [`clear`][Self::clear],
        ///   [`reset`][Self::reset],
        ///   [`sanitize`][Self::sanitize],
        ///   [`pop`][Self::pop]
        ///     *([try_][Self::try_pop],
        ///       [_unchecked][Self::pop_unchecked])*,
        ///   [`push`][Self::push]
        ///     *([try_][Self::try_push])*.
        ///   [`push_str`][Self::push]
        ///     *([try_][Self::try_push_str],
        ///       [try__complete][Self::try_push_str_complete])*.
        #[must_use]
        #[derive(Clone, Copy, Eq, PartialOrd, Ord)]
        pub struct $name<const CAP: usize> {
            arr: [u8; CAP], // WAIT: for when possible CAP:u8|u16|u32 for panic-less boundary check.
            len: $t,
        }

        /// # Constructors
        impl<const CAP: usize> $name<CAP> {
            #[doc = "Creates a new empty `String" $t:camel "` with a capacity of `CAP` bytes."]
            ///
            /// # Panics
            #[doc = "Panics if `CAP > `[`" $t "::MAX`]."]
            ///
            /// # Example
            /// ```
            #[doc = "# use devela::" $name ";"]
            #[doc = "let mut s = " $name "::<10>::new();"]
            #[doc = "assert![size_of_val(&s) >= 10 + size_of::<" $t ">()]; // + padding"]
            /// ```
            pub const fn new() -> Self {
                assert![CAP <= $t::MAX as usize,
                    concat!["Mismatched capacity, greater than ", stringify![$t], "::MAX"]
                ];
                Self { arr: [0; CAP], len: 0 }
            }
            #[doc = "Creates a new empty `String" $t:camel "` with a capacity of `CAP` bytes."]
            ///
            /// # Errors
            #[doc = "Returns [`MismatchedCapacity`] if `CAP > `[`" $t "::MAX`]."]
            pub const fn new_checked() -> Result<Self, MismatchedCapacity> {
                if CAP <= $t::MAX as usize {
                    Ok(Self { arr: [0; CAP], len: 0 })
                } else {
                    Err(MismatchedCapacity::too_large(CAP, <$t>::MAX as usize))
                }
            }

            /* from_str* conversions */

            #[doc = "Creates a new `String" $t:camel "` from a complete `&str`."]
            ///
            /// # Errors
            #[doc = "Returns [`MismatchedCapacity`] if `CAP > `[`" $t "::MAX`]."]
            /// or if `CAP < string.len()`.
            ///
            /// This is implemented via `Self::`[`try_push_str_complete()`][Self::try_push_str_complete].
            ///
            /// # Example
            /// ```
            /// # use devela::StringU8;
            /// let s = StringU8::<13>::from_str("Hello Wørld!").unwrap();
            /// assert_eq![s.as_str(), "Hello Wørld!"];
            /// ```
            pub const fn from_str(string: &str) -> Result<Self, MismatchedCapacity> {
                let mut new_string = unwrap![ok? Self::new_checked()];
                if let Ok(_) = new_string.try_push_str_complete(string) { Ok(new_string) }
                else { Err(MismatchedCapacity::too_small(CAP, string.len())) }
            }

            #[doc = "Creates a new `String" $t:camel "` from a `&str`,"]
            /// truncating if it does not fit.
            ///
            #[doc = "Returns [`MismatchedCapacity`] if `CAP > `[`" $t "::MAX`]"]
            ///
            /// This is implemented via `Self::`[`push_str()`][Self::push_str].
            pub const fn from_str_truncate(string: &str) -> Result<Self, MismatchedCapacity> {
                let mut new_string = unwrap![ok? Self::new_checked()];
                let _ = new_string.push_str(string);
                Ok(new_string)
            }

            #[doc = "Creates a new `String" $t:camel "` from a `&str`,"]
            /// truncating if it does not fit.
            ///
            /// # Panics
            #[doc = "Panics if `CAP > `[`" $t "::MAX`]."]
            ///
            /// This is implemented via `Self::`[`push_str()`][Self::push_str].
            pub const fn from_str_unchecked(string: &str) -> Self {
                let mut new_string = Self::new();
                let _ = new_string.push_str(string);
                new_string
            }

            /* from_char* conversions */

            #[doc = "Creates a new `String" $t:camel "` from a `char`."]
            ///
            /// # Errors
            #[doc = "Returns [`MismatchedCapacity`] if `CAP > `[`" $t "::MAX`]."]
            /// or if `CAP < c.`[`len_utf8()`].
            ///
            #[doc = "Will always succeed if `CAP >= 4 && CAP <= `[`" $t "::MAX`]."]
            /// # Example
            /// ```
            /// # use devela::{StringU8, char};
            /// assert_eq![StringU8::<4>::from_char('🐛').unwrap().as_str(), "🐛"];
            /// assert![StringU8::<3>::from_char('🐛').is_err()];
            /// ```
            #[doc = crate::doclink!(custom devela
                "[`len_utf8()`]" "text/grapheme/trait.UnicodeScalar.html#method.len_utf8")]
            pub const fn from_char(c: char) -> Result<Self, MismatchedCapacity> {
                let bytes = Char(c).to_utf8_bytes();
                let len = Char(bytes[0]).len_utf8_unchecked();
                is![CAP < len, return Err(MismatchedCapacity::too_small(CAP, len))];
                let mut new = unwrap![ok? Self::new_checked()];
                new.len = len as $t;
                new.arr[0] = bytes[0];
                if new.len > 1 { new.arr[1] = bytes[1]; }
                if new.len > 2 { new.arr[2] = bytes[2]; }
                if new.len > 3 { new.arr[3] = bytes[3]; }
                Ok(new)
            }

            #[doc = "Creates a new `String" $t:camel "` from a `char7`."]
            ///
            /// # Errors
            #[doc = "Returns [`MismatchedCapacity`] if `CAP > `[`" $t "::MAX`]."]
            /// or if `CAP < 1.
            ///
            #[doc = "Will always succeed if `CAP >= 1 && CAP <= `[`" $t "::MAX`]."]
            /// # Example
            /// ```
            /// # use devela::{StringU8, char7};
            /// let s = StringU8::<1>::from_char7(char7::try_from_char('@').unwrap()).unwrap();
            /// assert_eq![s.as_str(), "@"];
            ///
            /// assert![StringU8::<0>::from_char7(char7::try_from_char('@').unwrap()).is_err()];
            /// ```
            pub const fn from_char7(c: char7) -> Result<Self, MismatchedCapacity> {
                is![CAP == 0, return Err(MismatchedCapacity::too_small(CAP, 1))];
                let mut new = unwrap![ok? Self::new_checked()];
                new.arr[0] = c.to_utf8_bytes()[0];
                new.len = 1;
                Ok(new)
            }

            #[doc = "Creates a new `String" $t:camel "` from a `char8`."]
            ///
            /// # Errors
            #[doc = "Returns [`MismatchedCapacity`] if `CAP > `[`" $t "::MAX`]."]
            /// or if `CAP < 2.
            ///
            #[doc = "Will always succeed if `CAP >= 2 && CAP <= `[`" $t "::MAX`]."]
            /// # Example
            /// ```
            /// # use devela::{StringU8, char8};
            /// let s = StringU8::<2>::from_char8(char8::try_from_char('ß').unwrap()).unwrap();
            /// assert_eq![s.as_str(), "ß"];
            ///
            /// assert![StringU8::<1>::from_char8(char8::try_from_char('ß').unwrap()).is_err()];
            /// ```
            pub const fn from_char8(c: char8) -> Result<Self, MismatchedCapacity> {
                let bytes = c.to_utf8_bytes();
                let len = Char(bytes[0]).len_utf8_unchecked();
                is![CAP < len, return Err(MismatchedCapacity::too_small(CAP, len))];
                let mut new = unwrap![ok? Self::new_checked()];
                new.len = len as $t;
                new.arr[0] = bytes[0];
                if len > 1 { new.arr[1] = bytes[1]; }
                Ok(new)
            }

            #[doc = "Creates a new `String" $t:camel "` from a `char16`."]
            ///
            /// # Errors
            #[doc = "Returns [`MismatchedCapacity`] if `CAP > `[`" $t
                "::MAX`]` || CAP < c.`[`len_utf8()`][char16#method.len_utf8]."]
            ///
            #[doc = "Will always succeed if `CAP >= 3 && CAP <= `[`" $t "::MAX`]."]
            /// # Example
            /// ```
            /// # use devela::{StringU8, char16};
            /// let s = StringU8::<3>::from_char16(char16::try_from_char('€').unwrap()).unwrap();
            /// assert_eq![s.as_str(), "€"];
            ///
            /// assert![StringU8::<2>::from_char16(char16::try_from_char('€').unwrap()).is_err()];
            /// ```
            pub const fn from_char16(c: char16) -> Result<Self, MismatchedCapacity> {
                let bytes = c.to_utf8_bytes();
                let len = Char(bytes[0]).len_utf8_unchecked();
                is![CAP < len, return Err(MismatchedCapacity::too_small(CAP, len))];
                let mut new = unwrap![ok? Self::new_checked()];
                new.len = len as $t;
                new.arr[0] = bytes[0];
                if len > 1 { new.arr[1] = bytes[1]; }
                if len > 2 { new.arr[2] = bytes[2]; }
                // slice![mut &mut new.arr, 0,..len].copy_from_slice(slice![&bytes, 0,..len]);
                Ok(new)
            }

            #[doc = "Creates a new `String" $t:camel "` from a `charu`."]
            ///
            /// # Errors
            #[doc = "Returns [`MismatchedCapacity`] if `CAP > `[`" $t
                "::MAX`]` || CAP < c.`[`len_utf8()`][charu#method.len_utf8]."]
            ///
            #[doc = "Will always succeed if `CAP >= 4 && CAP <= `[`" $t "::MAX`]."]
            /// # Example
            /// ```
            /// # use devela::{StringU8, charu};
            /// let s = StringU8::<4>::from_charu(charu::from_char('🐛')).unwrap();
            /// assert_eq![s.as_str(), "🐛"];
            ///
            /// assert![StringU8::<3>::from_charu(charu::from_char('🐛')).is_err()];
            /// ```
            pub const fn from_charu(c: charu) -> Result<Self, MismatchedCapacity> {
                let (bytes, len) = (c.to_utf8_bytes(), c.len_utf8());
                if len <= CAP {
                    let mut new = unwrap![ok? Self::new_checked()];
                    slice![mut &mut new.arr, 0,..len].copy_from_slice(slice![&bytes, 0,..len]);
                    new.len = len as $t;
                    Ok(new)
                } else {
                    Err(MismatchedCapacity::too_small(CAP, len))
                }
            }

            #[doc = "Creates a new `String" $t:camel "` from a `charu`."]
            ///
            /// # Panics
            #[doc = "Panics if `CAP > `[`" $t
                "::MAX`]` || CAP < c.`[`len_utf8()`][charu#method.len_utf8]."]
            ///
            #[doc = "Will always succeed if `CAP >= 4 && CAP <= `[`" $t "::MAX`]."]
            /// # Examples
            /// ```
            /// # use devela::{StringU8, charu};
            /// let s = StringU8::<3>::from_charu_unchecked(charu::from_char('€'));
            /// assert_eq![s, "€"]
            /// ```
            /// ```should_panic
            /// # use devela::{StringU8, charu};
            /// StringU8::<2>::from_charu_unchecked(charu::from_char('€'));
            /// ```
            pub const fn from_charu_unchecked(c: charu) -> Self {
                let (bytes, len) = (c.to_utf8_bytes(), c.len_utf8());
                let mut new = Self::new();
                slice![mut &mut new.arr, 0,..len].copy_from_slice(slice![&bytes, 0,..len]);
                new.len = len as $t;
                new
            }

            /* from_array* conversions */

            /// Returns a string from a slice of `bytes`.
            ///
            /// # Errors
            /// Returns [`InvalidUtf8`] if the bytes are not valid UTF-8.
            pub const fn from_array(bytes: [u8; CAP]) -> Result<Self, InvalidUtf8> {
                match Str::from_utf8(&bytes) {
                    Ok(_) => { Ok(Self { arr: bytes, len: CAP as $t }) },
                    Err(e) => Err(e),
                }
            }

            /// Returns a string from an array of `bytes` that must be valid UTF-8.
            ///
            /// # Safety
            /// The caller must ensure that the content of the slice is valid UTF-8.
            ///
            /// Use of a `str` whose contents are not valid UTF-8 is undefined behavior.
            #[cfg(all(not(feature = "safe_text"), feature = "unsafe_str"))]
            #[cfg_attr(nightly_doc, doc(cfg(feature = "unsafe_str")))]
            pub const unsafe fn from_array_unchecked(bytes: [u8; CAP]) -> Self {
                Self { arr: bytes, len: CAP as $t }
            }
            /// Internal accessor for trusted formatting operations, avoiding safe re-validation.
            #[inline(always)]
            pub(crate) const fn _from_array_len_trusted(array: [u8; CAP], len: $t) -> Self {
                Self { arr: array, len }
            }

            /// Returns a string from an array of `bytes`,
            /// truncated to `n` bytes counting from the left.
            ///
            /// The new `length` is maxed out at `CAP`.
            ///
            /// # Errors
            /// Returns [`InvalidUtf8`] if the bytes are not valid UTF-8.
            pub const fn from_array_nleft(bytes: [u8; CAP], length: $t)
            -> Result<Self, InvalidUtf8> {
                let length = Cmp(length).min(CAP as $t);
                match Str::from_utf8(slice![&bytes, ..length as usize]) {
                    Ok(_) => Ok(Self { arr: bytes, len: length }),
                    Err(e) => Err(e),
                }
            }

            /// Returns a string from an array of `bytes`, which must be valid UTF-8,
            /// truncated to `n` bytes counting from the left.
            ///
            /// The new `length` is maxed out at `CAP`.
            ///
            /// # Safety
            /// The caller must ensure that the content of the truncated slice is valid UTF-8.
            ///
            /// Use of a `str` whose contents are not valid UTF-8 is undefined behavior.
            #[cfg(all(not(feature = "safe_text"), feature = "unsafe_str"))]
            #[cfg_attr(nightly_doc, doc(cfg(feature = "unsafe_str")))]
            pub const unsafe fn from_array_nleft_unchecked(bytes: [u8; CAP], length: $t)
                -> Self {
                Self { arr: bytes, len: Cmp(length).min(CAP as $t) }
            }

            /// Returns a string from an array of `bytes`,
            /// truncated to `n` bytes counting from the right.
            ///
            /// The new `length` is maxed out at `CAP`.
            /// Bytes are shift-copied without allocating a new array.
            ///
            /// # Errors
            /// Returns [`InvalidUtf8`] if the bytes are not valid UTF-8.
            pub const fn from_array_nright(mut bytes: [u8; CAP], length: $t)
            -> Result<Self, InvalidUtf8> {
                let length = Cmp(length).min(CAP as $t);
                let ulen = length as usize;
                let start = CAP - ulen;
                whilst![i in 0..ulen; bytes[i] = bytes[start + i]];
                match Str::from_utf8(slice![&bytes, ..ulen]) {
                    Ok(_) => Ok(Self { arr: bytes, len: length }),
                    Err(e) => Err(e),
                }
            }

            /// Returns a string from an array of `bytes`, which must be valid UTF-8,
            /// truncated to `n` bytes counting from the right.
            ///
            /// The new `length` is maxed out at `CAP`.
            /// Bytes are shift-copied without allocating a new array.
            ///
            /// # Safety
            /// The caller must ensure that the content of the truncated slice is valid UTF-8.
            ///
            /// Use of a `str` whose contents are not valid UTF-8 is undefined behavior.
            #[cfg(all(not(feature = "safe_text"), feature = "unsafe_str"))]
            #[cfg_attr(nightly_doc, doc(cfg(feature = "unsafe_str")))]
            pub const unsafe fn from_array_nright_unchecked(mut bytes: [u8; CAP], length: $t)
                -> Self {
                let length = Cmp(length).min(CAP as $t);
                let ulen = length as usize;
                let start = CAP - ulen;
                whilst![i in 0..ulen; bytes[i] = bytes[start + i]];
                Self { arr: bytes, len: length }
            }
        }

        /// # Deconstructors
        impl<const CAP: usize> $name<CAP> {
            /// Returns the inner array with the full contents.
            ///
            /// The array contains all the bytes, including those outside the current length.
            #[must_use] #[inline(always)]
            pub const fn into_array(self) -> [u8; CAP] { self.arr }

            /// Returns a copy of the inner array with the full contents.
            ///
            /// The array contains all the bytes, including those outside the current length.
            #[must_use] #[inline(always)]
            pub const fn as_array(&self) -> &[u8; CAP] { &self.arr }

            /// Returns a byte slice of the inner string slice.
            ///
            /// # Features
            /// Uses the `unsafe_slice` feature to skip validation checks.
            #[must_use] #[inline(always)]
            pub const fn as_bytes(&self) -> &[u8] {
                #[cfg(any(feature = "safe_text", not(feature = "unsafe_slice")))]
                return slice![&self.arr, ..self.len as usize];

                #[cfg(all(not(feature = "safe_text"), feature = "unsafe_slice"))]
                // SAFETY: we ensure to contain a correct length
                unsafe { slice![unchecked &self.arr, ..self.len as usize] }
            }

            /// Returns an exclusive byte slice of the inner string slice.
            ///
            /// # Safety
            /// The caller must ensure that the content of the slice is valid UTF-8
            /// before the borrow ends and the underlying `str` is used.
            ///
            /// # Features
            /// Uses the `unsafe_slice` feature to skip validation checks.
            #[must_use] #[inline(always)]
            #[cfg(all(not(feature = "safe_text"), feature = "unsafe_str"))]
            #[cfg_attr(nightly_doc, doc(cfg(feature = "unsafe_str")))]
            pub const unsafe fn as_bytes_mut(&mut self) -> &mut [u8] {
                #[cfg(any(feature = "safe_text", not(feature = "unsafe_slice")))]
                return slice![mut &mut self.arr, ..self.len as usize];

                #[cfg(all(not(feature = "safe_text"), feature = "unsafe_slice"))]
                // SAFETY: we ensure to contain a correct length
                unsafe { slice![mut_unchecked &mut self.arr, ..self.len as usize] }
            }

            /// Returns a reference to the inner string slice.
            ///
            /// # Features
            /// Uses the `unsafe_str` feature to skip validation checks.
            #[must_use]
            #[inline(always)]
            pub const fn as_str(&self) -> &str {
                #[cfg(any(feature = "safe_text", not(feature = "unsafe_str")))]
                return unwrap![ok_expect Str::from_utf8(self.as_bytes()), "Invalid UTF-8"];

                #[cfg(all(not(feature = "safe_text"), feature = "unsafe_str"))]
                // SAFETY: we ensure to contain only valid UTF-8
                unsafe { Str::from_utf8_unchecked(self.as_bytes()) }
            }

            /// Returns an exclusive reference to the inner string slice.
            ///
            /// # Safety
            /// The caller must ensure that the content of the slice is valid UTF-8
            /// before the borrow ends and the underlying `str` is used.
            #[must_use] #[inline(always)]
            #[cfg(all(not(feature = "safe_text"), feature = "unsafe_str"))]
            #[cfg_attr(nightly_doc, doc(cfg(feature = "unsafe_str")))]
            pub const unsafe fn as_mut_str(&mut self) -> &mut str {
                // SAFETY: we ensure to contain only valid UTF-8
                unsafe { Str::from_utf8_unchecked_mut(self.as_bytes_mut()) }
            }

            /// Returns an iterator over the `chars` of the string.
            ///
            /// # Features
            /// Uses the `unsafe_str` feature to skip validation checks.
            #[inline(always)]
            pub const fn chars(&self) -> CharIter<'_, &str> {
                CharIter::<&str>::new(self.as_str())
            }
        }

        /// # Queries
        impl<const CAP: usize> $name<CAP> {
            /// Returns the current string length in bytes.
            #[must_use]
            #[inline(always)]
            pub const fn len(&self) -> usize { self.len as usize }

            /// Returns `true` if the current length is 0.
            #[must_use]
            #[inline(always)]
            pub const fn is_empty(&self) -> bool { self.len == 0 }

            /// Returns `true` if the current remaining capacity is 0.
            #[must_use]
            #[inline(always)]
            pub const fn is_full(&self) -> bool { self.len == CAP as $t }

            /// Returns the total capacity in bytes.
            #[must_use]
            #[inline(always)]
            pub const fn capacity() -> usize { CAP }

            /// Returns the remaining capacity in bytes.
            #[must_use]
            #[inline(always)]
            pub const fn remaining_capacity(&self) -> usize { CAP - self.len as usize }

            /// Checks the equality of two strings, with the same capacity and length.
            ///
            /// It only checks the first `self.len()` bytes.
            /// # Example
            /// ```
            /// # use devela::StringU8;
            /// let mut a = StringU8::<16>::from_str_unchecked("hello world!");
            /// let mut b = StringU8::<16>::from_str_unchecked("hello world!!!");
            /// assert![!a.eq(&b)];
            /// b.pop();
            /// b.pop();
            /// assert![a.eq(&b)];
            /// ```
            #[must_use]
            #[inline(always)]
            pub const fn eq(&self, other: &Self) -> bool {
                self.len == other.len && {
                    whilst![i in 0..self.len(); is![self.arr[i] != other.arr[i], return false]];
                    true
                }
            }
        }

        /// # Modifiers
        impl<const CAP: usize> $name<CAP> {
            /// Sets the length to 0.
            #[inline(always)]
            pub const fn clear(&mut self) { self.len = 0; }

            /// Sets the length to 0, and resets all the bytes to 0.
            #[inline(always)]
            pub const fn reset(&mut self) { self.arr = [0; CAP]; self.len = 0; }

            /// Zeros all unused bytes while maintaining the current length.
            #[inline(always)]
            pub const fn sanitize(&mut self) {
                whilst![i in (self.len as usize),..CAP; self.arr[i] = 0];
            }

            /// Removes the last character and returns it, or `None` if the string is empty.
            #[must_use]
            pub const fn pop(&mut self) -> Option<char> {
                if self.is_empty() { None } else { Some(self.pop_unchecked()) }
            }

            /// Tries to remove the last character and returns it.
            ///
            /// # Errors
            /// Returns a [`NotEnoughElements`] error
            /// if the capacity is not enough to hold the `character`.
            pub const fn try_pop(&mut self) -> Result<char, NotEnoughElements> {
                is![self.is_empty(), Err(NotEnoughElements(Some(1))), Ok(self.pop_unchecked())]
            }

            /// Removes the last character and returns it.
            ///
            /// # Panics
            /// Panics if the string is empty.
            ///
            /// # Example
            /// ```
            /// # use devela::StringU8;
            /// let mut s = StringU8::<16>::new();
            /// s.push_str("hello worlð!");
            /// assert_eq![s.len(), 13];
            ///
            /// assert_eq![s.pop_unchecked(), '!'];
            /// assert_eq![s.len(), 12];
            ///
            /// assert_eq![s.pop_unchecked(), 'ð'];
            /// assert_eq![s.len(), 10];
            /// ```
            pub const fn pop_unchecked(&mut self) -> char {
                let string = self.as_str();
                let mut index = string.len();
                whilst![index > 0 && !string.is_char_boundary(index - 1); index -= 1];
                let idx_last_char = index - 1;
                let range = Str::range_from(string, idx_last_char);
                let last_char = unwrap![some CharIter::<&str>::new(range).next_char()];
                self.len -= last_char.len_utf8() as $t;
                last_char
            }

            /// Appends to the end of the string the given `character`.
            ///
            /// Returns the number of bytes written.
            ///
            /// Returns 0 bytes if the given `character` doesn't fit in the remaining capacity.
            pub const fn push(&mut self, character: char) -> usize {
                let char_len = character.len_utf8();
                if self.remaining_capacity() >= char_len {
                    let beg = self.len as usize;
                    let end = beg + char_len;
                    let _ = character.encode_utf8(slice![mut &mut self.arr, beg, ..end]);
                    self.len += char_len as $t;
                    char_len
                } else {
                    0
                }
            }

            /// Tries to append to the end of the string the given `character`.
            ///
            /// Returns the number of bytes written.
            ///
            /// # Errors
            /// Returns [`NotEnoughSpace`]
            /// if the available capacity is not enough to hold the given `character`.
            pub const fn try_push(&mut self, character: char) -> Result<usize, NotEnoughSpace> {
                let char_len = character.len_utf8();
                if self.remaining_capacity() >= char_len {
                    let beg = self.len as usize;
                    let end = beg + char_len;
                    let _ = character.encode_utf8(slice![mut &mut self.arr, beg, ..end]);
                    self.len += char_len as $t;
                    Ok(char_len)
                } else {
                    Err(NotEnoughSpace(Some(char_len)))
                }
            }

            /// Appends to the end of the string the given character.
            ///
            /// Returns the number of bytes written.
            ///
            /// Returns 0 bytes if the given `character` doesn't fit in the remaining capacity.
            pub const fn push_charu(&mut self, c: charu) -> usize {
                let (bytes, len) = (c.to_utf8_bytes(), c.len_utf8());
                if self.remaining_capacity() >= len {
                    slice![mut &mut self.arr, 0,..len].copy_from_slice(slice![&bytes, 0,..len]);
                    self.len = len as $t;
                    len
                } else {
                    0
                }
            }

            /// Appends as many complete characters from `string` as will fit.
            ///
            /// Returns the number of bytes written. UTF-8 characters are never split.
            ///
            /// # Example
            /// ```
            /// # use devela::StringU8;
            /// let mut s = StringU8::<5>::new();
            /// assert_eq!(s.push_str("café"), 5);
            /// assert_eq!(s, "café");
            ///
            /// let mut s = StringU8::<4>::new();
            /// assert_eq!(s.push_str("café"), 3);
            /// assert_eq!(s, "caf");
            ///
            /// let mut s = StringU8::<2>::new();
            /// assert_eq!(s.push_str("サ"), 0);
            /// assert_eq!(s, "");
            /// ```
            pub const fn push_str(&mut self, string: &str) -> usize {
                let remaining_capacity = CAP - self.len as usize;
                is! { remaining_capacity == 0, return 0 }
                let string_len = string.len();
                let bytes_to_write = if string_len <= remaining_capacity {
                    string_len
                } else {
                    let mut amount = remaining_capacity;
                    while amount > 0 && !string.is_char_boundary(amount) { amount -= 1; }
                    amount
                };
                if bytes_to_write > 0 {
                    let start_pos = self.len as usize;
                    slice![mut &mut self.arr, start_pos, ..start_pos+bytes_to_write]
                        .copy_from_slice(slice![string.as_bytes(), ..bytes_to_write]);
                    self.len += bytes_to_write as $t;
                    bytes_to_write
                } else {
                    0
                }
            }

            /// Appends characters from `string`, returning `Ok` if all fit, `Err` if partial.
            ///
            /// - `Ok(bytes)`: Entire string was written successfully
            /// - `Err(partial)`: Only `partial` bytes could be written (UTF-8 safe)
            ///
            /// In both cases, the bytes are appended to the buffer.
            pub const fn try_push_str(&mut self, string: &str) -> Result<usize, usize> {
                let bytes_written = self.push_str(string);
                is![bytes_written == string.len(), Ok(bytes_written), Err(bytes_written)]
            }

            /// Appends the entire `string` or nothing at all.
            ///
            /// Returns `Ok(bytes)` if the string fits completely, or `Err(0)` if it doesn't.
            /// No partial writes will occur to the buffer.
            pub const fn try_push_str_complete(&mut self, string: &str) -> Result<usize, usize> {
                is![self.remaining_capacity() >= string.len(), Ok(self.push_str(string)), Err(0)]
            }
        }

        /* utility traits */

        impl<const CAP: usize> Default for $name<CAP> {
            /// Returns an empty string.
            /// # Panics
            #[doc = "Panics if `CAP > `[`" $t "::MAX`]."]
            fn default() -> Self { Self::new() }
        }
        impl<const CAP: usize> ConstInit for $name<CAP> {
            /// Returns an empty string.
            /// # Panics
            #[doc = "Panics if `CAP > `[`" $t "::MAX`]."]
            const INIT: Self = Self::new();
        }

        impl<const CAP: usize> Display for $name<CAP> {
            fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult<()> {
                f.write_str(self.as_str())
            }
        }

        impl<const CAP: usize> Debug for $name<CAP> {
            fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult<()> {
                write!(f, "{:?}", self.as_str())
            }
        }

        /// Leverages [`try_push`][Self::try_push] and [`try_push_str`][Self::try_push_str].
        impl<const CAP: usize> FmtWrite for $name<CAP> {
            fn write_str(&mut self, s: &str) -> FmtResult<()> {
                self.try_push_str(s).map_err(|_| FmtError)?;
                Ok(())
            }
            fn write_char(&mut self, c: char) -> FmtResult<()> {
                self.try_push(c).map_err(|_| FmtError)?;
                Ok(())
            }
        }

        impl<const CAP: usize> PartialEq for $name<CAP> {
            fn eq(&self, other: &Self) -> bool { self.eq(&other) }
        }

        impl<const CAP: usize> PartialEq<str> for $name<CAP> { // str on the RHS
            fn eq(&self, string: &str) -> bool { self.as_str() == string }
        }
        impl<const CAP: usize> PartialEq<&str> for $name<CAP> { // &str on the RHS
            fn eq(&self, string: &&str) -> bool { self.as_str() == *string }
        }
        impl<const CAP: usize> PartialEq<&[u8]> for $name<CAP> { // &[u8] on the RHS
            fn eq(&self, bytes: &&[u8]) -> bool { self.as_bytes() == *bytes }
        }

        impl<const CAP: usize> PartialEq<$name<CAP>> for str { // str on the LHS
            fn eq(&self, string: &$name<CAP>) -> bool { self == string.as_str() }
        }
        impl<const CAP: usize> PartialEq<$name<CAP>> for &str { // &str on the LHS
            fn eq(&self, string: &$name<CAP>) -> bool { *self == string.as_str() }
        }
        impl<const CAP: usize> PartialEq<$name<CAP>> for &[u8] { // &[u8] on the LHS
            fn eq(&self, string: &$name<CAP>) -> bool { *self == string.as_bytes() }
        }

        impl<const CAP: usize> Hash for $name<CAP> {
            fn hash<H: Hasher>(&self, state: &mut H) {
                self.len.hash(state);
                self.arr[..self.len as usize].hash(state);
            }
        }

        impl<const CAP: usize> Deref for $name<CAP> {
            type Target = str;
            fn deref(&self) -> &Self::Target { self.as_str() }
        }

        impl<const CAP: usize> AsRef<str> for $name<CAP> {
            fn as_ref(&self) -> &str { self.as_str() }
        }

        impl<const CAP: usize> AsRef<[u8]> for $name<CAP> {
            fn as_ref(&self) -> &[u8] { self.as_bytes() }
        }

        /* conversions */

        impl<const CAP: usize> TryFrom<&str> for $name<CAP> {
            type Error = MismatchedCapacity;

            #[doc = "Tries to create a new `String" $t:camel "` from the given `string` slice."]
            ///
            /// This is implemented via `Self::`[`from_str()`][Self::from_str].
            /// # Errors
            #[doc = "Returns [`MismatchedCapacity`] if `CAP > `[`" $t "::MAX`]"]
            /// or if `CAP < string.len()`.
            fn try_from(string: &str) -> Result<Self, MismatchedCapacity> { Self::from_str(string) }
        }

        impl<const CAP: usize> TryFrom<&[u8]> for $name<CAP> {
            type Error = InvalidText;

            #[doc = "Tries to create a new `String" $t:camel "` from the given slice of` bytes`."]
            ///
            /// # Errors
            #[doc = "Returns [`InvalidText::MismatchedCapacity`] if `CAP > `[`" $t "::MAX`],"]
            /// or if `CAP < bytes.len()`, and [`InvalidText::Utf8`] if `bytes` are not valid UTF-8.
            fn try_from(bytes: &[u8]) -> Result<Self, InvalidText> {
                let bytes_len = bytes.len();
                if CAP < bytes_len { Err(MismatchedCapacity::too_small(CAP, bytes_len).into()) }
                else {
                    match Str::from_utf8(bytes) {
                        Ok(_) => {
                            let mut arr = [0; CAP];
                            arr[..bytes_len].copy_from_slice(bytes);
                            Ok(Self { arr, len: bytes_len as $t })
                        },
                        Err(e) => Err(e.into()),
                    }
                }
            }
        }

        /* Extend & FromIterator */

        impl<const CAP: usize> Extend<char> for $name<CAP> {
            /// Creates an instance from an iterator of characters.
            ///
            /// Processes characters until it can fit no more, discarding the rest.
            ///
            /// # Panics
            #[doc = "Panics if `CAP > `[`" $t "::MAX`]."]
            ///
            /// # Example
            /// ```
            /// # use devela::StringU8;
            /// let chars = ['a', 'b', 'c', '€', 'さ'];
            /// let mut s = StringU8::<6>::new();
            /// s.extend(chars);
            /// assert_eq![s, "abc€"];
            /// ```
            fn extend<I: IntoIterator<Item=char>>(&mut self, iter: I) {
                for i in iter { is![self.push(i) == 0, break]; }
            }
        }
        impl<const CAP: usize> FromIterator<char> for $name<CAP> {
            /// Creates an instance from an iterator of characters.
            ///
            /// Processes characters until it can fit no more, discarding the rest.
            ///
            /// # Panics
            #[doc = "Panics if `CAP > `[`" $t "::MAX`]."]
            ///
            /// # Example
            /// ```
            /// # use devela::StringU8;
            /// let chars = ['a', 'b', 'c', '€', 'さ'];
            /// assert_eq!(StringU8::<9>::from_iter(chars), "abc€さ");
            /// assert_eq!(StringU8::<6>::from_iter(chars), "abc€");
            /// assert_eq!(StringU8::<5>::from_iter(chars), "abc");
            /// assert_eq!(StringU8::<2>::from_iter(chars), "ab");
            /// assert_eq!(StringU8::<0>::from_iter(chars), "");
            /// ```
            fn from_iter<I: IntoIterator<Item=char>>(iter: I) -> Self {
                let mut string = $name::new();
                string.extend(iter);
                string
            }
        }
    }};
}
impl_str_u!();

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

    #[test]
    fn push() {
        let mut s = StringU8::<3>::new();
        assert![s.try_push('ñ').is_ok()];
        assert_eq![2, s.len()];
        assert![s.try_push('ñ').is_err()];
        assert_eq![2, s.len()];
        assert![s.try_push('a').is_ok()];
        assert_eq![3, s.len()];
    }
    #[test]
    fn push_str() {
        let mut s = StringU8::<5>::new();
        assert_eq!(s.push_str("café"), 5);

        let mut s = StringU8::<4>::new();
        assert_eq!(s.push_str("café"), 3);
        assert_eq!(s, "caf")
    }
    #[test]
    fn try_push_str() {
        let mut s = StringU8::<5>::new();
        assert_eq!(s.try_push_str("café"), Ok(5));

        let mut s = StringU8::<4>::new();
        assert_eq!(s.try_push_str("café"), Err(3));
        assert_eq!(s, "caf")
    }
    #[test]
    fn try_push_str_complete() {
        let mut s = StringU8::<5>::new();
        assert_eq!(s.try_push_str_complete("café"), Ok(5));

        let mut s = StringU8::<4>::new();
        assert_eq!(s.try_push_str_complete("café"), Err(0));
        assert_eq!(s, "")
    }

    #[test]
    fn pop() {
        let mut s = StringU8::<3>::new();
        s.push('ñ');
        s.push('a');
        assert_eq![Some('a'), s.pop()];
        assert_eq![Some('ñ'), s.pop()];
        assert_eq![None, s.pop()];
    }
}