alloc/

bstr.rs

//! The `ByteStr` and `ByteString` types and trait implementations.

// This could be more fine-grained.
#![cfg(not(no_global_oom_handling))]

use core::borrow::{Borrow, BorrowMut};
#[unstable(feature = "bstr", issue = "134915")]
pub use core::bstr::ByteStr;
use core::bstr::{impl_partial_eq, impl_partial_eq_n, impl_partial_eq_ord};
use core::cmp::Ordering;
use core::ops::{
    Deref, DerefMut, DerefPure, Index, IndexMut, Range, RangeFrom, RangeFull, RangeInclusive,
    RangeTo, RangeToInclusive,
};
use core::str::{FromStr, Utf8Error};
use core::{fmt, hash};

use crate::borrow::{Cow, ToOwned};
use crate::boxed::Box;
#[cfg(not(no_rc))]
use crate::rc::Rc;
use crate::string::String;
#[cfg(all(not(no_rc), not(no_sync), target_has_atomic = "ptr"))]
use crate::sync::Arc;
use crate::vec::Vec;

/// A wrapper for `Vec<u8>` representing a human-readable string that's conventionally, but not
/// always, UTF-8.
///
/// Unlike `String`, this type permits non-UTF-8 contents, making it suitable for user input,
/// non-native filenames (as `Path` only supports native filenames), and other applications that
/// need to round-trip whatever data the user provides.
///
/// A `ByteString` owns its contents and can grow and shrink, like a `Vec` or `String`. For a
/// borrowed byte string, see [`ByteStr`](../../std/bstr/struct.ByteStr.html).
///
/// `ByteString` implements `Deref` to `&Vec<u8>`, so all methods available on `&Vec<u8>` are
/// available on `ByteString`. Similarly, `ByteString` implements `DerefMut` to `&mut Vec<u8>`,
/// so you can modify a `ByteString` using any method available on `&mut Vec<u8>`.
///
/// The `Debug` and `Display` implementations for `ByteString` are the same as those for `ByteStr`,
/// showing invalid UTF-8 as hex escapes or the Unicode replacement character, respectively.
#[unstable(feature = "bstr", issue = "134915")]
#[repr(transparent)]
#[derive(Clone)]
#[doc(alias = "BString")]
pub struct ByteString(pub Vec<u8>);

impl ByteString {
    #[inline]
    pub(crate) fn as_bytes(&self) -> &[u8] {
        &self.0
    }

    #[inline]
    pub(crate) fn as_bytestr(&self) -> &ByteStr {
        ByteStr::new(&self.0)
    }

    #[inline]
    pub(crate) fn as_mut_bytestr(&mut self) -> &mut ByteStr {
        ByteStr::from_bytes_mut(&mut self.0)
    }
    /// Try to get a `String` representation of the `&ByteString`, if it is
    /// valid UTF-8.
    ///
    /// This method is named `to_string()` because we want `ByteString` to
    /// implement `Display`, but the `ToString` trait has a blanket
    /// implementation for types that implement `Display`, and the trait version
    /// will use the Unicode replacement character rather than returning a
    /// `Result` and allowing for the possibility of the content not being UTF-8.
    #[unstable(feature = "bstr_to_string", issue = "134915")]
    #[rustc_allow_incoherent_impl]
    pub fn to_string(&self) -> Result<String, Utf8Error> {
        // Avoid allocating a copy of the contents for invalid UTF-8
        if let Err(e) = str::from_utf8(&self.0) {
            return Err(e);
        }
        // SAFETY: we just checked that the contents are valid UTF-8
        Ok(unsafe { String::from_utf8_unchecked(self.0.clone()) })
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl Deref for ByteString {
    type Target = Vec<u8>;

    #[inline]
    fn deref(&self) -> &Self::Target {
        &self.0
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl DerefMut for ByteString {
    #[inline]
    fn deref_mut(&mut self) -> &mut Self::Target {
        &mut self.0
    }
}

#[unstable(feature = "deref_pure_trait", issue = "87121")]
unsafe impl DerefPure for ByteString {}

#[unstable(feature = "bstr", issue = "134915")]
impl fmt::Debug for ByteString {
    #[inline]
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt::Debug::fmt(self.as_bytestr(), f)
    }
}

#[unstable(feature = "bstr_to_string", issue = "134915")]
impl fmt::Display for ByteString {
    #[inline]
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt::Display::fmt(self.as_bytestr(), f)
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl AsRef<[u8]> for ByteString {
    #[inline]
    fn as_ref(&self) -> &[u8] {
        &self.0
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl AsRef<ByteStr> for ByteString {
    #[inline]
    fn as_ref(&self) -> &ByteStr {
        self.as_bytestr()
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl AsMut<[u8]> for ByteString {
    #[inline]
    fn as_mut(&mut self) -> &mut [u8] {
        &mut self.0
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl AsMut<ByteStr> for ByteString {
    #[inline]
    fn as_mut(&mut self) -> &mut ByteStr {
        self.as_mut_bytestr()
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl Borrow<[u8]> for ByteString {
    #[inline]
    fn borrow(&self) -> &[u8] {
        &self.0
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl Borrow<ByteStr> for ByteString {
    #[inline]
    fn borrow(&self) -> &ByteStr {
        self.as_bytestr()
    }
}

// `impl Borrow<ByteStr> for Vec<u8>` omitted to avoid inference failures
// `impl Borrow<ByteStr> for String` omitted to avoid inference failures

#[unstable(feature = "bstr", issue = "134915")]
impl BorrowMut<[u8]> for ByteString {
    #[inline]
    fn borrow_mut(&mut self) -> &mut [u8] {
        &mut self.0
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl BorrowMut<ByteStr> for ByteString {
    #[inline]
    fn borrow_mut(&mut self) -> &mut ByteStr {
        self.as_mut_bytestr()
    }
}

// `impl BorrowMut<ByteStr> for Vec<u8>` omitted to avoid inference failures

#[unstable(feature = "bstr", issue = "134915")]
impl Default for ByteString {
    fn default() -> Self {
        ByteString(Vec::new())
    }
}

// Omitted due to inference failures
//
// #[unstable(feature = "bstr", issue = "134915")]
// impl<'a, const N: usize> From<&'a [u8; N]> for ByteString {
//     #[inline]
//     fn from(s: &'a [u8; N]) -> Self {
//         ByteString(s.as_slice().to_vec())
//     }
// }
//
// #[unstable(feature = "bstr", issue = "134915")]
// impl<const N: usize> From<[u8; N]> for ByteString {
//     #[inline]
//     fn from(s: [u8; N]) -> Self {
//         ByteString(s.as_slice().to_vec())
//     }
// }
//
// #[unstable(feature = "bstr", issue = "134915")]
// impl<'a> From<&'a [u8]> for ByteString {
//     #[inline]
//     fn from(s: &'a [u8]) -> Self {
//         ByteString(s.to_vec())
//     }
// }
//
// #[unstable(feature = "bstr", issue = "134915")]
// impl From<Vec<u8>> for ByteString {
//     #[inline]
//     fn from(s: Vec<u8>) -> Self {
//         ByteString(s)
//     }
// }

#[unstable(feature = "bstr", issue = "134915")]
impl From<ByteString> for Vec<u8> {
    #[inline]
    fn from(s: ByteString) -> Self {
        s.0
    }
}

// Omitted due to inference failures
//
// #[unstable(feature = "bstr", issue = "134915")]
// impl<'a> From<&'a str> for ByteString {
//     #[inline]
//     fn from(s: &'a str) -> Self {
//         ByteString(s.as_bytes().to_vec())
//     }
// }
//
// #[unstable(feature = "bstr", issue = "134915")]
// impl From<String> for ByteString {
//     #[inline]
//     fn from(s: String) -> Self {
//         ByteString(s.into_bytes())
//     }
// }

#[unstable(feature = "bstr", issue = "134915")]
impl<'a> From<&'a ByteStr> for ByteString {
    #[inline]
    fn from(s: &'a ByteStr) -> Self {
        ByteString(s.0.to_vec())
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl<'a> From<ByteString> for Cow<'a, ByteStr> {
    #[inline]
    fn from(s: ByteString) -> Self {
        Cow::Owned(s)
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl<'a> From<&'a ByteString> for Cow<'a, ByteStr> {
    #[inline]
    fn from(s: &'a ByteString) -> Self {
        Cow::Borrowed(s.as_bytestr())
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl FromIterator<char> for ByteString {
    #[inline]
    fn from_iter<T: IntoIterator<Item = char>>(iter: T) -> Self {
        ByteString(iter.into_iter().collect::<String>().into_bytes())
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl FromIterator<u8> for ByteString {
    #[inline]
    fn from_iter<T: IntoIterator<Item = u8>>(iter: T) -> Self {
        ByteString(iter.into_iter().collect())
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl<'a> FromIterator<&'a str> for ByteString {
    #[inline]
    fn from_iter<T: IntoIterator<Item = &'a str>>(iter: T) -> Self {
        ByteString(iter.into_iter().collect::<String>().into_bytes())
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl<'a> FromIterator<&'a [u8]> for ByteString {
    #[inline]
    fn from_iter<T: IntoIterator<Item = &'a [u8]>>(iter: T) -> Self {
        let mut buf = Vec::new();
        for b in iter {
            buf.extend_from_slice(b);
        }
        ByteString(buf)
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl<'a> FromIterator<&'a ByteStr> for ByteString {
    #[inline]
    fn from_iter<T: IntoIterator<Item = &'a ByteStr>>(iter: T) -> Self {
        let mut buf = Vec::new();
        for b in iter {
            buf.extend_from_slice(&b.0);
        }
        ByteString(buf)
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl FromIterator<ByteString> for ByteString {
    #[inline]
    fn from_iter<T: IntoIterator<Item = ByteString>>(iter: T) -> Self {
        let mut buf = Vec::new();
        for mut b in iter {
            buf.append(&mut b.0);
        }
        ByteString(buf)
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl FromStr for ByteString {
    type Err = core::convert::Infallible;

    #[inline]
    fn from_str(s: &str) -> Result<Self, Self::Err> {
        Ok(ByteString(s.as_bytes().to_vec()))
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl Index<usize> for ByteString {
    type Output = u8;

    #[inline]
    fn index(&self, idx: usize) -> &u8 {
        &self.0[idx]
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl Index<RangeFull> for ByteString {
    type Output = ByteStr;

    #[inline]
    fn index(&self, _: RangeFull) -> &ByteStr {
        self.as_bytestr()
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl Index<Range<usize>> for ByteString {
    type Output = ByteStr;

    #[inline]
    fn index(&self, r: Range<usize>) -> &ByteStr {
        ByteStr::from_bytes(&self.0[r])
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl Index<RangeInclusive<usize>> for ByteString {
    type Output = ByteStr;

    #[inline]
    fn index(&self, r: RangeInclusive<usize>) -> &ByteStr {
        ByteStr::from_bytes(&self.0[r])
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl Index<RangeFrom<usize>> for ByteString {
    type Output = ByteStr;

    #[inline]
    fn index(&self, r: RangeFrom<usize>) -> &ByteStr {
        ByteStr::from_bytes(&self.0[r])
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl Index<RangeTo<usize>> for ByteString {
    type Output = ByteStr;

    #[inline]
    fn index(&self, r: RangeTo<usize>) -> &ByteStr {
        ByteStr::from_bytes(&self.0[r])
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl Index<RangeToInclusive<usize>> for ByteString {
    type Output = ByteStr;

    #[inline]
    fn index(&self, r: RangeToInclusive<usize>) -> &ByteStr {
        ByteStr::from_bytes(&self.0[r])
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl IndexMut<usize> for ByteString {
    #[inline]
    fn index_mut(&mut self, idx: usize) -> &mut u8 {
        &mut self.0[idx]
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl IndexMut<RangeFull> for ByteString {
    #[inline]
    fn index_mut(&mut self, _: RangeFull) -> &mut ByteStr {
        self.as_mut_bytestr()
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl IndexMut<Range<usize>> for ByteString {
    #[inline]
    fn index_mut(&mut self, r: Range<usize>) -> &mut ByteStr {
        ByteStr::from_bytes_mut(&mut self.0[r])
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl IndexMut<RangeInclusive<usize>> for ByteString {
    #[inline]
    fn index_mut(&mut self, r: RangeInclusive<usize>) -> &mut ByteStr {
        ByteStr::from_bytes_mut(&mut self.0[r])
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl IndexMut<RangeFrom<usize>> for ByteString {
    #[inline]
    fn index_mut(&mut self, r: RangeFrom<usize>) -> &mut ByteStr {
        ByteStr::from_bytes_mut(&mut self.0[r])
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl IndexMut<RangeTo<usize>> for ByteString {
    #[inline]
    fn index_mut(&mut self, r: RangeTo<usize>) -> &mut ByteStr {
        ByteStr::from_bytes_mut(&mut self.0[r])
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl IndexMut<RangeToInclusive<usize>> for ByteString {
    #[inline]
    fn index_mut(&mut self, r: RangeToInclusive<usize>) -> &mut ByteStr {
        ByteStr::from_bytes_mut(&mut self.0[r])
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl hash::Hash for ByteString {
    #[inline]
    fn hash<H: hash::Hasher>(&self, state: &mut H) {
        self.0.hash(state);
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl Eq for ByteString {}

#[unstable(feature = "bstr", issue = "134915")]
impl PartialEq for ByteString {
    #[inline]
    fn eq(&self, other: &ByteString) -> bool {
        self.0 == other.0
    }
}

macro_rules! impl_partial_eq_ord_cow {
    ($lhs:ty, $rhs:ty) => {
        #[unstable(feature = "bstr", issue = "134915")]
        impl PartialEq<$rhs> for $lhs {
            #[inline]
            fn eq(&self, other: &$rhs) -> bool {
                let other: &[u8] = (&**other).as_ref();
                PartialEq::eq(self.as_bytes(), other)
            }
        }

        #[unstable(feature = "bstr", issue = "134915")]
        impl PartialEq<$lhs> for $rhs {
            #[inline]
            fn eq(&self, other: &$lhs) -> bool {
                let this: &[u8] = (&**self).as_ref();
                PartialEq::eq(this, other.as_bytes())
            }
        }

        #[unstable(feature = "bstr", issue = "134915")]
        impl PartialOrd<$rhs> for $lhs {
            #[inline]
            fn partial_cmp(&self, other: &$rhs) -> Option<Ordering> {
                let other: &[u8] = (&**other).as_ref();
                PartialOrd::partial_cmp(self.as_bytes(), other)
            }
        }

        #[unstable(feature = "bstr", issue = "134915")]
        impl PartialOrd<$lhs> for $rhs {
            #[inline]
            fn partial_cmp(&self, other: &$lhs) -> Option<Ordering> {
                let this: &[u8] = (&**self).as_ref();
                PartialOrd::partial_cmp(this, other.as_bytes())
            }
        }
    };
}

// PartialOrd with `Vec<u8>` omitted to avoid inference failures
impl_partial_eq!(ByteString, Vec<u8>);
// PartialOrd with `[u8]` omitted to avoid inference failures
impl_partial_eq!(ByteString, [u8]);
// PartialOrd with `&[u8]` omitted to avoid inference failures
impl_partial_eq!(ByteString, &[u8]);
// PartialOrd with `String` omitted to avoid inference failures
impl_partial_eq!(ByteString, String);
// PartialOrd with `str` omitted to avoid inference failures
impl_partial_eq!(ByteString, str);
// PartialOrd with `&str` omitted to avoid inference failures
impl_partial_eq!(ByteString, &str);
impl_partial_eq_ord!(ByteString, ByteStr);
impl_partial_eq_ord!(ByteString, &ByteStr);
// PartialOrd with `[u8; N]` omitted to avoid inference failures
impl_partial_eq_n!(ByteString, [u8; N]);
// PartialOrd with `&[u8; N]` omitted to avoid inference failures
impl_partial_eq_n!(ByteString, &[u8; N]);
impl_partial_eq_ord_cow!(ByteString, Cow<'_, ByteStr>);
impl_partial_eq_ord_cow!(ByteString, Cow<'_, str>);
impl_partial_eq_ord_cow!(ByteString, Cow<'_, [u8]>);

#[unstable(feature = "bstr", issue = "134915")]
impl Ord for ByteString {
    #[inline]
    fn cmp(&self, other: &ByteString) -> Ordering {
        Ord::cmp(&self.0, &other.0)
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl PartialOrd for ByteString {
    #[inline]
    fn partial_cmp(&self, other: &ByteString) -> Option<Ordering> {
        PartialOrd::partial_cmp(&self.0, &other.0)
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl ToOwned for ByteStr {
    type Owned = ByteString;

    #[inline]
    fn to_owned(&self) -> ByteString {
        ByteString(self.0.to_vec())
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl TryFrom<ByteString> for String {
    type Error = crate::string::FromUtf8Error;

    #[inline]
    fn try_from(s: ByteString) -> Result<Self, Self::Error> {
        String::from_utf8(s.0)
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl<'a> TryFrom<&'a ByteString> for &'a str {
    type Error = crate::str::Utf8Error;

    #[inline]
    fn try_from(s: &'a ByteString) -> Result<Self, Self::Error> {
        crate::str::from_utf8(s.0.as_slice())
    }
}

// Additional impls for `ByteStr` that require types from `alloc`:

#[unstable(feature = "bstr", issue = "134915")]
impl Clone for Box<ByteStr> {
    #[inline]
    fn clone(&self) -> Self {
        Self::from(Box::<[u8]>::from(&self.0))
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl<'a> From<&'a ByteStr> for Cow<'a, ByteStr> {
    #[inline]
    fn from(s: &'a ByteStr) -> Self {
        Cow::Borrowed(s)
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl From<Box<[u8]>> for Box<ByteStr> {
    #[inline]
    fn from(s: Box<[u8]>) -> Box<ByteStr> {
        // SAFETY: `ByteStr` is a transparent wrapper around `[u8]`.
        unsafe { Box::from_raw(Box::into_raw(s) as _) }
    }
}

#[unstable(feature = "bstr", issue = "134915")]
impl From<Box<ByteStr>> for Box<[u8]> {
    #[inline]
    fn from(s: Box<ByteStr>) -> Box<[u8]> {
        // SAFETY: `ByteStr` is a transparent wrapper around `[u8]`.
        unsafe { Box::from_raw(Box::into_raw(s) as _) }
    }
}

#[unstable(feature = "bstr", issue = "134915")]
#[cfg(not(no_rc))]
impl From<Rc<[u8]>> for Rc<ByteStr> {
    #[inline]
    fn from(s: Rc<[u8]>) -> Rc<ByteStr> {
        // SAFETY: `ByteStr` is a transparent wrapper around `[u8]`.
        unsafe { Rc::from_raw(Rc::into_raw(s) as _) }
    }
}

#[unstable(feature = "bstr", issue = "134915")]
#[cfg(not(no_rc))]
impl From<Rc<ByteStr>> for Rc<[u8]> {
    #[inline]
    fn from(s: Rc<ByteStr>) -> Rc<[u8]> {
        // SAFETY: `ByteStr` is a transparent wrapper around `[u8]`.
        unsafe { Rc::from_raw(Rc::into_raw(s) as _) }
    }
}

#[unstable(feature = "bstr", issue = "134915")]
#[cfg(all(not(no_rc), not(no_sync), target_has_atomic = "ptr"))]
impl From<Arc<[u8]>> for Arc<ByteStr> {
    #[inline]
    fn from(s: Arc<[u8]>) -> Arc<ByteStr> {
        // SAFETY: `ByteStr` is a transparent wrapper around `[u8]`.
        unsafe { Arc::from_raw(Arc::into_raw(s) as _) }
    }
}

#[unstable(feature = "bstr", issue = "134915")]
#[cfg(all(not(no_rc), not(no_sync), target_has_atomic = "ptr"))]
impl From<Arc<ByteStr>> for Arc<[u8]> {
    #[inline]
    fn from(s: Arc<ByteStr>) -> Arc<[u8]> {
        // SAFETY: `ByteStr` is a transparent wrapper around `[u8]`.
        unsafe { Arc::from_raw(Arc::into_raw(s) as _) }
    }
}

// PartialOrd with `Vec<u8>` omitted to avoid inference failures
impl_partial_eq!(ByteStr, Vec<u8>);
// PartialOrd with `String` omitted to avoid inference failures
impl_partial_eq!(ByteStr, String);
impl_partial_eq_ord_cow!(&ByteStr, Cow<'_, ByteStr>);
impl_partial_eq_ord_cow!(&ByteStr, Cow<'_, str>);
impl_partial_eq_ord_cow!(&ByteStr, Cow<'_, [u8]>);

#[unstable(feature = "bstr", issue = "134915")]
impl<'a> TryFrom<&'a ByteStr> for String {
    type Error = core::str::Utf8Error;

    #[inline]
    fn try_from(s: &'a ByteStr) -> Result<Self, Self::Error> {
        Ok(core::str::from_utf8(&s.0)?.into())
    }
}

impl ByteStr {
    /// Try to get a `String` representation of the `&ByteStr`, if it is valid
    /// UTF-8.
    ///
    /// This method is named `to_string()` because we want `ByteStr` to
    /// implement `Display`, but the `ToString` trait has a blanket
    /// implementation for types that implement `Display`, and the trait version
    /// will use the Unicode replacement character rather than returning a
    /// `Result` and allowing for the possibility of the content not being UTF-8.
    #[unstable(feature = "bstr_to_string", issue = "134915")]
    #[rustc_allow_incoherent_impl]
    pub fn to_string(&self) -> Result<String, Utf8Error> {
        // Avoid allocating a copy of the contents for invalid UTF-8
        if let Err(e) = str::from_utf8(&self.0) {
            return Err(e);
        }
        // SAFETY: we just checked that the contents are valid UTF-8
        Ok(unsafe { String::from_utf8_unchecked(self.0.to_vec()) })
    }
}