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.

oCollection.Add(item, [key], [before|after])

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.

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)

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.

    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.

Items can be removed either by their indices or key values.

oCollection.Remove(index)

oCollection.Remove(key)

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.

    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