Enum Value 

#[repr(C, u8)]
pub enum Value {
    Nil,
    Bool(bool),
    Int(i64),
    Float(f64),
    Str(Gc<LuaStr>),
    Table(Gc<Table>),
    Closure(Gc<LuaClosure>),
    Native(Gc<NativeClosure>),
    Coro(Gc<Coro>),
    Userdata(Gc<Userdata>),
    LightUserdata(*const ()),
}

P17-D v2 Direction E (E1) — #[repr(C, u8)] makes the discriminant a 1-byte tag at offset 0, with the variant payload starting at offset 8 (after 7 bytes of alignment padding). The total size stays 16 bytes (same as the prior plain Rust enum representation), preserving P02’s arithmetic-fast-path 24% win over NaN-boxing.

The PUC-equivalent layout this gives us means LJ_FR2-style frame metadata reads (stack[base-2] for closure, stack[base-1] for the packed frame marker) can use a single 1-byte tag load + payload branch — see Value::tag_byte and friends. The previous enum repr left discriminant position unspecified, so byte-level reads of Value layout would have been unportable.

Variant order MUST stay stable: rustc assigns discriminants 0..11 in declaration order (Nil=0, Bool=1, …, LightUserdata=10), and Phase 3+ hot paths read those discriminants via tag_byte(). New variants must be appended; reordering changes the wire layout.

Variants

Nil

Lua nil.

Bool(bool)

Lua boolean.

Tuple Fields

0: bool

Underlying boolean.

Int(i64)

Lua integer (5.3+; in 5.1 all numbers arrive as Float).

Tuple Fields

0: i64

64-bit signed value.

Float(f64)

Lua float.

Tuple Fields

0: f64

IEEE-754 double.

Str(Gc<LuaStr>)

Lua string — GC-managed byte string.

Tuple Fields

0: Gc<LuaStr>

String handle.

Table(Gc<Table>)

Lua table.

Tuple Fields

0: Gc<Table>

Table handle.

Closure(Gc<LuaClosure>)

Lua function backed by a LuaClosure.

Tuple Fields

0: Gc<LuaClosure>

Closure handle.

Native(Gc<NativeClosure>)

Lua function backed by a host NativeClosure.

Tuple Fields

0: Gc<NativeClosure>

Native closure handle.

Coro(Gc<Coro>)

Lua thread (coroutine).

Tuple Fields

0: Gc<Coro>

Coroutine handle.

Userdata(Gc<Userdata>)

Full userdata — GC-managed host-allocated payload with a metatable.

Tuple Fields

0: Gc<Userdata>

Userdata handle.

LightUserdata(*const ())

PUC LUA_TLIGHTUSERDATA: an opaque host pointer that participates only as an identity token (raw equality on pointer bits, no metatable, not GC-managed). Currently produced exclusively by debug.upvalueid — it points at the upvalue cell’s Value slot and stays distinct per cell.

Tuple Fields

0: *const ()

Opaque host pointer used as an identity token.

Implementations

impl Value

pub fn type_name(self) -> &'static str

Lua-visible type name ("nil", "boolean", "number", "string", "table", "function", "thread", "userdata") matching type().

pub fn is_nil(self) -> bool

True when this is Value::Nil.

pub fn truthy(self) -> bool

Lua truth: everything except nil and false.

pub fn tag_byte(&self) -> u8

P17-D v2 Direction E (E1) — read the variant’s discriminant byte directly. The #[repr(C, u8)] on the enum makes this a single 1-byte load from &self, regardless of variant.

Discriminant values follow declaration order: Nil=0, Bool=1, Int=2, Float=3, Str=4, Table=5, Closure=6, Native=7, Coro=8, Userdata=9, LightUserdata=10.

Use tag constants instead of literal numbers at call sites — see the module-level tag constants below.

pub fn is_callable(self) -> bool

Fast tag-only check for Lua function-call sites. Returns true iff the value’s discriminant is Closure or Native (the callable types). Avoids matching the entire enum.

pub fn try_as_str(&self) -> Option<&str>

Borrow the Lua string’s bytes as a UTF-8 &str (B7 — Phase 2). Returns None if this value is not a Value::Str, or if the string’s bytes are not valid UTF-8.

Embedders dealing with text data use this. For binary data (Redis protocol buffers, etc.) use Value::as_bytes.

pub fn as_bytes(&self) -> Option<&[u8]>

Borrow the raw bytes of a Value::Str (B7 — Phase 2). Returns None for non-string variants. Always safe — Lua strings are byte sequences and may carry non-UTF-8 content.

pub fn raw_eq(self, other: Value) -> bool

Raw equality (no metamethods): rawequal and table-key identity. Mixed int/float numbers are equal iff the float is exactly integral and equals the integer (PUC luaV_equalobj F2Ieq rule).

Trait Implementations

impl Clone for Value

fn clone(&self) -> Value

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for Value

impl Debug for Value

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl FromLuaValue for Value

fn from_lua_value(v: Value) -> Result<Self, LuaError>

Decode a single Lua Value into Self. Returns a LuaError("type mismatch …") if the value’s type does not match.

impl IntoLuaReturn for Value

fn into_lua_return(self, vm: &mut Vm, fs: u32) -> Result<u32, LuaError>

Push the encoded values starting at fs and return the result count.

impl IntoValue for Value

fn into_value(self, _vm: &mut Vm) -> Value

Convert self to a Lua Value, interning strings or allocating other GC-managed types via vm.heap as needed.