Add Method (Collection Object)

Adds an element to a Collection object.

Public Sub Add( _
   ByVal Item As Object, _
   Optional ByVal Key As String, _
   Optional ByVal { Before | After } As Object = Nothing _
)

Parameters

• Item
  Required. An object of any type that specifies the element to add to the collection.

• Key
  Optional. A unique String expression that specifies a key string that can be used instead of a positional index to access this new element in the collection.

• Before
  Optional. An expression that specifies a relative position in the collection. The element to be added is placed in the collection before the element identified by the Before argument. If Before is a numeric expression, it must be a number from 1 through the value of the collection's Count Property (Collection Object). If Before is a String expression, it must correspond to the key string specified when the element being referred to was added to the collection. You cannot specify both Before and After.

• After
  Optional. An expression that specifies a relative position in the collection. The element to be added is placed in the collection after the element identified by the After argument. If After is a numeric expression, it must be a number from 1 through the value of the collection's Count property. If After is a String expression, it must correspond to the key string specified when the element referred to was added to the collection. You cannot specify both Before and After.

Exceptions/Error Codes

Exception type	Error number	Condition
ArgumentException	5	Both Before and After are specified. The Before or After argument does not refer to an existing element of the collection. The specified Key already exists.

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

The Before or After argument must refer to an existing element of the collection; otherwise, an error occurs.

An error also happens if a specified Key value matches the key for an existing element of the collection.

Example

The following example uses the Add method to add child objects — instances of a class called child containing a Public property name — to a collection called family. To see how this works, create a Form with two Button controls and set their Text properties to Add and List. Add the child class definition and the family declaration to the form code. Modify the _Click event handlers for the Add and List buttons as shown. The Add button lets you add children. The List button displays the names of all the children.

Public Class child
    Public name As String 
    Sub New(ByVal newName As String)
        name = newName
    End Sub 
End Class 
' Create a Collection object. 
Private family As New Collection()
Private Sub addChild_Click(ByVal sender As System.Object, _
    ByVal e As System.EventArgs) Handles Button1.Click
    Dim newName As String
    newName = InputBox("Name of new family member: ")
    If newName <> "" Then
        family.Add(New child(newName), newName)
    End If 
End Sub 
Private Sub listChild_Click(ByVal sender As System.Object, _
    ByVal e As System.EventArgs) Handles Button2.Click
    For Each aChild As child In family
        MsgBox(aChild.name)
    Next 
End Sub

Requirements

Namespace: Microsoft.VisualBasic

Module: Collection

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

See Also

Reference

Collection Object (Visual Basic)

Item Property (Collection Object)

Remove Method (Collection Object)