A Collection object is an ordered set of items that can be referred to as a unit.
Collection
The Collection object provides a convenient way to refer to a related group of items as a single object. The items, or members, in a collection need only be related by the fact that they exist in the collection. Members of a collection don't have to share the same data type, because they are converted to a Variant.
An instance of a collection can be created using the New keyword. For example:
Dim X As New Collection
Once a collection is created, members can be added using the Add method and removed using the Remove method. Specific members can be returned from the collection using the Item method, while the entire collection can be iterated using the For Each...Next statement.
| Count | Long | Returns the number of objects |
Add item[, key] [, before][, after]
item, key, before, after: Variant
Adds a member to a Collection
| item | An expression of any type to add. |
| key | Optional. A unique string that specifies a key string that can be used, instead of a positional index, to access a member of the collection. |
| before | Optional. An expression that specifies a relative position in the collection. The member to be added is placed in the collection before the member identified by the before argument. If a numeric expression, before must be a number from 1 to the value of the collection's Count property. If a string expression, before must correspond to the key specified when the member being referred to was added to the collection. You can specify a before position or an after position, but not both. |
| after | Optional. An expression that specifies a relative position in the collection. The member to be added is placed in the collection after the member identified by the after argument. If numeric, after must be a number from 1 to the value of the collection's Count property. If a string, after must correspond to the key specified when the member referred to was added to the collection. You can specify a before position or an after position, but not both. |
Remove index index: Variant
Removes a member at the specified position ( 1 … .Count), or when index is a string expression the key.
Item(index) index: Variant
Returns a member at the specified position ( 1 … .Count), or when index is a string expression the key.
Item is the default method for a Collection and can be left out, e.g.
col.Item(1) => col(1)
To refer to an individual member in a collection when you know the key name, use the ! operator syntax, as shown in the following example.
col.Add "String", Key := "str1"
Print col!str1
The ! operator increases the performance with 30%, but is only applicable with literal keys (no variables) that start with a letter (a..z). Keys are not case sensitive.
Dim a%
OpenW 1
Coltest()
Proc Coltest()
Dim f As Form
Dim col As New Collection
col.Add Win_1, "Win1" // a form object
col.Add "a string", "s1" // a string
col.Add 1.0, Before := "Win1" // a double
Dim v As Variant // collection member
For Each v In col // show positions ...
Print TypeName(v) // ... their type
Next
Print "col(1) = "; col(1)
Print "col(""s1"") = "; col("s1")
Print "col!s1 = "; col!s1
Set f = col!Win1
Print "Caption Win_1: "; f.Caption
col.Remove 1
Set f = Nothing
Set col = Nothing
EndProc
An object's position in the collection can change whenever a change occurs in the collection; therefore, the position of any specific object in the collection can vary.
Whether the before or after argument is a string expression or numeric expression, it must refer to an existing member of the collection, or an error occurs.
An error also occurs if a specified key duplicates the key for an existing member of the collection.
Internally, the Collection type is built on the Hash type. Collection is actually a special type of Hash: Hash Variant. Since the Collection is an OLE compatible type, the keys are UNICODE strings and strings must be converted to OLE strings first. GFA-BASIC 32 doesn't call the API conversion functions, but instead uses its own, faster, conversion routines. Despite these optimizations the Hash is much faster than the Collection and can be used instead in most cases.
The ! operator increases the performance with 30%, because the key isn't converted to a UNICODE string. In this special case GFA-BASIC 32 uses a non-compatible optimization to increase member access performance.
The ! operator is useful with OCX controls as well. Items stored in collections like ListImages, Buttons, Panels, etc., can be accessed using ! as well and profit from the performance increase.
{Created by Sjouke Hamstra; Last updated: 25/09/2014 by James Gaite}