Struct LuaTable 

pub struct LuaTable { /* private fields */ }

A Lua table: hybrid array + hash map.

All public methods take &self so the type works through GcRef<LuaTable> (which only dereferences to a shared borrow). Mutations are routed through an internal RefCell.

Implementations

impl LuaTable

pub fn placeholder() -> Self

Construct an empty table. Used as a placeholder by callers that will populate it via the normal API.

pub fn with_inner<R>(&self, f: impl FnOnce(&TableInner) -> R) -> R

Borrow inner storage for read access. Intended for advanced callers (e.g. the GC trace impl); prefer the typed methods.

pub fn get(&self, k: &LuaValue) -> LuaValue

Read a key. Returns LuaValue::Nil if absent or if k is nil. Integer keys take the direct array-part fast path used by LuaTable::get_int; short-string keys take the analogous hash-chain fast path used by LuaTable::get_short_str; every other key shape falls through to the cold generic slot lookup. Marked #[inline(always)] so the dispatch folds into the caller (the hot state::fast_get / state::table_get_with_tm frames in the VM); profiling at #[inline] showed LLVM was still emitting a cross-crate function call here.

pub fn get_int(&self, key: i64) -> LuaValue

Read by integer key. Hot path: callers like state.fast_get_int and state.table_get_with_tm dispatch here on every integer-key access in user code (t[1], OP_GETI, ipairs loops, etc.). The array-part lookup folds into a single bounds-checked load, matching C’s luaH_getint.

pub fn get_short_str(&self, k: &GcRef<LuaString>) -> LuaValue

Read by string key. Despite the name (kept for compatibility with the old API), this dispatches internally to either the short- or long-string path; passing a long string is safe. The short-string branch (the common case — all interned identifiers and most table-field keys are short) takes the folded hash-walk in TableInner::get_str_value; long strings still go through the slot indirection.

pub fn get_str_bytes(&self, key_bytes: &[u8]) -> LuaValue

Read by raw byte-string key. Linear scan over the hash part — rarely-used helper for callers that don’t have a GcRef<LuaString> handle.

pub fn raw_set(&self, k: LuaValue, v: LuaValue)

Raw set without metamethod dispatch. Nil keys are an error; NaN-float keys are an error. Setting v == Nil clears the slot.

pub fn try_raw_set(&self, k: LuaValue, v: LuaValue) -> Result<(), LuaError>

Raw set with explicit error returns; preferred path used by LuaTableRefExt::raw_set in lua-vm. Integer keys (and floats that are exact integers) take the same direct array-part fast path used by LuaTable::try_raw_set_int; other key shapes fall through to the generic slot lookup.

pub fn try_raw_set_int(&self, k: i64, v: LuaValue) -> Result<(), LuaError>

Raw set by integer key with explicit error returns. Routes the array-part fast path through [TableInner::set_int_value] — a single bounds-checked store with no intermediate TableSlotRef indirection — and only consults the TOTAL_GROW_CAP allocation guard when the key would create a new slot.

pub fn resize(&self, new_asize: u32, new_hsize: u32) -> Result<(), LuaError>

Resize the table to new array and hash sizes (sizing hint from the bytecode’s OP_NEWTABLE).

pub fn array_len(&self) -> usize

Number of array-part slots currently allocated. Cheap counter for sizing decisions; NOT the Lua #t length operator.

pub fn len(&self) -> usize

Total occupied slots (array + hash) — used for legacy len() callers; prefer getn for the Lua # operator.

pub fn is_empty(&self) -> bool

pub fn getn(&self) -> u64

#t boundary (C: luaH_getn). Mutates internal caching state.

pub fn contains_key(&self, k: &LuaValue) -> bool

Returns true iff k resolves to a slot in this table (array or hash). Used by next to validate the resumption key.

pub fn metatable(&self) -> Option<GcRef<LuaTable>>

pub fn set_metatable(&self, mt: Option<GcRef<LuaTable>>)

Install a metatable. Inspects its __mode field eagerly so the GC trace impl can read [weak_mode] without re-entering the metatable RefCell.

pub fn weak_mode(&self) -> u8

pub fn next_pair(&self, k: &LuaValue) -> Option<(LuaValue, LuaValue)>

Implements Lua’s next(t, k).

pub fn try_next_pair( &self, k: &LuaValue, ) -> Result<Option<(LuaValue, LuaValue)>, LuaError>

Like [next_pair] but reports the "invalid key to 'next'" error when k is non-nil and not present.

pub fn for_each_entry(&self, f: impl FnMut(&LuaValue, &LuaValue))

Walk every live (key, value) pair via the given closure. Used by the GC trace impl to avoid the overhead of repeatedly re-entering find_index from next_pair.

pub fn prune_weak_dead( &self, is_reachable: &dyn Fn(usize) -> bool, ) -> Vec<LuaValue>

Drop weak entries whose weakly-tracked target is unreachable, and return the list of values whose strings must still be marked by the caller.

pub fn ephemeron_values_to_mark( &self, is_reachable: &dyn Fn(usize) -> bool, ) -> Vec<LuaValue>

Ephemeron-convergence helper for pure __mode = "k" tables.

Trait Implementations

impl Debug for LuaTable

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

Formats the value using the given formatter.

impl Default for LuaTable

fn default() -> Self

Returns the “default value” for a type.

impl Trace for LuaTable

LuaTable — array+hash entries plus optional metatable.

Weak-table semantics (matches lgc.c::traversetable):

• __mode = "v" — strong keys, weak values. Trace keys here; value side is deferred — string values get marked in prune_weak_dead’s surviving-entry pass (Lua’s iscleared), non-string dead values trigger entry removal.
• __mode = "kv" — both sides weak. Trace NEITHER here; everything is handled by prune_weak_dead (matches Lua’s “just add to allweak, traverse nothing” path).
• __mode = "k" — weak keys, strong values. Trace NEITHER here. The post-mark ephemeron convergence pass walks each weak-key table’s entries and marks values only for entries whose keys are independently reachable. String keys get marked in prune_weak_dead.
• No __mode — trace both unconditionally.

Marking strings inline for weak slots (the previous behavior) would pin them alive even when their containing entry is about to be cleared because the other side died — breaking the gc.lua weak-string-key block, which expects unreferenced long strings to free their bytes after a single collectgarbage() cycle.

fn trace(&self, m: &mut Marker)