ascii_string.rs

use alloc::borrow::{Borrow, BorrowMut, Cow, ToOwned};
use alloc::fmt;
use alloc::string::String;
use alloc::vec::Vec;
use alloc::boxed::Box;
use alloc::rc::Rc;
use alloc::sync::Arc;
#[cfg(feature = "std")]
use core::any::Any;
use core::iter::FromIterator;
use core::mem;
use core::ops::{Add, AddAssign, Deref, DerefMut, Index, IndexMut};
use core::str::FromStr;
#[cfg(feature = "std")]
use std::error::Error;
#[cfg(feature = "std")]
use std::ffi::{CStr, CString};

use ascii_char::AsciiChar;
use ascii_str::{AsAsciiStr, AsAsciiStrError, AsciiStr};

/// A growable string stored as an ASCII encoded buffer.
#[derive(Clone, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[repr(transparent)]
pub struct AsciiString {
    vec: Vec<AsciiChar>,
}

impl AsciiString {
    /// Creates a new, empty ASCII string buffer without allocating.
    ///
    /// # Examples
    /// ```
    /// # use ascii::AsciiString;
    /// let mut s = AsciiString::new();
    /// ```
    #[inline]
    #[must_use]
    pub const fn new() -> Self {
        AsciiString { vec: Vec::new() }
    }

    /// Creates a new ASCII string buffer with the given capacity.
    /// The string will be able to hold exactly `capacity` bytes without reallocating.
    /// If `capacity` is 0, the ASCII string will not allocate.
    ///
    /// # Examples
    /// ```
    /// # use ascii::AsciiString;
    /// let mut s = AsciiString::with_capacity(10);
    /// ```
    #[inline]
    #[must_use]
    pub fn with_capacity(capacity: usize) -> Self {
        AsciiString {
            vec: Vec::with_capacity(capacity),
        }
    }

    /// Creates a new `AsciiString` from a length, capacity and pointer.
    ///
    /// # Safety
    ///
    /// This is highly unsafe, due to the number of invariants that aren't checked:
    ///
    /// * The memory at `buf` need to have been previously allocated by the same allocator this
    ///   library uses, with an alignment of 1.
    /// * `length` needs to be less than or equal to `capacity`.
    /// * `capacity` needs to be the correct value.
    /// * `buf` must have `length` valid ascii elements and contain a total of `capacity` total,
    ///   possibly, uninitialized, elements.
    /// * Nothing else must be using the memory `buf` points to.
    ///
    /// Violating these may cause problems like corrupting the allocator's internal data structures.
    ///
    /// # Examples
    ///
    /// Basic usage:
    ///
    /// ```
    /// # use ascii::AsciiString;
    /// use std::mem;
    ///
    /// unsafe {
    ///    let mut s = AsciiString::from_ascii("hello").unwrap();
    ///    let ptr = s.as_mut_ptr();
    ///    let len = s.len();
    ///    let capacity = s.capacity();
    ///
    ///    mem::forget(s);
    ///
    ///    let s = AsciiString::from_raw_parts(ptr, len, capacity);
    ///
    ///    assert_eq!(AsciiString::from_ascii("hello").unwrap(), s);
    /// }
    /// ```
    #[inline]
    #[must_use]
    pub unsafe fn from_raw_parts(buf: *mut AsciiChar, length: usize, capacity: usize) -> Self {
        AsciiString {
            // SAFETY: Caller guarantees that `buf` was previously allocated by this library,
            //         that `buf` contains `length` valid ascii elements and has a total capacity
            //         of `capacity` elements, and that nothing else is using the momory.
            vec: unsafe { Vec::from_raw_parts(buf, length, capacity) },
        }
    }

    /// Converts a vector of bytes to an `AsciiString` without checking for non-ASCII characters.
    ///
    /// # Safety
    /// This function is unsafe because it does not check that the bytes passed to it are valid
    /// ASCII characters. If this constraint is violated, it may cause memory unsafety issues with
    /// future of the `AsciiString`, as the rest of this library assumes that `AsciiString`s are
    /// ASCII encoded.
    #[inline]
    #[must_use]
    pub unsafe fn from_ascii_unchecked<B>(bytes: B) -> Self
    where
        B: Into<Vec<u8>>,
    {
        let mut bytes = bytes.into();
        // SAFETY: The caller guarantees all bytes are valid ascii bytes.
        let ptr = bytes.as_mut_ptr().cast::<AsciiChar>();
        let length = bytes.len();
        let capacity = bytes.capacity();
        mem::forget(bytes);

        // SAFETY: We guarantee all invariants, as we got the
        //         pointer, length and capacity from a `Vec`,
        //         and we also guarantee the pointer is valid per
        //         the `SAFETY` notice above.
        let vec = Vec::from_raw_parts(ptr, length, capacity);

        Self { vec }
    }

    /// Converts anything that can represent a byte buffer into an `AsciiString`.
    ///
    /// # Errors
    /// Returns the byte buffer if not all of the bytes are ASCII characters.
    ///
    /// # Examples
    /// ```
    /// # use ascii::AsciiString;
    /// let foo = AsciiString::from_ascii("foo".to_string()).unwrap();
    /// let err = AsciiString::from_ascii("Ŋ".to_string()).unwrap_err();
    /// assert_eq!(foo.as_str(), "foo");
    /// assert_eq!(err.into_source(), "Ŋ");
    /// ```
    pub fn from_ascii<B>(bytes: B) -> Result<AsciiString, FromAsciiError<B>>
    where
        B: Into<Vec<u8>> + AsRef<[u8]>,
    {
        match bytes.as_ref().as_ascii_str() {
            // SAFETY: `as_ascii_str` guarantees all bytes are valid ascii bytes.
            Ok(_) => Ok(unsafe { AsciiString::from_ascii_unchecked(bytes) }),
            Err(e) => Err(FromAsciiError {
                error: e,
                owner: bytes,
            }),
        }
    }

    /// Pushes the given ASCII string onto this ASCII string buffer.
    ///
    /// # Examples
    /// ```
    /// # use ascii::{AsciiString, AsAsciiStr};
    /// use std::str::FromStr;
    /// let mut s = AsciiString::from_str("foo").unwrap();
    /// s.push_str("bar".as_ascii_str().unwrap());
    /// assert_eq!(s, "foobar".as_ascii_str().unwrap());
    /// ```
    #[inline]
    pub fn push_str(&mut self, string: &AsciiStr) {
        self.vec.extend(string.chars());
    }

    /// Inserts the given ASCII string at the given place in this ASCII string buffer.
    ///
    /// # Panics
    ///
    /// Panics if `idx` is larger than the `AsciiString`'s length.
    ///
    /// # Examples
    /// ```
    /// # use ascii::{AsciiString, AsAsciiStr};
    /// use std::str::FromStr;
    /// let mut s = AsciiString::from_str("abc").unwrap();
    /// s.insert_str(1, "def".as_ascii_str().unwrap());
    /// assert_eq!(&*s, "adefbc");
    #[inline]
    pub fn insert_str(&mut self, idx: usize, string: &AsciiStr) {
        self.vec.reserve(string.len());
        self.vec.splice(idx..idx, string.into_iter().copied());
    }

    /// Returns the number of bytes that this ASCII string buffer can hold without reallocating.
    ///
    /// # Examples
    /// ```
    /// # use ascii::AsciiString;
    /// let s = String::with_capacity(10);
    /// assert!(s.capacity() >= 10);
    /// ```
    #[inline]
    #[must_use]
    pub fn capacity(&self) -> usize {
        self.vec.capacity()
    }

    /// Reserves capacity for at least `additional` more bytes to be inserted in the given
    /// `AsciiString`. The collection may reserve more space to avoid frequent reallocations.
    ///
    /// # Panics
    /// Panics if the new capacity overflows `usize`.
    ///
    /// # Examples
    /// ```
    /// # use ascii::AsciiString;
    /// let mut s = AsciiString::new();
    /// s.reserve(10);
    /// assert!(s.capacity() >= 10);
    /// ```
    #[inline]
    pub fn reserve(&mut self, additional: usize) {
        self.vec.reserve(additional);
    }

    /// Reserves the minimum capacity for exactly `additional` more bytes to be inserted in the
    /// given `AsciiString`. Does nothing if the capacity is already sufficient.
    ///
    /// Note that the allocator may give the collection more space than it requests. Therefore
    /// capacity can not be relied upon to be precisely minimal. Prefer `reserve` if future
    /// insertions are expected.
    ///
    /// # Panics
    /// Panics if the new capacity overflows `usize`.
    ///
    /// # Examples
    /// ```
    /// # use ascii::AsciiString;
    /// let mut s = AsciiString::new();
    /// s.reserve_exact(10);
    /// assert!(s.capacity() >= 10);
    /// ```
    #[inline]

    pub fn reserve_exact(&mut self, additional: usize) {
        self.vec.reserve_exact(additional);
    }

    /// Shrinks the capacity of this ASCII string buffer to match it's length.
    ///
    /// # Examples
    /// ```
    /// # use ascii::AsciiString;
    /// use std::str::FromStr;
    /// let mut s = AsciiString::from_str("foo").unwrap();
    /// s.reserve(100);
    /// assert!(s.capacity() >= 100);
    /// s.shrink_to_fit();
    /// assert_eq!(s.capacity(), 3);
    /// ```
    #[inline]

    pub fn shrink_to_fit(&mut self) {
        self.vec.shrink_to_fit();
    }

    /// Adds the given ASCII character to the end of the ASCII string.
    ///
    /// # Examples
    /// ```
    /// # use ascii::{ AsciiChar, AsciiString};
    /// let mut s = AsciiString::from_ascii("abc").unwrap();
    /// s.push(AsciiChar::from_ascii('1').unwrap());
    /// s.push(AsciiChar::from_ascii('2').unwrap());
    /// s.push(AsciiChar::from_ascii('3').unwrap());
    /// assert_eq!(s, "abc123");
    /// ```
    #[inline]

    pub fn push(&mut self, ch: AsciiChar) {
        self.vec.push(ch);
    }

    /// Shortens a ASCII string to the specified length.
    ///
    /// # Panics
    /// Panics if `new_len` > current length.
    ///
    /// # Examples
    /// ```
    /// # use ascii::AsciiString;
    /// let mut s = AsciiString::from_ascii("hello").unwrap();
    /// s.truncate(2);
    /// assert_eq!(s, "he");
    /// ```
    #[inline]

    pub fn truncate(&mut self, new_len: usize) {
        self.vec.truncate(new_len);
    }

    /// Removes the last character from the ASCII string buffer and returns it.
    /// Returns `None` if this string buffer is empty.
    ///
    /// # Examples
    /// ```
    /// # #![allow(bindings_with_variant_name)]
    /// # use ascii::AsciiString;
    /// let mut s = AsciiString::from_ascii("foo").unwrap();
    /// assert_eq!(s.pop().map(|c| c.as_char()), Some('o'));
    /// assert_eq!(s.pop().map(|c| c.as_char()), Some('o'));
    /// assert_eq!(s.pop().map(|c| c.as_char()), Some('f'));
    /// assert_eq!(s.pop(), None);
    /// ```
    #[inline]
    #[must_use]
    pub fn pop(&mut self) -> Option<AsciiChar> {
        self.vec.pop()
    }

    /// Removes the ASCII character at position `idx` from the buffer and returns it.
    ///
    /// # Warning
    /// This is an O(n) operation as it requires copying every element in the buffer.
    ///
    /// # Panics
    /// If `idx` is out of bounds this function will panic.
    ///
    /// # Examples
    /// ```
    /// # use ascii::AsciiString;
    /// let mut s = AsciiString::from_ascii("foo").unwrap();
    /// assert_eq!(s.remove(0).as_char(), 'f');
    /// assert_eq!(s.remove(1).as_char(), 'o');
    /// assert_eq!(s.remove(0).as_char(), 'o');
    /// ```
    #[inline]
    #[must_use]
    pub fn remove(&mut self, idx: usize) -> AsciiChar {
        self.vec.remove(idx)
    }

    /// Inserts an ASCII character into the buffer at position `idx`.
    ///
    /// # Warning
    /// This is an O(n) operation as it requires copying every element in the buffer.
    ///
    /// # Panics
    /// If `idx` is out of bounds this function will panic.
    ///
    /// # Examples
    /// ```
    /// # use ascii::{AsciiString,AsciiChar};
    /// let mut s = AsciiString::from_ascii("foo").unwrap();
    /// s.insert(2, AsciiChar::b);
    /// assert_eq!(s, "fobo");
    /// ```
    #[inline]

    pub fn insert(&mut self, idx: usize, ch: AsciiChar) {
        self.vec.insert(idx, ch);
    }

    /// Returns the number of bytes in this ASCII string.
    ///
    /// # Examples
    /// ```
    /// # use ascii::AsciiString;
    /// let s = AsciiString::from_ascii("foo").unwrap();
    /// assert_eq!(s.len(), 3);
    /// ```
    #[inline]
    #[must_use]
    pub fn len(&self) -> usize {
        self.vec.len()
    }

    /// Returns true if the ASCII string contains zero bytes.
    ///
    /// # Examples
    /// ```
    /// # use ascii::{AsciiChar, AsciiString};
    /// let mut s = AsciiString::new();
    /// assert!(s.is_empty());
    /// s.push(AsciiChar::from_ascii('a').unwrap());
    /// assert!(!s.is_empty());
    /// ```
    #[inline]
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.len() == 0
    }

    /// Truncates the ASCII string, setting length (but not capacity) to zero.
    ///
    /// # Examples
    /// ```
    /// # use ascii::AsciiString;
    /// let mut s = AsciiString::from_ascii("foo").unwrap();
    /// s.clear();
    /// assert!(s.is_empty());
    /// ```
    #[inline]

    pub fn clear(&mut self) {
        self.vec.clear();
    }

    /// Converts this [`AsciiString`] into a [`Box`]`<`[`AsciiStr`]`>`.
    ///
    /// This will drop any excess capacity
    #[inline]
    #[must_use]
    pub fn into_boxed_ascii_str(self) -> Box<AsciiStr> {
        let slice = self.vec.into_boxed_slice();
        Box::from(slice)
    }
}

impl Deref for AsciiString {
    type Target = AsciiStr;

    #[inline]
    fn deref(&self) -> &AsciiStr {
        self.vec.as_slice().as_ref()
    }
}

impl DerefMut for AsciiString {
    #[inline]
    fn deref_mut(&mut self) -> &mut AsciiStr {
        self.vec.as_mut_slice().as_mut()
    }
}

impl PartialEq<str> for AsciiString {
    #[inline]
    fn eq(&self, other: &str) -> bool {
        **self == *other
    }
}

impl PartialEq<AsciiString> for str {
    #[inline]
    fn eq(&self, other: &AsciiString) -> bool {
        **other == *self
    }
}

macro_rules! impl_eq {
    ($lhs:ty, $rhs:ty) => {
        impl PartialEq<$rhs> for $lhs {
            #[inline]
            fn eq(&self, other: &$rhs) -> bool {
                PartialEq::eq(&**self, &**other)
            }
        }
    };
}

impl_eq! { AsciiString, String }
impl_eq! { String, AsciiString }
impl_eq! { &AsciiStr, String }
impl_eq! { String, &AsciiStr }
impl_eq! { &AsciiStr, AsciiString }
impl_eq! { AsciiString, &AsciiStr }
impl_eq! { &str, AsciiString }
impl_eq! { AsciiString, &str }

impl Borrow<AsciiStr> for AsciiString {
    #[inline]
    fn borrow(&self) -> &AsciiStr {
        &**self
    }
}

impl BorrowMut<AsciiStr> for AsciiString {
    #[inline]
    fn borrow_mut(&mut self) -> &mut AsciiStr {
        &mut **self
    }
}

impl From<Vec<AsciiChar>> for AsciiString {
    #[inline]
    fn from(vec: Vec<AsciiChar>) -> Self {
        AsciiString { vec }
    }
}

impl From<AsciiChar> for AsciiString {
    #[inline]
    fn from(ch: AsciiChar) -> Self {
        AsciiString { vec: vec![ch] }
    }
}

impl From<AsciiString> for Vec<u8> {
    fn from(mut s: AsciiString) -> Vec<u8> {
        // SAFETY: All ascii bytes are valid `u8`, as we are `repr(u8)`.
        // Note: We forget `self` to avoid `self.vec` from being deallocated.
        let ptr = s.vec.as_mut_ptr().cast::<u8>();
        let length = s.vec.len();
        let capacity = s.vec.capacity();
        mem::forget(s);

        // SAFETY: We guarantee all invariants due to getting `ptr`, `length`
        //         and `capacity` from a `Vec`. We also guarantee `ptr` is valid
        //         due to the `SAFETY` block above.
        unsafe { Vec::from_raw_parts(ptr, length, capacity) }
    }
}

impl From<AsciiString> for Vec<AsciiChar> {
    fn from(s: AsciiString) -> Vec<AsciiChar> {
        s.vec
    }
}

impl<'a> From<&'a AsciiStr> for AsciiString {
    #[inline]
    fn from(s: &'a AsciiStr) -> Self {
        s.to_ascii_string()
    }
}

impl<'a> From<&'a [AsciiChar]> for AsciiString {
    #[inline]
    fn from(s: &'a [AsciiChar]) -> AsciiString {
        s.iter().copied().collect()
    }
}

impl From<AsciiString> for String {
    #[inline]
    fn from(s: AsciiString) -> String {
        // SAFETY: All ascii bytes are `utf8`.
        unsafe { String::from_utf8_unchecked(s.into()) }
    }
}

impl From<Box<AsciiStr>> for AsciiString {
    #[inline]
    fn from(boxed: Box<AsciiStr>) -> Self {
        boxed.into_ascii_string()
    }
}

impl From<AsciiString> for Box<AsciiStr> {
    #[inline]
    fn from(string: AsciiString) -> Self {
        string.into_boxed_ascii_str()
    }
}

impl From<AsciiString> for Rc<AsciiStr> {
    fn from(s: AsciiString) -> Rc<AsciiStr> {
        let var: Rc<[AsciiChar]> = s.vec.into();
        // SAFETY: AsciiStr is repr(transparent) and thus has the same layout as [AsciiChar]
        unsafe { Rc::from_raw(Rc::into_raw(var) as *const AsciiStr) }
    }
}

impl From<AsciiString> for Arc<AsciiStr> {
    fn from(s: AsciiString) -> Arc<AsciiStr> {
        let var: Arc<[AsciiChar]> = s.vec.into();
        // SAFETY: AsciiStr is repr(transparent) and thus has the same layout as [AsciiChar]
        unsafe { Arc::from_raw(Arc::into_raw(var) as *const AsciiStr) }
    }
}

impl<'a> From<Cow<'a, AsciiStr>> for AsciiString {
    fn from(cow: Cow<'a, AsciiStr>) -> AsciiString {
        cow.into_owned()
    }
}

impl<'a> From<AsciiString> for Cow<'a, AsciiStr> {
    fn from(string: AsciiString) -> Cow<'a, AsciiStr> {
        Cow::Owned(string)
    }
}

impl<'a> From<&'a AsciiStr> for Cow<'a, AsciiStr> {
    fn from(s: &'a AsciiStr) -> Cow<'a, AsciiStr> {
        Cow::Borrowed(s)
    }
}

impl AsRef<AsciiStr> for AsciiString {
    #[inline]
    fn as_ref(&self) -> &AsciiStr {
        &**self
    }
}

impl AsRef<[AsciiChar]> for AsciiString {
    #[inline]
    fn as_ref(&self) -> &[AsciiChar] {
        &self.vec
    }
}

impl AsRef<[u8]> for AsciiString {
    #[inline]
    fn as_ref(&self) -> &[u8] {
        self.as_bytes()
    }
}

impl AsRef<str> for AsciiString {
    #[inline]
    fn as_ref(&self) -> &str {
        self.as_str()
    }
}

impl AsMut<AsciiStr> for AsciiString {
    #[inline]
    fn as_mut(&mut self) -> &mut AsciiStr {
        &mut *self
    }
}

impl AsMut<[AsciiChar]> for AsciiString {
    #[inline]
    fn as_mut(&mut self) -> &mut [AsciiChar] {
        &mut self.vec
    }
}

impl FromStr for AsciiString {
    type Err = AsAsciiStrError;

    fn from_str(s: &str) -> Result<AsciiString, AsAsciiStrError> {
        s.as_ascii_str().map(AsciiStr::to_ascii_string)
    }
}

impl fmt::Display for AsciiString {
    #[inline]
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        fmt::Display::fmt(&**self, f)
    }
}

impl fmt::Debug for AsciiString {
    #[inline]
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        fmt::Debug::fmt(&**self, f)
    }
}

/// Please note that the `std::fmt::Result` returned by these methods does not support
/// transmission of an error other than that an error occurred.
impl fmt::Write for AsciiString {
    fn write_str(&mut self, s: &str) -> fmt::Result {
        if let Ok(astr) = AsciiStr::from_ascii(s) {
            self.push_str(astr);
            Ok(())
        } else {
            Err(fmt::Error)
        }
    }

    fn write_char(&mut self, c: char) -> fmt::Result {
        if let Ok(achar) = AsciiChar::from_ascii(c) {
            self.push(achar);
            Ok(())
        } else {
            Err(fmt::Error)
        }
    }
}

impl<A: AsRef<AsciiStr>> FromIterator<A> for AsciiString {
    fn from_iter<I: IntoIterator<Item = A>>(iter: I) -> AsciiString {
        let mut buf = AsciiString::new();
        buf.extend(iter);
        buf
    }
}

impl<A: AsRef<AsciiStr>> Extend<A> for AsciiString {
    fn extend<I: IntoIterator<Item = A>>(&mut self, iterable: I) {
        let iterator = iterable.into_iter();
        let (lower_bound, _) = iterator.size_hint();
        self.reserve(lower_bound);
        for item in iterator {
            self.push_str(item.as_ref());
        }
    }
}

impl<'a> Add<&'a AsciiStr> for AsciiString {
    type Output = AsciiString;

    #[inline]
    fn add(mut self, other: &AsciiStr) -> AsciiString {
        self.push_str(other);
        self
    }
}

impl<'a> AddAssign<&'a AsciiStr> for AsciiString {
    #[inline]
    fn add_assign(&mut self, other: &AsciiStr) {
        self.push_str(other);
    }
}

#[allow(clippy::indexing_slicing)] // In `Index`, if it's out of bounds, panic is the default
impl<T> Index<T> for AsciiString
where
    AsciiStr: Index<T>,
{
    type Output = <AsciiStr as Index<T>>::Output;

    #[inline]
    fn index(&self, index: T) -> &<AsciiStr as Index<T>>::Output {
        &(**self)[index]
    }
}

#[allow(clippy::indexing_slicing)] // In `IndexMut`, if it's out of bounds, panic is the default
impl<T> IndexMut<T> for AsciiString
where
    AsciiStr: IndexMut<T>,
{
    #[inline]
    fn index_mut(&mut self, index: T) -> &mut <AsciiStr as Index<T>>::Output {
        &mut (**self)[index]
    }
}

/// A possible error value when converting an `AsciiString` from a byte vector or string.
/// It wraps an `AsAsciiStrError` which you can get through the `ascii_error()` method.
///
/// This is the error type for `AsciiString::from_ascii()` and
/// `IntoAsciiString::into_ascii_string()`. They will never clone or touch the content of the
/// original type; It can be extracted by the `into_source` method.
///
/// #Examples
/// ```
/// # use ascii::IntoAsciiString;
/// let err = "bø!".to_string().into_ascii_string().unwrap_err();
/// assert_eq!(err.ascii_error().valid_up_to(), 1);
/// assert_eq!(err.into_source(), "bø!".to_string());
/// ```
#[derive(Clone, Copy, PartialEq, Eq)]
pub struct FromAsciiError<O> {
    error: AsAsciiStrError,
    owner: O,
}
impl<O> FromAsciiError<O> {
    /// Get the position of the first non-ASCII byte or character.
    #[inline]
    #[must_use]
    pub fn ascii_error(&self) -> AsAsciiStrError {
        self.error
    }
    /// Get back the original, unmodified type.
    #[inline]
    #[must_use]
    pub fn into_source(self) -> O {
        self.owner
    }
}
impl<O> fmt::Debug for FromAsciiError<O> {
    #[inline]
    fn fmt(&self, fmtr: &mut fmt::Formatter) -> fmt::Result {
        fmt::Debug::fmt(&self.error, fmtr)
    }
}
impl<O> fmt::Display for FromAsciiError<O> {
    #[inline]
    fn fmt(&self, fmtr: &mut fmt::Formatter) -> fmt::Result {
        fmt::Display::fmt(&self.error, fmtr)
    }
}
#[cfg(feature = "std")]
impl<O: Any> Error for FromAsciiError<O> {
    #[inline]
    #[allow(deprecated)] // TODO: Remove deprecation once the earliest version we support deprecates this method.
    fn description(&self) -> &str {
        self.error.description()
    }
    /// Always returns an `AsAsciiStrError`
    fn cause(&self) -> Option<&dyn Error> {
        Some(&self.error as &dyn Error)
    }
}

/// Convert vectors into `AsciiString`.
pub trait IntoAsciiString: Sized {
    /// Convert to `AsciiString` without checking for non-ASCII characters.
    ///
    /// # Safety
    /// If `self` contains non-ascii characters, calling this function is
    /// undefined behavior.
    unsafe fn into_ascii_string_unchecked(self) -> AsciiString;

    /// Convert to `AsciiString`.
    ///
    /// # Errors
    /// If `self` contains non-ascii characters, this will return `Err`
    fn into_ascii_string(self) -> Result<AsciiString, FromAsciiError<Self>>;
}

impl IntoAsciiString for Vec<AsciiChar> {
    #[inline]
    unsafe fn into_ascii_string_unchecked(self) -> AsciiString {
        AsciiString::from(self)
    }
    #[inline]
    fn into_ascii_string(self) -> Result<AsciiString, FromAsciiError<Self>> {
        Ok(AsciiString::from(self))
    }
}

impl<'a> IntoAsciiString for &'a [AsciiChar] {
    #[inline]
    unsafe fn into_ascii_string_unchecked(self) -> AsciiString {
        AsciiString::from(self)
    }
    #[inline]
    fn into_ascii_string(self) -> Result<AsciiString, FromAsciiError<Self>> {
        Ok(AsciiString::from(self))
    }
}

impl<'a> IntoAsciiString for &'a AsciiStr {
    #[inline]
    unsafe fn into_ascii_string_unchecked(self) -> AsciiString {
        AsciiString::from(self)
    }
    #[inline]
    fn into_ascii_string(self) -> Result<AsciiString, FromAsciiError<Self>> {
        Ok(AsciiString::from(self))
    }
}

macro_rules! impl_into_ascii_string {
    ('a, $wider:ty) => {
        impl<'a> IntoAsciiString for $wider {
            #[inline]
            unsafe fn into_ascii_string_unchecked(self) -> AsciiString {
                // SAFETY: Caller guarantees `self` only has valid ascii bytes
                unsafe { AsciiString::from_ascii_unchecked(self) }
            }

            #[inline]
            fn into_ascii_string(self) -> Result<AsciiString, FromAsciiError<Self>> {
                AsciiString::from_ascii(self)
            }
        }
    };

    ($wider:ty) => {
        impl IntoAsciiString for $wider {
            #[inline]
            unsafe fn into_ascii_string_unchecked(self) -> AsciiString {
                // SAFETY: Caller guarantees `self` only has valid ascii bytes
                unsafe { AsciiString::from_ascii_unchecked(self) }
            }

            #[inline]
            fn into_ascii_string(self) -> Result<AsciiString, FromAsciiError<Self>> {
                AsciiString::from_ascii(self)
            }
        }
    };
}

impl_into_ascii_string! {AsciiString}
impl_into_ascii_string! {Vec<u8>}
impl_into_ascii_string! {'a, &'a [u8]}
impl_into_ascii_string! {String}
impl_into_ascii_string! {'a, &'a str}

/// # Notes
/// The trailing null byte `CString` has will be removed during this conversion.
#[cfg(feature = "std")]
impl IntoAsciiString for CString {
    #[inline]
    unsafe fn into_ascii_string_unchecked(self) -> AsciiString {
        // SAFETY: Caller guarantees `self` only has valid ascii bytes
        unsafe { AsciiString::from_ascii_unchecked(self.into_bytes()) }
    }

    fn into_ascii_string(self) -> Result<AsciiString, FromAsciiError<Self>> {
        AsciiString::from_ascii(self.into_bytes_with_nul())
            .map_err(|FromAsciiError { error, owner }| {
                FromAsciiError {
                    // SAFETY: We don't discard the NULL byte from the original
                    //         string, so we ensure that it's null terminated
                    owner: unsafe { CString::from_vec_unchecked(owner) },
                    error,
                }
            })
            .map(|mut s| {
                let nul = s.pop();
                debug_assert_eq!(nul, Some(AsciiChar::Null));
                s
            })
    }
}

/// Note that the trailing null byte will be removed in the conversion.
#[cfg(feature = "std")]
impl<'a> IntoAsciiString for &'a CStr {
    #[inline]
    unsafe fn into_ascii_string_unchecked(self) -> AsciiString {
        // SAFETY: Caller guarantees `self` only has valid ascii bytes
        unsafe { AsciiString::from_ascii_unchecked(self.to_bytes()) }
    }

    fn into_ascii_string(self) -> Result<AsciiString, FromAsciiError<Self>> {
        AsciiString::from_ascii(self.to_bytes_with_nul())
            .map_err(|FromAsciiError { error, owner }| FromAsciiError {
                // SAFETY: We don't discard the NULL byte from the original
                //         string, so we ensure that it's null terminated
                owner: unsafe { CStr::from_ptr(owner.as_ptr().cast()) },
                error,
            })
            .map(|mut s| {
                let nul = s.pop();
                debug_assert_eq!(nul, Some(AsciiChar::Null));
                s
            })
    }
}

impl<'a, B> IntoAsciiString for Cow<'a, B>
where
    B: 'a + ToOwned + ?Sized,
    &'a B: IntoAsciiString,
    <B as ToOwned>::Owned: IntoAsciiString,
{
    #[inline]
    unsafe fn into_ascii_string_unchecked(self) -> AsciiString {
        // SAFETY: Caller guarantees `self` only has valid ascii bytes
        unsafe { IntoAsciiString::into_ascii_string_unchecked(self.into_owned()) }
    }

    fn into_ascii_string(self) -> Result<AsciiString, FromAsciiError<Self>> {
        match self {
            Cow::Owned(b) => {
                IntoAsciiString::into_ascii_string(b).map_err(|FromAsciiError { error, owner }| {
                    FromAsciiError {
                        owner: Cow::Owned(owner),
                        error,
                    }
                })
            }
            Cow::Borrowed(b) => {
                IntoAsciiString::into_ascii_string(b).map_err(|FromAsciiError { error, owner }| {
                    FromAsciiError {
                        owner: Cow::Borrowed(owner),
                        error,
                    }
                })
            }
        }
    }
}

#[cfg(test)]
mod tests {
    use super::{AsciiString, IntoAsciiString};
    use alloc::str::FromStr;
    use alloc::string::{String, ToString};
    use alloc::vec::Vec;
    use alloc::boxed::Box;
    #[cfg(feature = "std")]
    use std::ffi::CString;
    use {AsciiChar, AsciiStr};

    #[test]
    fn into_string() {
        let v = AsciiString::from_ascii(&[40_u8, 32, 59][..]).unwrap();
        assert_eq!(Into::<String>::into(v), "( ;".to_string());
    }

    #[test]
    fn into_bytes() {
        let v = AsciiString::from_ascii(&[40_u8, 32, 59][..]).unwrap();
        assert_eq!(Into::<Vec<u8>>::into(v), vec![40_u8, 32, 59]);
    }

    #[test]
    fn from_ascii_vec() {
        let vec = vec![
            AsciiChar::from_ascii('A').unwrap(),
            AsciiChar::from_ascii('B').unwrap(),
        ];
        assert_eq!(AsciiString::from(vec), AsciiString::from_str("AB").unwrap());
    }

    #[test]
    #[cfg(feature = "std")]
    fn from_cstring() {
        let cstring = CString::new("baz").unwrap();
        let ascii_str = cstring.clone().into_ascii_string().unwrap();
        let expected_chars = &[AsciiChar::b, AsciiChar::a, AsciiChar::z];
        assert_eq!(ascii_str.len(), 3);
        assert_eq!(ascii_str.as_slice(), expected_chars);

        // SAFETY: "baz" only contains valid ascii characters.
        let ascii_str_unchecked = unsafe { cstring.into_ascii_string_unchecked() };
        assert_eq!(ascii_str_unchecked.len(), 3);
        assert_eq!(ascii_str_unchecked.as_slice(), expected_chars);

        let sparkle_heart_bytes = vec![240_u8, 159, 146, 150];
        let cstring = CString::new(sparkle_heart_bytes).unwrap();
        let cstr = &*cstring;
        let ascii_err = cstr.into_ascii_string().unwrap_err();
        assert_eq!(ascii_err.into_source(), &*cstring);
    }

    #[test]
    #[cfg(feature = "std")]
    fn fmt_ascii_string() {
        let s = "abc".to_string().into_ascii_string().unwrap();
        assert_eq!(format!("{}", s), "abc".to_string());
        assert_eq!(format!("{:?}", s), "\"abc\"".to_string());
    }

    #[test]
    fn write_fmt() {
        use alloc::{fmt, str};

        let mut s0 = AsciiString::new();
        fmt::write(&mut s0, format_args!("Hello World")).unwrap();
        assert_eq!(s0, "Hello World");

        let mut s1 = AsciiString::new();
        fmt::write(&mut s1, format_args!("{}", 9)).unwrap();
        assert_eq!(s1, "9");

        let mut s2 = AsciiString::new();
        let sparkle_heart_bytes = [240, 159, 146, 150];
        let sparkle_heart = str::from_utf8(&sparkle_heart_bytes).unwrap();
        assert!(fmt::write(&mut s2, format_args!("{}", sparkle_heart)).is_err());
    }

    #[test]
    fn to_and_from_box() {
        let string = "abc".into_ascii_string().unwrap();
        let converted: Box<AsciiStr> = Box::from(string.clone());
        let converted: AsciiString = converted.into();
        assert_eq!(string, converted);
    }
}