public abstract class Table extends LuaObject
Note on equality: according to §3.4.4 of the Lua Reference Manual,
tables a
and b
are expected to be equal if and only if they are
the same object. However, Ordering.isRawEqual(Object, Object)
compares
tables using Object.equals(Object)
. Exercise caution when overriding
equals()
.
Constructor and Description |
---|
Table() |
Modifier and Type | Method and Description |
---|---|
Table |
getMetatable()
Returns the metatable of this object, or
null if this object does not have
a metatable. |
abstract Object |
initialKey()
Returns the initial key for iterating through the set of keys in this table.
|
Object |
rawget(long idx)
Retrieves the value associated with the given integer
idx , returning
null when idx has no value associated with it. |
abstract Object |
rawget(Object key)
Retrieves the value associated with the given
key , returning null
when key has no value associated with it. |
long |
rawlen()
If this table is a sequence, returns the length of this sequence.
|
void |
rawset(long idx,
Object value)
Sets the value associated with the integer key
idx to value . |
abstract void |
rawset(Object key,
Object value)
Sets the value associated with the key
key to value . |
Table |
setMetatable(Table mt)
Sets the metatable of this table to
mt . |
protected abstract void |
setMode(boolean weakKeys,
boolean weakValues)
Sets the weakness of this table.
|
abstract Object |
successorKeyOf(Object key)
Returns the next key for iterating through the set of keys in this table.
|
protected void |
updateBasetableModes(Object key,
Object value)
If
key is equal to Metatables.MT_MODE , updates the weakness of the tables
that use this table as their metatable (i.e., the basetables of this table). |
public abstract Object rawget(Object key)
key
, returning null
when key
has no value associated with it.
Implementations of this method must ensure that the Lua rules for valid
table keys are honoured, e.g. by normalising keys using
Conversions.normaliseKey(Object)
.
This method provides raw access to the table. For non-raw access
(i.e., handling the __index
metamethod), use
Dispatch.index(ExecutionContext, Table, Object)
.
key
- the key, may be null
key
, or null
when there is no
value associated with key
in this tablepublic Object rawget(long idx)
idx
, returning
null
when idx
has no value associated with it.
This method must be functionally equivalent to rawget(Object)
with the
corresponding boxed key. However, implementations of this method may optimise the retrieval
in this case, since the type of the key is known at compile-time.
This method provides raw access to the table. For non-raw access
(i.e., handling the __index
metamethod), use
Dispatch.index(ExecutionContext, Table, long)
.
idx
- the integer keyidx
, or null
when there is no
value associated with idx
in this tablepublic abstract void rawset(Object key, Object value)
key
to value
. When value
is null
, removes key
from the table.
When key
is null
(i.e., a nil) or a NaN,
an IllegalArgumentException
is thrown.
This method provides raw access to the table. For non-raw access
(i.e., handling the __newindex
metamethod), use
Dispatch.setindex(ExecutionContext, Table, Object, Object)
.
Implementation notes: Implementations of this method must ensure that the behaviour of this method conforms to the Lua semantics as delineated in the Lua Reference Manual. In particular:
Conversions.normaliseKey(Object)
;"__mode"
must call updateBasetableModes(Object, Object)
.key
- the key, must not be null
or NaNvalue
- the value to associate with key
, may be null
IllegalArgumentException
- when key
is null
or a NaNpublic void rawset(long idx, Object value)
idx
to value
.
When value
is null
, removes idx
from the table.
This method must be functionally equivalent to rawset(Object,Object)
with the
corresponding boxed key. However, implementations of this method may be more optimised
than in the generic case, since the type of the key is known at compile-time.
This method provides raw access to the table. For non-raw access
(i.e., handling the __newindex
metamethod), use
Dispatch.setindex(ExecutionContext, Table, long, Object)
.
idx
- the integer keyvalue
- the value to associate with idx
, may be null
public long rawlen()
According to §2.1 of the Lua Reference Manual, a sequence is
a table where the set of all positive numeric keys is equal to {1..n} for some non-negative integer n, which is called the length of the sequence
Note that when this table is not a sequence, the return value of this method is undefined.
public abstract Object initialKey()
Conceptually speaking, all keys in this table are totally ordered; this method returns the minimal key.
The key returned by this method, together with the subsequent calls
to successorKeyOf(Object)
will visit all keys in this table exactly once
(in an unspecified order):
Object k = table.initialIndex(); while (k != null) { // process the key k k = table.nextIndex(k); } // at this point, we visited all keys in table exactly once
public abstract Object successorKeyOf(Object key)
Conceptually speaking, all keys in this table are totally ordered; this method
returns the immediate successor of key
, or null
if key
is
the maximal key.
When no value is associated with the key key
in this table,
an IllegalArgumentException
is thrown.
To retrieve the initial key for iterating through this table, use
initialKey()
.
key
- the key to get the immediate successor of, must not be null
key
in this tableIllegalArgumentException
- when no value is associated with key
in this table, or key
is null
public Table setMetatable(Table mt)
mt
. mt
may be null
:
in that case, removes the metatable from this object.
Returns the metatable previously associated with this object (i.e., the metatable
before the call of this method; possibly null
).
This method maintains the weakness of this table by invoking
setMode(boolean, boolean)
every time it is called.
setMetatable
in class LuaObject
mt
- new metatable to attach to this object, may be null
public Table getMetatable()
LuaObject
null
if this object does not have
a metatable.getMetatable
in class LuaObject
null
if this object does not have
a metatableprotected void updateBasetableModes(Object key, Object value)
key
is equal to Metatables.MT_MODE
, updates the weakness of the tables
that use this table as their metatable (i.e., the basetables of this table).
Otherwise, this method has no effect.
Whenever applicable, this method must be called by the implementations
of rawset(Object, Object)
in order to ensure that assignments to
the Metatables.MT_MODE
key update the weakness mode of the tables that use this
table as a metatable, as required by §2.5.2 of the Lua Reference Manual.
It is safe not to call this method when key
is known not to be equal to
Metatables.MT_MODE
.
key
- the key, may be null
value
- the value, may be null
protected abstract void setMode(boolean weakKeys, boolean weakValues)
weakKeys
is true
, the table will have
weak keys (otherwise, the table will have non-weak keys). Similarly, if weakValues
is true
, the table will have weak values (and non-weak values if false
).
This method is not meant to be called directly: according to §2.5.2 of the Lua
Reference Manual, the weakness of a table is fully determined by the value of the
"__mode"
field of its metatable. It is, however, meant to be called as part
of maintenance of this requirement by setMetatable(Table)
and
updateBasetableModes(Object, Object)
.
weakKeys
- key mode (true
for weak, false
for non-weak keys)weakValues
- value mode (true
for weak, false
for non-weak values)Copyright © 2016. All rights reserved.