Collection Class

Collection Class

Namespace

Microsoft.VisualBasic

Createable

Yes

Syntax

 Dim   objectvariable   As [New] Collection

objectvariable (required; Collection): The name of the Collection object

Description

A Collection object allows you to store members of any data type, including object data types or even other collection objects, and to retrieve them using a unique key.

Collection objects allow us to create a form of associative array, which is an array whose members are indexed by something more meaningful than an integer. The real power of a collection comes by using collections with class objects. The Collection object is discussed in more detail in Chapter 3.

Collection objects are created in exactly the same way as other objects, as in:

 Dim   obj   As New Collection

or:

 Dim obj As Collection   obj   = New Collection

In the former syntax, the Collection object is created at the time that the obj variable is declared, which may be sooner than you actually need the Collection object. The latter syntax gives you more control over the creation process.

Rules at a Glance

You can use a Collection object to store data of any data type, including object types and even other Collection objects.
The Add method of the Collection object is used to add items to the collection (see the Collection.Add entry).
Members of a collection can be accessed using either their ordinal number or their key, assuming that one was assigned at the time that the member was added to the collection (see the Collection.Item entry).
The first member in a collection is stored at ordinal position 1 (not at 0, as with arrays).
The Count method returns the number of members in the collection (see the Collection.Count entry).
The Remove method removes items from a collection (see the Collection.Remove entry).

Example

This example shows how you can nest one collection within another collection. We create 10 instances of colSubCollection , each containing two integer values. These colSubCollection objects are stored in the collection named colMainCollection . The code also shows how to read the values of colMainCollection and colSubCollection :

 Sub testCollection(  )    'declare objects for the main and sub collections    'creating a new instance of the main collection     'in the process    Dim colMainCollection As New Collection    Dim colSubCollection As Collection    Dim i As Integer      For i = 1 To 10       'create a new instance of the sub collection object       colSubCollection = New Collection       'populate the sub collection with two integer values       colSubCollection.Add(Item:=i + 6, _                            Key:="MySixPlusVal")       colSubCollection.Add(Item:=i + 3, _                            Key:="MyThreePlusVal")       'now add the sub collection to the main collection       'using the count converted to a string as the key       colMainCollection.Add(Item:=colSubCollection, _                             Key:=CStr(i))       'destroy the reference the sub collection        colSubCollection = Nothing    Next i    MsgBox(colMainCollection.Count)    For i = 1 To colMainCollection.Count       'use the Item method to obtain a reference to the       'subcollection       colSubCollection = _                            colMainCollection.Item(CStr(i))       'display the values held in the sub collection.       Console.WriteLine("6 + " & i & " = " & _                   colSubCollection.Item("MySixPlusVal"))       Console.WriteLine("3 + " & i & " = " & _                   colSubCollection.Item("MyThreePlusVal"))       'destroy the reference to the sub collection       colSubCollection = Nothing    Next i End Sub

Programming Tips and Gotchas

A highly efficient method of enumerating the members of a collection is to use the For Each...Next loop, as the following example shows:

 Dim colMyCollection As New Collection Dim colSubCollection As Collection      For i = 1 To 10    Set colSubCollection = New Collection    colSubCollection.Add Item:=i + 6, _                         Key:="MySixPlusVal"    colSubCollection.Add Item:=i + 3, _                         Key:="MyThreePlusVal"    colMyCollection.Add Item:=colSubCollection, _                        Key:=CStr(i)    Set colSubCollection = Nothing Next i For Each colSubCollection In colMyCollection    MsgBox colSubCollection.Item("MySixPlusVal") Next

Interestingly, although most Visual Basic data types are merely wrappers for data types in the Base Class Library, the Collection object is a "native" VB data type that's derived from System.Object and implements the ICollection , IEnumerable , and IList interfaces. This can be seen from the following code fragment:

 Dim oColl As New Collection Dim oType As Type, oInt As Type oType = oColl.GetType(  ) Console.WriteLine("Type: " & oType.ToString) Console.WriteLine("Base Type: " & oType.BaseType.ToString) Dim oTypes(  ) As Type = oType.GetInterfaces For Each oInt in oTypes    Console.WriteLine("Interface: " & oInt.ToString) Next