Struct mlua::Table

pub struct Table<'lua>(_);

Handle to an internal Lua table.

Implementations

impl<'lua> Table<'lua>

pub fn set<K: ToLua<'lua>, V: ToLua<'lua>>(
    &self,
    key: K,
    value: V
) -> Result<()>

Sets a key-value pair in the table.

If the value is nil, this will effectively remove the pair.

This might invoke the __newindex metamethod. Use the raw_set method if that is not desired.

Examples

Export a value as a global to make it usable from Lua:

let globals = lua.globals();

globals.set("assertions", cfg!(debug_assertions))?;

lua.load(r#"
    if assertions == true then
        -- ...
    elseif assertions == false then
        -- ...
    else
        error("assertions neither on nor off?")
    end
"#).exec()?;

pub fn get<K: ToLua<'lua>, V: FromLua<'lua>>(&self, key: K) -> Result<V>

Gets the value associated to key from the table.

If no value is associated to key, returns the nil value.

This might invoke the __index metamethod. Use the raw_get method if that is not desired.

Examples

Query the version of the Lua interpreter:

let globals = lua.globals();

let version: String = globals.get("_VERSION")?;
println!("Lua version: {}", version);

pub fn contains_key<K: ToLua<'lua>>(&self, key: K) -> Result<bool>

Checks whether the table contains a non-nil value for key.

pub fn equals<T: AsRef<Self>>(&self, other: T) -> Result<bool>

Compares two tables for equality.

Tables are compared by reference first. If they are not primitively equals, then mlua will try to invoke the __eq metamethod. mlua will check self first for the metamethod, then other if not found.

Examples

Compare two tables using __eq metamethod:

let table1 = lua.create_table()?;
table1.set(1, "value")?;

let table2 = lua.create_table()?;
table2.set(2, "value")?;

let always_equals_mt = lua.create_table()?;
always_equals_mt.set("__eq", lua.create_function(|_, (_t1, _t2): (Table, Table)| Ok(true))?)?;
table2.set_metatable(Some(always_equals_mt));

assert!(table1.equals(&table1.clone())?);
assert!(table1.equals(&table2)?);

pub fn raw_set<K: ToLua<'lua>, V: ToLua<'lua>>(
    &self,
    key: K,
    value: V
) -> Result<()>

Sets a key-value pair without invoking metamethods.

pub fn raw_get<K: ToLua<'lua>, V: FromLua<'lua>>(&self, key: K) -> Result<V>

Gets the value associated to key without invoking metamethods.

pub fn raw_insert<V: ToLua<'lua>>(&self, idx: Integer, value: V) -> Result<()>

Inserts element value at position idx to the table, shifting up the elements from table[idx]. The worst case complexity is O(n), where n is the table length.

pub fn raw_remove<K: ToLua<'lua>>(&self, key: K) -> Result<()>

Removes a key from the table.

If key is an integer, mlua shifts down the elements from table[key+1], and erases element table[key]. The complexity is O(n) in the worst case, where n is the table length.

For other key types this is equivalent to setting table[key] = nil.

pub fn len(&self) -> Result<Integer>

Returns the result of the Lua # operator.

This might invoke the __len metamethod. Use the raw_len method if that is not desired.

pub fn raw_len(&self) -> Integer

Returns the result of the Lua # operator, without invoking the __len metamethod.

pub fn get_metatable(&self) -> Option<Table<'lua>>

Returns a reference to the metatable of this table, or None if no metatable is set.

Unlike the getmetatable Lua function, this method ignores the __metatable field.

pub fn set_metatable(&self, metatable: Option<Table<'lua>>)

Sets or removes the metatable of this table.

If metatable is None, the metatable is removed (if no metatable is set, this does nothing).

pub fn pairs<K: FromLua<'lua>, V: FromLua<'lua>>(self) -> TablePairs<'lua, K, V>

Consume this table and return an iterator over the pairs of the table.

This works like the Lua pairs function, but does not invoke the __pairs metamethod.

The pairs are wrapped in a Result, since they are lazily converted to K and V types.

Note

While this method consumes the Table object, it can not prevent code from mutating the table while the iteration is in progress. Refer to the Lua manual for information about the consequences of such mutation.

Examples

Iterate over all globals:

let globals = lua.globals();

for pair in globals.pairs::<Value, Value>() {
    let (key, value) = pair?;
    // ...
}

pub fn sequence_values<V: FromLua<'lua>>(self) -> TableSequence<'lua, V>

Consume this table and return an iterator over all values in the sequence part of the table.

The iterator will yield all values t[1], t[2], and so on, until a nil value is encountered. This mirrors the behavior of Lua’s ipairs function and will invoke the __index metamethod according to the usual rules. However, the deprecated __ipairs metatable will not be called.

Just like pairs, the values are wrapped in a Result.

Note

While this method consumes the Table object, it can not prevent code from mutating the table while the iteration is in progress. Refer to the Lua manual for information about the consequences of such mutation.

Examples

let my_table: Table = lua.load(r#"
    {
        [1] = 4,
        [2] = 5,
        [4] = 7,
        key = 2
    }
"#).eval()?;

let expected = [4, 5];
for (&expected, got) in expected.iter().zip(my_table.sequence_values::<u32>()) {
    assert_eq!(expected, got?);
}

pub fn raw_sequence_values<V: FromLua<'lua>>(self) -> TableSequence<'lua, V>

Consume this table and return an iterator over all values in the sequence part of the table.

Unlike the sequence_values, does not invoke __index metamethod when iterating.

Trait Implementations

impl<'lua> AsRef<Table<'lua>> for Table<'lua>

fn as_ref(&self) -> &Self

Converts this type into a shared reference of the (usually inferred) input type.

impl<'lua> Clone for Table<'lua>

fn clone(&self) -> Table<'lua>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'lua> Debug for Table<'lua>

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

Formats the value using the given formatter.

impl<'lua> FromLua<'lua> for Table<'lua>

fn from_lua(value: Value<'lua>, _: &'lua Lua) -> Result<Table<'lua>>

Performs the conversion.

impl<'lua> PartialEq<Table<'lua>> for Table<'lua>

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'lua> Serialize for Table<'lua>

fn serialize<S>(&self, serializer: S) -> StdResult<S::Ok, S::Error> where
    S: Serializer, 

Serialize this value into the given Serde serializer.

impl<'lua> TableExt<'lua> for Table<'lua>

fn call<A, R>(&self, args: A) -> Result<R> where
    A: ToLuaMulti<'lua>,
    R: FromLuaMulti<'lua>, 

Calls the table as function assuming it has __call metamethod.

fn call_async<'fut, A, R>(&self, args: A) -> LocalBoxFuture<'fut, Result<R>> where
    'lua: 'fut,
    A: ToLuaMulti<'lua>,
    R: FromLuaMulti<'lua> + 'fut, 

This is supported on crate feature async only.

Asynchronously calls the table as function assuming it has __call metamethod.

fn call_method<K, A, R>(&self, key: K, args: A) -> Result<R> where
    K: ToLua<'lua>,
    A: ToLuaMulti<'lua>,
    R: FromLuaMulti<'lua>, 

Gets the function associated to key from the table and executes it, passing the table itself along with args as function arguments.

fn call_function<K, A, R>(&self, key: K, args: A) -> Result<R> where
    K: ToLua<'lua>,
    A: ToLuaMulti<'lua>,
    R: FromLuaMulti<'lua>, 

Gets the function associated to key from the table and executes it, passing args as function arguments.

fn call_async_method<'fut, K, A, R>(
    &self,
    key: K,
    args: A
) -> LocalBoxFuture<'fut, Result<R>> where
    'lua: 'fut,
    K: ToLua<'lua>,
    A: ToLuaMulti<'lua>,
    R: FromLuaMulti<'lua> + 'fut, 

This is supported on crate feature async only.

Gets the function associated to key from the table and asynchronously executes it, passing the table itself along with args as function arguments and returning Future.

fn call_async_function<'fut, K, A, R>(
    &self,
    key: K,
    args: A
) -> LocalBoxFuture<'fut, Result<R>> where
    'lua: 'fut,
    K: ToLua<'lua>,
    A: ToLuaMulti<'lua>,
    R: FromLuaMulti<'lua> + 'fut, 

This is supported on crate feature async only.

Gets the function associated to key from the table and asynchronously executes it, passing args as function arguments and returning Future.

impl<'lua> ToLua<'lua> for Table<'lua>

fn to_lua(self, _: &'lua Lua) -> Result<Value<'lua>>

Performs the conversion.