mlua/
value.rs

1use std::cmp::Ordering;
2use std::collections::HashSet;
3use std::os::raw::c_void;
4use std::{fmt, ptr, str};
5
6use num_traits::FromPrimitive;
7
8use crate::error::{Error, Result};
9use crate::function::Function;
10use crate::string::LuaString;
11use crate::table::Table;
12use crate::thread::Thread;
13use crate::types::{Integer, LightUserData, Number, ValueRef};
14use crate::userdata::AnyUserData;
15use crate::util::{StackGuard, check_stack};
16
17#[cfg(feature = "serde")]
18use {
19    crate::table::SerializableTable,
20    rustc_hash::FxHashSet,
21    serde::ser::{self, Serialize, Serializer},
22    std::{cell::RefCell, rc::Rc, result::Result as StdResult},
23};
24
25/// A dynamically typed Lua value.
26///
27/// The non-primitive variants (eg. string/table/function/thread/userdata) contain handle types
28/// into the internal Lua state. It is a logic error to mix handle types between separate
29/// `Lua` instances, and doing so will result in a panic.
30#[derive(Clone, Default)]
31pub enum Value {
32    /// The Lua value `nil`.
33    #[default]
34    Nil,
35    /// The Lua value `true` or `false`.
36    Boolean(bool),
37    /// A "light userdata" object, equivalent to a raw pointer.
38    LightUserData(LightUserData),
39    /// An integer number.
40    ///
41    /// Any Lua number convertible to an `Integer` will be represented as this variant.
42    Integer(Integer),
43    /// A floating point number.
44    Number(Number),
45    /// A Luau vector.
46    #[cfg(any(feature = "luau", doc))]
47    #[cfg_attr(docsrs, doc(cfg(feature = "luau")))]
48    Vector(crate::Vector),
49    /// An interned string, managed by Lua.
50    ///
51    /// Unlike Rust strings, Lua strings may not be valid UTF-8.
52    String(LuaString),
53    /// Reference to a Lua table.
54    Table(Table),
55    /// Reference to a Lua function (or closure).
56    Function(Function),
57    /// Reference to a Lua thread (or coroutine).
58    Thread(Thread),
59    /// Reference to a userdata object that holds a custom type which implements `UserData`.
60    ///
61    /// Special builtin userdata types will be represented as other `Value` variants.
62    UserData(AnyUserData),
63    /// A Luau buffer.
64    #[cfg(any(feature = "luau", doc))]
65    #[cfg_attr(docsrs, doc(cfg(feature = "luau")))]
66    Buffer(crate::Buffer),
67    /// `Error` is a special builtin userdata type. When received from Lua it is implicitly cloned.
68    Error(Box<Error>),
69    /// Any other value not known to mlua (eg. LuaJIT CData).
70    Other(#[doc(hidden)] ValueRef),
71}
72
73pub use self::Value::Nil;
74
75impl Value {
76    /// A special value (lightuserdata) to represent null value.
77    ///
78    /// It can be used in Lua tables without downsides of `nil`.
79    pub const NULL: Value = Value::LightUserData(LightUserData(ptr::null_mut()));
80
81    /// Returns type name of this value.
82    pub fn type_name(&self) -> &'static str {
83        match *self {
84            Value::Nil => "nil",
85            Value::Boolean(_) => "boolean",
86            Value::LightUserData(_) => "lightuserdata",
87            Value::Integer(_) => "integer",
88            Value::Number(_) => "number",
89            #[cfg(feature = "luau")]
90            Value::Vector(_) => "vector",
91            Value::String(_) => "string",
92            Value::Table(_) => "table",
93            Value::Function(_) => "function",
94            Value::Thread(_) => "thread",
95            Value::UserData(_) => "userdata",
96            #[cfg(feature = "luau")]
97            Value::Buffer(_) => "buffer",
98            Value::Error(_) => "error",
99            Value::Other(_) => "other",
100        }
101    }
102
103    /// Compares two values for equality.
104    ///
105    /// Equality comparisons do not convert strings to numbers or vice versa.
106    /// Tables, functions, threads, and userdata are compared by reference:
107    /// two objects are considered equal only if they are the same object.
108    ///
109    /// If table or userdata have `__eq` metamethod then mlua will try to invoke it.
110    /// The first value is checked first. If that value does not define a metamethod
111    /// for `__eq`, then mlua will check the second value.
112    /// Then mlua calls the metamethod with the two values as arguments, if found.
113    pub fn equals(&self, other: &Self) -> Result<bool> {
114        match (self, other) {
115            (Value::Table(a), Value::Table(b)) => a.equals(b),
116            (Value::UserData(a), Value::UserData(b)) => a.equals(b),
117            (a, b) => Ok(a == b),
118        }
119    }
120
121    /// Converts the value to a generic C pointer.
122    ///
123    /// The value can be a userdata, a table, a thread, a string, or a function; otherwise it
124    /// returns NULL. Different objects will give different pointers.
125    /// There is no way to convert the pointer back to its original value.
126    ///
127    /// Typically this function is used only for hashing and debug information.
128    #[inline]
129    pub fn to_pointer(&self) -> *const c_void {
130        match self {
131            Value::LightUserData(ud) => ud.0,
132            Value::Table(Table(vref))
133            | Value::Function(Function(vref))
134            | Value::Thread(Thread(vref, ..))
135            | Value::UserData(AnyUserData(vref))
136            | Value::Other(vref) => vref.to_pointer(),
137            Value::String(s) => s.to_pointer(),
138            #[cfg(feature = "luau")]
139            Value::Buffer(crate::Buffer(vref)) => vref.to_pointer(),
140            _ => ptr::null(),
141        }
142    }
143
144    /// Converts the value to a string.
145    ///
146    /// This might invoke the `__tostring` metamethod for non-primitive types (eg. tables,
147    /// functions).
148    pub fn to_string(&self) -> Result<String> {
149        unsafe fn invoke_tostring(vref: &ValueRef) -> Result<String> {
150            let lua = vref.lua.lock();
151            let state = lua.state();
152            let _guard = StackGuard::new(state);
153            check_stack(state, 3)?;
154
155            lua.push_ref(vref);
156            protect_lua!(state, 1, 1, fn(state) {
157                ffi::luaL_tolstring(state, -1, ptr::null_mut());
158            })?;
159            Ok(LuaString(lua.pop_ref()).to_str()?.to_string())
160        }
161
162        match self {
163            Value::Nil => Ok("nil".to_string()),
164            Value::Boolean(b) => Ok(b.to_string()),
165            Value::LightUserData(ud) if ud.0.is_null() => Ok("null".to_string()),
166            Value::LightUserData(ud) => Ok(format!("lightuserdata: {:p}", ud.0)),
167            Value::Integer(i) => Ok(i.to_string()),
168            Value::Number(n) => Ok(n.to_string()),
169            #[cfg(feature = "luau")]
170            Value::Vector(v) => Ok(v.to_string()),
171            Value::String(s) => Ok(s.to_str()?.to_string()),
172            Value::Table(Table(vref))
173            | Value::Function(Function(vref))
174            | Value::Thread(Thread(vref, ..))
175            | Value::UserData(AnyUserData(vref))
176            | Value::Other(vref) => unsafe { invoke_tostring(vref) },
177            #[cfg(feature = "luau")]
178            Value::Buffer(crate::Buffer(vref)) => unsafe { invoke_tostring(vref) },
179            Value::Error(err) => Ok(err.to_string()),
180        }
181    }
182
183    /// Returns `true` if the value is a [`Nil`].
184    #[inline]
185    pub fn is_nil(&self) -> bool {
186        self == &Nil
187    }
188
189    /// Returns `true` if the value is a [`NULL`].
190    ///
191    /// [`NULL`]: Value::NULL
192    #[inline]
193    pub fn is_null(&self) -> bool {
194        self == &Self::NULL
195    }
196
197    /// Returns `true` if the value is a boolean.
198    #[inline]
199    pub fn is_boolean(&self) -> bool {
200        self.as_boolean().is_some()
201    }
202
203    /// Cast the value to boolean.
204    ///
205    /// If the value is a Boolean, returns it or `None` otherwise.
206    #[inline]
207    pub fn as_boolean(&self) -> Option<bool> {
208        match *self {
209            Value::Boolean(b) => Some(b),
210            _ => None,
211        }
212    }
213
214    /// Returns `true` if the value is a [`LightUserData`].
215    #[inline]
216    pub fn is_light_userdata(&self) -> bool {
217        self.as_light_userdata().is_some()
218    }
219
220    /// Cast the value to [`LightUserData`].
221    ///
222    /// If the value is a [`LightUserData`], returns it or `None` otherwise.
223    #[inline]
224    pub fn as_light_userdata(&self) -> Option<LightUserData> {
225        match *self {
226            Value::LightUserData(l) => Some(l),
227            _ => None,
228        }
229    }
230
231    /// Returns `true` if the value is an [`Integer`].
232    #[inline]
233    pub fn is_integer(&self) -> bool {
234        self.as_integer().is_some()
235    }
236
237    /// Cast the value to [`Integer`].
238    ///
239    /// If the value is a Lua [`Integer`], returns it or `None` otherwise.
240    #[inline]
241    pub fn as_integer(&self) -> Option<Integer> {
242        match *self {
243            Value::Integer(i) => Some(i),
244            _ => None,
245        }
246    }
247
248    /// Cast the value to `i32`.
249    ///
250    /// If the value is a Lua [`Integer`], try to convert it to `i32` or return `None` otherwise.
251    #[inline]
252    pub fn as_i32(&self) -> Option<i32> {
253        #[allow(clippy::useless_conversion)]
254        self.as_integer().and_then(|i| i32::try_from(i).ok())
255    }
256
257    /// Cast the value to `u32`.
258    ///
259    /// If the value is a Lua [`Integer`], try to convert it to `u32` or return `None` otherwise.
260    #[inline]
261    pub fn as_u32(&self) -> Option<u32> {
262        self.as_integer().and_then(|i| u32::try_from(i).ok())
263    }
264
265    /// Cast the value to `i64`.
266    ///
267    /// If the value is a Lua [`Integer`], try to convert it to `i64` or return `None` otherwise.
268    #[inline]
269    pub fn as_i64(&self) -> Option<i64> {
270        #[cfg(target_pointer_width = "64")]
271        return self.as_integer();
272        #[cfg(not(target_pointer_width = "64"))]
273        return self.as_integer().map(i64::from);
274    }
275
276    /// Cast the value to `u64`.
277    ///
278    /// If the value is a Lua [`Integer`], try to convert it to `u64` or return `None` otherwise.
279    #[inline]
280    pub fn as_u64(&self) -> Option<u64> {
281        self.as_integer().and_then(|i| u64::try_from(i).ok())
282    }
283
284    /// Cast the value to `isize`.
285    ///
286    /// If the value is a Lua [`Integer`], try to convert it to `isize` or return `None` otherwise.
287    #[inline]
288    pub fn as_isize(&self) -> Option<isize> {
289        self.as_integer().and_then(|i| isize::try_from(i).ok())
290    }
291
292    /// Cast the value to `usize`.
293    ///
294    /// If the value is a Lua [`Integer`], try to convert it to `usize` or return `None` otherwise.
295    #[inline]
296    pub fn as_usize(&self) -> Option<usize> {
297        self.as_integer().and_then(|i| usize::try_from(i).ok())
298    }
299
300    /// Returns `true` if the value is a Lua [`Number`].
301    #[inline]
302    pub fn is_number(&self) -> bool {
303        self.as_number().is_some()
304    }
305
306    /// Cast the value to [`Number`].
307    ///
308    /// If the value is a Lua [`Number`], returns it or `None` otherwise.
309    #[inline]
310    pub fn as_number(&self) -> Option<Number> {
311        match *self {
312            Value::Number(n) => Some(n),
313            _ => None,
314        }
315    }
316
317    /// Cast the value to `f32`.
318    ///
319    /// If the value is a Lua [`Number`], try to convert it to `f32` or return `None` otherwise.
320    #[inline]
321    pub fn as_f32(&self) -> Option<f32> {
322        self.as_number().and_then(f32::from_f64)
323    }
324
325    /// Cast the value to `f64`.
326    ///
327    /// If the value is a Lua [`Number`], try to convert it to `f64` or return `None` otherwise.
328    #[inline]
329    pub fn as_f64(&self) -> Option<f64> {
330        self.as_number()
331    }
332
333    /// Returns `true` if the value is a [`LuaString`].
334    #[inline]
335    pub fn is_string(&self) -> bool {
336        self.as_string().is_some()
337    }
338
339    /// Cast the value to a [`LuaString`].
340    ///
341    /// If the value is a [`LuaString`], returns it or `None` otherwise.
342    #[inline]
343    pub fn as_string(&self) -> Option<&LuaString> {
344        match self {
345            Value::String(s) => Some(s),
346            _ => None,
347        }
348    }
349
350    /// Returns `true` if the value is a Lua [`Table`].
351    #[inline]
352    pub fn is_table(&self) -> bool {
353        self.as_table().is_some()
354    }
355
356    /// Cast the value to [`Table`].
357    ///
358    /// If the value is a Lua [`Table`], returns it or `None` otherwise.
359    #[inline]
360    pub fn as_table(&self) -> Option<&Table> {
361        match self {
362            Value::Table(t) => Some(t),
363            _ => None,
364        }
365    }
366
367    /// Returns `true` if the value is a Lua [`Thread`].
368    #[inline]
369    pub fn is_thread(&self) -> bool {
370        self.as_thread().is_some()
371    }
372
373    /// Cast the value to [`Thread`].
374    ///
375    /// If the value is a Lua [`Thread`], returns it or `None` otherwise.
376    #[inline]
377    pub fn as_thread(&self) -> Option<&Thread> {
378        match self {
379            Value::Thread(t) => Some(t),
380            _ => None,
381        }
382    }
383
384    /// Returns `true` if the value is a Lua [`Function`].
385    #[inline]
386    pub fn is_function(&self) -> bool {
387        self.as_function().is_some()
388    }
389
390    /// Cast the value to [`Function`].
391    ///
392    /// If the value is a Lua [`Function`], returns it or `None` otherwise.
393    #[inline]
394    pub fn as_function(&self) -> Option<&Function> {
395        match self {
396            Value::Function(f) => Some(f),
397            _ => None,
398        }
399    }
400
401    /// Returns `true` if the value is an [`AnyUserData`].
402    #[inline]
403    pub fn is_userdata(&self) -> bool {
404        self.as_userdata().is_some()
405    }
406
407    /// Cast the value to [`AnyUserData`].
408    ///
409    /// If the value is an [`AnyUserData`], returns it or `None` otherwise.
410    #[inline]
411    pub fn as_userdata(&self) -> Option<&AnyUserData> {
412        match self {
413            Value::UserData(ud) => Some(ud),
414            _ => None,
415        }
416    }
417
418    /// Cast the value to a [`Vector`].
419    ///
420    /// If the value is a [`Vector`], returns it or `None` otherwise.
421    ///
422    /// [`Vector`]: crate::Vector
423    #[cfg(any(feature = "luau", doc))]
424    #[cfg_attr(docsrs, doc(cfg(feature = "luau")))]
425    #[inline]
426    pub fn as_vector(&self) -> Option<crate::Vector> {
427        match self {
428            Value::Vector(v) => Some(*v),
429            _ => None,
430        }
431    }
432
433    /// Returns `true` if the value is a [`Vector`].
434    ///
435    /// [`Vector`]: crate::Vector
436    #[cfg(any(feature = "luau", doc))]
437    #[cfg_attr(docsrs, doc(cfg(feature = "luau")))]
438    #[inline]
439    pub fn is_vector(&self) -> bool {
440        self.as_vector().is_some()
441    }
442
443    /// Cast the value to a [`Buffer`].
444    ///
445    /// If the value is [`Buffer`], returns it or `None` otherwise.
446    ///
447    /// [`Buffer`]: crate::Buffer
448    #[cfg(any(feature = "luau", doc))]
449    #[cfg_attr(docsrs, doc(cfg(feature = "luau")))]
450    #[inline]
451    pub fn as_buffer(&self) -> Option<&crate::Buffer> {
452        match self {
453            Value::Buffer(b) => Some(b),
454            _ => None,
455        }
456    }
457
458    /// Returns `true` if the value is a [`Buffer`].
459    ///
460    /// [`Buffer`]: crate::Buffer
461    #[cfg(any(feature = "luau", doc))]
462    #[cfg_attr(docsrs, doc(cfg(feature = "luau")))]
463    #[inline]
464    pub fn is_buffer(&self) -> bool {
465        self.as_buffer().is_some()
466    }
467
468    /// Returns `true` if the value is an [`Error`].
469    #[inline]
470    pub fn is_error(&self) -> bool {
471        self.as_error().is_some()
472    }
473
474    /// Cast the value to [`Error`].
475    ///
476    /// If the value is an [`Error`], returns it or `None` otherwise.
477    pub fn as_error(&self) -> Option<&Error> {
478        match self {
479            Value::Error(e) => Some(e),
480            _ => None,
481        }
482    }
483
484    /// Wrap reference to this Value into [`SerializableValue`].
485    ///
486    /// This allows customizing serialization behavior using serde.
487    #[cfg(feature = "serde")]
488    #[cfg_attr(docsrs, doc(cfg(feature = "serde")))]
489    pub fn to_serializable(&self) -> SerializableValue<'_> {
490        SerializableValue::new(self, Default::default(), None)
491    }
492
493    // Compares two values.
494    // Used to sort values for Debug printing.
495    pub(crate) fn sort_cmp(&self, other: &Self) -> Ordering {
496        match (self, other) {
497            // Nil
498            (Value::Nil, Value::Nil) => Ordering::Equal,
499            (Value::Nil, _) => Ordering::Less,
500            (_, Value::Nil) => Ordering::Greater,
501            // Null (a special case)
502            (Value::LightUserData(ud1), Value::LightUserData(ud2)) if ud1 == ud2 => Ordering::Equal,
503            (Value::LightUserData(ud1), _) if ud1.0.is_null() => Ordering::Less,
504            (_, Value::LightUserData(ud2)) if ud2.0.is_null() => Ordering::Greater,
505            // Boolean
506            (Value::Boolean(a), Value::Boolean(b)) => a.cmp(b),
507            (Value::Boolean(_), _) => Ordering::Less,
508            (_, Value::Boolean(_)) => Ordering::Greater,
509            // Integer && Number
510            (Value::Integer(a), Value::Integer(b)) => a.cmp(b),
511            (Value::Integer(a), Value::Number(b)) => (*a as Number).partial_cmp(b).unwrap_or(Ordering::Equal),
512            (Value::Number(a), Value::Integer(b)) => {
513                a.partial_cmp(&(*b as Number)).unwrap_or(Ordering::Equal)
514            }
515            (Value::Number(a), Value::Number(b)) => a.partial_cmp(b).unwrap_or(Ordering::Equal),
516            (Value::Integer(_) | Value::Number(_), _) => Ordering::Less,
517            (_, Value::Integer(_) | Value::Number(_)) => Ordering::Greater,
518            // Vector (Luau)
519            #[cfg(feature = "luau")]
520            (Value::Vector(a), Value::Vector(b)) => a.partial_cmp(b).unwrap_or(Ordering::Equal),
521            // String
522            (Value::String(a), Value::String(b)) => a.as_bytes().cmp(&b.as_bytes()),
523            (Value::String(_), _) => Ordering::Less,
524            (_, Value::String(_)) => Ordering::Greater,
525            // Other variants can be ordered by their pointer
526            (a, b) => a.to_pointer().cmp(&b.to_pointer()),
527        }
528    }
529
530    pub(crate) fn fmt_pretty(
531        &self,
532        fmt: &mut fmt::Formatter,
533        recursive: bool,
534        ident: usize,
535        visited: &mut HashSet<*const c_void>,
536    ) -> fmt::Result {
537        match self {
538            Value::Nil => write!(fmt, "nil"),
539            Value::Boolean(b) => write!(fmt, "{b}"),
540            Value::LightUserData(ud) if ud.0.is_null() => write!(fmt, "null"),
541            Value::LightUserData(ud) => write!(fmt, "lightuserdata: {:?}", ud.0),
542            Value::Integer(i) => write!(fmt, "{i}"),
543            Value::Number(n) => write!(fmt, "{n}"),
544            #[cfg(feature = "luau")]
545            Value::Vector(v) => write!(fmt, "{v}"),
546            Value::String(s) => write!(fmt, "{s:?}"),
547            Value::Table(t) if recursive && !visited.contains(&t.to_pointer()) => {
548                t.fmt_pretty(fmt, ident, visited)
549            }
550            t @ Value::Table(_) => write!(fmt, "table: {:?}", t.to_pointer()),
551            f @ Value::Function(_) => write!(fmt, "function: {:?}", f.to_pointer()),
552            t @ Value::Thread(_) => write!(fmt, "thread: {:?}", t.to_pointer()),
553            Value::UserData(ud) => ud.fmt_pretty(fmt),
554            #[cfg(feature = "luau")]
555            buf @ Value::Buffer(_) => write!(fmt, "buffer: {:?}", buf.to_pointer()),
556            Value::Error(e) if recursive => write!(fmt, "{e:?}"),
557            Value::Error(_) => write!(fmt, "error"),
558            Value::Other(v) => write!(fmt, "other: {:?}", v.to_pointer()),
559        }
560    }
561}
562
563impl fmt::Debug for Value {
564    fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
565        if fmt.alternate() {
566            return self.fmt_pretty(fmt, true, 0, &mut HashSet::new());
567        }
568
569        match self {
570            Value::Nil => write!(fmt, "Nil"),
571            Value::Boolean(b) => write!(fmt, "Boolean({b})"),
572            Value::LightUserData(ud) => write!(fmt, "{ud:?}"),
573            Value::Integer(i) => write!(fmt, "Integer({i})"),
574            Value::Number(n) => write!(fmt, "Number({n})"),
575            #[cfg(feature = "luau")]
576            Value::Vector(v) => write!(fmt, "{v:?}"),
577            Value::String(s) => write!(fmt, "String({s:?})"),
578            Value::Table(t) => write!(fmt, "{t:?}"),
579            Value::Function(f) => write!(fmt, "{f:?}"),
580            Value::Thread(t) => write!(fmt, "{t:?}"),
581            Value::UserData(ud) => write!(fmt, "{ud:?}"),
582            #[cfg(feature = "luau")]
583            Value::Buffer(buf) => write!(fmt, "{buf:?}"),
584            Value::Error(e) => write!(fmt, "Error({e:?})"),
585            Value::Other(v) => write!(fmt, "Other({v:?})"),
586        }
587    }
588}
589
590impl PartialEq for Value {
591    fn eq(&self, other: &Self) -> bool {
592        match (self, other) {
593            (Value::Nil, Value::Nil) => true,
594            (Value::Boolean(a), Value::Boolean(b)) => a == b,
595            (Value::LightUserData(a), Value::LightUserData(b)) => a == b,
596            (Value::Integer(a), Value::Integer(b)) => *a == *b,
597            (Value::Integer(a), Value::Number(b)) => *a as Number == *b,
598            (Value::Number(a), Value::Integer(b)) => *a == *b as Number,
599            (Value::Number(a), Value::Number(b)) => *a == *b,
600            #[cfg(feature = "luau")]
601            (Value::Vector(v1), Value::Vector(v2)) => v1 == v2,
602            (Value::String(a), Value::String(b)) => a == b,
603            (Value::Table(a), Value::Table(b)) => a == b,
604            (Value::Function(a), Value::Function(b)) => a == b,
605            (Value::Thread(a), Value::Thread(b)) => a == b,
606            (Value::UserData(a), Value::UserData(b)) => a == b,
607            #[cfg(feature = "luau")]
608            (Value::Buffer(a), Value::Buffer(b)) => a == b,
609            _ => false,
610        }
611    }
612}
613
614/// A wrapped [`Value`] with customized serialization behavior.
615#[cfg(feature = "serde")]
616#[cfg_attr(docsrs, doc(cfg(feature = "serde")))]
617pub struct SerializableValue<'a> {
618    value: &'a Value,
619    options: crate::serde::de::Options,
620    // In many cases we don't need `visited` map, so don't allocate memory by default
621    visited: Option<Rc<RefCell<FxHashSet<*const c_void>>>>,
622}
623
624#[cfg(feature = "serde")]
625impl Serialize for Value {
626    #[inline]
627    fn serialize<S: Serializer>(&self, serializer: S) -> StdResult<S::Ok, S::Error> {
628        SerializableValue::new(self, Default::default(), None).serialize(serializer)
629    }
630}
631
632#[cfg(feature = "serde")]
633impl<'a> SerializableValue<'a> {
634    #[inline]
635    pub(crate) fn new(
636        value: &'a Value,
637        options: crate::serde::de::Options,
638        visited: Option<&Rc<RefCell<FxHashSet<*const c_void>>>>,
639    ) -> Self {
640        if let Value::Table(_) = value {
641            return Self {
642                value,
643                options,
644                // We need to always initialize the `visited` map for Tables
645                visited: visited.cloned().or_else(|| Some(Default::default())),
646            };
647        }
648        Self {
649            value,
650            options,
651            visited: None,
652        }
653    }
654
655    /// If true, an attempt to serialize types such as [`Function`], [`Thread`], [`LightUserData`]
656    /// and [`Error`] will cause an error.
657    /// Otherwise these types skipped when iterating or serialized as unit type.
658    ///
659    /// Default: **true**
660    #[must_use]
661    pub fn deny_unsupported_types(mut self, enabled: bool) -> Self {
662        self.options.deny_unsupported_types = enabled;
663        self
664    }
665
666    /// If true, an attempt to serialize a recursive table (table that refers to itself)
667    /// will cause an error.
668    /// Otherwise subsequent attempts to serialize the same table will be ignored.
669    ///
670    /// Default: **true**
671    #[must_use]
672    pub fn deny_recursive_tables(mut self, enabled: bool) -> Self {
673        self.options.deny_recursive_tables = enabled;
674        self
675    }
676
677    /// If true, keys in tables will be iterated (and serialized) in sorted order.
678    ///
679    /// Default: **false**
680    #[must_use]
681    pub fn sort_keys(mut self, enabled: bool) -> Self {
682        self.options.sort_keys = enabled;
683        self
684    }
685
686    /// If true, empty Lua tables will be encoded as array, instead of map.
687    ///
688    /// Default: **false**
689    #[must_use]
690    pub fn encode_empty_tables_as_array(mut self, enabled: bool) -> Self {
691        self.options.encode_empty_tables_as_array = enabled;
692        self
693    }
694
695    /// If true, enable detection of mixed tables.
696    ///
697    /// A mixed table is a table that has both array-like and map-like entries or several borders.
698    ///
699    /// Default: **false**
700    #[must_use]
701    pub fn detect_mixed_tables(mut self, enabled: bool) -> Self {
702        self.options.detect_mixed_tables = enabled;
703        self
704    }
705}
706
707#[cfg(feature = "serde")]
708impl Serialize for SerializableValue<'_> {
709    fn serialize<S>(&self, serializer: S) -> StdResult<S::Ok, S::Error>
710    where
711        S: Serializer,
712    {
713        match self.value {
714            Value::Nil => serializer.serialize_unit(),
715            Value::Boolean(b) => serializer.serialize_bool(*b),
716            #[allow(clippy::useless_conversion)]
717            Value::Integer(i) => serializer.serialize_i64((*i).into()),
718            Value::Number(n) => serializer.serialize_f64(*n),
719            #[cfg(feature = "luau")]
720            Value::Vector(v) => v.serialize(serializer),
721            Value::String(s) => s.serialize(serializer),
722            Value::Table(t) => {
723                let visited = self.visited.as_ref().unwrap().clone();
724                SerializableTable::new(t, self.options, visited).serialize(serializer)
725            }
726            Value::LightUserData(ud) if ud.0.is_null() => serializer.serialize_none(),
727            Value::UserData(ud) if ud.is_serializable() || self.options.deny_unsupported_types => {
728                ud.serialize(serializer)
729            }
730            #[cfg(feature = "luau")]
731            Value::Buffer(buf) => buf.serialize(serializer),
732            Value::Function(_)
733            | Value::Thread(_)
734            | Value::UserData(_)
735            | Value::LightUserData(_)
736            | Value::Error(_)
737            | Value::Other(_) => {
738                if self.options.deny_unsupported_types {
739                    let msg = format!("cannot serialize <{}>", self.value.type_name());
740                    Err(ser::Error::custom(msg))
741                } else {
742                    serializer.serialize_unit()
743                }
744            }
745        }
746    }
747}
748
749#[cfg(test)]
750mod assertions {
751    use super::*;
752
753    #[cfg(not(feature = "send"))]
754    static_assertions::assert_not_impl_any!(Value: Send);
755    #[cfg(feature = "send")]
756    static_assertions::assert_impl_all!(Value: Send, Sync);
757}
mlua/value.rs

mlua/
value.rs
