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 [, [eBeforeItem |, eAfterItem ]]] )

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.

  • [, [ eBeforeItem |, eAfterItem ]]
    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 a eBeforeItem or an eAfterItem expression but not both, which generates the appropriate message. This expression can be one of two types:

    • Numeric. The eBeforeItem and eAfterItem expression must have a value from 1 to the value of the Count property for the collection.
    • String. The eBeforeItem and eAfterItem 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 eBeforeItem or eAfterItem parameter, the new item is added before or after the index value of the specified key. In this case, the value of CollectionKeySort 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:

    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 eBeforeItem as shown in the following example:

    loItems.Add("Orchids", "flower3",, "flower2")

    If eBeforeItem and eAfterItem 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 eBeforeItem or eAfterItem are not specified.

Remarks

When adding objects to collections, Visual FoxPro increases the reference count for that object. According to usual Visual FoxPro object behavior, you can release an object only when its reference count is 0. Therefore, you should make sure that the reference to the object in the collection is released when releasing the object; otherwise, the Visual FoxPro does not remove the object entirely from memory.

You are not limited to the number of items you can add to a collection. However, the size of a collection can affect the performance of operations such as accessing, searching, and enumerating items in the collection. For example, creating a large collection based on records from a very large table (.dbf) is not recommended because you cannot use query optimization and other features associated with the Visual FoxPro native data engine.

You can have a collection of collections because collections are objects. However, avoid creating circular references, such as attempting to add an outer collection to an inner collection.

Adding arrays as items to a collection instantiated from the base class has limited use because there is no easy way to reference all the elements in the array. Consider the following example:

DIMENSION x[3]
x[1] = 1
x[2] = 22
x[3] = 333
y = CREATEOBJECT("collection")
y.Add(@x)
z = y.item(1)   && Returns just the first element
? z[2]         && Error

Therefore, you should create a subclass with special handling for this scenario.

You can pass a value of NULL as an item type and use TYPE( ) and VARTYPE( ) functions to query the type of the item in the collection.

You can add items of mixed type. However, Visual FoxPro does not enforce type safety, so you should provide it for the class if needed. If an incorrect type is passed for a specific parameter, an error occurs.

Include the NODEFAULT command in the Add method for collection objects to prevent adding a particular item to the collection.

Example

The following example illustrates the following tasks:

  • Adds four items to a collection using the cKey parameter.
  • Adds a second item with a key that precedes the first item using the eBeforeItem parameter.
  • Adds a fourth item with a key that follows the first added item using the eAfterItem parameter.
  • Iterates through all the items displaying to the screen.
CLEAR
LOCAL loItems, lcFlower
loItems = NEWOBJECT("Collection")
loItems.Add("Daffodils", "flower2")

* Add "Roses" with "flower1" key before "flower2".
loItems.Add("Roses", "flower1", "flower2")
loItems.Add("Daisies", "flower4")

* Add "Orchids" with "flower4" key after "flower2".
loItems.Add("Orchids","flower3",,"flower2")
FOR EACH lcFlower IN loItems
   ? lcFlower
ENDFOR

The following example generates an error. You cannot specify both an eBeforeItem and an eAfterItem.

* Generates an error. Cannot specify both eBeforeItem and eAfterItem.
loItems.Add("Violets","flower5","flower2","flower1")

See Also

Collection Object Properties, Methods, and Events | Collection Class | KeySort Property | TYPE( ) Function | VARTYPE( ) Function | NODEFAULT Command