Collection Object
Collections can be used to store items of different types. Each item can be accessed by its index or by an optional key associated with it.
A Collection object has the following methods:
- Add: inserts a new item into the collection. Optionally a string value can be defined as the key to the item.
- Count: returns the number of items in the collection.
- Item: returns the item in the collection by passing its index or key.
- Remove: removes the specified item from the collection by its index or key.
Items in a Collection can be accessed either by their indices (as in a 1-based single-dimensional Array) or by their associated keys.
The ScriptForge Dictionary service extends the Collection object by providing supplemental features as key retrieval and replacement, as well as import/export to Array objects and JSON strings.
Creating a Collection
To create a Collection use the New keyword. The following example creates a Collection object and populates it with three items:
Dim myCollection as New Collection
myCollection.Add("Some text")
myCollection.Add(100)
myCollection.Add(Array(1, 2, 3, 4))
MsgBox myCollection.Count ' 3
Adding Items
The Add method can be used to add new items into the Collection object.
Syntax:
oCollection.Add(item, [key], [before|after])
Parameters:
item: the item to be added to the Collection. May be of any type.
key: string value used as the unique key used to identify this value.
before, after: optional keyword argument that indicates where the new item will be placed in the Collection. Only one of the arguments before or after can be specified to determine the index or key before which (or after which) the new item is to be placed.
Example:
The example below adds two elements into a Collection. The first has a key associated with it, whereas the second does not.
Dim myCollection as New Collection
myCollection.Add(100, "first")
myCollection.Add(101)
The Add method also supports keyword arguments:
myCollection.Add(item := 100, key := "first")
Keys must be unique in a Collection object. Comparison between keys is case-insensitive. Adding duplicated keys will result in a runtime error.
The example below illustrates how to use the Before and After keyword arguments to determine the position of the item that is being added.
Dim myCollection as Variant
myCollection = New Collection
myCollection.Add(item := 101, key := "first")
myCollection.Add(item := 103, key := "third")
myCollection.Add(item := 105, key := "fifth")
MsgBox myCollection.Item(2) ' 103
myCollection.Add(item := 102, key := "second", before := "third")
MsgBox myCollection.Item(2) ' 102
myCollection.Add(item := 104, key := "fourth", after := 3)
MsgBox myCollection.Item(4) ' 104
Items in a Collection object are assigned an integer index value that starts at 1 and corresponds to the order in which they were added.
Accessing Items
Use the Item method to access a given item by its index or key.
oCollection.Item(index)
oCollection.Item(key)
Parameters:
index: an integer value specifying the index of the item to be returned.
key: a string value specifying the key of the item to be returned.
Example:
Dim myCollection as New Collection
myCollection.Add(item := 101, key := "A")
myCollection.Add(item := 102, key := "B")
myCollection.Add(item := 103, key := "C")
MsgBox myCollection.Item("A") ' 101
MsgBox myCollection.Item(3) ' 103
Removing Items
Use the Remove method to delete items from a Collection object.
Syntax:
Items can be removed either by their indices or key values.
oCollection.Remove(index)
oCollection.Remove(key)
Parameters:
index: an integer value specifying the index of the item to be removed.
key: a string value specifying the key of the item to be removed.
Example:
Dim myCollection as New Collection
myCollection.Add(item := 101, key := "first")
myCollection.Add(item := 102, key := "second")
myCollection.Add(item := 103, key := "third")
MsgBox myCollection.Count ' 3
' Removes the first value
myCollection.Remove(1)
' Removes the value whose key is "third"
myCollection.Remove("third")
MsgBox myCollection.Count ' 1
Iterating Over all Items
It is possible to use a For Each ... Next statement to iterate over all items in a Collection.
Dim myCollection as New Collection
myCollection.Add(item := 101, key := "A")
myCollection.Add(item := 102, key := "B")
myCollection.Add(item := 103, key := "C")
For Each value In myCollection
MsgBox value
Next value
Clearing a Collection
To remove all items from a Collection object call the Remove method for each item, as illustrated in the example below:
' Create a sample Collection with two entries
Dim myCollection as New Collection
myCollection.Add(item := 10, key := "A")
myCollection.Add(item := 11, key := "B")
MsgBox myCollection.Count ' 2
' Removes all items in the collection
For i = myCollection.Count To 1 Step -1
myCollection.Remove(i)
Next i
MsgBox myCollection.Count ' 0