pub struct LuaTable<L> { /* private fields */ }
Expand description
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.ok()) {
println!("{} => {}", k, v);
}
Implementations§
source§impl<'lua, L> LuaTable<L>where
L: 'lua + AsLua,
impl<'lua, L> LuaTable<L>where
L: 'lua + AsLua,
sourcepub fn into_inner(self) -> L
pub fn into_inner(self) -> L
Destroys the LuaTable
and returns its inner Lua context. Useful when it takes Lua by
value.
sourcepub fn iter<K, V>(&self) -> LuaTableIterator<'_, L, K, V> ⓘ
pub fn iter<K, V>(&self) -> LuaTableIterator<'_, L, K, V> ⓘ
Iterates over the elements inside the table.
sourcepub fn get<R, I>(&'lua self, index: I) -> Option<R>
pub fn get<R, I>(&'lua self, index: I) -> Option<R>
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);
}
sourcepub fn try_get<K, R>(&'lua self, key: K) -> Result<R, LuaError>
pub fn try_get<K, R>(&'lua self, key: K) -> Result<R, LuaError>
Loads a value from the table given its key
.
Possible errors:
LuaError::ExecutionError
if an error happened during the check thatindex
is valid inself
or in__index
metamethodLuaError::WrongType
if the result lua value couldn’t be read as the expected rust type
The key
must implement the PushOneInto
trait and the return type
must implement the LuaRead
trait. See the documentation at the
crate root for more information.
sourcepub fn into_get<R, I>(self, index: I) -> Result<R, Self>
pub fn into_get<R, I>(self, index: I) -> Result<R, Self>
Loads a value in the table, with the result capturing the table by value.
See also LuaTable::get
sourcepub fn set<I, V>(&self, index: I, value: V)
pub fn set<I, V>(&self, index: I, value: V)
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.
sourcepub fn checked_set<I, V>(
&self,
index: I,
value: V
) -> Result<(), CheckedSetError<I::Err, V::Err>>
pub fn checked_set<I, V>( &self, index: I, value: V ) -> Result<(), CheckedSetError<I::Err, V::Err>>
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>>
sourcepub fn empty_array<I>(&'lua self, index: I) -> LuaTable<PushGuard<&'lua L>>
pub fn empty_array<I>(&'lua self, index: I) -> LuaTable<PushGuard<&'lua L>>
Inserts an empty array, then loads it.
sourcepub fn get_or_create_metatable(self) -> LuaTable<PushGuard<L>>
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
}));
}
sourcepub fn registry(lua: L) -> LuaTable<L>
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§
source§impl<L> AsLua for LuaTable<L>where
L: AsLua,
impl<L> AsLua for LuaTable<L>where
L: AsLua,
fn as_lua(&self) -> LuaState
source§fn try_push<T>(
self,
v: T
) -> Result<PushGuard<Self>, (<T as PushInto<Self>>::Err, Self)>
fn try_push<T>( self, v: T ) -> Result<PushGuard<Self>, (<T as PushInto<Self>>::Err, Self)>
v
onto the lua stack. Read moresource§fn try_push_one<T>(
self,
v: T
) -> Result<PushGuard<Self>, (<T as PushInto<Self>>::Err, Self)>where
Self: Sized,
T: PushOneInto<Self>,
fn try_push_one<T>(
self,
v: T
) -> Result<PushGuard<Self>, (<T as PushInto<Self>>::Err, Self)>where
Self: Sized,
T: PushOneInto<Self>,
v
onto the lua stack. Read moresource§fn push_iter<I>(self, iterator: I) -> Result<PushGuard<Self>, Self>
fn push_iter<I>(self, iterator: I) -> Result<PushGuard<Self>, Self>
iterator
onto the lua stack as a lua table. Read moresource§fn try_push_iter<I>(
self,
iterator: I
) -> Result<PushGuard<Self>, (PushIterErrorOf<I>, Self)>
fn try_push_iter<I>( self, iterator: I ) -> Result<PushGuard<Self>, (PushIterErrorOf<I>, Self)>
iterator
onto the lua stack as a lua table. Read morefn read<T>(self) -> ReadResult<T, Self>
fn read_at<T>(self, index: i32) -> ReadResult<T, Self>
fn read_at_nz<T>(self, index: NonZeroI32) -> ReadResult<T, Self>
source§impl<L> Index<L> for LuaTable<L>where
L: AsLua,
impl<L> Index<L> for LuaTable<L>where
L: AsLua,
source§fn get<'lua, K, R>(&'lua self, key: K) -> Option<R>
fn get<'lua, K, R>(&'lua self, key: K) -> Option<R>
__index
metamethod) given its index
. Read moresource§fn try_get<'lua, K, R>(&'lua self, key: K) -> Result<R, LuaError>
fn try_get<'lua, K, R>(&'lua self, key: K) -> Result<R, LuaError>
__index
metamethod) given its index
. Read moresource§fn into_get<K, R>(self, key: K) -> Result<R, Self>
fn into_get<K, R>(self, key: K) -> Result<R, Self>
__index
metamethod) given its index
, with the result capturing the table by
value. Read moresource§fn try_into_get<K, R>(self, key: K) -> Result<R, (Self, LuaError)>
fn try_into_get<K, R>(self, key: K) -> Result<R, (Self, LuaError)>
__index
metamethod) given its index
, with the result capturing the table by
value. Read moresource§fn call_method<'lua, A, R>(
&'lua self,
name: &str,
args: A
) -> Result<R, MethodCallError<A::Err>>
fn call_method<'lua, A, R>( &'lua self, name: &str, args: A ) -> Result<R, MethodCallError<A::Err>>
name
of the table (or other indexable object)
with the provided args
. Read moresource§impl<L> LuaRead<L> for LuaTable<L>where
L: AsLua,
impl<L> LuaRead<L> for LuaTable<L>where
L: AsLua,
source§fn lua_read_at_position(lua: L, index: NonZeroI32) -> ReadResult<Self, L>
fn lua_read_at_position(lua: L, index: NonZeroI32) -> ReadResult<Self, L>
fn n_values_expected() -> i32
source§fn lua_read(lua: L) -> ReadResult<Self, L>
fn lua_read(lua: L) -> ReadResult<Self, L>
fn lua_read_at_maybe_zero_position(lua: L, index: i32) -> ReadResult<Self, L>where
L: AsLua,
source§impl<L> NewIndex<L> for LuaTable<L>where
L: AsLua,
impl<L> NewIndex<L> for LuaTable<L>where
L: AsLua,
source§fn set<K, V>(&self, key: K, value: V)
fn set<K, V>(&self, key: K, value: V)
value
of the table (or other object using the
__index
or __newindex
metamethod) given its index
. Read moresource§fn try_set<K, V>(&self, key: K, value: V) -> Result<(), LuaError>
fn try_set<K, V>(&self, key: K, value: V) -> Result<(), LuaError>
value
of the table (or other object using the
__index
or __newindex
metamethod) given its index
. Read moresource§fn checked_set<K, V>(
&self,
key: K,
value: V
) -> Result<(), CheckedSetError<K::Err, V::Err>>
fn checked_set<K, V>( &self, key: K, value: V ) -> Result<(), CheckedSetError<K::Err, V::Err>>
value
of the table (or other object using the
__newindex
metamethod) given its index
. Read more