Collections

The built-in Collection class is one form of dynamic data structure provided by Visual Basic. Collections provide a convenient way to group objects of the same class together.  Collection objects allow parts to be accessed individually as needed, or the entire collection can be accessed as a whole.  Collections are similar in concept to arrays in that they are used to store lists of objects, but they are much more powerful and flexible than arrays:  

• A collection allows objects to be added at any position: an array allows objects to be added (easily) only to its end. 
• Collections allow objects to be deleted from the middle of the collection: arrays have no easy way to allow an object to be removed.  
• Collections allow objects to be retrieved using a "key" value; arrays require you to write code to explicitly search the array.

While collections are more powerful and flexible than arrays they are less efficient.  You never have to indicate the number of occurrences a collection might need, however, and you never have to ReDim a collection to add a new value.  Therefore, using collections results in simpler, easier-to-read, and easier-to-maintain code.

A collection does not store the objects managed by the collection.  Rather, it stores a reference to the individual objects, or pointers to the objects.

Note that the objects contained in a collection do not have to belong to the same class.

Creating a Collection

In order to create a collection, a variable must be defined with data type Collection.  Since a collection is an object, the New keyword must be used in the declaration statement.  If the New keyword is omitted, the declaration results in a reference to a collection, but no Collection object is created.  

The following statement defines a form-scope collection that can be used to hold references to Employee objects:

    Dim fEmployees As New Collection( )

Adding Items to a Collection

After a Collection object is created, the collection's Add method can be used to add object references to it.  An event procedure in a form might create a new Employee object and add it to the form's Employee collection using code similar to the following:

    Dim Emp As New CEmployee
    Call fEmployees.Add (Emp)

The Add method also provides for an optional Key argument. The key value can then be used at a later point to directly retrieve the object reference from the collection.  Note that the key value must be unique within the collection, and must be a string that cannot be evaluated as a number.  "Bob" and "B14" are valid collection key values, for example, but "123" is not.

To add an Employee object to a collection using the employee's name as a key value, you can use code similar to the following:  (if the Get property procedures are available)

   Dim Emp As New CEmployee
   Call fEmployees.Add (Emp, Emp.EmpName)

or ...

If standard accessor and mutator methods are used, the code would resemble the following: 

    Call fEmployees.Add(employee1, employee1.getFirstname( ))

============================

Method Add notes:

The complete syntax for the method is 

   object.Add ( item, key, before, after )

The before and after arguments are optional.  They are expressions that specify a relative position in the collection.  The member to be added is placed in the collection before (or after) the member identified by the before (or after) argument. For a numeric expression, the argument must be a number from 1 to the value of the collection's Count property.  For a string expression, the argument must correspond to the key specified when the member being referred to was added to the collection (otherwise you get an ArgumentException exception.)  You can specify a before position or an after position, but not both.

     fEmployees.Add (employee2, employee2.getFirstname( ), "Bob")

     fEmployees.Add (employee2, , "Bob")

     fEmployees.Add (employee2, , 1)

     fEmployees.Add (employee2, , ,"Chris")

See this illustration for more on the mechanics of adding an object to a collection.

Retrieving an Object Reference from a Collection

Object references are retrieved from a collection using the collection's Item method, with either a position index value or a key value.  The first object in the collection uses an Index value of 1.  The following example retrieves the reference to the first employee in the fEmployees collection and assigns it to a local variable:

    Dim Emp as CEmployee  ' declare an Employee object reference
    Emp = fEmployees.Item (1)

Alternatively, you can retrieve an object reference using a key value--no searching is required.  The following example retrieves a reference to the Employee object with a key value of "Bob."

    Dim Emp as CEmployee ' declare an Employee object reference
    Emp = fEmployees.Item ("Bob")

With either approach, if an object reference with the specified index or key value is not found in the collection, an IndexOutOfRangeException exception will result.

Iterating Though a Collection

For...Next loops can be used to iterate through the items in a collection.  The collection object provides a Count property that indicates the number of objects in the collection.  The following code iterates through the collection and calls each Employee object's ToString method:

   Dim Emp as CEmployee   ' declare an Employee object reference
   Dim Indx As Long                 ' declare a variable to use as an index

    For Indx = 1 to fEmployees.Count
        Emp = fEmployees.Item (Indx)
        Console.Out.WriteLine ( Emp.ToString( ) )
    Next Indx

You can also access the collection member directly:

   Dim Indx As Long

   For Indx = 1 To fEmployees.Count( )
       Console.Out.WriteLine ( fEmployees (Indx).ToString( ) )
   Next Indx

There is a better technique for iterating through a collection, one that is both easier to code and more efficient.  The For Each...Next looping structure can be used to process each object in a collection.  The For Each...Next is easier to use because it does not require an index variable to be declared, and the object reference is automatically set to a variable.  The following example demonstrates the use of the For Each...Next:

    Dim Emp as CEmployee  ' declare an Employee object reference

    For Each Emp in fEmployees
        Console.Out.WriteLine ( Emp.ToString ( ) )
    Next Emp

Deleting an Object Reference from a Collection

Objects can be deleted from a collection using the collection's Remove method.  The Remove method will accept either an index position or a key value.  The first example removes the first employee from the collection:

    fEmployees.Remove (1)  ' removes the first item

The following example removes the employee named "Bob" from the collection:

    fEmployees.Remove ("Bob") ' removes employee named Bob

Whenever an object reference is removed from a collection, the collection's Count property is decreased by 1.  Note that if an object reference with the specified index or key value is not found in the collection, an IndexOutOfRangeException exception will result.

Summary