Murl Engine Lua Addon API  Version 1.0 beta
Murl.MapBase.StringUInt32ArrayUInt32StdHashString

A generic map template base class.

A map stores a number of key/value pairs, where the keys do not have to be unique.
This is the base class of the Map and ObjectMap class.
This class is based on the NTL AMap container, see http://www.ultimatepp.org


Table members

Methods


Clear()

Clear the map and remove the underlying storage.

Clear()


Empty()

Empty the map, but keep the underlying storage.

Empty()


Shrink()

Shrink the map so that the underlying key and value storage is only as large as necessary.

Shrink()


Trim(n)

Reduce the map to a given number of items.

Trim(Integer n)

Parameters
nThe new number of items in the map, must be smaller than the current item count.

Drop(n)

Reduce the map by removing a given number of items from the end.

Drop(Integer n)

Parameters
nThe number of items to remove from the end.

Reserve(n)

Reserve storage space. If the given size is less than the actual size, nothing is done.

Reserve(Integer n)

Parameters
nThe number of items the underlying storage should hold.

Sweep()

Remove any unlinked pairs from the map.

Sweep()


SetKey(index, key)

Set the key of a given index.

SetKey(Integer index, String key)

Parameters
indexThe index to replace.
keyThe new key.

Add(key)

Add a new key/value pair to the map. The newly added value is initialized using the value type's default constructor.

Integer Add(String key)

Parameters
keyThe key under which the value can be retrieved.
Returns
Integer A reference to the newly constructed value.

Add(key, value)

Add a key/value pair to the map. The newly added value is initialized using the given reference value's copy constructor.

Integer Add(String key, Integer value)

Parameters
keyThe key under which the value can be retrieved.
valueThe reference value to add.
Returns
Integer A reference to the newly constructed value.

Put(key)

Add a new key/value pair to the map, replacing an unlinked element if present. The newly added value is initialized using the value type's default constructor.

Integer Put(String key)

Parameters
keyThe key under which the value can be retrieved.
Returns
Integer A reference to the newly added value.

Put(key, value)

Add a key/value pair to the map, replacing an unlinked element if present. The newly added value is initialized using the given reference value's copy constructor.

Integer Put(String key, Integer value)

Parameters
keyThe key under which the value can be retrieved.
valueThe reference value to add.
Returns
Integer The index of the pair in the map.

Insert(index, key)

Insert a new key/value pair into the map at a given position. The newly added value is initialized using the value type's default constructor.

Integer Insert(Integer index, String key)

Parameters
indexThe index where to insert the new pair.
keyThe key under which the value can be retrieved.
Returns
Integer A reference to the newly constructed value.

Insert(index, key, value)

Insert a key/value pair into the map at a given position. The newly added value is initialized using the given reference value's copy constructor.

Integer Insert(Integer index, String key, Integer value)

Parameters
indexThe index where to insert the new pair.
keyThe key under which the value can be retrieved.
valueThe reference value to insert.
Returns
Integer A reference to the newly constructed value.

Unlink(index)

Unlink the pair at a given index. Unlinked elements remain in the map, but are ignored by any search operations.

Unlink(Integer index)

Parameters
indexThe index of the pair to unlink.

UnlinkKey(key)

Unlink all pairs matching a given key. Unlinked elements remain in the map, but are ignored by any search operations.

Integer UnlinkKey(String key)

Parameters
keyThe key for which to unlink all elements.
Returns
Integer The number of elements that were unlinked.

UnlinkKey(key, hash)

Unlink all pairs matching a given key, using a precomputed hash value. Unlinked elements remain in the map, but are ignored by any search operations.

Integer UnlinkKey(String key, Integer hash)

Parameters
keyThe key for which to unlink all elements.
hashThe precomputed hash value.
Returns
Integer The number of elements that were unlinked.

IsUnlinked(index)

Check if the pair at a given index is unlinked.

Boolean IsUnlinked(Integer index)

Parameters
indexThe index of the pair to check.
Returns
Boolean true if the pair is unlinked.

Remove(index)

Remove the key/value pair at a given position from the map.

Remove(Integer index)

Parameters
indexThe zero-based index from where to remove the pair.

Remove(index, count)

Remove a number of key/value pairs from the map at a given starting position.

Remove(Integer index, Integer count)

Parameters
indexThe zero-based index from where to remove the first pair.
countThe number of subsequent pairs to remove.

Remove(sortedIndices)

Remove a number of key/value pairs from the map at given positions.

Remove(Murl.Array.SInt32 sortedIndices)

Parameters
sortedIndicesA sorted array of indices where to remove the items.

RemoveKey(key)

Remove all pairs from the map that match a given key.

Integer RemoveKey(String key)

Parameters
keyThe key for which to remove the pairs.
Returns
Integer The number of pairs that were removed.

Find(key)

Find the first occurrence of a given key in the map.

Integer Find(String key)

Parameters
keyThe key to search for.
Returns
Integer The index of the pair in the map, or -1 if not found.

Find(key, hash)

Find the first occurrence of a given key in the map, using a precomputed hash value.

Integer Find(String key, Integer hash)

Parameters
keyThe key to search for.
hashThe precomputed hash value.
Returns
Integer The index of the pair in the map, or -1 if not found.

FindLast(key)

Find the last occurrence of a given key in the map.

Integer FindLast(String key)

Parameters
keyThe key to search for.
Returns
Integer The index of the pair in the map, or -1 if not found.

FindLast(key, hash)

Find the last occurrence of a given key in the map, using a precomputed hash value.

Integer FindLast(String key, Integer hash)

Parameters
keyThe key to search for.
hashThe precomputed hash value.
Returns
Integer The index of the pair in the map, or -1 if not found.

FindNext(index)

Find the next occurrence of a key that is specified by a given index.

Integer FindNext(Integer index)

Parameters
indexThe index of the pair containing the key to search for.
Returns
Integer The index of the next pair in the map, or -1 if not found.

FindPrev(index)

Find the previous occurrence of a key that is specified by a given index.

Integer FindPrev(Integer index)

Parameters
indexThe index of the pair containing the key to search for.
Returns
Integer The index of the previous pair in the map, or -1 if not found.

FindAdd(key)

Find the first occurrence of a given key in the map, or add a new pair if the key was not found. If a pair needs to be added, the newly created value is initialized using the value type's default constructor.

Integer FindAdd(String key)

Parameters
keyThe key to search for.
Returns
Integer The index of the pair in the map.

FindAdd(key, value)

Find the first occurrence of a given key in the map, or add a new pair if the key was not found. If a pair needs to be added, the newly created value is initialized using the given value's copy constructor.

Integer FindAdd(String key, Integer value)

Parameters
keyThe key to search for.
valueThe reference value to add.
Returns
Integer The index of the pair in the map.

FindPut(key)

Find the first occurrence of a given key in the map, or add a new pair if the key was not found, hereby replacing an unlinked element if possible. If a pair needs to be added, the newly created value is initialized using the value type's default constructor.

Integer FindPut(String key)

Parameters
keyThe key to search for.
Returns
Integer The index of the pair in the map.

FindPut(key, value)

Find the first occurrence of a given key in the map, or add a new pair if the key was not found, hereby replacing an unlinked element if possible. If a pair needs to be added, the newly created value is initialized using the given value's copy constructor.

Integer FindPut(String key, Integer value)

Parameters
keyThe key to search for.
valueThe reference value to add.
Returns
Integer The index of the pair in the map.

Get(key)

Get a reference to the first occurrence of a given key in the map. If the key was not found, the behaviour is undefined.

Integer Get(String key)

Parameters
keyThe key to search for.
Returns
Integer A reference to the value of the first pair found.

Get(key, defaultValue)

Get a const reference to the first occurrence of a given key in the map. If the key was not found, the given default value is returned

Integer Get(String key, Integer defaultValue)

Parameters
keyThe key to search for.
defaultValueThe default value to return if the key was not found.
Returns
Integer A const reference to the value of the first pair, or the given default value.

GetAdd(key)

Get a reference to the first occurrence of a given key in the map, or add a new pair if the key was not found. If a pair needs to be added, the newly created value is initialized using the value type's default constructor.

Integer GetAdd(String key)

Parameters
keyThe key to search for.
Returns
Integer A reference to the value of the first pair found.

GetAdd(key, value)

Get a reference to the first occurrence of a given key in the map, or add a new pair if the key was not found. If a pair needs to be added, the newly created value is initialized using the given value's copy constructor.

Integer GetAdd(String key, Integer value)

Parameters
keyThe key to search for.
valueThe reference value to add.
Returns
Integer A reference to the value of the first pair found.

GetPut(key)

Get a reference to the first occurrence of a given key in the map, or add a new pair if the key was not found, hereby replacing an unlinked element if possible. If a pair needs to be added, the newly created value is initialized using the value type's default constructor.

Integer GetPut(String key)

Parameters
keyThe key to search for.
Returns
Integer A reference to the value of the first pair found.

GetPut(key, value)

Get a reference to the first occurrence of a given key in the map, or add a new pair if the key was not found, hereby replacing an unlinked element if possible. If a pair needs to be added, the newly created value is initialized using the given value's copy constructor.

Integer GetPut(String key, Integer value)

Parameters
keyThe key to search for.
valueThe reference value to add.
Returns
Integer A reference to the value of the first pair found.

GetKey(index)

Get a const reference to the key at a given index. If the index is out of range, the behaviour is undefined.

String GetKey(Integer index)

Parameters
indexThe index of the key to retrieve.
Returns
String A const reference to the requested key.

GetIndex()

Get a const reference to the key storage.

Murl.Index.String GetIndex()

Returns
Murl.Index.String A const reference to the underlying key storage.

GetKeys()

Get a const reference to the array of keys.

Murl.Array.String GetKeys()

Returns
Murl.Array.String A const reference to the underlying key storage array.

GetValues()

Get a const reference to the array of values.

Murl.Array.UInt32 GetValues()

Returns
Murl.Array.UInt32 A const reference to the underlying value array.

IsIndexValid(index)

Check if a given index is a valid index.

Boolean IsIndexValid(Integer index)

Parameters
indexThe index to check.
Returns
Boolean true if index >= 0 and index < GetCount().

Bottom()

Get a const reference to the first value in the storage.

Integer Bottom()

Returns
Integer A const reference to the first value.

BottomKey()

Get a const reference to the first key in the storage.

String BottomKey()

Returns
String A const reference to the first key.

Top()

Get a const reference to the last value in the storage.

Integer Top()

Returns
Integer A const reference to the last value.

TopKey()

Get a const reference to the last key in the storage.

String TopKey()

Returns
String A const reference to the last key.

PopKey()

Remove the last key/value pair from the map and return its key.

String PopKey()

Returns
String The key of the removed pair.

GetAlloc()

Get the number of actually allocated pairs.

Integer GetAlloc()

Returns
Integer The number of allocated pairs.

GetCount()

Get the number of items in the map.

Integer GetCount()

Returns
Integer The number of items.

IsEmpty()

Check if the map is empty.

Boolean IsEmpty()

Returns
Boolean true if the map is empty, false otherwise.

IsEqual(other)

Compare the map to another one.

Boolean IsEqual(Murl.MapBase.StringUInt32ArrayUInt32StdHashString other)

Parameters
otherThe map to compare.
Returns
Boolean true if all key value pairs have identical contents.


Metamethods


The length operator

The length operator is denoted by the unary prefix operator #.

Returns
GetCount()

The array subscript operator.

Get a reference to the value at a given index. If the index is out of range, the behaviour is undefined.

Parameters
indexThe index of the value to retrieve.
Returns
Integer = Murl.MapBase.StringUInt32ArrayUInt32StdHashString [Integer index]
Assign
Murl.MapBase.StringUInt32ArrayUInt32StdHashString [Integer index] = Integer

The equal to operator.

The "equal to" comparison operator, calls IsEqual().

Returns
Boolean = Murl.MapBase.StringUInt32ArrayUInt32StdHashString == Murl.MapBase.StringUInt32ArrayUInt32StdHashString