Collection Item Method

Named Arguments

Syntax objectvariable .Item( index) objectvariable Use: Required

Data Type: Collection object

An object variable of type Collection.

index

Use: Required

Data Type: Numeric or String

If a string, index is the key; if numeric, index is the ordinal position. Description

Returns the member of the collection whose key or ordinal position corresponds to index.

Rules at a Glance

• If index is a string, it's taken to be the key, and the member of the collection with the key of index is returned.

• If index is a number, it's taken to be the index number and the member in the ordinal position index is returned.

• If index is a string and the key doesn't exist in the collection, an error (runtime error 5, "Invalid procedure call or argument") is generated.

• If index is numeric, it must be between 1 and the maximum number of items in the collection, or an error (runtime error 9, "Subscript out of range") is generated.

Programming Tips & Gotchas

• When writing wrapper classes for collections, you can make your object model more readable by making the name of the property that wraps the

Collection.Item Method 169

Item method the same as the name of the object being obtained from the collection. For example, if your collection class is called Employees and is a collection of Employee records, your object model reads much better with an Employee Property Get procedure, as follows:

Public Property Get Employee(vEmpCode as Variant) _ As Boolean Employee = mcolEmployees.Item(vEmpCode) End Property

• Note that in the above Property Get procedure, the parameter is passed as a variant. This is because a Collection item can be extracted by its key (a string) or by its ordinal number (integer or long). Therefore, by passing a variant, your Property Get procedure can accept a number or a string, and the Item method determines whether to access the collection by its key or its ordinal number. There is, however, one little glitch here: what happens if you have used the string representation of a number for the key? For example:

mcol.Add Item:="Somestuff" Key:=CStr(iKey)

In this case, passing a string representation of the number as a variant doesn't work; the Item method is passed a number and assumes you want the item at that ordinal position.

• Unlike the Dictionary object in VB6, there is no Exists method in the Collection object, so you can't find out in advance if a particular key exists within the Collection. However, you can create an "Exists" function by calling the Item method with a given key and returning True if an item is returned or False if an error is generated, as the following code shows:

Public Function Exists(vKey As Variant) As Boolean On Error Resume Next msValue = mcolMyCollection.Item(vKey)

If Err.Number = 0 Then Exists = True

Else

Exists = False End If

End Function

• When I create wrapper classes for collections, I always include an Exists function like the one shown above, but with a little extra—if the Item requested by the client doesn't exist, I attempt to load it into the collection, as this code demonstrates:

Public Function Exists(sEmpCode As String) As Boolean

On Error Goto Exists_Err

'declare an object variable to hold the test object Dim oTest as Employee

'attempt to get the Employee object from

170 Chapter 7- The Language Reference

'the Employees collection oTest = mcolEmpoyees.Item(sEmpCode) 'if the code gets here then we know all is well 'clean up and leave Set oTest = Nothing Exists = True Exit Function Exists_Err:

'was the error because the Employee object did not 'exist in the collection? If Err.Number = 5 Then

'attempt to get the Employee object If GetEmployee(sEmpCode) then

'we got the employee record and added it to 'the collection Exists = True Else

'the employee code does not exist so we 'couldn't get the record Exists = False End If Else

Exists = False End If

End Function

With this function in place, I can always ensure that the client-side code operates smoothly:

Dim oEmployees As New Employees Dim oEmployees As Employee

If oEmployees.Exists(sEmpCode) Then

Set oEmployee = oEmployees.Employee(sEmpCode)

Else

MsgBox "This Employee Code could not be found" End if

• The Item method is the default member of the Collection object. This means that, when retrieving a member of a collection, you don't have to actually include an explicit call to the Item method. The following two statements, for example, are identical to one another:

set objMember = objCollection.Item(6) set objMember = objCollection(6)

See Also

Collection Object, Collection.Add Method, Collection.Count Property, Collection.Remove Method

Collection.Item Method 171

Was this article helpful?

0 0

Post a comment