mlua/
string.rs

1//! Lua string handling.
2//!
3//! This module provides types for working with Lua strings from Rust.
4//!
5//! # Main Types
6//!
7//! - [`LuaString`] - A handle to an internal Lua string (may not be valid UTF-8).
8//! - [`BorrowedStr`] - A borrowed `&str` view of a Lua string that holds a strong reference to the
9//!   Lua state.
10//! - [`BorrowedBytes`] - A borrowed `&[u8]` view of a Lua string that holds a strong reference to
11//!   the Lua state.
12
13use std::borrow::Borrow;
14use std::hash::{Hash, Hasher};
15use std::ops::Deref;
16use std::os::raw::{c_int, c_void};
17use std::{cmp, fmt, mem, slice, str};
18
19use crate::error::{Error, Result};
20use crate::state::Lua;
21use crate::traits::IntoLua;
22use crate::types::{LuaType, ValueRef};
23use crate::value::Value;
24
25#[cfg(feature = "serde")]
26use {
27    serde::ser::{Serialize, Serializer},
28    std::result::Result as StdResult,
29};
30
31/// Handle to an internal Lua string.
32///
33/// Unlike Rust strings, Lua strings may not be valid UTF-8.
34#[derive(Clone)]
35pub struct LuaString(pub(crate) ValueRef);
36
37impl LuaString {
38    /// Get a [`BorrowedStr`] if the Lua string is valid UTF-8.
39    ///
40    /// The returned `BorrowedStr` holds a strong reference to the Lua state to guarantee the
41    /// validity of the underlying data.
42    ///
43    /// # Examples
44    ///
45    /// ```
46    /// # use mlua::{Lua, LuaString, Result};
47    /// # fn main() -> Result<()> {
48    /// # let lua = Lua::new();
49    /// let globals = lua.globals();
50    ///
51    /// let version: LuaString = globals.get("_VERSION")?;
52    /// assert!(version.to_str()?.contains("Lua"));
53    ///
54    /// let non_utf8: LuaString = lua.load(r#"  "test\255"  "#).eval()?;
55    /// assert!(non_utf8.to_str().is_err());
56    /// # Ok(())
57    /// # }
58    /// ```
59    #[inline]
60    pub fn to_str(&self) -> Result<BorrowedStr> {
61        BorrowedStr::try_from(self)
62    }
63
64    /// Converts this Lua string to a [`String`].
65    ///
66    /// Any non-Unicode sequences are replaced with [`U+FFFD REPLACEMENT CHARACTER`][U+FFFD].
67    ///
68    /// This method returns [`String`] instead of [`Cow<'_, str>`] because lifetime cannot be
69    /// bound to a weak Lua object.
70    ///
71    /// [U+FFFD]: std::char::REPLACEMENT_CHARACTER
72    /// [`Cow<'_, str>`]: std::borrow::Cow
73    ///
74    /// # Examples
75    ///
76    /// ```
77    /// # use mlua::{Lua, Result};
78    /// # fn main() -> Result<()> {
79    /// let lua = Lua::new();
80    ///
81    /// let s = lua.create_string(b"test\xff")?;
82    /// assert_eq!(s.to_string_lossy(), "test\u{fffd}");
83    /// # Ok(())
84    /// # }
85    /// ```
86    #[inline]
87    pub fn to_string_lossy(&self) -> String {
88        String::from_utf8_lossy(&self.as_bytes()).into_owned()
89    }
90
91    /// Returns an object that implements [`Display`] for safely printing a [`LuaString`] that may
92    /// contain non-Unicode data.
93    ///
94    /// This may perform lossy conversion.
95    ///
96    /// [`Display`]: fmt::Display
97    pub fn display(&self) -> impl fmt::Display + '_ {
98        Display(self)
99    }
100
101    /// Get the bytes that make up this string.
102    ///
103    /// The returned `BorrowedStr` holds a strong reference to the Lua state to guarantee the
104    /// validity of the underlying data. The data will not contain the terminating null byte, but
105    /// will contain any null bytes embedded into the Lua string.
106    ///
107    /// # Examples
108    ///
109    /// ```
110    /// # use mlua::{Lua, LuaString, Result};
111    /// # fn main() -> Result<()> {
112    /// # let lua = Lua::new();
113    /// let non_utf8: LuaString = lua.load(r#"  "test\255"  "#).eval()?;
114    /// assert!(non_utf8.to_str().is_err());    // oh no :(
115    /// assert_eq!(non_utf8.as_bytes(), &b"test\xff"[..]);
116    /// # Ok(())
117    /// # }
118    /// ```
119    #[inline]
120    pub fn as_bytes(&self) -> BorrowedBytes {
121        BorrowedBytes::from(self)
122    }
123
124    /// Get the bytes that make up this string, including the trailing null byte.
125    pub fn as_bytes_with_nul(&self) -> BorrowedBytes {
126        let BorrowedBytes { buf, vref, _lua } = BorrowedBytes::from(self);
127        // Include the trailing null byte (it's always present but excluded by default)
128        let buf = unsafe { slice::from_raw_parts((*buf).as_ptr(), (*buf).len() + 1) };
129        BorrowedBytes { buf, vref, _lua }
130    }
131
132    // Does not return the terminating null byte
133    unsafe fn to_slice(&self) -> (&[u8], Lua) {
134        let lua = self.0.lua.upgrade();
135        let slice = {
136            let rawlua = lua.lock();
137            let ref_thread = rawlua.ref_thread();
138
139            mlua_debug_assert!(
140                ffi::lua_type(ref_thread, self.0.index) == ffi::LUA_TSTRING,
141                "string ref is not string type"
142            );
143
144            // This will not trigger a 'm' error, because the reference is guaranteed to be of
145            // string type
146            let mut size = 0;
147            let data = ffi::lua_tolstring(ref_thread, self.0.index, &mut size);
148            slice::from_raw_parts(data as *const u8, size)
149        };
150        (slice, lua)
151    }
152
153    /// Converts this Lua string to a generic C pointer.
154    ///
155    /// There is no way to convert the pointer back to its original value.
156    ///
157    /// Typically this function is used only for hashing and debug information.
158    #[inline]
159    pub fn to_pointer(&self) -> *const c_void {
160        self.0.to_pointer()
161    }
162}
163
164impl fmt::Debug for LuaString {
165    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
166        let bytes = self.as_bytes();
167        // Check if the string is valid utf8
168        if let Ok(s) = str::from_utf8(&bytes) {
169            return s.fmt(f);
170        }
171
172        // Format as bytes
173        write!(f, "b")?;
174        <bstr::BStr as fmt::Debug>::fmt(bstr::BStr::new(&bytes), f)
175    }
176}
177
178// Lua strings are basically `&[u8]` slices, so implement `PartialEq` for anything resembling that.
179//
180// This makes our `LuaString` comparable with `Vec<u8>`, `[u8]`, `&str` and `String`.
181//
182// The only downside is that this disallows a comparison with `Cow<str>`, as that only implements
183// `AsRef<str>`, which collides with this impl. Requiring `AsRef<str>` would fix that, but limit us
184// in other ways.
185impl<T> PartialEq<T> for LuaString
186where
187    T: AsRef<[u8]> + ?Sized,
188{
189    fn eq(&self, other: &T) -> bool {
190        self.as_bytes() == other.as_ref()
191    }
192}
193
194impl PartialEq for LuaString {
195    fn eq(&self, other: &LuaString) -> bool {
196        self.as_bytes() == other.as_bytes()
197    }
198}
199
200impl Eq for LuaString {}
201
202impl<T> PartialOrd<T> for LuaString
203where
204    T: AsRef<[u8]> + ?Sized,
205{
206    fn partial_cmp(&self, other: &T) -> Option<cmp::Ordering> {
207        <[u8]>::partial_cmp(&self.as_bytes(), other.as_ref())
208    }
209}
210
211impl PartialOrd for LuaString {
212    fn partial_cmp(&self, other: &LuaString) -> Option<cmp::Ordering> {
213        Some(self.cmp(other))
214    }
215}
216
217impl Ord for LuaString {
218    fn cmp(&self, other: &LuaString) -> cmp::Ordering {
219        self.as_bytes().cmp(&other.as_bytes())
220    }
221}
222
223impl Hash for LuaString {
224    fn hash<H: Hasher>(&self, state: &mut H) {
225        self.as_bytes().hash(state);
226    }
227}
228
229#[cfg(feature = "serde")]
230impl Serialize for LuaString {
231    fn serialize<S>(&self, serializer: S) -> StdResult<S::Ok, S::Error>
232    where
233        S: Serializer,
234    {
235        match self.to_str() {
236            Ok(s) => serializer.serialize_str(&s),
237            Err(_) => serializer.serialize_bytes(&self.as_bytes()),
238        }
239    }
240}
241
242struct Display<'a>(&'a LuaString);
243
244impl fmt::Display for Display<'_> {
245    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
246        let bytes = self.0.as_bytes();
247        <bstr::BStr as fmt::Display>::fmt(bstr::BStr::new(&bytes), f)
248    }
249}
250
251/// A borrowed string (`&str`) that holds a strong reference to the Lua state.
252pub struct BorrowedStr {
253    // `buf` points to a readonly memory managed by Lua
254    pub(crate) buf: &'static str,
255    pub(crate) vref: ValueRef,
256    pub(crate) _lua: Lua,
257}
258
259impl Deref for BorrowedStr {
260    type Target = str;
261
262    #[inline(always)]
263    fn deref(&self) -> &str {
264        self.buf
265    }
266}
267
268impl Borrow<str> for BorrowedStr {
269    #[inline(always)]
270    fn borrow(&self) -> &str {
271        self.buf
272    }
273}
274
275impl AsRef<str> for BorrowedStr {
276    #[inline(always)]
277    fn as_ref(&self) -> &str {
278        self.buf
279    }
280}
281
282impl fmt::Display for BorrowedStr {
283    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
284        self.buf.fmt(f)
285    }
286}
287
288impl fmt::Debug for BorrowedStr {
289    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
290        self.buf.fmt(f)
291    }
292}
293
294impl<T> PartialEq<T> for BorrowedStr
295where
296    T: AsRef<str>,
297{
298    fn eq(&self, other: &T) -> bool {
299        self.buf == other.as_ref()
300    }
301}
302
303impl Eq for BorrowedStr {}
304
305impl<T> PartialOrd<T> for BorrowedStr
306where
307    T: AsRef<str>,
308{
309    fn partial_cmp(&self, other: &T) -> Option<cmp::Ordering> {
310        self.buf.partial_cmp(other.as_ref())
311    }
312}
313
314impl Ord for BorrowedStr {
315    fn cmp(&self, other: &Self) -> cmp::Ordering {
316        self.buf.cmp(other.buf)
317    }
318}
319
320impl TryFrom<&LuaString> for BorrowedStr {
321    type Error = Error;
322
323    #[inline]
324    fn try_from(value: &LuaString) -> Result<Self> {
325        let BorrowedBytes { buf, vref, _lua } = BorrowedBytes::from(value);
326        let buf =
327            str::from_utf8(buf).map_err(|e| Error::from_lua_conversion("string", "&str", e.to_string()))?;
328        Ok(Self { buf, vref, _lua })
329    }
330}
331
332/// A borrowed byte slice (`&[u8]`) that holds a strong reference to the Lua state.
333pub struct BorrowedBytes {
334    // `buf` points to a readonly memory managed by Lua
335    pub(crate) buf: &'static [u8],
336    pub(crate) vref: ValueRef,
337    pub(crate) _lua: Lua,
338}
339
340impl Deref for BorrowedBytes {
341    type Target = [u8];
342
343    #[inline(always)]
344    fn deref(&self) -> &[u8] {
345        self.buf
346    }
347}
348
349impl Borrow<[u8]> for BorrowedBytes {
350    #[inline(always)]
351    fn borrow(&self) -> &[u8] {
352        self.buf
353    }
354}
355
356impl AsRef<[u8]> for BorrowedBytes {
357    #[inline(always)]
358    fn as_ref(&self) -> &[u8] {
359        self.buf
360    }
361}
362
363impl fmt::Debug for BorrowedBytes {
364    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
365        self.buf.fmt(f)
366    }
367}
368
369impl<T> PartialEq<T> for BorrowedBytes
370where
371    T: AsRef<[u8]>,
372{
373    fn eq(&self, other: &T) -> bool {
374        self.buf == other.as_ref()
375    }
376}
377
378impl Eq for BorrowedBytes {}
379
380impl<T> PartialOrd<T> for BorrowedBytes
381where
382    T: AsRef<[u8]>,
383{
384    fn partial_cmp(&self, other: &T) -> Option<cmp::Ordering> {
385        self.buf.partial_cmp(other.as_ref())
386    }
387}
388
389impl Ord for BorrowedBytes {
390    fn cmp(&self, other: &Self) -> cmp::Ordering {
391        self.buf.cmp(other.buf)
392    }
393}
394
395impl<'a> IntoIterator for &'a BorrowedBytes {
396    type Item = &'a u8;
397    type IntoIter = slice::Iter<'a, u8>;
398
399    fn into_iter(self) -> Self::IntoIter {
400        self.iter()
401    }
402}
403
404impl From<&LuaString> for BorrowedBytes {
405    #[inline]
406    fn from(value: &LuaString) -> Self {
407        let (buf, _lua) = unsafe { value.to_slice() };
408        let vref = value.0.clone();
409        // SAFETY: The `buf` is valid for the lifetime of the Lua state and occupied slot index
410        let buf = unsafe { mem::transmute::<&[u8], &'static [u8]>(buf) };
411        Self { buf, vref, _lua }
412    }
413}
414
415struct WrappedString<T: AsRef<[u8]>>(T);
416
417impl LuaString {
418    /// Wraps bytes, returning an opaque type that implements [`IntoLua`] trait.
419    ///
420    /// This function uses [`Lua::create_string`] under the hood.
421    pub fn wrap(data: impl AsRef<[u8]>) -> impl IntoLua {
422        WrappedString(data)
423    }
424}
425
426impl<T: AsRef<[u8]>> IntoLua for WrappedString<T> {
427    fn into_lua(self, lua: &Lua) -> Result<Value> {
428        lua.create_string(self.0).map(Value::String)
429    }
430}
431
432impl LuaType for LuaString {
433    const TYPE_ID: c_int = ffi::LUA_TSTRING;
434}
435
436#[cfg(test)]
437mod assertions {
438    use super::*;
439
440    #[cfg(not(feature = "send"))]
441    static_assertions::assert_not_impl_any!(LuaString: Send);
442    #[cfg(feature = "send")]
443    static_assertions::assert_impl_all!(LuaString: Send, Sync);
444    #[cfg(feature = "send")]
445    static_assertions::assert_impl_all!(BorrowedBytes: Send, Sync);
446    #[cfg(feature = "send")]
447    static_assertions::assert_impl_all!(BorrowedStr: Send, Sync);
448}
mlua/string.rs

mlua/
string.rs
