1use core::mem;
2
3#[cfg(feature = "alloc")]
4use 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)]
34pub struct BStr {
35 pub(crate) bytes: [u8],
36}
37
38impl 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]
63 pub fn new<'a, B: ?Sized + AsRef<[u8]>>(bytes: &'a B) -> &'a BStr {
64 BStr::from_bytes(bytes.as_ref())
65 }
66
67 #[inline]
68 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]
75 pub(crate) fn from_bytes(slice: &[u8]) -> &BStr {
76 unsafe { mem::transmute(slice) }
77 }
78
79 #[inline]
80 pub(crate) fn from_bytes_mut(slice: &mut [u8]) -> &mut BStr {
81 unsafe { mem::transmute(slice) }
82 }
83
84 #[inline]
85 #[cfg(feature = "alloc")]
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")]
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]
97 pub(crate) fn as_bytes(&self) -> &[u8] {
98 &self.bytes
99 }
100}
101