Class: Collection

Collections.VoltScriptCollections.Collection

```
Base class for Collections
```

Class Summary

Project ID FD17E29641C6117580258994003AF3B0
Version 3
Class ID F394C037755FD326802589950053668D
Class Type Base
Attributes

Project ID	FD17E29641C6117580258994003AF3B0
Version	3
Class ID	F394C037755FD326802589950053668D
Class Type	Base
Attributes

Property Summaries

`comparator (Get) As Comparator`
`contentType (Get) As String`
`elementCount (Get) As Long`
`hasContent (Get) As Boolean`
`isLocked (Get) As Boolean`
`isReversed (Get) As Boolean`
`isSorted (Get) As Boolean`
`isUnique (Get) As Boolean`
`suppressErrors (Get) As Boolean`
`suppressErrors (Set) As Boolean`

Method Summaries

`add(source As Variant) As Long`
`addAll(source As Variant) As Collection`
`clone() As Collection`
`contains(checkValue As Variant) As Boolean`
`filter(filterObj As CollectionFilter) As Collection`
`getAndRemoveFirstRaw() As Variant`
`getAndRemoveLastRaw() As Variant`
`getIndex(checkValue As Variant) As Variant`
`getNthElementRaw(index As Long) As Variant`
`insertAt(source As Variant, index As Long) As Boolean`
`join(delim As String) As String`
`remove(source As Variant, allMatches As Boolean) As Long`
`replace(oldValue As Variant, newValue As Variant, allMatches As Boolean) As Long`
`toJson() As JsonObject`
`clear()`
`fromJson(jsonObj As JsonObject)`
`lock()`
`New(contentType As String, comparator As Comparator, mustBeUnique As Boolean, isSorted As Boolean)`
`reverse()`
`transform(transformer As CollectionTransformer, newColl As Collection)`
`unlock()`

Properties Detail

comparator (Get)
Public Property Get comparator As Comparator
Comparator to compare values with

Public Property Get comparator As Comparator
Comparator to compare values with

contentType (Get)

Public Property Get contentType As String
TypeName(s) of elements within the Collection

Code Sample
Dim coll as New Collection("SCALAR",Nothing,False,False) Print coll.contentType 'Prints "SCALAR"

elementCount (Get)

Public Property Get elementCount As Long
Number of elements within the Collection

Code Sample
Dim coll as New Collection("STRING", Nothing, False, False) Print coll.elementCount 'Prints 0

hasContent (Get)

Public Property Get hasContent As Boolean
Flag indicating if the Collection has elemens

Code Sample
Dim coll as New Collection("STRING", Nothig, False, False) Print coll.hasContent 'Prints False Call coll.add("Hello") Print coll.hasContent 'Prints True

isLocked (Get)

Public Property Get isLocked As Boolean
Flag indicating if the Collection is locked, so adds, removes and replaces are aborted

Code Sample
Dim coll as New Collection("STRING", Nothing, False, False) Call coll.lock() Print coll.isLocked 'Prints True

isReversed (Get)

Public Property Get isReversed As Boolean
Flagindicating whether the Collection has been reversed

Code Sample
Dim coll as New Collection("STRING", Nothing, False, False) Print coll.isReversed ' Prints False Call coll.reverse() Print coll.isReversed ' Prints True Call coll.reverse() Print coll.isReversed ' Prints False

isSorted (Get)

Public Property Get isSorted As Boolean
Flag indicating if the Collection is sorted (using Comparator object internally)

Code Sample
Dim coll as New Collection("STRING", Nothing, False, False) Print coll.isSorted 'Prints false

isUnique (Get)

Public Property Get isUnique As Boolean
Flag indicating if the elements in the Collection must be unique

Code Sample
Dim coll as New Collection("STRING", Nothing, False, False) Print coll.isUnique ' Prints False

suppressErrors (Get)

Public Property Get suppressErrors As Boolean
Suppress errors on adding elements. Errors wll still be thrown if the Collection is locked or attempting to insert an entry into a sorted Collection. Instead of throwing an error, e.g. for wrong content type, the method will just return false

Code Sample
%REM The following code will print "Error adding" for the first Try/Catch. But for the second, the error will be suppressed and the call to .add() will return False %END REM Dim coll as New Collection("STRING", Nothing, False, False) Dim success as Boolean Try success = coll.add(2) Print success ' Code will not get to this line Catch Print "Error adding" ' This will be printed End Try coll.suppressErrors = True Try success = coll.add(2) Print success ' Code will print False Catch Print "Error adding" ' This will NOT be printed End Try

suppressErrors (Set)

Public Property Set suppressErrors As Boolean
Suppress errors on adding elements. Errors wll still be thrown if the Collection is locked or attempting to insert an entry into a sorted Collection. Instead of throwing an error, e.g. for wrong content type, the method will just return false

Code Sample
%REM The following code will print "Error adding" for the first Try/Catch. But for the second, the error will be suppressed and the call to .add() will return False %END REM Dim coll as New Collection("STRING", Nothing, False, False) Dim success as Boolean Try success = coll.add(2) Print success ' Code will not get to this line Catch Print "Error adding" ' This will be printed End Try coll.suppressErrors = True Try success = coll.add(2) Print success ' Code will print False Catch Print "Error adding" ' This will NOT be printed End Try

Methods Detail

add

Public Function add(source As Variant) As Long
Adds an element to the container
idx	Argument	Data Type	Attributes	Comments
1	source	Variant		Must match Collection's ContentType

Code Sample
%REM The following code will print "Error adding" for the first Try/Catch. But for the second, the error will be suppressed and the call to .add() will return False %END REM Dim coll as New Collection("STRING", Nothing, False, False) Dim success as Boolean Try success = coll.add(2) Print success ' Code will not get to this line Catch Print "Error adding" ' This will be printed End Try success = coll.add("2") Print success ' Code will print False

Throws Exceptions
Message	Error Code	Comments
This collection can only accept ContentType, passed value is passedType	1400	if source is different to ContentType
Collection is locked	1403

addAll

Public Function addAll(source As Variant) As Collection
Adds all elements from an array or source Collection to the current Collection.
idx	Argument	Data Type	Attributes	Comments
1	source	Variant		Variant array or Collection of elements matching the Collection's ContentType

Code Sample
%REM The following code creates a collection of scalars containing "One" and 2. It sets suppressErrors on the second collection, then adds the first collection to the second. This adds any strings to the second collection (i.e. "One"), while suppressing errors from any non-String entries (i.e. 2). The second collection contains one element, the string "One". %END REM Dim coll as New Collection("SCALAR", Nothing, False, False) Dim coll2 as New Collection("STRING", Nothing, False, False) Call coll.add("One") Call coll.add(2) coll2.suppressErrors = True Call coll2.addAll(coll)

Throws Exceptions
Message	Error Code	Comments
This collection can only accept ContentType, passed value is passedType	1400	if source is different to ContentType
Collection is locked	1403

clone

Public Function clone() As Collection
Creates a copy of the Collection

Code Sample
Dim coll as New Collection("STRING", Nothing, False, False) Dim coll1 as Collection Call coll.add("One") Set coll1 = coll.clone()

contains

Public Function contains(checkValue As Variant) As Boolean
Checks whether the Collection contains a specific value. Requires a valid Comparator to compare each element.
idx	Argument	Data Type	Attributes	Comments
1	checkValue	Variant		Value to check for

Code Sample
%REM Although no explicit comparator is passed into this Collection, an instance of the default Comparator class is used. This works for scalars, by comparing the datatype (treating all numerics as the same datatype) and then CStr-ing the value. %END REM Dim coll as New Collection("SCALAR", Nothing, False, False) Call coll.add("One") Call coll.add(2) Print coll.contains(1) ' Prints False Print coll.contains(2) ' Prints True

filter

Public Function filter(filterObj As CollectionFilter) As Collection
Filters a collection using a CollectionFilter and returns a new "filtered" collection
idx	Argument	Data Type	Attributes	Comments
1	filterObj	CollectionFilter		Collection filter to check each value with

Code Sample
%REM The following code shows how to create a filter for even numbers and use it. The code is very basic with no error handling. %END REM Class EvenFilterer as CollectionFilter Function filter(source as Variant) as Boolean If (source Mod 2 = 0) Then Return True End Function End Class Dim coll1 as New Collection("INTEGER", Nothing, False, False) Dim coll2 as Collection Dim filterer as New EvenFilterer() ' Populating collection omitted Set coll2 = coll1.filter(filterer)

getAndRemoveFirstRaw

Public Function getAndRemoveFirstRaw() As Variant
Returns the FIRST element in the collection and removes it from the collection. If the collection is empty it just exits the function

Code Sample
%REM The following code builds a FIFO queue, printing the entries from the collection %END REM Dim coll as New Collection("STRING", Nothing, False, False) Call coll.add("One") Call coll.add("Two") Print CStr(coll.getAndRemoveFirstRaw()) 'Prints One Print CStr(coll.getAndRemoveFirstRaw()) 'Prints Two Print coll.hasContent 'Prints False

Throws Exceptions
Message	Error Code	Comments
Collection is locked	1403

getAndRemoveLastRaw

Public Function getAndRemoveLastRaw() As Variant
Returns the LAST element in the collection and removes it from the collection. If the collection is empty it just exits the function

Code Sample
%REM The following code builds a LIFO stack, printing the entries from the collection %END REM Dim coll as New Collection("STRING", Nothing, False, False) Call coll.add("One") Call coll.add("Two") Print CStr(coll.getAndRemoveLastRaw()) 'Prints Two Print CStr(coll.getAndRemoveLastRaw()) 'Prints One Print coll.hasContent 'Prints False

Throws Exceptions
Message	Error Code	Comments
Collection is locked	1403

getIndex

Public Function getIndex(checkValue As Variant) As Variant
Checks whether the Collection contains a specific value.
idx	Argument	Data Type	Attributes	Comments
1	checkValue	Variant		Value to check for

Code Sample
%REM The following code creates a Collection of strings. This will print "Contains One" and "Does not contain Two". %END REM Dim coll as New Collection("STRING", Nothing, False, False) Call coll.add("One") If (Not IsNull(coll.getIndex("One")) Then Print "Contains One" If (IsNull(coll.getIndex("Two")) Then Print "Does not contain Two"

getNthElementRaw

Public Function getNthElementRaw(index As Long) As Variant
Gets the nth elment as a raew variant, starting at index 0
idx	Argument	Data Type	Attributes	Comments
1	index	Long		Index of the element to return

Code Sample
%REM The following code gets the element at index 1. It then checks an entry at index 2, which returns that it is empty %END REM Dim coll as New Collection("STRING", Nothing, False, False) Call coll.add("One") Call coll.add("Two") Print CStr(coll.getNthElementRaw(1)) ' Prints "Two" Print IsEmpty(coll.getNthElementRaw(5)) ' Prints True

insertAt

Public Function insertAt(source As Variant, index As Long) As Boolean
Inserts an element in the collection at an index, starting at index 0. Not allowed for sorted collections
idx	Argument	Data Type	Attributes	Comments
1	source	Variant		Must match Collection's ContentType
2	index	Long		Index at which to insert the element

Code Sample
%REM The following code is abbreviated code from Collection.getIndex. It compares each element against the value being checked, and if it matches, returns the current index. %END REM Dim coll as New Collection("STRING", Nothing, False, False) Dim testSuite as New TestSuite("Validate collections") Call coll.add("One") Call coll.add("Two") Call coll.insertAt("Three", 1) Call testSuite.describe("Check 3 elements").assertEqualsLong(3, coll.elementCount) Call testSuite.describe("Check second element is Three").assertEqualsString("Three", CStr(coll.getNthElementRaw(1), True) Call testSuite.describe("Check third element is Two").assertEqualsString("Two", CStr(coll.getNthElementRaw(2), True) Dim coll1 as New Collection("STRING", Nothing, False, True) ' Sorted Call coll1.addAll(coll) Call testSuite.describe("Test adding to sorted collection") Try Call coll.insertAt("Three", 1) Call testSuite.addResult(False, "Successfully inserted into sorted collection, this should have errored") Catch Call testSuite.addResult(True, "") End Try

Throws Exceptions
Message	Error Code	Comments
insertAt not allowed for sorted collections	1403
Collection is locked	1403
Collection is smaller than required position to insert at	1501

join

Public Function join(delim As String) As String
Joins a collection of scalar values into a single string response separated by a passed delimiter
idx	Argument	Data Type	Attributes	Comments
1	delim	String		Delimiter to separate values

Code Sample
Dim coll as New Collection(INTEGER, Nothing, False, False) Call coll.add(1) Call coll.add(2) Print coll.join(",") ' Prints "1,2" Set coll = new Collection(PERSON, Nothing, False, False) ' Assumes a Person class available Dim p1 as New Person Dim p2 as New Person Call coll.add(p1) Call coll.add(p2) Print coll.join(",") ' Prints "NOT STRINGABLE,NOT STRINGABLE"

remove

Public Function remove(source As Variant, allMatches As Boolean) As Long
Removes an element (or elements, if not unique) from the Collection. Returns the number of elements removed.
idx	Argument	Data Type	Attributes	Comments
1	source	Variant		Element to remove
2	allMatches	Boolean		Whether to remove all elements that match source or just the first match

Code Sample
Dim coll as New Collection("INTEGER", Nothing, False, False) Call coll.add(1) Call coll.add(2) Call coll.add(2) Call coll.add(6) Call coll.add(2) Print coll.remove(2, False) 'Prints 1 Print coll.remove(2, True) ' Prints 2

Throws Exceptions
Message	Error Code	Comments
Collection is locked	1403

replace

Public Function replace(oldValue As Variant, newValue As Variant, allMatches As Boolean) As Long
Replaces an element with another and returns the number of replacements made. If the Collection is unsorted, replacements are made at the same positions. If the Collection is sorted, the old elements are removed and new ones inserted at the appropriate sorted location.
idx	Argument	Data Type	Attributes	Comments
1	oldValue	Variant		Value to replace
2	newValue	Variant		Value to insert
3	allMatches	Boolean		Whether to replace the first match or all matches

Code Sample
Dim coll as New Collection("INTEGER", Nothing, False, False) Call coll.add(1) Call coll.add(2) Call coll.add(6) Call coll.add(1) Call coll.replace(1, 3, True) Print coll.join(",") 'Prints 3,2,6,3 Dim coll1 as New Collection("INTEGER", Nothing, False, True) Call coll1.add(1) Call coll1.add(2) Call coll1.add(6) Call coll1.add(1) Call coll1.replace(1, 3, True) Print coll1.join(",") 'Prints 2,3,3,6

Throws Exceptions
Message	Error Code	Comments
Collection is locked	1403

toJson

Public Function toJson() As JsonObject
Converts the Collection to a JsonObject that's an array. If the array values are objects, the code will try to call a toJson method on the object, otherwise skip them.

Code Sample
Dim coll as New Collection("STRING", Nothing, False, False) Dim jsonObj as JsonObject Call coll.add("One") Call coll.add("Two") Set jsonObj = coll.toJson() Print jsonObj.toString(False) 'Prints ["One","Two"]

clear

Public Sub clear()
Removes all values from the Collection and resets whether the collection is reversed.

Code Sample
Dim coll as New Collection("STRING", Nothing, False, False) Call coll.add("One") Print coll.elementCount ' Prints 1 Call coll.clear() Print coll.elementCount ' Prints 0

Throws Exceptions
Message	Error Code	Comments
Collection is locked	1403

fromJson

Public Sub fromJson(jsonObj As JsonObject)
Loads the scalar values array from the JsonObject into the Collection. Can only be used for a JsonObject that contains a single array of scalars.
idx	Argument	Data Type	Attributes	Comments
1	jsonObj	JsonObject		JsonObject containig an array of scalars

Code Sample
Dim jsonObj as New JsonObject Call jsonObj.appendToJsonArray(1) Call jsonObj.appendToJsonArray(2) Call jsonObj.appendToJsonArray(3) Dim coll as New Collection("INTEGER", Nothing, True, True) Call coll.fromJson(jsonObj)

Throws Exceptions
Message	Error Code	Comments
A collection can only accept an array	1400

lock

Public Sub lock()
Locks the collection, so any add, remove, replace or reverse functions trigger errors. Useful when passing a collection to other functions.

Code Sample
Dim coll as New Collection("STRING", Nothing, False, False) Call coll.add("One") Call coll.lock() Call coll.add("Two") ' Throws error

New

Public Sub New(contentType As String, comparator As Comparator, mustBeUnique As Boolean, isSorted As Boolean)
Constructor
idx	Argument	Data Type	Attributes	Comments
1	contentType	String		Defines the Content Type of the Collection
2	comparator	Comparator		Comparator instance to use when checking for unique and sorting elements. If Nothing is passed, a default Comparator will be used which works for scalars, grouping numbers and comparing on data type and value
3	mustBeUnique	Boolean		Flag indicating if elements within the Collection must be unique
4	isSorted	Boolean		Flag indicating if the content within the Collection shall be sorted

reverse

Public Sub reverse()
Reverses a collection

Code Sample
Dim coll as New Collection("STRING", Nothing, False, False) Call coll.add("A") Call coll.add("B") Call coll.reverse() Call coll.add("C") Print coll.join(",") ' Prints B,A,C Set coll = new Collection("STRING", Nothing, False, True) Call coll.add("A") Call coll.add("B") Call coll.reverse() Call coll.add("C") Print coll.join(",") Prints C,B,A

transform

Public Sub transform(transformer As CollectionTransformer, newColl As Collection)
Transforms members of this Collection using a CollectionTransformer and adds them to the new Collection passed
idx	Argument	Data Type	Attributes	Comments
1	transformer	CollectionTransformer		CollectionTransformer to transform members
2	newColl	Collection		Collection to load transformed members into

Code Sample
%REM The following code shows how to create a transformer to square values. The code is very basic with no error handling. %END REM Class SquareTransformer as CollectionTransformer Function transform(source as Variant) as Variant transform = source * source End Function End Class Dim coll1 as New Collection("INTEGER", Nothing, False, False) Dim coll2 as New Collection("INTEGER", Nothing, False, False) Dim transformer as New SquareTransformer() Call coll1.add(2) Call coll1.add(3) Call coll1.add(4) Call coll1.transform(transformer, coll2) Print coll2.join(",") ' Prints 4,9,16

unlock

Public Sub unlock()
Unlocks the Collection, so add, remove, replace or reverse functions can be used again

Code Sample
Dim coll as New Collection("STRING", Nothing, False, False) Call coll.lock() Try Call coll.add("One") Catch ' Code will enter this catch block End Try Call coll.unlock() Call coll.add("One") ' This will be successful

Public Class Collection

Collections.VoltScriptCollections.Collection

Class Summary

Property Summaries

Method Summaries

Properties Detail

comparator (Get)

contentType (Get)

elementCount (Get)

hasContent (Get)

isLocked (Get)

isReversed (Get)

isSorted (Get)

isUnique (Get)

suppressErrors (Get)

suppressErrors (Set)

Methods Detail

add

addAll

clone

contains

filter

getAndRemoveFirstRaw

getAndRemoveLastRaw

getIndex

getNthElementRaw

insertAt

join

remove

replace

toJson

clear

fromJson

lock

New

reverse

transform

unlock