ObjectType:collection

Object Type Vitals

collection
Defined By	LavishScript
Inherits	objectcontainer
Reduces To	NULL
Variable Object Type	collection
Uses Sub-Types	yes
C/C++ Type	LSObjectCollection *

Overview

A collection is a sorted list of objects, each referenced by a unique key. Collection keys are text, and not case sensitive.

Members

• sub-type Element[key]: Retrieves the element, if any, identified by the given key
• sub-type FirstValue: Begins iterating with an internal iterator, and retrieves the first value
• sub-type NextValue: Continues iterating with an internal iterator, retrieving the next value
• sub-type CurrentValue: Retrieves the current value in the iteration (with an internal iterator)
• string FirstKey: Begins iterating with an internal iterator, and retrieves the first key
• string NextKey: Continues iterating with an internal iterator, retrieving the next key
• string CurrentKey: Retrieves the current key in the iteration (with an internal iterator)
• type Type: The data type contained by this collection
• unistring AsJSON: Returns a JSON object representation of this collection, with each element converted by using its AsJSON member. The keys from the collection will be used as keys in the JSON object
• unistring AsJSON[array]: Returns a JSON array representation of this collection, with each element converted by using its AsJSON member.

Methods

• ForEach[code]: For each element in the collection, performs the specified code. The ForEach Top-Level Object is used to access the Key or Value for each iteration
• Set[key,value]: Sets (adding, if necessary) the element identified by the given key with the given value
• Erase[key]: Erases the element, if any, identified by the given key
• EraseByQuery[uint query_id]: Erases any elements in the collection matching the given Query
• EraseByQuery[uint query_id,bool remove_MATCHES]: Erases any elements in the collection that either match or do not match the given Query

Declaring collection Variables

Collection objects require a sub-type -- an object type to be a collection of. Append the sub-type to the word collection, with a colon separating the words. It is possible to have sub-subtypes (such as collection:collection:int for a collection of collections of ints).

Example 1

Declaring a collection of "int"

DeclareVariable MyCollection collection:int

Setting Collection Values

To set a value in a collection, use the Set method, as demonstrated in this example

Example 1

DeclareVariable MyCollection collection:int
MyCollection:Set["jumbo",10]
MyCollection:Set["small",1]

Iterating

Collections have a single built-in iterator for convenience, or you can initialize an iterator object for use with this collection with the GetIterator method. The following information explains how to use the built-in iterator.

There are two possibilities for iteration, and each are tied to the same iterator. This means that you do not have to effectively iterate twice to get each key and value.

Example 1

Iterating Keys

DeclareVariable MyCollection collection:int
.
.
if "${MyCollection.FirstKey(exists)}"
{
  ; We'll echo it inside our loop
  do
  {
    ; Display the current key
    echo ${MyCollection.CurrentKey}
  }
  while "${MyCollection.NextKey(exists)}"
 ; This makes sure we have a next key, and continues looping until we dont
}

Example 2

Iterating Values. This will be strikingly similar to Example 1. It may be helpful to remember that there is always a value to a key. Thus, we could use FirstKey and NextKey in the following example, and echo CurrentValue. This would have absolutely no visible difference.

DeclareVariable MyCollection collection:int
.
.
if "${MyCollection.FirstValue(exists)}"
{
  ; We'll echo it inside our loop
  do
  {
    ; Display the current value
    echo ${MyCollection.CurrentValue}
  }
  while "${MyCollection.ValueKey(exists)}"
 ; This makes sure we have a next value, and continues looping until we dont
}

Example 3

Iterating both Values and Keys. All we need to do is echo both the CurrentKey and CurrentValue!

DeclareVariable MyCollection collection:int
.
.
if "${MyCollection.FirstKey(exists)}"
{
  ; We'll echo it inside our loop
  do
  {
    ; Display the current key and value
    echo "[${MyCollection.CurrentKey}]: ${MyCollection.CurrentValue}"
  }
  while "${MyCollection.NextKey(exists)}"
 ; This makes sure we have a next key, and continues looping until we dont
}

See Also

LavishScript Object Types

Text

string - mutablestring - unistring

Numbers

byte - float - float64 - int - uint - int64

Boolean (TRUE/FALSE)

bool

Pointers

boolptr - byteptr - floatptr - float64ptr - intptr - uintptr - int64ptr - rgbptr - stringptr

Containers

objectcontainer - array - index - collection - queue - stack - set - variablescope

JSON

jsonobject - jsonarray - jsonvaluecontainer - jsonvalue

Iteration

iterator - jsoniterator

Date/Time

time

Events

anonevent - event

Other

point3f - rgb - script - binary - enumtype

File Handling

filepath - file - filelist - filelistentry

Utilities

exists - lavishscript - math - system - type - variable

Tasks

lavishmachine - Accessed via the Top-Level Object LMAC

task - tasklibrary - taskmanager - tasktype - taskpulseargs - elmactaskstate

XML

xmlnode - xmlreader