class list

This is the built-in list class.

It is a double-chained, associative list implementation. Items can be stored and retrieved by an associative 'key'. The key can be an integer, a floating-point number, or a string. The list does not enforce that an item's key is unique.

Note that all methods that access items by their key will actually search the list for the first occurrence of a matching key. This will only work reliably, if you use unique values for the keys. It also means that performance of these methods gets worse the larger the list gets. For very large collections, consider using the table class, or use the iterator class for sequential access to items.

Constructors

list ()Constructs a new, empty list.
list (const list)Copy-constructs a new list from the specified list.
list (const var[])Constructs a list from the specified array.

Methods

add (const var, var)Adds a new item to the list by key and value.
addOrSet (const var, var)Sets an existing item in the list to a new value, or adds a new item.
clear ()Removes all items from the list.
list deepCopy ()Returns a deep-copy of this list.
enumerate (list::enumerator, var)Calls the specified enumerator delegate for every item in this list.
insert (const var, const var, var)Inserts a new item in the list.
insertAfter (const var, const var, var)Inserst a new item in the list.
int keyExists (const var)Returns true if the specified key exists in this list, otherwise false.
const var keyFromIndex (const int)Returns the key from the list that is associated with the specified zero based index.
moveToFirst (const var)Moves the specified item to the beginning of the list.
moveToLast (const var)Moves the specified item to the end of the list.
remove (const var)Removes the specified item from the list.
sort (const int, array::comparator)Sorts the list according to the specified mode and comparator delegate.
swap (const var, const var)Exchanges the positions of the specified items in the list.
var[] toArray ()Returns an array of all values in this list.
var value (const var)Returns the value from the list that is associated with the specified key.
var valueFromIndex (const int)Returns the value from the list that is associated with the specified zero based index.

Properties

int length ()Returns current number of items in this list.

Reference

method list ()

Constructs a new, empty list.


method list (const list)

Copy-constructs a new list from the specified list.

The new list will be a shall-copy, meaning items in the list will be copied only by reference.


method list (const var[])

Constructs a list from the specified array.

If the array is multi-dimensional, sub-arrays will be added to the list. The array index will be used as a key for every element added to the list.


method add (const var key, var val)

Adds a new item to the list by key and value.

The key must be an integer, floating-point value, or a string. No checking is performed wheter the key is already in the list. The value can be of any type.


method addOrSet (const var key, var val)

Sets an existing item in the list to a new value, or adds a new item.

The method first checks if the specified key is already in the list. If it is, the associated value is replaced by the new value. If the key is not found in the list, a new item is added.


method clear ()

Removes all items from the list.


method list deepCopy ()

Returns a deep-copy of this list.

WARNING: All element data will be copied! If the list contains script objects that have copy-constructors, this method can be time consuming. It should only be called in cases where a shallow-copy would not suffice.


method enumerate (list::enumerator fn, var args)

Calls the specified enumerator delegate for every item in this list.


method insert (const var key, const var newKey, var newVal)

Inserts a new item in the list.

The new item will be inserted before the specified item. If the specified item does not exist, the call has no effect.


method insertAfter (const var key, const var newKey, var newVal)

Inserst a new item in the list.

The new item will be inserted after the specified item. If the specified item does not exist, the call has no effect.


method int keyExists (const var key)

Returns true if the specified key exists in this list, otherwise false.


method const var keyFromIndex (const int index)

Returns the key from the list that is associated with the specified zero based index.

If the index is out of range, null is returned.


method moveToFirst (const var key)

Moves the specified item to the beginning of the list.

If the specified item does not exist, the call has no effect.


method moveToLast (const var key)

Moves the specified item to the end of the list.

If the specified item does not exist, the call has no effect.


method remove (const var key)

Removes the specified item from the list.

If the specified item does not exist, the call has no effect.


method sort (const int mode, array::comparator fn)

Sorts the list according to the specified mode and comparator delegate.

'mode' is defined as follows:

  1. sort by key first, ascending
  2. sort by key first, descending
  3. sort by value first, ascending
  4. sort by value first, descending


method swap (const var key1, const var key2)

Exchanges the positions of the specified items in the list.

If one or both items are not found, the call is ignored.


method var[] toArray ()

Returns an array of all values in this list.

The list item's keys will be disregarded.


method var value (const var key)

Returns the value from the list that is associated with the specified key.

If the key is not found, null is returned.


method var valueFromIndex (const int index)

Returns the value from the list that is associated with the specified zero based index.

If the index is out of range, null is returned.


accessor int length ()

Returns current number of items in this list.