org.luaj.vm2
Class LuaTable

java.lang.Object
  org.luaj.vm2.Varargs
      org.luaj.vm2.LuaValue
          org.luaj.vm2.LuaTable

Direct Known Subclasses:

Globals

public class LuaTable
extends LuaValue

Subclass of LuaValue for representing lua tables.

Almost all API's implemented in LuaTable are defined and documented in LuaValue.

If a table is needed, the one of the type-checking functions can be used such as istable(), checktable(), or opttable(LuaTable)

The main table operations are defined on LuaValue for getting and setting values with and without metatag processing:

• get(LuaValue)
• set(LuaValue,LuaValue)
• rawget(LuaValue)
• rawset(LuaValue,LuaValue)
• plus overloads such as LuaValue.get(String), get(int), and so on

To iterate over key-value pairs from Java, use

 LuaValue k = LuaValue.NIL;
 while ( true ) {
    Varargs n = table.next(k);
    if ( (k = n.arg1()).isnil() )
       break;
    LuaValue v = n.arg(2)
    process( k, v )
 }

As with other types, LuaTable instances should be constructed via one of the table constructor methods on LuaValue:

• LuaValue.tableOf() empty table
• LuaValue.tableOf(int, int) table with capacity
• LuaValue.listOf(LuaValue[]) initialize array part
• LuaValue.listOf(LuaValue[], Varargs) initialize array part
• LuaValue.tableOf(LuaValue[]) initialize named hash part
• LuaValue.tableOf(Varargs, int) initialize named hash part
• LuaValue.tableOf(LuaValue[], LuaValue[]) initialize array and named parts
• LuaValue.tableOf(LuaValue[], LuaValue[], Varargs) initialize array and named parts

See Also:

LuaValue

Field Summary

protected LuaValue[]	array the array values
protected org.luaj.vm2.LuaTable.Slot[]	hash the hash part
protected int	hashEntries the number of hash entries
protected org.luaj.vm2.Metatable	m_metatable metatable for this table, or null

Fields inherited from class org.luaj.vm2.LuaValue

ADD, CALL, CONCAT, DIV, EMPTYSTRING, ENV, EQ, FALSE, INDEX, LE, LEN, LT, METATABLE, MINUSONE, MOD, MODE, MUL, NEWINDEX, NIL, NILS, NONE, NOVALS, ONE, POW, SUB, TBOOLEAN, TFUNCTION, TINT, TLIGHTUSERDATA, TNIL, TNONE, TNUMBER, TOSTRING, TRUE, TSTRING, TTABLE, TTHREAD, TUSERDATA, TVALUE, TYPE_NAMES, UNM, ZERO

Constructor Summary

LuaTable()
Construct empty table

LuaTable(int narray, int nhash)
Construct table with preset capacity.

LuaTable(LuaValue[] named, LuaValue[] unnamed, Varargs lastarg)
Construct table with named and unnamed parts.

LuaTable(Varargs varargs)
Construct table of unnamed elements.

LuaTable(Varargs varargs, int firstarg)
Construct table of unnamed elements.

Method Summary

LuaValue	arrayget(LuaValue[] array, int index) Returns the value at the given index in the array, or null if it is a weak reference that has been dropped.
LuaTable	checktable() Check that this is a LuaTable, or throw LuaError if it is not
LuaValue	concat(LuaString sep, int i, int j) Concatenate the contents of a table efficiently, using Buffer
protected static org.luaj.vm2.LuaTable.Entry	defaultEntry(LuaValue key, LuaValue value)
org.luaj.vm2.LuaTable.Slot	entry(LuaValue key, LuaValue value) Return an instance of Slot appropriate for the given key and value.
boolean	eq_b(LuaValue val) Equals: Perform equality comparison with another value including metatag processing using LuaValue.EQ, and return java boolean
LuaValue	eq(LuaValue val) Equals: Perform equality comparison with another value including metatag processing using LuaValue.EQ.
LuaValue	get(int key) Get a value in a table including metatag processing using LuaValue.INDEX.
LuaValue	get(LuaValue key) Get a value in a table including metatag processing using LuaValue.INDEX.
protected int	getArrayLength() Get the length of the array part of the table.
protected int	getHashLength() Get the length of the hash part of the table.
LuaValue	getmetatable() Get the metatable for this LuaValue
protected LuaValue	hashget(LuaValue key)
static int	hashmod(int hashCode, int mask)
static int	hashpow2(int hashCode, int mask)
void	hashset(LuaValue key, LuaValue value) Set a hashtable value
static int	hashSlot(LuaValue key, int hashMask) Find the hashtable slot index to use.
Varargs	inext(LuaValue key) Get the next element after a particular key in the contiguous array part of a table
void	insert(int pos, LuaValue value) Insert an element at a position in a list-table
protected static boolean	isLargeKey(LuaValue key)
boolean	istable() Check if this is a table
int	keyCount() This may be deprecated in a future release.
LuaValue[]	keys() This may be deprecated in a future release.
LuaValue	len() Length operator: return lua length of object (#this) including metatag processing as java int
int	length() Length operator: return lua length of object (#this) including metatag processing as java int
Varargs	next(LuaValue key) Get the next element after a particular key in the table
LuaTable	opttable(LuaTable defval) Check that optional argument is a table and return as LuaTable
void	presize(int narray) Preallocate the array part of a table to be a certain size,
void	presize(int narray, int nhash)
LuaValue	rawget(int key) Get a value in a table without metatag processing.
LuaValue	rawget(LuaValue key) Get a value in a table without metatag processing.
int	rawlen() Get raw length of table or string without metatag processing.
void	rawset(int key, LuaValue value) Set a value in a table without metatag processing.
void	rawset(LuaValue key, LuaValue value) caller must ensure key is not nil
LuaValue	remove(int pos) Remove the element at a position in a list-table
void	set(int key, LuaValue value) Set a value in a table without metatag processing using LuaValue.NEWINDEX.
void	set(LuaValue key, LuaValue value) caller must ensure key is not nil
LuaValue	setmetatable(LuaValue metatable) Set the metatable for this LuaValue
void	sort(LuaValue comparator) Sort the table using a comparator.
LuaValue	toLuaValue() Return this metatable as a LuaValue.
int	type() Get the enumeration value for the type of this value.
java.lang.String	typename() Get the String name of the type of this value.
Varargs	unpack() Unpack all the elements of this table
Varargs	unpack(int i) Unpack all the elements of this table from element i
Varargs	unpack(int i, int j) Unpack the elements from i to j inclusive
boolean	useWeakKeys() Return whether or not this table's keys are weak.
boolean	useWeakValues() Return whether or not this table's values are weak.
LuaValue	wrap(LuaValue value) Returns the given value wrapped in a weak reference if appropriate.

Methods inherited from class org.luaj.vm2.LuaValue

add, add, add, and, arg, arg1, argerror, argerror, aritherror, aritherror, arithmt, arithmtwith, assert_, buffer, call, call, call, call, call, callmt, checkboolean, checkclosure, checkdouble, checkfunction, checkglobals, checkint, checkinteger, checkjstring, checklong, checkmetatag, checknotnil, checknumber, checknumber, checkstring, checkthread, checkuserdata, checkuserdata, compareerror, compareerror, comparemt, concat, concat, concatmt, concatTo, concatTo, concatTo, div, div, div, divInto, eqmtcall, equals, error, get, gettable, gt_b, gt_b, gt_b, gt, gt, gt, gteq_b, gteq_b, gteq_b, gteq, gteq, gteq, illegal, initupvalue1, invoke, invoke, invoke, invoke, invoke, invoke, invokemethod, invokemethod, invokemethod, invokemethod, invokemethod, invokemethod, isboolean, isclosure, isfunction, isint, isinttype, islong, isnil, isnumber, isstring, isthread, isuserdata, isuserdata, isvalidkey, lenerror, listOf, listOf, load, lt_b, lt_b, lt_b, lt, lt, lt, lteq_b, lteq_b, lteq_b, lteq, lteq, lteq, metatableOf, metatag, method, method, method, method, method, method, mod, mod, mod, modFrom, mul, mul, mul, narg, neg, neq_b, neq, not, onInvoke, optboolean, optclosure, optdouble, optfunction, optint, optinteger, optjstring, optlong, optnumber, optstring, optthread, optuserdata, optuserdata, optvalue, or, pow, pow, pow, powWith, powWith, raweq, raweq, raweq, raweq, raweq, rawget, rawset, rawset, rawset, rawset, rawset, rawsetlist, set, set, set, set, set, settable, strcmp, strcmp, strongvalue, strvalue, sub, sub, sub, subargs, subFrom, subFrom, tableOf, tableOf, tableOf, tableOf, tableOf, tableOf, tailcallOf, testfor_b, toboolean, tobyte, tochar, todouble, tofloat, toint, tojstring, tolong, tonumber, toshort, tostring, toString, touserdata, touserdata, typerror, unimplemented, userdataOf, userdataOf, valueOf, valueOf, valueOf, valueOf, valueOf, valueOf, varargsOf, varargsOf, varargsOf, varargsOf, varargsOf, varargsOf

Methods inherited from class org.luaj.vm2.Varargs

argcheck, checkboolean, checkclosure, checkdouble, checkfunction, checkint, checkinteger, checkjstring, checklong, checknotnil, checknumber, checkstring, checktable, checkthread, checkuserdata, checkuserdata, checkvalue, eval, isfunction, isnil, isnoneornil, isnumber, isstring, istable, isTailcall, isthread, isuserdata, isvalue, optboolean, optclosure, optdouble, optfunction, optint, optinteger, optjstring, optlong, optnumber, optstring, opttable, optthread, optuserdata, optuserdata, optvalue, toboolean, tobyte, tochar, todouble, tofloat, toint, tojstring, tolong, toshort, touserdata, touserdata, type

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

array

protected LuaValue[] array

the array values

hash

protected org.luaj.vm2.LuaTable.Slot[] hash

the hash part

hashEntries

protected int hashEntries

the number of hash entries

m_metatable

protected org.luaj.vm2.Metatable m_metatable

metatable for this table, or null

Constructor Detail

LuaTable

public LuaTable()

Construct empty table

LuaTable

public LuaTable(int narray,
                int nhash)

Construct table with preset capacity.

Parameters:

narray - capacity of array part

nhash - capacity of hash part

LuaTable

public LuaTable(LuaValue[] named,
                LuaValue[] unnamed,
                Varargs lastarg)

Construct table with named and unnamed parts.

Parameters:

named - Named elements in order key-a, value-a, key-b, value-b, ...

unnamed - Unnamed elements in order value-1, value-2, ...

lastarg - Additional unnamed values beyond unnamed.length

LuaTable

public LuaTable(Varargs varargs)

Construct table of unnamed elements.

Parameters:

varargs - Unnamed elements in order value-1, value-2, ...

LuaTable

public LuaTable(Varargs varargs,
                int firstarg)

Construct table of unnamed elements.

Parameters:

varargs - Unnamed elements in order value-1, value-2, ...

firstarg - the index in varargs of the first argument to include in the table

Method Detail

type

public int type()

Description copied from class: LuaValue

Get the enumeration value for the type of this value.

Specified by:

type in class LuaValue

Returns:

value for this type, one of LuaValue.TNIL, LuaValue.TBOOLEAN, LuaValue.TNUMBER, LuaValue.TSTRING, LuaValue.TTABLE, LuaValue.TFUNCTION, LuaValue.TUSERDATA, LuaValue.TTHREAD

See Also:

LuaValue.typename()

typename

public java.lang.String typename()

Description copied from class: LuaValue

Get the String name of the type of this value.

Specified by:

typename in class LuaValue

Returns:

name from type name list LuaValue.TYPE_NAMES corresponding to the type of this value: "nil", "boolean", "number", "string", "table", "function", "userdata", "thread"

See Also:

LuaValue.type()

istable

public boolean istable()

Description copied from class: LuaValue

Check if this is a table

Overrides:

istable in class LuaValue

Returns:

true if this is a table, otherwise false

See Also:

LuaValue.checktable(), LuaValue.opttable(LuaTable), LuaValue.TTABLE

checktable

public LuaTable checktable()

Description copied from class: LuaValue

Check that this is a LuaTable, or throw LuaError if it is not

Overrides:

checktable in class LuaValue

Returns:

this if it is a LuaTable

See Also:

LuaValue.istable(), LuaValue.opttable(LuaTable), LuaValue.TTABLE

opttable

public LuaTable opttable(LuaTable defval)

Description copied from class: LuaValue

Check that optional argument is a table and return as LuaTable

Overrides:

opttable in class LuaValue

Parameters:

defval - LuaTable to return if this is nil or none

Returns:

this cast to LuaTable if a table, defval if nil or none, throws LuaError if some other type

See Also:

LuaValue.checktable(), LuaValue.istable(), LuaValue.TTABLE

presize

public void presize(int narray)

Description copied from class: LuaValue

Preallocate the array part of a table to be a certain size,

Primarily used internally in response to a SETLIST bytecode.

Overrides:

presize in class LuaValue

Parameters:

narray - the number of array slots to preallocate in the table.

presize

public void presize(int narray,
                    int nhash)

getArrayLength

protected int getArrayLength()

Get the length of the array part of the table.

Returns:

length of the array part, does not relate to count of objects in the table.

getHashLength

protected int getHashLength()

Get the length of the hash part of the table.

Returns:

length of the hash part, does not relate to count of objects in the table.

getmetatable

public LuaValue getmetatable()

Description copied from class: LuaValue

Get the metatable for this LuaValue

For LuaTable and LuaUserdata instances, the metatable returned is this instance metatable. For all other types, the class metatable value will be returned.

Overrides:

getmetatable in class LuaValue

Returns:

metatable, or null if it there is none

See Also:

LuaBoolean.s_metatable, LuaNumber.s_metatable, LuaNil.s_metatable, LuaFunction.s_metatable, LuaThread.s_metatable

setmetatable

public LuaValue setmetatable(LuaValue metatable)

Description copied from class: LuaValue

Set the metatable for this LuaValue

For LuaTable and LuaUserdata instances, the metatable is per instance. For all other types, there is one metatable per type that can be set directly from java

Overrides:

setmetatable in class LuaValue

Parameters:

metatable - LuaValue instance to serve as the metatable, or null to reset it.

Returns:

this to allow chaining of Java function calls

See Also:

LuaBoolean.s_metatable, LuaNumber.s_metatable, LuaNil.s_metatable, LuaFunction.s_metatable, LuaThread.s_metatable

get

public LuaValue get(int key)

Description copied from class: LuaValue

Get a value in a table including metatag processing using LuaValue.INDEX.

Overrides:

get in class LuaValue

Parameters:

key - the key to look up

Returns:

LuaValue for that key, or LuaValue.NIL if not found

See Also:

LuaValue.get(LuaValue), LuaValue.rawget(int)

get

public LuaValue get(LuaValue key)

Description copied from class: LuaValue

Get a value in a table including metatag processing using LuaValue.INDEX.

Overrides:

get in class LuaValue

Parameters:

key - the key to look up, must not be LuaValue.NIL or null

Returns:

LuaValue for that key, or LuaValue.NIL if not found and no metatag

See Also:

LuaValue.get(int), LuaValue.get(String), LuaValue.rawget(LuaValue)

rawget

public LuaValue rawget(int key)

Description copied from class: LuaValue

Get a value in a table without metatag processing.

Overrides:

rawget in class LuaValue

Parameters:

key - the key to look up

Returns:

LuaValue for that key, or LuaValue.NIL if not found

rawget

public LuaValue rawget(LuaValue key)

Description copied from class: LuaValue

Get a value in a table without metatag processing.

Overrides:

rawget in class LuaValue

Parameters:

key - the key to look up, must not be LuaValue.NIL or null

Returns:

LuaValue for that key, or LuaValue.NIL if not found

hashget

protected LuaValue hashget(LuaValue key)

set

public void set(int key,
                LuaValue value)

Description copied from class: LuaValue

Set a value in a table without metatag processing using LuaValue.NEWINDEX.

Overrides:

set in class LuaValue

Parameters:

key - the key to use

value - the value to use, can be LuaValue.NIL, must not be null

set

public void set(LuaValue key,
                LuaValue value)

caller must ensure key is not nil

Overrides:

set in class LuaValue

Parameters:

key - the key to use, must not be LuaValue.NIL or null

value - the value to use, can be LuaValue.NIL, must not be null

rawset

public void rawset(int key,
                   LuaValue value)

Description copied from class: LuaValue

Set a value in a table without metatag processing.

Overrides:

rawset in class LuaValue

Parameters:

key - the key to use

value - the value to use, can be LuaValue.NIL, must not be null

rawset

public void rawset(LuaValue key,
                   LuaValue value)

caller must ensure key is not nil

Overrides:

rawset in class LuaValue

Parameters:

key - the key to use, must not be LuaValue.NIL or null

value - the value to use, can be LuaValue.NIL, must not be null

remove

public LuaValue remove(int pos)

Remove the element at a position in a list-table

Parameters:

pos - the position to remove

Returns:

The removed item, or LuaValue.NONE if not removed

insert

public void insert(int pos,
                   LuaValue value)

Insert an element at a position in a list-table

Parameters:

pos - the position to remove

value - The value to insert

concat

public LuaValue concat(LuaString sep,
                       int i,
                       int j)

Concatenate the contents of a table efficiently, using Buffer

Parameters:

sep - LuaString separater to apply between elements

i - the first element index

j - the last element index, inclusive

Returns:

LuaString value of the concatenation

length

public int length()

Description copied from class: LuaValue

Length operator: return lua length of object (#this) including metatag processing as java int

Overrides:

length in class LuaValue

Returns:

length as defined by the lua # operator or metatag processing result converted to java int using LuaValue.toint()

len

public LuaValue len()

Description copied from class: LuaValue

Length operator: return lua length of object (#this) including metatag processing as java int

Overrides:

len in class LuaValue

Returns:

length as defined by the lua # operator or metatag processing result

rawlen

public int rawlen()

Description copied from class: LuaValue

Get raw length of table or string without metatag processing.

Overrides:

rawlen in class LuaValue

Returns:

the length of the table or string.

next

public Varargs next(LuaValue key)

Get the next element after a particular key in the table

Overrides:

next in class LuaValue

Parameters:

key - LuaInteger value identifying a key to start from, or LuaValue.NIL to start at the beginning

Returns:

key,value or nil

See Also:

LuaTable, LuaValue.inext(LuaValue), LuaValue.valueOf(int), Varargs.arg1(), Varargs.arg(int), LuaValue.isnil()

inext

public Varargs inext(LuaValue key)

Get the next element after a particular key in the contiguous array part of a table

Overrides:

inext in class LuaValue

Parameters:

key - LuaInteger value identifying a key to start from, or LuaValue.NIL to start at the beginning

Returns:

key,value or none

See Also:

LuaTable, LuaValue.next(LuaValue), LuaValue.valueOf(int), Varargs.arg1(), Varargs.arg(int), LuaValue.isnil()

hashset

public void hashset(LuaValue key,
                    LuaValue value)

Set a hashtable value

Parameters:

key - key to set

value - value to set

hashpow2

public static int hashpow2(int hashCode,
                           int mask)

hashmod

public static int hashmod(int hashCode,
                          int mask)

hashSlot

public static int hashSlot(LuaValue key,
                           int hashMask)

Find the hashtable slot index to use.

Parameters:

key - the key to look for

hashMask - N-1 where N is the number of hash slots (must be power of 2)

Returns:

the slot index

entry

public org.luaj.vm2.LuaTable.Slot entry(LuaValue key,
                                        LuaValue value)

Return an instance of Slot appropriate for the given key and value.

isLargeKey

protected static boolean isLargeKey(LuaValue key)

defaultEntry

protected static org.luaj.vm2.LuaTable.Entry defaultEntry(LuaValue key,
                                                          LuaValue value)

sort

public void sort(LuaValue comparator)

Sort the table using a comparator.

Parameters:

comparator - LuaValue to be called to compare elements.

keyCount

public int keyCount()

This may be deprecated in a future release. It is recommended to count via iteration over next() instead

Returns:

count of keys in the table

keys

public LuaValue[] keys()

This may be deprecated in a future release. It is recommended to use next() instead

Returns:

array of keys in the table

eq

public LuaValue eq(LuaValue val)

Description copied from class: LuaValue

Equals: Perform equality comparison with another value including metatag processing using LuaValue.EQ.

Overrides:

eq in class LuaValue

Parameters:

val - The value to compare with.

Returns:

LuaValue.TRUE if values are comparable and (this == rhs), LuaValue.FALSE if comparable but not equal, LuaValue if metatag processing occurs.

See Also:

LuaValue.eq_b(LuaValue), LuaValue.raweq(LuaValue), LuaValue.neq(LuaValue), LuaValue.eqmtcall(LuaValue, LuaValue, LuaValue, LuaValue), LuaValue.EQ

eq_b

public boolean eq_b(LuaValue val)

Description copied from class: LuaValue

Equals: Perform equality comparison with another value including metatag processing using LuaValue.EQ, and return java boolean

Overrides:

eq_b in class LuaValue

Parameters:

val - The value to compare with.

Returns:

true if values are comparable and (this == rhs), false if comparable but not equal, result converted to java boolean if metatag processing occurs.

See Also:

LuaValue.eq(LuaValue), LuaValue.raweq(LuaValue), LuaValue.neq_b(LuaValue), LuaValue.eqmtcall(LuaValue, LuaValue, LuaValue, LuaValue), LuaValue.EQ

unpack

public Varargs unpack()

Unpack all the elements of this table

unpack

public Varargs unpack(int i)

Unpack all the elements of this table from element i

unpack

public Varargs unpack(int i,
                      int j)

Unpack the elements from i to j inclusive

useWeakKeys

public boolean useWeakKeys()

Return whether or not this table's keys are weak.

useWeakValues

public boolean useWeakValues()

Return whether or not this table's values are weak.

toLuaValue

public LuaValue toLuaValue()

Return this metatable as a LuaValue.

wrap

public LuaValue wrap(LuaValue value)

Returns the given value wrapped in a weak reference if appropriate.

arrayget

public LuaValue arrayget(LuaValue[] array,
                         int index)

Returns the value at the given index in the array, or null if it is a weak reference that has been dropped.