vortex_buffer/
string.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright the Vortex contributors
3
4use std::fmt::Debug;
5use std::fmt::Formatter;
6use std::ops::Deref;
7
8use vortex_error::VortexError;
9use vortex_error::vortex_err;
10
11use crate::ByteBuffer;
12
13/// A wrapper around a [`ByteBuffer`] that guarantees that the buffer contains valid UTF-8.
14#[derive(Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
15pub struct BufferString(ByteBuffer);
16
17impl BufferString {
18    /// Creates a new `BufferString` from a [`ByteBuffer`].
19    ///
20    /// # Safety
21    /// Assumes that the buffer contains valid UTF-8.
22    pub const unsafe fn new_unchecked(buffer: ByteBuffer) -> Self {
23        Self(buffer)
24    }
25
26    /// Creates an empty `BufferString`.
27    pub fn empty() -> Self {
28        Self(ByteBuffer::from(vec![]))
29    }
30
31    /// Return a view of the contents of BufferString as an immutable `&str`.
32    pub fn as_str(&self) -> &str {
33        // SAFETY: We have already validated that the buffer is valid UTF-8
34        unsafe { std::str::from_utf8_unchecked(self.0.as_ref()) }
35    }
36
37    /// Returns the inner [`ByteBuffer`].
38    pub fn into_inner(self) -> ByteBuffer {
39        self.0
40    }
41
42    /// Returns reference to the inner [`ByteBuffer`].
43    pub fn inner(&self) -> &ByteBuffer {
44        &self.0
45    }
46}
47
48impl Debug for BufferString {
49    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
50        f.debug_struct("BufferString")
51            .field("string", &self.as_str())
52            .finish()
53    }
54}
55
56impl From<BufferString> for ByteBuffer {
57    fn from(value: BufferString) -> Self {
58        value.0
59    }
60}
61
62impl From<String> for BufferString {
63    fn from(value: String) -> Self {
64        Self(ByteBuffer::from(value.into_bytes()))
65    }
66}
67
68impl From<&str> for BufferString {
69    fn from(value: &str) -> Self {
70        Self(ByteBuffer::from(String::from(value).into_bytes()))
71    }
72}
73
74impl TryFrom<ByteBuffer> for BufferString {
75    type Error = VortexError;
76
77    fn try_from(value: ByteBuffer) -> Result<Self, Self::Error> {
78        simdutf8::basic::from_utf8(value.as_ref()).map_err(|_| {
79            #[expect(
80                clippy::unwrap_used,
81                reason = "unwrap is intentional - the error was already detected"
82            )]
83            // run validation using `compat` package to get more detailed error message
84            let err = simdutf8::compat::from_utf8(value.as_ref()).unwrap_err();
85            vortex_err!("invalid utf-8: {err}")
86        })?;
87
88        Ok(Self(value))
89    }
90}
91
92impl TryFrom<&[u8]> for BufferString {
93    type Error = VortexError;
94
95    fn try_from(value: &[u8]) -> Result<Self, Self::Error> {
96        simdutf8::basic::from_utf8(value).map_err(|_| {
97            #[expect(
98                clippy::unwrap_used,
99                reason = "unwrap is intentional - the error was already detected"
100            )]
101            // run validation using `compat` package to get more detailed error message
102            let err = simdutf8::compat::from_utf8(value).unwrap_err();
103            vortex_err!("invalid utf-8: {err}")
104        })?;
105
106        Ok(Self(ByteBuffer::from(value.to_vec())))
107    }
108}
109
110impl Deref for BufferString {
111    type Target = str;
112
113    #[inline]
114    fn deref(&self) -> &Self::Target {
115        self.as_str()
116    }
117}
118
119impl AsRef<str> for BufferString {
120    #[inline]
121    fn as_ref(&self) -> &str {
122        self.as_str()
123    }
124}
125
126impl AsRef<[u8]> for BufferString {
127    #[inline]
128    fn as_ref(&self) -> &[u8] {
129        self.as_str().as_bytes()
130    }
131}
132
133#[cfg(test)]
134mod test {
135    use crate::Alignment;
136    use crate::BufferString;
137    use crate::buffer;
138
139    #[test]
140    fn buffer_string() {
141        let buf = BufferString::from("hello");
142        assert_eq!(buf.len(), 5);
143        assert_eq!(buf.into_inner().alignment(), Alignment::of::<u8>());
144    }
145
146    #[test]
147    fn buffer_string_non_ut8() {
148        assert!(BufferString::try_from(buffer![0u8, 255]).is_err());
149    }
150}
vortex_buffer/string.rs

vortex_buffer/
string.rs
