ObjectType:collection

From Lavish Software Wiki
Jump to navigation Jump to search
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