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

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, Integer 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.

String Add(Integer key)

Parameters
keyThe key under which the value can be retrieved.
Returns
String 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.

String Add(Integer key, String value)

Parameters
keyThe key under which the value can be retrieved.
valueThe reference value to add.
Returns
String 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.

String Put(Integer key)

Parameters
keyThe key under which the value can be retrieved.
Returns
String 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(Integer key, String 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.

String Insert(Integer index, Integer key)

Parameters
indexThe index where to insert the new pair.
keyThe key under which the value can be retrieved.
Returns
String 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.

String Insert(Integer index, Integer key, String 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
String 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(Integer 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(Integer 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(Integer 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(Integer 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(Integer 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(Integer 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(Integer 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(Integer 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(Integer key, String 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(Integer 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(Integer key, String 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.

String Get(Integer key)

Parameters
keyThe key to search for.
Returns
String 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

String Get(Integer key, String defaultValue)

Parameters
keyThe key to search for.
defaultValueThe default value to return if the key was not found.
Returns
String 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.

String GetAdd(Integer key)

Parameters
keyThe key to search for.
Returns
String 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.

String GetAdd(Integer key, String value)

Parameters
keyThe key to search for.
valueThe reference value to add.
Returns
String 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.

String GetPut(Integer key)

Parameters
keyThe key to search for.
Returns
String 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.

String GetPut(Integer key, String value)

Parameters
keyThe key to search for.
valueThe reference value to add.
Returns
String 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.

Integer GetKey(Integer index)

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

GetIndex()

Get a const reference to the key storage.

Murl.Index.UInt32 GetIndex()

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

GetKeys()

Get a const reference to the array of keys.

Murl.Array.UInt32 GetKeys()

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

GetValues()

Get a const reference to the array of values.

Murl.Array.String GetValues()

Returns
Murl.Array.String 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.

String Bottom()

Returns
String A const reference to the first value.

BottomKey()

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

Integer BottomKey()

Returns
Integer A const reference to the first key.

Top()

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

String Top()

Returns
String A const reference to the last value.

TopKey()

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

Integer TopKey()

Returns
Integer A const reference to the last key.

PopKey()

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

Integer PopKey()

Returns
Integer 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.UInt32StringArrayStringStdHashUInt32 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
String = Murl.MapBase.UInt32StringArrayStringStdHashUInt32 [Integer index]
Assign
Murl.MapBase.UInt32StringArrayStringStdHashUInt32 [Integer index] = String

The equal to operator.

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

Returns
Boolean = Murl.MapBase.UInt32StringArrayStringStdHashUInt32 == Murl.MapBase.UInt32StringArrayStringStdHashUInt32