Add Method (Collection Class)

Use to add a member to a collection.

The member object can have any valid type that can be assigned to a memory variable. This includes simple data types, such as strings, numbers, dates, logical, or more complex types such as Visual FoxPro and Component Object Model (COM) objects.

Collection.Add( eItem [, cKey [, [eBefore |, eAfter ]]] )

Parameters

eItem

Specifies an expression of any type that represents a member to add to the collection. Usually, this is an object, but it could be a number, string, or member that has a valid type.

cKey

Specifies an optional, unique, alphanumeric (character type) expression that represents a key string, instead of a positional index, that can be used to access a member of the collection.

For collections using keys, cKey is a case-sensitive parameter and cannot be empty or have a null value (.NULL.).

Either all items added to the collection must have the cKey parameter specified for them or not specified because of performance reasons. The first item added determines the behavior for the collection. You can test for the presence of keys in a collection by using the following code:

GetKey(1)

If the key already exists for a member in the collection, an error occurs. However, because cKey is case-sensitive, no duplication error occurs if the same keys with different case are added. A key includes any trailing spaces present in cKey.

[, [ eBefore|, eAfter]]

Specifies an optional expression that represents a position where a new member is to be inserted before or after another item in the collection.

You can specify an eBefore or an eAfter expression but not both, which generates the appropriate message. This expression can be one of two types:

  • Numeric. The eBefore and eAfter expression must have a value from 1 to the value of the Count property for the collection.

  • String. The eBefore and eAfter expression must correspond to the cKey that was specified for the referenced item when it was added to the collection.

Inserting a new item into a collection before or after an existing one requires that the collection must be a keyed collection. When you specify a cKey value with an eBefore or eAfter parameter, the new item is added before or after the index value of the specified key. In this case, the value of Collection KeySort has no effect. For example, suppose cKey for a new item is "ZZZ", and for an existing item, cKey is "YYY", and its index value is 15. The new item would receive an index value of 15, and the existing item would receive a new index value of 16.

To insert a new item before an existing item, include the key of the item you want to insert the new item before as shown in the following example:

 CopyCode imageCopy Code
loItems.Add("Roses", "flower1", "flower2")

To insert a new item after an existing item, include the key of the item you want to insert the new item after. In addition, you must pass an empty third parameter for eBefore as shown in the following example:

 CopyCode imageCopy Code
loItems.Add("Orchids", "flower3",, "flower2")

If eBefore and eAfter do not refer to an existing member of the collection, an error occurs. Visual FoxPro adds an item to the end of a collection when eBefore or eAfter are not specified.

Expand imageRemarks

Expand imageExample

Expand imageSee Also


© , 1996-2020 • Updated: 11/10/20
Comment or report problem with topic