Collection
The Collection class manages Collection type variables.
A collection is initialized with:
New collection {( ...value : any )} : Collection creates a new empty or prefilled collection |
New shared collection {( ...value : any )} : Collection creates a new empty or prefilled shared collection |
Example
var $colVar : Collection //creation of collection type 4D variable
$colVar:=New collection //initialization of the collection and assignment to the 4D variable
Summary
.at( index : Integer ) : any returns the item at position index, allowing for positive and negative integers |
.average( {propertyPath : Text } ) : Real returns the arithmetic mean (average) of defined values in the collection instance |
.clear() : Collection removes all elements from the collection instance and returns an empty collection |
.combine( col2 : Collection {; index : Integer } ) : Collection inserts col2 elements at the end or at the specified index position in the collection instance and returns the edited collection |
.concat( value : any { ;...valueN } ) : Collection returns a new collection containing the elements of the original collection with all elements of the value parameter added to the end |
.copy() : Collection .copy( option : Integer ) : Collection .copy( option : Integer ; groupWithCol : Collection ) : Collection .copy( option : Integer ; groupWithObj : Object ) : Collection returns a deep copy of the collection instance |
.count( { propertyPath : Text } ) : Real returns the number of non-null elements in the collection |
.countValues( value : any {; propertyPath : Text } ) : Real returns the number of times value is found in the collection |
.distinct( {options : Integer} ) : Collection .distinct( propertyPath : Text {; options : Integer } ) : Collection returns a collection containing only distinct (different) values from the original collection |
.equal( collection2 : Collection {; option : Integer } ) : Boolean compares the collection with collection2 |
.every( { startFrom : Integer ; } formula : 4D.Function { ;...param : any } ) : Boolean .every( { startFrom : Integer ; } methodName : Text { ;...param : any } ) : Boolean returns true if all elements in the collection successfully passed a test implemented in the provided formula object or methodName method |
.extract( propertyPath : Text { ; option : Integer } ) : Collection .extract( propertyPath : Text ; targetPath : Text { ;...propertyPathOrTargetPathN : Text } ) : Collection creates and returns a new collection containing propertyPath values extracted from the original collection of objects |
.fill( value : any ) : Collection .fill( value : any ; startFrom : Integer { ; end : Integer } ) : Collection fills the collection with the specified value, optionally from startFrom index to end index, and returns the resulting collection |
.filter( formula : 4D.Function { ; ...param : any } ) : Collection .filter( methodName : Text { ; ...param : any } ) : Collection returns a new collection containing all elements of the original collection for which the formula or methodName result is true |
.find( { startFrom : Integer ; } formula : 4D.Function { ; ...param : any } ) : any .find( { startFrom : Integer ; } methodName : Text { ; ...param : any } ) : any returns the first value in the collection for which formula or methodName result, applied on each element, returns true |
.findIndex( { startFrom : Integer ; } formula : 4D.Function { ; ...param : any } ) : Integer .findIndex( { startFrom : Integer ; } methodName : Text { ; ...param : any } ) : Integer returns the index, in the collection, of the first value for which formula or methodName, applied on each element, returns true |
.first() : any returns the first element of the collection |
.flat( { depth : Integer } ) : Collection creates a new collection with all sub-collection elements concatenated into it recursively up to the specified depth |
.flatMap( formula : 4D.Function { ; ...param : any } ) : Collection .flatMap( methodName : Text { ; ...param : any } ) : Collection creates a new collection based upon the result of the call of the formula 4D function or methodName method on each element of the original collection and flattened by a depth of 1 |
.includes( toSearch : expression { ; startFrom : Integer } ) : Boolean returns True if the toSearch expression is found among collection elements, otherwise False |
.indexOf( toSearch : expression { ; startFrom : Integer } ) : Integer searches the toSearch expression among collection elements and returns the index of the first found occurrence, or -1 if it was not found |
.indices( queryString : Text { ; ...value : any } ) : Collection returns indexes, in the original collection, of object collection elements that match the queryString search conditions |
.insert( index : Integer ; element : any ) : Collection inserts element at the specified index position in the collection instance and returns the edited collection |
.join( delimiter : Text { ; option : Integer } ) : Text converts all elements of the collection to strings and concatenates them using the specified delimiter string as separator |
.last() : any returns the last element of the collection |
.lastIndexOf( toSearch : expression { ; startFrom : Integer } ) : Integer searches the toSearch expression among collection elements and returns the index of the last occurrence |
.length : Integer returns the number of elements in the collection |
.map( formula : 4D.Function { ; ...param : any } ) : Collection .map( methodName : Text { ; ...param : any } ) : Collection creates a new collection based upon the result of the call of the formula 4D function or methodName method on each element of the original collection |
.max( { propertyPath : Text } ) : any returns the element with the highest value in the collection |
.min( { propertyPath : Text } ) : any returns the element with the smallest value in the collection |
.orderBy( ) : Collection .orderBy( pathStrings : Text ) : Collection .orderBy( pathObjects : Collection ) : Collection .orderBy( ascOrDesc : Integer ) : Collection returns a new collection containing all elements of the collection in the specified order |
.orderByMethod( formula : 4D.Function { ; ...extraParam : expression } ) : Collection .orderByMethod( methodName : Text { ; ...extraParam : expression } ) : Collection returns a new collection containing all elements of the collection in the order defined through the formula 4D function or methodName method |
.pop() : any removes the last element from the collection and returns it as the function result |
.push( element : any { ;...elementN } ) : Collection appends one or more element(s) to the end of the collection instance and returns the edited collection |
.query( queryString : Text ; ...value : any ) : Collection .query( queryString : Text ; querySettings : Object ) : Collection returns all elements of a collection of objects that match the search conditions |
.reduce( formula : 4D.Function { ; initValue : any { ; ...param : expression }} ) : any .reduce( methodName : Text { ; initValue : any { ; ...param : expression }} ) : any applies the formula or methodName callback against an accumulator and each element in the collection (from left to right) to reduce it to a single value |
.reduceRight( formula : 4D.Function { ; initValue : any { ; ...param : expression }} ) : any .reduceRight( methodName : Text { ; initValue : any { ; ...param : expression }} ) : any applies the formula or methodName callback against an accumulator and each element in the collection (from right to left) to reduce it to a single value |
.remove( index : Integer { ; howMany : Integer } ) : Collection removes one or more element(s) from the specified index position in the collection and returns the edited collection |
.resize( size : Integer { ; defaultValue : any } ) : Collection sets the collection length to the specified new size and returns the resized collection |
.reverse( ) : Collection returns a deep copy of the collection with all its elements in reverse order |
.shift() : any removes the first element of the collection and returns it as the function result |
.slice( startFrom : Integer { ; end : Integer } ) : Collection returns a portion of a collection into a new collection |
.some( { startFrom : Integer ; } formula : 4D.Function { ; ...param : any } ) : Boolean .some( { startFrom : Integer ; } methodName : Text { ; ...param : any } ) : Boolean returns true if at least one element in the collection successfully passed a test implemented in the provided formula or methodName code |
.sort() : Collection .sort( formula : 4D.Function { ; ...extraParam : any } ) : Collection .sort( methodName : Text { ; ...extraParam : any } ) : Collection sorts the elements of the original collection and also returns the sorted collection |
.sum( { propertyPath : Text } ) : Real returns the sum for all values in the collection instance |
.unshift( value : any { ;...valueN : any } ) : Collection inserts the given value(s) at the beginning of the collection |
New collection
New collection {( ...value : any )} : Collection
Parameter | Type | Description | |
---|---|---|---|
value | Number, Text, Date, Time, Boolean, Object, Collection, Picture, Pointer | -> | Collection's value(s) |
Result | Collection | <- | The 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 of the Collection type.
Keep in mind that
var : Collection
orC_COLLECTION
statements declare a variable of theCollection
type but do 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 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.
You can pass any number of values of any supported type (number, text, date, picture, 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. 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 theSET 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"]
New shared collection
History
Release | Changes |
---|---|
v16 R6 | Added |
New shared collection {( ...value : any )} : Collection
Parameter | Type | Description | |
---|---|---|---|
value | Number, Text, Date, Time, Boolean, Shared object, Shared collection | -> | Shared collection's value(s) |
Result | Collection | <- | The new shared collection |
Description
The New shared collection
command creates a new empty or prefilled shared collection and returns its reference.
Adding an element to this collection using the assignment operator must be surrounded by the Use...End use
structure, otherwise an error is generated (this is not necessary when adding elements using functions such as push()
or map()
because they automatically trigger an internal Use...End use). Reading an element without a Use...End use structure is, however, possible.
For more information on shared collections, please refer to the Shared objects and collections page.
If you do not pass any parameters, New shared collection
creates an empty shared collection and returns its reference.
You must assign the returned reference to a 4D variable of the Collection type.
Keep in mind that
var : Collection
orC_COLLECTION
statements declare a variable of theCollection
type but do not create any collection.
Optionally, you can prefill the new shared collection by passing one or several value(s) as parameter(s). Otherwise, you can add or modify elements subsequently through object notation assignment (see example).
If the new element index is beyond the last existing element of the shared collection, the collection is automatically resized and all new intermediary elements are assigned a null value.
You can pass any number of values of the following supported types:
- number (real, longint...). Number values are always stored as reals.
- text
- boolean
- date
- time (stored as number of milliseconds - real)
- null
- shared object(*)
- shared collection(*)
Unlike standard (not shared) collections, shared collections do not support pictures, pointers, and objects or collections that are not shared.
(*)When a shared object or collection is added to a shared collection, they share the same locking identifier. For more information on this point, refer to 4D Doc Center.
Example
$mySharedCol:=New shared collection("alpha";"omega")
Use($mySharedCol)
$mySharedCol[1]:="beta"
End use
.at()
History
Release | Changes |
---|---|
20 | Added |
.at( index : Integer ) : any
Parameter | Type | Description | |
---|---|---|---|
index | Integer | -> | Index of element to return |
Result | any | <- | The element at that index |
Description
The .at()
function returns the item at position index, allowing for positive and negative integers.
This function does not modify the original collection.
Negative integers count back from the last item in the collection.
The function returns Undefined if index is beyond collection limits.
Example
var $col : Collection
$col:=New collection(10; 20; 30; 40; 50)
$element:=$col.at(0) // 10
$element:=$col.at(1) // 20
$element:=$col.at(-1) // 50
$element:=$col.at(-2) // 40
$element:=$col.at(10) // undefined
.average()
History
Release | Changes |
---|---|
v16 R6 | Added |
.average( {propertyPath : Text } ) : Real
Parameter | Type | Description | |
---|---|---|---|
propertyPath | Text | -> | Object property path to be used for calculation |
Result | Real, Undefined | <- | Arithmetic mean (average) of collection values |
Description
The .average()
function returns the arithmetic mean (average) of defined values in the collection instance.
Only numerical elements are taken into account for the calculation (other element types are ignored).
If the collection contains objects, pass the propertyPath parameter to indicate the object property to take into account.
.average()
returns undefined
if:
- the collection is empty,
- the collection does not contain numerical elements,
- propertyPath is not found in the collection.
Example 1
var $col : Collection
$col:=New collection(10;20;"Monday";True;6)
$vAvg:=$col.average() //12
Example 2
var $col : Collection
$col:=New collection
$col.push(New object("name";"Smith";"salary";10000))
$col.push(New object("name";"Wesson";"salary";50000))
$col.push(New object("name";"Gross";"salary";10500))
$vAvg:=$col.average("salary") //23500
.clear()
History
Release | Changes |
---|---|
v16 R6 | Added |
.clear() : Collection
Parameter | Type | Description | |
---|---|---|---|
Result | Collection | <- | Original collection with all elements removed |
Description
The .clear()
function removes all elements from the collection instance and returns an empty collection.
This function modifies the original collection.
Example
var $col : Collection
$col:=New collection(1;2;5)
$col.clear()
$vSize:=$col.length //$vSize=0
.combine()
History
Release | Changes |
---|---|
v16 R6 | Added |
.combine( col2 : Collection {; index : Integer } ) : Collection
Parameter | Type | Description | |
---|---|---|---|
col2 | Collection | -> | Collection to combine |
index | Integer | -> | Position to which insert elements to combine in collection (default=length+1) |
Result | Collection | <- | Original collection containing combined element(s) |
Description
The .combine()
function inserts col2 elements at the end or at the specified index position in the collection instance and returns the edited collection. Unlike the .insert()
function, .combine()
adds each value of col2 in the original collection, and not as a single collection element.
This function modifies the original collection.
By default, col2 elements are added at the end of the orginal collection. You can pass in index the position where you want the col2 elements to be inserted in the collection.
Warning: Keep in mind that collection elements are numbered from 0.
- If index > the length of the collection, the actual starting index will be set to the length of the collection.
- If index < 0, it is recalculated as index:=index+length (it is considered as the offset from the end of the collection).
- If the calculated value is negative, index is set to 0.