bstr/
bstr.rs

1#[cfg(feature = "alloc")]
2use alloc::boxed::Box;
3
4/// A wrapper for `&[u8]` that provides convenient string oriented trait impls.
5///
6/// If you need ownership or a growable byte string buffer, then use
7/// [`BString`](struct.BString.html).
8///
9/// Using a `&BStr` is just like using a `&[u8]`, since `BStr`
10/// implements `Deref` to `[u8]`. So all methods available on `[u8]`
11/// are also available on `BStr`.
12///
13/// # Representation
14///
15/// A `&BStr` has the same representation as a `&str`. That is, a `&BStr` is
16/// a fat pointer which consists of a pointer to some bytes and a length.
17///
18/// # Trait implementations
19///
20/// The `BStr` type has a number of trait implementations, and in particular,
21/// defines equality and ordinal comparisons between `&BStr`, `&str` and
22/// `&[u8]` for convenience.
23///
24/// The `Debug` implementation for `BStr` shows its bytes as a normal string.
25/// For invalid UTF-8, hex escape sequences are used.
26///
27/// The `Display` implementation behaves as if `BStr` were first lossily
28/// converted to a `str`. Invalid UTF-8 bytes are substituted with the Unicode
29/// replacement codepoint, which looks like this: �.
30#[repr(transparent)]
31pub struct BStr {
32    pub(crate) bytes: [u8],
33}
34
35impl BStr {
36    /// Directly creates a `BStr` slice from anything that can be converted
37    /// to a byte slice.
38    ///
39    /// This is very similar to the [`B`](crate::B) function, except this
40    /// returns a `&BStr` instead of a `&[u8]`.
41    ///
42    /// This is a cost-free conversion.
43    ///
44    /// # Example
45    ///
46    /// You can create `BStr`'s from byte arrays, byte slices or even string
47    /// slices:
48    ///
49    /// ```
50    /// use bstr::BStr;
51    ///
52    /// let a = BStr::new(b"abc");
53    /// let b = BStr::new(&b"abc"[..]);
54    /// let c = BStr::new("abc");
55    ///
56    /// assert_eq!(a, b);
57    /// assert_eq!(a, c);
58    /// ```
59    #[inline]
60    pub fn new<B: ?Sized + AsRef<[u8]>>(bytes: &B) -> &BStr {
61        BStr::from_bytes(bytes.as_ref())
62    }
63
64    #[inline]
65    pub(crate) fn new_mut<B: ?Sized + AsMut<[u8]>>(
66        bytes: &mut B,
67    ) -> &mut BStr {
68        BStr::from_bytes_mut(bytes.as_mut())
69    }
70
71    #[inline]
72    pub(crate) fn from_bytes(slice: &[u8]) -> &BStr {
73        unsafe { &*(slice as *const [u8] as *const BStr) }
74    }
75
76    #[inline]
77    pub(crate) fn from_bytes_mut(slice: &mut [u8]) -> &mut BStr {
78        unsafe { &mut *(slice as *mut [u8] as *mut BStr) }
79    }
80
81    #[inline]
82    #[cfg(feature = "alloc")]
83    pub(crate) fn from_boxed_bytes(slice: Box<[u8]>) -> Box<BStr> {
84        unsafe { Box::from_raw(Box::into_raw(slice) as _) }
85    }
86
87    #[inline]
88    #[cfg(feature = "alloc")]
89    pub(crate) fn into_boxed_bytes(slice: Box<BStr>) -> Box<[u8]> {
90        unsafe { Box::from_raw(Box::into_raw(slice) as _) }
91    }
92
93    #[inline]
94    pub(crate) fn as_bytes(&self) -> &[u8] {
95        &self.bytes
96    }
97}
bstr/bstr.rs

bstr/
bstr.rs
