public class ImmutableTable extends Table
The contents of this table may be queried, but not changed: the methods
rawset(Object, Object)
, rawset(long, Object)
and setMetatable(Table)
will throw an UnsupportedOperationException
.
The table has no metatable.
To instantiate a new ImmutableTable
, use one of the static constructor methods
(e.g., of(Iterable)
), or a ImmutableTable.Builder
as follows:
ImmutableTable t = new ImmutableTable.Builder() .add("key1", "value1") .add("key2", "value2") .build();
A word of caution: this class violates the expectation that all Lua tables are
mutable, and should therefore be used with care. In order to create a mutable copy of this
table, use newCopy(TableFactory)
.
Modifier and Type | Class and Description |
---|---|
static class |
ImmutableTable.Builder
Builder class for constructing instances of
ImmutableTable . |
Modifier and Type | Method and Description |
---|---|
boolean |
equals(Object o) |
Table |
getMetatable()
Returns the metatable of this object, or
null if this object does not have
a metatable. |
int |
hashCode() |
Object |
initialKey()
Returns the initial key for iterating through the set of keys in this table.
|
Table |
newCopy(TableFactory tableFactory)
Returns a new table constructed using the supplied
tableFactory , and copies
the contents of this table to it. |
static ImmutableTable |
of(Iterable<Map.Entry<Object,Object>> entries)
Returns an
ImmutableTable based on the contents of the sequence of
map entries entries . |
static ImmutableTable |
of(Map<Object,Object> map)
Returns an
ImmutableTable based on the contents of the map map . |
Object |
rawget(Object key)
Retrieves the value associated with the given
key , returning null
when key has no value associated with it. |
void |
rawset(long idx,
Object value)
Throws an
UnsupportedOperationException , since this table is immutable. |
void |
rawset(Object key,
Object value)
Throws an
UnsupportedOperationException , since this table is immutable. |
Table |
setMetatable(Table mt)
Throws an
UnsupportedOperationException , since this table is immutable. |
protected void |
setMode(boolean weakKeys,
boolean weakValues)
Sets the weakness of this table.
|
Object |
successorKeyOf(Object key)
Returns the next key for iterating through the set of keys in this table.
|
rawget, rawlen, updateBasetableModes
public static ImmutableTable of(Iterable<Map.Entry<Object,Object>> entries)
ImmutableTable
based on the contents of the sequence of
map entries entries
.
For every key
-value
pair in entries
, the behaviour of this
method is similar to that of Table.rawset(Object, Object)
:
value
is nil (i.e., null
), then key
will not have any value associated with it in the resulting table;key
is nil or NaN, a IllegalArgumentException
is thrown;key
is a number that has an integer value, it is converted to that integer
value.Keys may occur multiple times in entries
— only the last occurrence
counts.
entries
- the map entries, must not be null
entries
NullPointerException
- if entries
is null
IllegalArgumentException
- if entries
contains an entry with
a null
or NaN keypublic static ImmutableTable of(Map<Object,Object> map)
ImmutableTable
based on the contents of the map map
.
For every key
-value
pair in map
, the behaviour of this method
is similar to that of Table.rawset(Object, Object)
:
value
is nil (i.e., null
), then key
will not have any value associated with it in the resulting table;key
is nil or NaN, a IllegalArgumentException
is thrown;key
is a number that has an integer value, it is converted to that integer
value.map
- the map used to source the contents of the table, must not be null
map
NullPointerException
- if entries
is null
IllegalArgumentException
- if map
contains a null
or NaN keypublic Table newCopy(TableFactory tableFactory)
tableFactory
, and copies
the contents of this table to it.tableFactory
- the table factory to use, must not be null
public Object rawget(Object key)
Table
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)
.
public void rawset(Object key, Object value)
UnsupportedOperationException
, since this table is immutable.rawset
in class Table
key
- ignoredvalue
- ignoredUnsupportedOperationException
- every time this method is calledpublic void rawset(long idx, Object value)
UnsupportedOperationException
, since this table is immutable.rawset
in class Table
idx
- ignoredvalue
- ignoredUnsupportedOperationException
- every time this method is calledpublic Table getMetatable()
LuaObject
null
if this object does not have
a metatable.getMetatable
in class Table
null
if this object does not have
a metatablepublic Table setMetatable(Table mt)
UnsupportedOperationException
, since this table is immutable.setMetatable
in class Table
mt
- ignoredUnsupportedOperationException
- every time this method is calledpublic Object initialKey()
Table
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 Table.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
initialKey
in class Table
public Object successorKeyOf(Object key)
Table
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
Table.initialKey()
.
successorKeyOf
in class Table
key
- the key to get the immediate successor of, must not be null
key
in this tableprotected void setMode(boolean weakKeys, boolean weakValues)
Table
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 Table.setMetatable(Table)
and
Table.updateBasetableModes(Object, Object)
.
Copyright © 2016. All rights reserved.