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