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}
98