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        Ok(Self(value))
88    }
89}
90
91impl Deref for BufferString {
92    type Target = str;
93
94    #[inline]
95    fn deref(&self) -> &Self::Target {
96        self.as_str()
97    }
98}
99
100impl AsRef<str> for BufferString {
101    #[inline]
102    fn as_ref(&self) -> &str {
103        self.as_str()
104    }
105}
106
107impl AsRef<[u8]> for BufferString {
108    #[inline]
109    fn as_ref(&self) -> &[u8] {
110        self.as_str().as_bytes()
111    }
112}
113
114#[cfg(test)]
115mod test {
116    use crate::Alignment;
117    use crate::BufferString;
118    use crate::buffer;
119
120    #[test]
121    fn buffer_string() {
122        let buf = BufferString::from("hello");
123        assert_eq!(buf.len(), 5);
124        assert_eq!(buf.into_inner().alignment(), Alignment::of::<u8>());
125    }
126
127    #[test]
128    fn buffer_string_non_ut8() {
129        assert!(BufferString::try_from(buffer![0u8, 255]).is_err());
130    }
131}
vortex_buffer/string.rs

vortex_buffer/
string.rs
