Struct tlua::LuaTable

pub struct LuaTable<L> { /* private fields */ }

Represents a table stored in the Lua context.

Just like you can read variables as integers and strings, you can also read Lua table by requesting a LuaTable object. Doing so will mutably borrow the object which you got the table from.

Example: reading a global variable

let lua = tlua::Lua::new();
lua.exec("a = {28, 92, 17};").unwrap();

let table: tlua::LuaTable<_> = lua.get("a").unwrap();
for (k, v) in table.iter::<i32, i32>().filter_map(|e| e) {
    println!("{} => {}", k, v);
}

Implementations

impl<L> LuaTable<L>where
    L: AsLua,

pub fn empty(lua: L) -> Self

impl<'lua, L> LuaTable<L>where
    L: 'lua + AsLua,

pub fn into_inner(self) -> L

Destroys the LuaTable and returns its inner Lua context. Useful when it takes Lua by value.

pub fn iter<K, V>(&self) -> LuaTableIterator<'_, L, K, V>

Iterates over the elements inside the table.

pub fn get<R, I>(&'lua self, index: I) -> Option<R>where
    I: PushOneInto<LuaState, Err = Void>,
    R: LuaRead<PushGuard<&'lua L>>,

Loads a value in the table given its index.

The index must implement the PushOneInto trait and the return type must implement the LuaRead trait. See the documentation at the crate root for more information.

Example: reading a table inside of a table.

let lua = tlua::Lua::new();
lua.exec("a = { 9, { 8, 7 }, 6 }").unwrap();

let table = lua.get::<tlua::LuaTable<_>, _>("a").unwrap();

assert_eq!(table.get::<i32, _>(1).unwrap(), 9);
assert_eq!(table.get::<i32, _>(3).unwrap(), 6);

{
    let subtable: tlua::LuaTable<_> = table.get(2).unwrap();
    assert_eq!(subtable.get::<i32, _>(1).unwrap(), 8);
    assert_eq!(subtable.get::<i32, _>(2).unwrap(), 7);
}

pub fn into_get<R, I>(self, index: I) -> Result<R, Self>where
    I: PushOneInto<LuaState, Err = Void>,
    R: LuaRead<PushGuard<Self>>,

Loads a value in the table, with the result capturing the table by value.

See also LuaTable::get

pub fn set<I, V>(&self, index: I, value: V)where
    I: PushOneInto<LuaState>,
    V: PushOneInto<LuaState>,
    I::Err: Into<Void>,
    V::Err: Into<Void>,

Inserts or modifies an elements of the table.

Contrary to checked_set, can only be called when writing the key and value cannot fail (which is the case for most types).

The index and the value must both implement the PushOne trait. See the documentation at the crate root for more information.

pub fn checked_set<I, V>(
    &self,
    index: I,
    value: V
) -> Result<(), CheckedSetError<I::Err, V::Err>>where
    I: PushOneInto<LuaState>,
    V: PushOneInto<LuaState>,

Inserts or modifies an elements of the table.

Returns an error if we failed to write the key and the value. This can only happen for a limited set of types. You are encouraged to use the set method if writing cannot fail.

pub fn call_method<R, A>(
    &'lua self,
    name: &str,
    args: A
) -> Result<R, MethodCallError<A::Err>>where
    L: Debug,
    A: PushInto<LuaState> + Debug,
    R: LuaRead<PushGuard<Callable<PushGuard<&'lua L>>>>,

pub fn empty_array<I>(&'lua self, index: I) -> LuaTable<PushGuard<&'lua L>>where
    I: PushOne<LuaState, Err = Void>,

Inserts an empty array, then loads it.

pub fn get_or_create_metatable(self) -> LuaTable<PushGuard<L>>

Obtains or creates the metatable of the table.

A metatable is an additional table that can be attached to a table or a userdata. It can contain anything, but its most interesting usage are the following special methods:

• If non-nil, the __index entry of the metatable is used as a function whenever the user tries to read a non-existing entry in the table or userdata. Its signature is (object, index) -> value.
• If non-nil, the __newindex entry of the metatable is used as a function whenever the user tries to write a non-existing entry in the table or userdata. Its signature is (object, index, value).
• If non-nil, the __lt, __le and __eq entries correspond respectively to operators <, <= and ==. Their signature is (a, b) -> bool. Other operators are automatically derived from these three functions.
• If non-nil, the __add, __mul, __sub, __div, __unm, __pow and __concat entries correspond to operators +, *, -, /, - (unary), ^ and ... Their signature is (a, b) -> result.
• If non-nil, the __gc entry is called whenever the garbage collector is about to drop the object. Its signature is simply (obj). Remember that usercode is able to modify the metatable as well, so there is no strong guarantee that this is actually going to be called.

Interestingly enough, a metatable can also have a metatable. For example if you try to access a non-existing field in a table, Lua will look for the __index function in its metatable. If that function doesn’t exist, it will try to use the __index function of the metatable’s metatable in order to get the __index function of the metatable. This can go on infinitely.

Example

use tlua::Lua;
use tlua::LuaTable;
use tlua::AnyLuaValue;

let lua = Lua::new();
lua.exec("a = {}").unwrap();

{
    let table: LuaTable<_> = lua.get("a").unwrap();
    let metatable = table.get_or_create_metatable();
    metatable.set("__index", tlua::function2(|_: AnyLuaValue, var: String| -> AnyLuaValue {
        println!("The user tried to access non-existing index {:?}", var);
        AnyLuaValue::LuaNil
    }));
}

pub fn registry(lua: L) -> LuaTable<L>

Builds the LuaTable that yields access to the registry.

The registry is a special table available from anywhere and that is not directly accessible from Lua code. It can be used to store whatever you want to keep in memory.

Example

use tlua::Lua;
use tlua::LuaTable;

let lua = Lua::new();

let table = LuaTable::registry(&lua);
table.set(3, "hello");

Trait Implementations

impl<L> AsLua for LuaTable<L>where
    L: AsLua,

fn as_lua(&self) -> LuaState

fn try_push<T>(
    self,
    v: T
) -> Result<PushGuard<Self>, (<T as PushInto<Self>>::Err, Self)>where
    Self: Sized,
    T: PushInto<Self>,

Try to push v onto the lua stack.

fn push<T>(self, v: T) -> PushGuard<Self>where
    Self: Sized,
    T: PushInto<Self>,
    <T as PushInto<Self>>::Err: Into<Void>,

Push v onto the lua stack.

fn try_push_one<T>(
    self,
    v: T
) -> Result<PushGuard<Self>, (<T as PushInto<Self>>::Err, Self)>where
    Self: Sized,
    T: PushOneInto<Self>,

Try to push v onto the lua stack.

fn push_one<T>(self, v: T) -> PushGuard<Self>where
    Self: Sized,
    T: PushOneInto<Self>,
    <T as PushInto<Self>>::Err: Into<Void>,

Push v onto the lua stack.

fn push_iter<I>(self, iterator: I) -> Result<PushGuard<Self>, Self>where
    Self: Sized,
    I: Iterator,
    <I as Iterator>::Item: PushInto<LuaState>,
    <<I as Iterator>::Item as PushInto<LuaState>>::Err: Into<Void>,

Push iterator onto the lua stack as a lua table.

fn try_push_iter<I>(
    self,
    iterator: I
) -> Result<PushGuard<Self>, (PushIterErrorOf<I>, Self)>where
    Self: Sized,
    I: Iterator,
    <I as Iterator>::Item: PushInto<LuaState>,

Push iterator onto the lua stack as a lua table.

fn read<T>(self) -> Result<T, Self>where
    Self: Sized,
    T: LuaRead<Self>,

fn read_at<T>(self, index: i32) -> Result<T, Self>where
    Self: Sized,
    T: LuaRead<Self>,

fn read_at_nz<T>(self, index: NonZeroI32) -> Result<T, Self>where
    Self: Sized,
    T: LuaRead<Self>,

fn pcall<F, R>(&self, f: F) -> Result<R, LuaError>where
    F: FnOnce(StaticLua) -> R,

Call a rust function in protected mode. If a lua error is thrown during execution of f the function will return a LuaError.

impl<L> AsRef<Object<L>> for LuaTable<L>

fn as_ref(&self) -> &Object<L>

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

impl<L: Debug> Debug for LuaTable<L>

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

Formats the value using the given formatter.

impl<L> From<LuaTable<L>> for Object<L>where
    L: AsLua,

fn from(o: LuaTable<L>) -> Self

Converts to this type from the input type.

impl<L> Index<L> for LuaTable<L>where
    L: AsLua,

fn get<'lua, K, R>(&'lua self, key: K) -> Option<R>where
    L: 'lua,
    K: PushOneInto<LuaState>,
    K::Err: Into<Void>,
    R: LuaRead<PushGuard<&'lua L>>,

Loads a value from the table (or other object using the __index metamethod) given its index.

fn try_get<'lua, K, R>(&'lua self, key: K) -> Result<R, LuaError>where
    L: 'lua,
    K: PushOneInto<LuaState>,
    K::Err: Into<Void>,
    R: LuaRead<PushGuard<&'lua L>>,

Loads a value from the table (or other object using the __index metamethod) given its index.

fn into_get<K, R>(self, key: K) -> Result<R, Self>where
    Self: AsLua + Sized,
    K: PushOneInto<LuaState>,
    K::Err: Into<Void>,
    R: LuaRead<PushGuard<Self>>,

Loads a value in the table (or other object using the __index metamethod) given its index, with the result capturing the table by value.

fn try_into_get<K, R>(self, key: K) -> Result<R, (Self, LuaError)>where
    Self: AsLua + Sized,
    K: PushOneInto<LuaState>,
    K::Err: Into<Void>,
    R: LuaRead<PushGuard<Self>>,

Loads a value in the table (or other object using the __index metamethod) given its index, with the result capturing the table by value.

fn call_method<'lua, A, R>(
    &'lua self,
    name: &str,
    args: A
) -> Result<R, MethodCallError<A::Err>>where
    L: 'lua,
    Self: Push<LuaState>,
    Self::Err: Into<Void>,
    A: PushInto<LuaState>,
    R: LuaRead<PushGuard<Callable<PushGuard<&'lua L>>>>,

Calls the method called name of the table (or other indexable object) with the provided args.

impl<L> LuaRead<L> for LuaTable<L>where
    L: AsLua,

fn lua_read_at_position(lua: L, index: NonZeroI32) -> Result<Self, L>

Reads the data from Lua at a given position.

fn n_values_expected() -> i32

fn lua_read(lua: L) -> Result<Self, L>

Reads the data from Lua.

fn lua_read_at_maybe_zero_position(lua: L, index: i32) -> Result<Self, L>

impl<L> NewIndex<L> for LuaTable<L>where
    L: AsLua,

fn set<K, V>(&self, key: K, value: V)where
    K: PushOneInto<LuaState>,
    K::Err: Into<Void>,
    V: PushOneInto<LuaState>,
    V::Err: Into<Void>,

Inserts or modifies a value of the table (or other object using the __index or __newindex metamethod) given its index.

fn try_set<K, V>(&self, key: K, value: V) -> Result<(), LuaError>where
    K: PushOneInto<LuaState>,
    K::Err: Into<Void>,
    V: PushOneInto<LuaState>,
    V::Err: Into<Void>,

Inserts or modifies a value of the table (or other object using the __index or __newindex metamethod) given its index.

fn checked_set<K, V>(
    &self,
    key: K,
    value: V
) -> Result<(), CheckedSetError<K::Err, V::Err>>where
    K: PushOneInto<LuaState>,
    V: PushOneInto<LuaState>,

Inserts or modifies a value of the table (or other object using the __newindex metamethod) given its index.

fn try_checked_set<K, V>(
    &self,
    key: K,
    value: V
) -> Result<(), Result<CheckedSetError<K::Err, V::Err>, LuaError>>where
    K: PushOneInto<LuaState>,
    V: PushOneInto<LuaState>,

Inserts or modifies a value of the table (or other object using the __newindex metamethod) given its index.

impl<L, T> Push<L> for LuaTable<T>where
    L: AsLua,

type Err = Void

Error that can happen when pushing a value.

fn push_to_lua(&self, lua: L) -> PushResult<L, Self>

Pushes the value on the top of the stack.

fn push_no_err(&self, lua: L) -> PushGuard<L>where
    <Self as Push<L>>::Err: Into<Void>,

Same as push_to_lua but can only succeed and is only available if Err implements Into<Void>.

impl<L> TryFrom<Object<L>> for LuaTable<L>where
    L: AsLua,

type Error = Object<L>

The type returned in the event of a conversion error.

fn try_from(o: Object<L>) -> Result<Self, Self::Error>

Performs the conversion.

impl<L, T> PushOne<L> for LuaTable<T>where
    L: AsLua,