Class

Collection

Description

Used to store a set of related items in a larger structure. The concept of a Collection is similar to that of an array, except that each element in a Collection can be a different data type. A Collection can be thought of as an array of variants. Also, each element in a Collection can be named. Elements in a Collection can be referred to either by number or name.

Methods

Name	Parameters	Returns
Add	Value As Variant, [Key As String]
Count		Integer
Item	index As Integer	Variant
Key	index As Integer	Variant
Remove	index As Integer

Method descriptions

Collection.Add

Add(Value As Variant, [Key As String])

Adds Value as the last element of the Collection.

If Key is provided, it may be used to refer to the element using the Item property. Key defaults to the empty string.

The following code creates a Collection, populates it with both string and numeric values, and displays each element in TextFields or a Canvas control (The picture "lois" has been added to the project). Note that a Collection is much like a database record.

Var c As New Collection
c.Add(1, "ID")
c.Add("Lois Lane", "Name")
c.Add("Reporter", "JobTitle")
c.Add(85000, "Salary")
c.Add(lois, "Picture")
TextField1.Text = c.Item("ID")
TextField2.Text = c.Item(2) // returns "Lois Lane"
TextField3.Text = c.Item("JobTitle")
TextField4.Text = c.Item("Salary")
Canvas1.Backdrop = c.Item("Picture")

Collection.Count

Count As Integer

The number of elements in the Collection. Returns an integer. Each element is a Value, Key pair.

The following code displays the value of Count in a TextField.

Var c As New Collection
c.Add(1, "ID")
c.Add("Lois Lane", "Name")
c.Add("Reporter", "JobTitle")
c.Add(85000, "Salary")
c.Add(lois, "Picture") // lois is a Picture added to the project
TextField1.Text = c.Item("ID")
TextField2.Text = c.Item(2) // returns "Lois Lane"
TextField3.Text = c.Item("JobTitle")
TextField4.Text = c.Item("Salary")
Canvas1.Backdrop = c.Item("Picture")

TextField5.Text = c.Count.ToString

Collection.Item

Item(index As Integer) As Variant

Refers to an element of a Collection by the value of its Key.

The following code displays the elements in the Collection using Item.

Var c As New Collection
c.Add(1, "ID")
c.Add("Lois Lane", "Name")
c.Add("Reporter", "JobTitle")
c.Add(85000, "Salary")
c.Add(lois, "Picture") // lois is a Picture added to the project
TextField1.Text = c.Item("ID")
TextField2.Text = c.Item(2) // returns "Lois Lane"
TextField3.Text = c.Item("JobTitle")
TextField4.Text = c.Item("Salary")
Canvas1.Backdrop = c.Item("Picture")

Collection.Key

Key(index As Integer) As Variant

Refers to the key for an element of a Collection. index is 1-based.

The following code fetches some elements in the Collection:

Var c As New Collection
c.Add(1, "ID")
c.Add("Lois Lane", "Name")
c.Add("Reporter", "JobTitle")
c.Add(85000, "Salary")
Var name As String = c.Item(2) // returns "Lois Lane"
Var nameKey As String = c.Key(2) // returns "Name"

Collection.Remove

Remove(index As Integer)

Removes the element of a Collection specified by the value of its Key.

This code removes the first element.

Var c As New Collection
.
.
c.Remove(1)

If you want to use the Item or Remove methods to refer to an item, use parentheses around the parameter passed to the method. This is because the compiler doesn't know which data type you are passing. For example, use

c.Remove("Name")

rather than

c.Remove "Name"

Notes

The Dictionary class provides all the functionality of the Collection class and offers several advantages: With the Collection class, the time taken to locate an item is a function of the number of items in the Collection because the search is sequential. A Dictionary uses a hash table, making the time (relatively) independent of the number of items. It is designed for high-speed lookups. Also, the key parameter in a Dictionary is a Variant, but is a String in the Collection class. Therefore, we recommend that you use the Dictionary class rather than the Collection class whenever possible.

Sample code

The following example creates a Collection, populates it with both string and numeric values, and displays each element in TextFields or a Canvas control (The picture "lois" has been added to the project). Note that a Collection is much like a database record.

Var c As New Collection
c.Add(1, "ID")
c.Add("Lois Lane", "Name")
c.Add("Reporter", "JobTitle")
c.Add(85000, "Salary")
c.Add(lois, "Picture") // lois is a Picture added to the project
TextField1.Text = c.Item("ID")
TextField2.Text = c.Item(2) // returns "Lois Lane"
TextField3.Text = c.Item("JobTitle")
TextField4.Text = c.Item("Salary")
Canvas1.Backdrop = c.Item("Picture")