table.h File Reference

Operations on table values. More...

#include <functional>
#include <optional>
#include "utils/concepts.h"
#include "utils/tuple.h"
#include "get.h"
#include "push.h"
#include "state.h"
#include "value.h"

Include dependency graph for table.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
class	nngn::lua::detail::table_base< CRTP >
	CRTP base for stack table types. More...
struct	nngn::lua::detail::table_accessor
	Internal type used in nested table accesses. More...
struct	nngn::lua::table_view
	Non-owning reference to a table on the stack. More...
struct	nngn::lua::table
	Owning reference to a table on the stack, popped when destroyed. More...
class	nngn::lua::global_table
	Table interface to the global environment. More...
class	nngn::lua::table_proxy< T, Ks >
	Expression template for table assignemnts. More...
struct	nngn::lua::stack_get< std::vector< T > >
	Reads a table array as a vector. More...
struct	nngn::lua::stack_push< table_proxy< T, Ks... > >

Namespaces
namespace	nngn
namespace	nngn::lua
namespace	nngn::lua::detail

Functions
template<typename T , typename PT , typename ... Ks>
	nngn::lua::operator== (T &&lhs, const table_proxy< PT, Ks... > &rhs)
template<typename T , typename PT , typename ... Ks>
	nngn::lua::operator== (const table_proxy< PT, Ks... > &lhs, T &&rhs)
table	nngn::lua::table_array (state_view lua, auto &&...args)
	Creates a table array with each argument in succession.
template<std::ranges::range T>
table	nngn::lua::table_from_range (state_view lua, T &&r)
	Creates a table array from a range.
table	nngn::lua::table_map (state_view lua, auto &&...args)
	Creates a table with each successive argument pair as key/value.

Variables
template<typename T >
constexpr bool	nngn::lua::is_stack_ref< T > = true

Detailed Description

Operations on table values.

A reference to the global table can be obtained either via state_view::globals or by constructing a global_table object directly:

const global_table g = lua.globals();
const global_table g = {lua};

Indexing

Values can be obtained/set using operator[]:

g["i"] = 42;
assert(g["i"] == 42);

Accesses can be nested:

g["x"]["y"]["z"] = 42;
assert(g["x"]["y"]["z"] == 42);

References to the ultimate object can be created naturally:

const table t = g["x"]["y"]["z"];
t["w"] = 42;
std::cout << t["w"] << ' ' << g["x"]["y"]["z"];

Each level of access is popped from the stack as necessary during the traversal, so that at the end only the ultimate object remains.

Warning

operator[] creates a table_proxy object, which is an expression template holding a reference to the original table object. Most of the time, this is an irrelevant implementation detail, but care must be taken to guarantee that the table outlives the proxy:

const auto g = lua.globals();
const auto y = g["x"]["y"];
// Bad!  Temporary value (g["x"]) no longer exists!
std::cout << y;

Usually, immediately converting the proxy to an actual value, as shown in the examples above, is enough:

const auto y = g["x"]["y"];
// Good.
std::cout << y;
// Or simply:
std::cout << g["x"]["y"].get<int>();

Meta tables

Meta tables, in particular those used for user types, are no different than regular tables and can be manipulated in the same manner:

auto mt = lua.create_table();
mt["__name"] = "user_type";
mt["__index"] = mt;
mt["f"] = &user_type::f;
lua.globals()["user_type"] = mt.remove();
// …
const value u = lua.new_user_data<user_type>();
lua.set_meta_table(lua.globals()["user_type"], u.index());
std::cout << u.to_string().second;
// user_type: 0x01234567
call(lua, &user_type::f);

See also

nngn::lua::state_view::new_user_type performs a similar setup for user types automatically.

Iteration

See iter.h for iterator support for table objects.