bstr/
bstring.rs

1use alloc::vec::Vec;
2
3use 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)]
42#[repr(transparent)]
43pub struct BString {
44    bytes: Vec<u8>,
45}
46
47impl BString {
48    /// Constructs a new `BString` from the given [`Vec`].
49    ///
50    /// # Examples
51    ///
52    /// ```
53    /// use bstr::BString;
54    ///
55    /// let mut b = BString::new(Vec::with_capacity(10));
56    /// ```
57    ///
58    /// This function is `const`:
59    ///
60    /// ```
61    /// use bstr::BString;
62    ///
63    /// const B: BString = BString::new(vec![]);
64    /// ```
65    #[inline]
66    pub const fn new(bytes: Vec<u8>) -> BString {
67        BString { bytes }
68    }
69
70    #[inline]
71    pub(crate) fn as_bytes(&self) -> &[u8] {
72        &self.bytes
73    }
74
75    #[inline]
76    pub(crate) fn as_bytes_mut(&mut self) -> &mut [u8] {
77        &mut self.bytes
78    }
79
80    #[inline]
81    pub(crate) fn as_bstr(&self) -> &BStr {
82        BStr::new(&self.bytes)
83    }
84
85    #[inline]
86    pub(crate) fn as_mut_bstr(&mut self) -> &mut BStr {
87        BStr::new_mut(&mut self.bytes)
88    }
89
90    #[inline]
91    pub(crate) fn as_vec(&self) -> &Vec<u8> {
92        &self.bytes
93    }
94
95    #[inline]
96    pub(crate) fn as_vec_mut(&mut self) -> &mut Vec<u8> {
97        &mut self.bytes
98    }
99
100    #[inline]
101    pub(crate) fn into_vec(self) -> Vec<u8> {
102        self.bytes
103    }
104
105    #[inline]
106    pub(crate) fn from_vec_ref(v: &Vec<u8>) -> &BString {
107        // SAFETY: `BString` is a `repr(transparent)` wrapper around `Vec<u8>`, and accepts any
108        // `Vec<u8>` without validation.
109        //
110        // MSRV: Switch this to use `ptr::from_ref` once bstr can require at least Rust 1.72.
111        unsafe { &*(v as *const Vec<u8> as *const BString) }
112    }
113
114    #[inline]
115    pub(crate) fn from_vec_mut(v: &mut Vec<u8>) -> &mut BString {
116        // SAFETY: `BString` is a `repr(transparent)` wrapper around `Vec<u8>`, and accepts any
117        // `Vec<u8>` without validation.
118        //
119        // MSRV: Switch this to use `ptr::from_mut` once bstr can require at least Rust 1.72.
120        unsafe { &mut *(v as *mut Vec<u8> as *mut BString) }
121    }
122}
bstr/bstring.rs

bstr/
bstring.rs
