Difference between revisions of "ObjectType:collection"

From Lavish Software Wiki
Jump to navigation Jump to search
 
(8 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
{{ObjectType-Vitals|collection|[[LavishScript]]|[[ObjectType:objectcontainer|objectcontainer]]|NULL|collection|yes|LSObjectCollection *}}
 
== Overview ==
 
== Overview ==
{{ObjectType-Vitals|collection|[[LavishScript]]|none|NULL|collection|yes|LSCollection *}}
 
  
 
A '''collection''' is a sorted list of objects, each referenced by a unique key.  Collection keys are text, and not case sensitive.
 
A '''collection''' is a sorted list of objects, each referenced by a unique key.  Collection keys are text, and not case sensitive.
 +
  
 
== Members ==
 
== Members ==
*[[DataType:int|int]] '''Elements''': Number of elements in the collection
 
 
*sub-type '''Element['''key''']''': Retrieves the element, if any, identified by the given key
 
*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 '''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 '''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)
 
*sub-type '''CurrentValue''': Retrieves the current value in the iteration (with an internal iterator)
*[[DataType:string|string]] '''FirstKey''': Begins iterating with an internal iterator, and retrieves the first key
+
*[[ObjectType:string|string]] '''FirstKey''': Begins iterating with an internal iterator, and retrieves the first key
*[[DataType:string|string]] '''NextKey''': Continues iterating with an internal iterator, retrieving the next key
+
*[[ObjectType:string|string]] '''NextKey''': Continues iterating with an internal iterator, retrieving the next key
*[[DataType:string|string]] '''CurrentKey''': Retrieves the current key in the iteration (with an internal iterator)
+
*[[ObjectType:string|string]] '''CurrentKey''': Retrieves the current key in the iteration (with an internal iterator)
*[[DataType:type|type]] '''Type''': The data type contained by this collection
+
*[[ObjectType:type|type]] '''Type''': The data type contained by this collection
 +
*[[ObjectType:unistring|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
 +
*[[ObjectType:unistring|unistring]] '''AsJSON[array]''': Returns a JSON array representation of this collection, with each element converted by using its AsJSON member.
 +
 
  
 
== Methods ==
 
== Methods ==
 +
* '''ForEach['''code''']''': For each element in the collection, performs the specified code. The [[TLO:ForEach|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
 
*'''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
 
*'''Erase['''key''']''': Erases the element, if any, identified by the given key
*'''Reset''': Resets (clears) the collection
+
*'''EraseByQuery['''uint query_id''']''': Erases any elements in the collection matching the given [[LavishScript:Object_Queries|Query]]
*'''GetIterator['''[[ObjectType:iterator|iterator]] object''']''': Initializes the given [[ObjectType:iterator|iterator]] object for iteration of this collection
+
*'''EraseByQuery['''uint query_id''','''bool remove_MATCHES''']''': Erases any elements in the collection that either match or do not match the given [[LavishScript:Object_Queries|Query]]
*'''Initialize['''key''']''': Creates an element with the given key, with the object type's default value (or no value)
 
  
 
== Declaring collection Variables ==
 
== Declaring collection Variables ==
Line 28: Line 31:
 
Declaring a collection of "int"
 
Declaring a collection of "int"
 
  DeclareVariable MyCollection collection:int
 
  DeclareVariable MyCollection collection:int
 +
  
 
== Setting Collection Values ==
 
== Setting Collection Values ==
Line 35: Line 39:
 
  MyCollection:Set["jumbo",10]
 
  MyCollection:Set["jumbo",10]
 
  MyCollection:Set["small",1]
 
  MyCollection:Set["small",1]
 +
  
 
== Iterating ==
 
== Iterating ==
Line 43: Line 48:
 
=== Example 1 ===
 
=== Example 1 ===
 
Iterating Keys
 
Iterating Keys
  DeclareVariable MyCollection collection int
+
  DeclareVariable MyCollection collection:int
 
  .
 
  .
 
  .
 
  .
Line 59: Line 64:
 
=== Example 2 ===
 
=== 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.
 
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
+
  DeclareVariable MyCollection collection:int
 
  .
 
  .
 
  .
 
  .
Line 75: Line 80:
 
=== Example 3 ===
 
=== Example 3 ===
 
Iterating both Values and Keys.  All we need to do is echo both the CurrentKey and CurrentValue!
 
Iterating both Values and Keys.  All we need to do is echo both the CurrentKey and CurrentValue!
  DeclareVariable MyCollection collection int
+
  DeclareVariable MyCollection collection:int
 
  .
 
  .
 
  .
 
  .
Line 89: Line 94:
 
   ; This makes sure we have a next key, and continues looping until we dont
 
   ; This makes sure we have a next key, and continues looping until we dont
 
  }
 
  }
 +
  
 
== See Also ==
 
== See Also ==
* [[LavishScript]]
+
{{LavishScript:ObjectType}}
 
 
[[Category:LavishScript]]
 

Latest revision as of 14:44, 14 October 2019

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