Item Property (Collection Object)

  • Article

Returns a specific element of a Collection object either by position or by key. Read-only.

Default Public ReadOnly Property Item( _
    ByVal { Key As String | Index As Integer | Index As Object } _
) As Object

Parameters

  • Key
    A unique String expression that specifies a key string that can be used, instead of a positional index, to access an element of the collection. Key must correspond to the Key argument specified when the element was added to the collection.

  • Index
    (A) A numeric expression that specifies the position of an element of the collection. Index must be a number from 1 through the value of the collection's Count Property (Collection Object). Or (B) An Object expression that specifies the position or key string of an element of the collection.

Exceptions

Exception type

Error number

Condition

ArgumentException

5

  • Key is invalid or does not match an existing element of the collection.

  • Index cannot be interpreted as character or numeric data.

IndexOutOfRangeException

9

  • Key is Nothing.

  • Index does not match an existing element of the collection.

See the "Error number" column if you are upgrading Visual Basic 6.0 applications that use unstructured error handling. (You can compare the error number against the Number Property (Err Object).) However, when possible, you should consider replacing such error control with Structured Exception Handling Overview for Visual Basic.

Remarks

If Index is of type Object, the Item property attempts to treat it as a String, Char, Char array, or integer value. If Item cannot convert Index to String or Integer, it throws an ArgumentException exception.

The Item property is the default property for a collection. Therefore, the following lines of code are equivalent.

MsgBox(CStr(customers.Item(1)))
MsgBox(CStr(customers(1)))

Example

The following example uses the Item property to retrieve a reference to an object in a collection. It creates birthdays as a Collection object and then retrieves the object representing Bill's birthday, using the key "Bill" as the Index argument.

Dim birthdays As New Collection()
birthdays.Add(New DateTime(2001, 1, 12), "Bill")
birthdays.Add(New DateTime(2001, 1, 13), "Joe")
birthdays.Add(New DateTime(2001, 1, 14), "Mike")
birthdays.Add(New DateTime(2001, 1, 15), "Pete")


...


Dim aBirthday As DateTime
aBirthday = birthdays.Item("Bill")
MsgBox(CStr(aBirthday))
aBirthday = birthdays("Bill")
MsgBox(CStr(aBirthday))

Note that the first call explicitly specifies the Item property, but the second does not. Both calls work because the Item property is the default property for a Collection object.

Requirements

Namespace: Microsoft.VisualBasic

Module: Collection

Assembly: Visual Basic Runtime Library (in Microsoft.VisualBasic.dll)

See Also

Reference

Collection Object (Visual Basic)

Add Method (Collection Object)

Count Property (Collection Object)

Remove Method (Collection Object)