About collections

Home

4D v19.8

About collections

Overview

Commands of the Collections theme create and work with collections.

Collections are ordered lists of values of similar or mixed types (text, number, object, boolean, collection, or null). To manage Collection type variables you must use object notation (see Using object notation). For additional information on 4D collections, refer to the paragraph in the RELATE MANY section.

To access a collection element, you need to pass the element number inside square brackets:

collectionRef[expression]

You can pass any valid 4D expression which returns a positive integer in expression. Examples:

 myCollection[5]  //access to 6th element of the collection

 myCollection[$var]

Note: Keep in mind that collection elements are numbered from 0.

You can assign a value to a collection element or get a collection element value using object notation:

 myCol[10]:="My new element"

 $myVar:=myCol[0]

If you assign an element's index that surpasses the last existing element of the collection, the collection is automatically resized and all new intermediary elements are assigned a null value:

 C_COLLECTION(myCol)

 myCol:=New collection("A";"B")

 myCol[5]:="Z"

  //myCol[2]=null

  //myCol[3]=null

  //myCol[4]=null

Regular or shared collection

You can create two types of collections:

regular (non-shared) collections, using the New collection command.
These collections support a large number of data types, including pictures and pointers. They can be edited without any specific access control.
shared collections, using the New shared collection command.
These collections can be shared between processes, including preemptive threads. Access to these collections are controlled by Use...End use structures. For more information, please refer to the Shared objects and shared collections page.

Collection methods

4D collection references benefit from specific methods called member methods. Thanks to object notation (see Using object notation), these methods can be applied to collection references using the following syntax:

{$result:=}myCollection.method( {params} )

Note that, even if it does not have parameters, a member method must be called with () parenthesis, otherwise a syntax error is generated.

For example:

 $newCol:=$col.copy() //deep copy of $col to $newCol

 $col.push(10;100) //add 10 and 100 to the collection

Some methods return the original collection after modification, so that you can run the calls in a sequence:

 $col:=New collection(5;20)

 $col2:=$col.push(10;100).sort() //$col2=[5,10,20,100]

Warning: When using collection methods, you must use ECMA Script compliant property paths, i.e. you cannot use ".", "[ ]", or spaces in property names. For example, according to the Object property identifiers section, property names such as $o["My.special.property"] are supported. However, they will not be usable with methods:

 $vmin:=$col.min("My.special.property") //undefined

 $vmin:=$col.min(["My.special.property"]) //error

propertyPath parameter

Several collection methods accept a propertyPath as parameter. This parameter stands for:

either an object property name, for example "lastName"
or an object property path, i.e. a hierarchical sequence of sub-properties linked with dot characters, for example "employee.children.firstName".

Consequently, when a propertyPath parameter is expected, using property names containing one or more "." is not supported since it will prevent 4D from correctly parsing the path.

Note: For more information, please refer to the Object property identifiers section.