org.luaj.vm2
Class LuaTable

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

Direct Known Subclasses:

WeakTable

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 int	hashEntries the number of hash entries
protected LuaValue[]	hashKeys the hash keys
protected LuaValue[]	hashValues the hash values
protected LuaValue	m_metatable metatable for this table, or null

Fields inherited from class org.luaj.vm2.LuaValue

ADD, CALL, CONCAT, DIV, EMPTYSTRING, 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

protected LuaTable	changemode(boolean weakkeys, boolean weakvalues) Change the mode of a table
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
boolean	eq_b(LuaValue val) Equals: Perform equality comparison with another value including metatag processing using EQ, and return java boolean
LuaValue	eq(LuaValue val) Equals: Perform equality comparison with another value including metatag processing using EQ.
LuaValue	foreach(LuaValue func) Call the supplied function once for each key-value pair
LuaValue	foreachi(LuaValue func) Call the supplied function once for each key-value pair in the contiguous array part
LuaValue	get(int key) Get a value in a table including metatag processing using INDEX.
LuaValue	get(LuaValue key) Get a value in a table including metatag processing using 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
LuaValue	getn() Implementation of lua 5.0 getn() function.
protected void	hashClearSlot(int i) Clear a particular slot in the table
int	hashFindSlot(LuaValue key) Find the hashtable slot to use
protected LuaValue	hashget(LuaValue key)
void	hashset(LuaValue key, LuaValue value) Set a hashtable value
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
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
int	maxn() Return table.maxn() as defined by lua 5.0.
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.
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 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.
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.

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, callmt, checkboolean, checkclosure, checkdouble, checkfunction, checkint, checkinteger, checkjstring, checklong, checkmetatag, checknotnil, checknumber, checknumber, checkstring, checkthread, checkuserdata, checkuserdata, checkvalidkey, compareerror, compareerror, comparemt, concat, concat, concatmt, concatTo, concatTo, concatTo, div, div, div, divInto, eqmtcall, equals, error, get, getfenv, gettable, gt_b, gt_b, gt_b, gt, gt, gt, gteq_b, gteq_b, gteq_b, gteq, gteq, gteq, illegal, invoke, invoke, invoke, invoke, invoke, invoke, invokemethod, invokemethod, invokemethod, invokemethod, invokemethod, invokemethod, isboolean, isclosure, isfunction, isint, isinttype, islong, isnil, isnumber, isstring, isthread, isuserdata, isuserdata, isweaknil, lenerror, listOf, listOf, load, lt_b, lt_b, lt_b, lt, lt, lt, lteq_b, lteq_b, lteq_b, lteq, lteq, lteq, 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, setfenv, settable, strcmp, strcmp, strongkey, strongvalue, strvalue, sub, sub, sub, 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, subargs, 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

hashKeys

protected LuaValue[] hashKeys

the hash keys

hashValues

protected LuaValue[] hashValues

the hash values

hashEntries

protected int hashEntries

the number of hash entries

m_metatable

protected LuaValue 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 TNIL, TBOOLEAN, TNUMBER, TSTRING, TTABLE, TFUNCTION, TUSERDATA, 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

changemode

protected LuaTable changemode(boolean weakkeys,
                              boolean weakvalues)

Change the mode of a table

Parameters:

weakkeys - true to make the table have weak keys going forward

weakvalues - true to make the table have weak values going forward

Returns:

this or a new WeakTable if the mode change requires copying.

get

public LuaValue get(int key)

Description copied from class: LuaValue

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

Overrides:

get in class LuaValue

Parameters:

key - the key to look up

Returns:

LuaValue for that key, or 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 INDEX.

Overrides:

get in class LuaValue

Parameters:

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

Returns:

LuaValue for that key, or 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 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 NIL or null

Returns:

LuaValue for that key, or 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 NEWINDEX.

Overrides:

set in class LuaValue

Parameters:

key - the key to use

value - the value to use, can be 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 NIL or null

value - the value to use, can be 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 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 NIL or null

value - the value to use, can be 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

getn

public LuaValue getn()

Description copied from class: LuaValue

Implementation of lua 5.0 getn() function.

Overrides:

getn in class LuaValue

Returns:

value of getn() as defined in lua 5.0 spec if this is a LuaTable

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

maxn

public int maxn()

Return table.maxn() as defined by lua 5.0.

Provided for compatibility, not a scalable operation.

Returns:

value for maxn

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 NIL to start at the beginning

Returns:

key,value or nil

See Also:

LuaTable, #inext(), 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 NIL to start at the beginning

Returns:

key,value or none

See Also:

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

foreach

public LuaValue foreach(LuaValue func)

Call the supplied function once for each key-value pair

Parameters:

func - function to call

foreachi

public LuaValue foreachi(LuaValue func)

Call the supplied function once for each key-value pair in the contiguous array part

Parameters:

func -

hashset

public void hashset(LuaValue key,
                    LuaValue value)

Set a hashtable value

Parameters:

key - key to set

value - value to set

hashFindSlot

public int hashFindSlot(LuaValue key)

Find the hashtable slot to use

Parameters:

key - key to look for

Returns:

slot to use

hashClearSlot

protected void hashClearSlot(int i)

Clear a particular slot in the table

Parameters:

i - slot to clear.

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 EQ.

Overrides:

eq 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, 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 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