Collections by George Hernandez

Intro
Steps to Implement a Collection Class
Miscellany

Intro

A collection is an object that represents a set of variants. Each variant in the collection is traditionally of the same data type or class but this in not necessarily true.

A collection is similar to an array in concept (both are sets of scalar values or objects) but is basically different:

A collection has a property and several methods to it.
A collection does not have to be sized with the Redim keyword as the collection size changes.
You cannot have a multi-dimensional collection.

Collections can refer to their members by a Key (aka identifier. A string.), or by an Index (aka position. A long integer that can be from 1 to the Count property value.). The following examples all refer to a member of the collection:

col1.Item("strKey")
col1("strKey")
col1.Item(lngIndex)
col1(lngIndex)

A recordset is conceptually a collection and also has this additional syntax for accessing its member (i.e. fields):

recordset!field

A collection object has one property and just a few methods (Note that some objects may have collections with other properties and methods.).

Properties
- .Count. A long integer for the number of objects in the collection. Read only.
Methods
- .Add(NewMember, [NewKey [, [Before | After]]). Add a new member to the collection. The Before and After parameters adds the new member before or after an existing member. EG: myCol.Add(myObj, myObj.ID, before:=1).
- .Item(KeyOrIndex). The default method.
- .Remove(KeyOrIndex).
- .Refresh(). This method is only available with certain objects such as ADO collection objects of Fields, Parameters, and Properties.

For an example of how you might implement a collection in your own class, see Property Procedures.

Steps to Implement a Collection Class

The following list summarizes the steps required to create a collection class.

Add a class module to your project, and give it a name -- usually the plural of the name of the object the collection class will contain. EG: Employees.
Add a private variable to contain a reference to the Collection object your properties and methods will delegate to. EG: Private mEmployees As New Employees.
In the Class_Initialize event procedure, create the Collection object. (If you want to defer creation of this object until it's needed, you can declare the private variable in step 2 As New Collection. This adds a small amount of overhead each time the Collection is accessed.)
Add a Count property and Add, Item, and Remove methods to your class module; in each case, delegate to the private Collection by calling its corresponding member. EG:
```
Public Sub Delete(ByVal Index As Variant)
   mcolEmployees.Remove Index
End Sub
```
When you implement the Add() method, you can override the behavior of the Collection object's undiscriminating Add method by accepting only objects of one type. You can even make it impossible to add externally created objects to your collection, so that your Add method completely controls the creation and initialization of objects.
Use the Procedure Attributes dialog box to make the Item method the default for your collection class.
Add a NewEnum method, as shown below. Use the Procedure Attributes dialog box to mark it as hidden, and to give it a Procedure ID of -4 so that it will work with For Each Next. The following assumes that the private variable in step 2 is named mcol.
```
Public Function NewEnum() As IUnknown
   Set NewEnum = mcol.[_NewEnum]
End Function
```
Add custom properties, methods, and events to the collection class.

Miscellany

Some objects automatically come with collections.
VB comes with two special collections, Forms and Controls, that keep track of loaded forms and controls in your application.
You can make your own collections with this syntax:
```
Dim col1 As New Collection
```
VB collections are 1-based by default. Beware of mixed environments where some collections are zero-based.
You can perform iterations on collections with either the For...Next or For Each...Next statements.

Page Modified: (Hand noted: 2007-09-20 21:17:24Z) (Auto noted: 2007-11-17 06:36:54Z)