New collection
New collection {( value {; value2 ; ... ; valueN} )} -> Function result
| Parameter | Type | Description | |
|---|---|---|---|
| value | Number, Text, Date, Object, Collection, Pointer | 🡒 | Collection's value(s) |
| Function result | Collection | 🡐 | New collection |
Description
The New collection command creates a new empty or prefilled collection and returns its reference.
If you do not pass any parameters, New collection creates an empty collection and returns its reference.
You must assign the returned reference to a 4D variable declared with C_COLLECTION.
Note: Keep in mind that C_COLLECTION declares a variable of the Collection type but does not create any collection.
Optionally, you can prefill the new collection by passing one or several value(s) as parameter(s).
Otherwise, you can add or modify elements subsequently through object notation assignment. For example:
myCol[10]:="My new element"
If the new element index is beyond the last existing element of the collection, the collection is automatically resized and all new intermediary elements are assigned a null value.
Note: For more information on object notation, please refer to the Using object notation section.
You can pass any number of values of any supported type (number, text, date, pointer, object, collection...). Unlike arrays, collections can mix data of different types.
You must pay attention to the following conversion issues:
- If you pass a pointer, it is kept "as is"; it is evaluated using the JSON Stringify command
- Dates are stored as "yyyy-mm-dd" dates or strings with the "YYYY-MM-DDTHH:mm:ss.SSSZ" format, according to the current "dates inside objects" database setting (see Compatibility page). When converting 4D dates into text prior to storing them in the collection, by default the program takes the local time zone into account. You can modify this behavior using the Dates inside objects selector of the SET DATABASE PARAMETER command.
- If you pass a time, it is stored as a number of milliseconds (Real).
Example 1
You want to create a new empty collection and assign it to a 4D collection variable:
var $myCol : Collection
$myCol:=New collection
//$myCol=[]
Example 2
You want to create a prefilled collection:
var $filledColl : Collection
$filledColl:=New collection(33;"mike";"november";->myPtr;Current date)
//$filledColl=[33,"mike","november","->myPtr","2017-03-28T22:00:00.000Z"]
Example 3
You create a new collection and then add a new element:
var $coll : Collection
$coll:=New collection("a";"b";"c")
//$coll=["a","b","c"]
$coll[9]:="z" //add a 10th element with value "z"
$vcolSize:=$coll.length //10
//$coll=["a","b","c",null,null,null,null,null,null,"z"]
Note: This example requires that object notation is activated in the database (see Object Notation paragraph).