1 use alloc::vec::Vec;
2 
3 use crate::bstr::BStr;
4 
5 /// A wrapper for `Vec<u8>` that provides convenient string oriented trait
6 /// impls.
7 ///
8 /// A `BString` has ownership over its contents and corresponds to
9 /// a growable or shrinkable buffer. Its borrowed counterpart is a
10 /// [`BStr`](struct.BStr.html), called a byte string slice.
11 ///
12 /// Using a `BString` is just like using a `Vec<u8>`, since `BString`
13 /// implements `Deref` to `Vec<u8>`. So all methods available on `Vec<u8>`
14 /// are also available on `BString`.
15 ///
16 /// # Examples
17 ///
18 /// You can create a new `BString` from a `Vec<u8>` via a `From` impl:
19 ///
20 /// ```
21 /// use bstr::BString;
22 ///
23 /// let s = BString::from("Hello, world!");
24 /// ```
25 ///
26 /// # Deref
27 ///
28 /// The `BString` type implements `Deref` and `DerefMut`, where the target
29 /// types are `&Vec<u8>` and `&mut Vec<u8>`, respectively. `Deref` permits all of the
30 /// methods defined on `Vec<u8>` to be implicitly callable on any `BString`.
31 ///
32 /// For more information about how deref works, see the documentation for the
33 /// [`std::ops::Deref`](https://doc.rust-lang.org/std/ops/trait.Deref.html)
34 /// trait.
35 ///
36 /// # Representation
37 ///
38 /// A `BString` has the same representation as a `Vec<u8>` and a `String`.
39 /// That is, it is made up of three word sized components: a pointer to a
40 /// region of memory containing the bytes, a length and a capacity.
41 #[derive(Clone, Hash)]
42 pub struct BString {
43     bytes: Vec<u8>,
44 }
45 
46 impl BString {
47     /// Constructs a new `BString` from the given [`Vec`].
48     ///
49     /// # Examples
50     ///
51     /// ```
52     /// use bstr::BString;
53     ///
54     /// let mut b = BString::new(Vec::with_capacity(10));
55     /// ```
56     ///
57     /// This function is `const`:
58     ///
59     /// ```
60     /// use bstr::BString;
61     ///
62     /// const B: BString = BString::new(vec![]);
63     /// ```
64     #[inline]
new(bytes: Vec<u8>) -> BString65     pub const fn new(bytes: Vec<u8>) -> BString {
66         BString { bytes }
67     }
68 
69     #[inline]
as_bytes(&self) -> &[u8]70     pub(crate) fn as_bytes(&self) -> &[u8] {
71         &self.bytes
72     }
73 
74     #[inline]
as_bytes_mut(&mut self) -> &mut [u8]75     pub(crate) fn as_bytes_mut(&mut self) -> &mut [u8] {
76         &mut self.bytes
77     }
78 
79     #[inline]
as_bstr(&self) -> &BStr80     pub(crate) fn as_bstr(&self) -> &BStr {
81         BStr::new(&self.bytes)
82     }
83 
84     #[inline]
as_mut_bstr(&mut self) -> &mut BStr85     pub(crate) fn as_mut_bstr(&mut self) -> &mut BStr {
86         BStr::new_mut(&mut self.bytes)
87     }
88 
89     #[inline]
as_vec(&self) -> &Vec<u8>90     pub(crate) fn as_vec(&self) -> &Vec<u8> {
91         &self.bytes
92     }
93 
94     #[inline]
as_vec_mut(&mut self) -> &mut Vec<u8>95     pub(crate) fn as_vec_mut(&mut self) -> &mut Vec<u8> {
96         &mut self.bytes
97     }
98 
99     #[inline]
into_vec(self) -> Vec<u8>100     pub(crate) fn into_vec(self) -> Vec<u8> {
101         self.bytes
102     }
103 }
104