How to: Add, Delete, and Retrieve Items of a Collection

The Visual Basic Collection class contains built-in functionality to allow you to add, delete, and retrieve items.

• You might want to add an item to a collection as soon as the item is newly created or obtained, such as a new customer.

• You might want to delete an item from a collection when it no longer belongs in the collection, for example when an employee leaves your company.

• You might want to retrieve an item from a collection to edit its contents, for example to change a student's telephone number.

To add an item to a collection

• Use the Add Method (Collection Object) and specify the item by its Key.

  object.Add(Item, Key [, {Before | After}])

  For example, to add a work order object to a collection of work orders using the work order's ID property as its key, you can make the following call.

  workOrders.Add(woNew, woNew.ID)
  

  The preceding call assumes that the ID property is a string. If it is a number (for example, a Long integer), use its ToString method to convert it to the String value required for the Key argument.

  workOrders.Add(woNew, woNew.ID.ToString())
  

  The use of a key is optional. If you do not want to associate a key with the object in your collection, you may add it without a key.

  workOrders.Add(woNew)
  

  You can use the optional Before and After arguments to maintain an ordered collection of objects. The item to be added is placed in the collection before or after the item identified by the Before or After argument, respectively. For example, setting Before equal to 1 inserts an item at the beginning of the collection, because Collection objects are 1-based.

  workOrders.Add(woNew, woNew.ID, 1)
  

  Similarly, the After argument adds an item after the specified index. The following example adds an item as the third element.

  workOrders.Add(woNew, woNew.ID,,2)
  

  You can specify a value for either Before or After, but not both.

To delete an item from a collection

• Use the Remove Method (Collection Object) and specify the item by either its Index or its Key.

  object.Remove({Index | Key})

  The Index argument is the position of the item you want to delete. The Key argument is the same string you used to add the item to the collection. If the key of the third element in a collection is "W017493", you can use either of the following two statements to delete it.

  workOrders.Remove(3)
  workOrders.Remove("W017493")
  

To delete all items from a collection

• Use the Clear Method (Collection Object).

  object.Clear()

  The Clear method empties the collection.

To retrieve an item from a collection

1. Use the Item Property (Collection Object) and specify the item by either its Index or its Key.

   variable = object.Item({Index | Key})

   As with the Remove method, the Index argument is the item's position in the collection, and the Key argument is the string used when the item was added. Using the same example as for the Remove method, either of the following statements retrieves the third element in the collection.

   woCurrent = workOrders.Item(3)
   woCurrent = workOrders.Item("W017493")
   

   Note

   If you use numbers as keys, you must use their ToString methods to convert them to strings before passing them to the Add or Remove method, or to the Item property. A Visual Basic Collection object always assumes that a number is an index, rather than a key string.

2. If you know the key at compile time, you can alternatively use the dictionary access operator (!) to access an element of the collection without enclosing the key in quotation marks or parentheses. The preceding call could be written as follows.

   woCurrent = workOrders!W017493
   

See Also

Concepts

Visual Basic Collection Class

Collections as an Alternative to Arrays

Collections in Visual Basic

Reference

Collection Object Members

Add Method (Collection Object)

Remove Method (Collection Object)

Clear Method (Collection Object)

Item Property (Collection Object)