List functions
Functions for manipulating lists. For a discussion on how to use lists, see here.
Contains
Section titled “Contains”Contains (object parent, object child)Returns a boolean - true if the child object is contained by the parent. This doesn’t necessarily mean that there is a direct parent-child relationship - for example if object A has parent B, and B has parent C, then
Contains(C, A)will return true.
FilterByAttribute
Section titled “FilterByAttribute”FilterByAttribute (objectlist list, string attribute name, any value)Returns a new object list containing only the objects in the given list for which the named attribute has the given value (which can be of any type).
Note that if the value is null this effectively filters for objects without the named attribute.
See also FilterByNotAttribute.
Omit the value to get the objects that have the attribute set to anything: with no value, this function returns FilterByNotAttribute(list, name, null).
FilterByNotAttribute
Section titled “FilterByNotAttribute”FilterByNotAttribute (objectlist list, string attribute name, any value)Returns a new object list containing only the objects in the given list for which the named attribute does not have the given value (which can be of any type).
Note that if the value is null this effectively filters for objects with the named attribute, whatever the value.
See also FilterByAttribute.
Omit the value to get the objects that do not have the attribute set at all: with no value, this function returns FilterByAttribute(list, name, null).
FilterByType
Section titled “FilterByType”FilterByType (objectlist list, string typename)Returns a new object list containing only the objects in the given list that are of the given type.
IndexOf
Section titled “IndexOf”IndexOf (list, anything)Returns an int - the position of the given element in the list, or -1 if it is not in the list. Note that lists count from zero.
list = Split("One;Two;Three;Four")msg(IndexOf(list, "One"))// -> 0msg(IndexOf(list, "Four"))// -> 3msg(IndexOf(list, "Five"))// -> -1ListCombine
Section titled “ListCombine”ListCombine (list, list)Combines two stringlists or two objectlists or two generic lists (you cannot add a list of one type to another).
ListCompact
Section titled “ListCompact”ListCompact (any list list)Returns a list, based on the given list, but with any repeated entries removed and any entries that are null removed. The canonical use is when combining two lists that might have some entries in common:
combinedlist = ListCompact (list1 + list2)ListContains
Section titled “ListContains”ListContains (list, any type item)Returns a boolean - true if the list contains the item.
ListCount
Section titled “ListCount”ListCount (list)Returns an int - the number of items in the list.
ListExclude
Section titled “ListExclude”ListExclude (list, any type item or list)Returns a copy of the stringlist or objectlist, with the specified item removed, or with all the items removed if the second parameter is a list.
Note that this is different to the list remove script command, as that removes the item from the original list. ListExclude by contrast returns a copy of the list - the original list is unaffected.
ListItem
Section titled “ListItem”ListItem (list, int index)Returns a string or an object, depending on whether the list is a stringlist or an objectlist. Gets an item from the list by index. The index is zero-based. (The first item is at index 0, the second is at index 1, etc.)
Usually you will know the type of list that you’re passing in, so you should use the StringListItem or ObjectListItem functions instead.
NewList
Section titled “NewList”NewList ()Returns an empty list. The list can contain any type of data, or a mixture - for example, both objects and strings.
If the list will only contain one type of data (as will usually be the case), you should use NewStringList or NewObjectList instead.
NewObjectList
Section titled “NewObjectList”NewObjectList ()Returns an empty objectlist.
NewStringList
Section titled “NewStringList”NewStringList ()Returns an empty stringlist.
ObjectListCompact
Section titled “ObjectListCompact”ObjectListCompact (objectlist list)Returns an objectlist, based on the given list, but with any repeated entries removed and any entries that are null removed. The canonical use is when combining two lists that might have some entries in common:
combinedlist = ObjectListCompact (list1 + list2)ObjectListItem
Section titled “ObjectListItem”ObjectListItem (objectlist, int index)Returns the object from the list by the specified index. The index is zero-based. (The first item is at index 0, the second is at index 1, etc.)
You can use the ListItem function if you don’t know the type of the list.
Example
Section titled “Example”For example, to show a specific object’s name from a list, first create an objectlist called myList, in this example it is a list of objects that can be seen currently ScopeVisibleNotHeld.
myList = ScopeVisibleNotHeld()Now show the name of the second item in the list. Note that the second object is at index 1.
msg ("myList item 2 is " + ObjectListItem(myList, 1).name)This could be used with GetRandomInt to remove an item from the player’s inventory (ScopeInventory) and place it into the current room (for example, if you’re creating a poltergeist or thief).
ObjectListSort
Section titled “ObjectListSort”ObjectListSort (objectlist list, string attributes ...)Returns an objectlist - a copy of the input objectlist, sorted in order of the values of the first specified attribute (and then optionally by any subsequently specified attributes).
For example, to return a list of objects sorted by name:
sortedlist = ObjectListSort(list, "name")To return a list sorted by weight, with equivalent weight objects sorted by name:
sortedlist = ObjectListSort(list, "weight", "name")It is important to have all the objects in the list have the same type of attribute. If you are sorting by weight, and some objects have an integer attribute for weight and some have a double attribute, you will get an error:
Error evaluating expression ‘ObjectListSort(l, “weight”)’: Object must be of type Double.
On the other hand, if an object is missing the attribute, it will appear first in the list, which might not be what you are expecting!
If you are sorting using a string attribute, the list will be sorted alphabetically. Nothing comes first, then spaces, then underscores and punctuation, then numbers, then letters. Letters are sorted by what the letter is first, so “a” will be first, whatever the case or accents on it, but for a specific letter, lower case, then upper, then accented. The order within punctuation itself is the one .NET’s culture-aware comparison produces, and isn’t worth relying on.
So if we have a set of objects with string attributes, they would be sorted in this order:
null, “T”, “T “, “T_”, “T!”, “T.”, “T2”, “Ta”, “TA”, “Tá”, “Tb”
When sorting Booleans, false comes before true.
If you try to sort by object, script, list or dictionary attribute you will get an error:
Error evaluating expression ‘ObjectListSort(l, “weight”)’: At least one object must implement IComparable.
To return the values in reverse order, use ObjectListSortDescending.
ObjectListSortDescending
Section titled “ObjectListSortDescending”ObjectListSortDescending (objectlist list, string attributes ...)Returns the reversed version of ObjectListSort - see that page for usage.
ObjectListToStringList
Section titled “ObjectListToStringList”ObjectListToStringList (objectlist list, string attribute name)Returns a new string list containing the value of the named attribute for each object in the given list. The value must be a string or it will not be added. If an object does not have that attribute or it is not a string, then it will be missing from the list, so the string list that is returned could well be shorter than the object list.
RemoveInvisibleObjects
Section titled “RemoveInvisibleObjects”RemoveInvisibleObjects(objectlist)Returns a list where the player object and any objects flagged not visible are removed from the list objectlist. Unlike RemoveSceneryObjects, scenery objects are kept - used when building the “inventory” list, where scenery should still show as carried.
RemoveSceneryObjects
Section titled “RemoveSceneryObjects”RemoveSceneryObjects(objectlist)Returns a list where all scenery objects are removed from the list objectlist
StringListCompact
Section titled “StringListCompact”StringListCompact (stringlist list)Returns a stringlist, based on the given list, but with any repeated entries removed and any entries that are null removed. The canonical use is when combining two lists that might have some entries in common:
combinedlist = StringListCompact (list1 + list2)StringListItem
Section titled “StringListItem”StringListItem (stringlist, int index)Returns the string from the list by the specified index. The index is zero-based. (The first item is at index 0, the second is at index 1, etc.)
You can use the ListItem function if you don’t know the type of the list.
StringListSort
Section titled “StringListSort”StringListSort (stringlist list)Returns a stringlist - a copy of the input stringlist, sorted alphabetically.
To return the values in reverse order, use StringListSortDescending.
StringListSortDescending
Section titled “StringListSortDescending”StringListSortDescending (stringlist list)Returns a stringlist - a copy of the input stringlist, reverse sorted alphabetically.
To return the values in ascending order, use StringListSort.