Skip to main content

Collection

The Collection class manages collection type elements.

Example

 var c : collection //declaration of collection type variable
c = newCollection() //initialization of the collection and assignment to the variable
c.push("Hello",42,{o : "World"}) // c contains [Hello,42,{"o":"World"}]

Functions and properties

.at( index : integer ) : any     returns the item at position index, allowing for positive and negative integers
.average( {propertyPath : string } ) : number    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 : string } ) : number    returns the number of non-null elements in the collection
.countValues( value : any {, propertyPath : string } ) : number    returns the number of times value is found in the collection
.distinct( {options : integer} ) : collection
.distinct( propertyPath : string {, 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 : string { ,...param : any } ) : boolean
    returns true if all elements in the collection successfully passed a test implemented in the provided formula object or methodName name
.extract( propertyPath : string { , option : integer } ) : collection
.extract( propertyPath : string , targetPath : string { ,...propertyPathN : string ,... targetPathN : string } ) : 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 : string { , ...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 : string { , ...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 : string { , ...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 : string { , ...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 : string { , ...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 : string { , option : integer } ) : string     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 : string { , ...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 : string } ) : any     returns the element with the highest value in the collection
.min( { propertyPath : string } ) : any     returns the element with the smallest value in the collection
.multiSort() : collection
.multiSort( colsToSort : collection ) : collection
.multiSort( formula : 4D.Function , colsToSort : collection ) : collection
    enables you to carry out a multi-level synchronized sort on a set of collections
.orderBy() : collection
.orderBy( pathStrings : string ) : 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 : string { , ...extraParam : expression } ) : collection
    returns a new collection containing all elements of the collection in the order defined through the formula 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 : string , ...value : any ) : collection
.query( queryString : string , 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 : string { , 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 : string { , 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 : string { , ...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 : string { , ...extraParam : any } ) : collection
    sorts the elements of the original collection and also returns the sorted collection
.sum( { propertyPath : string } ) : number    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

.at()

.at( index : integer ) : any

ParameterTypeDescription
indexinteger->Index of element to return
Resultany<-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 = newCollection(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()

.average( {propertyPath : string } ) : number

ParameterTypeDescription
propertyPathstring->object property path to be used for calculation
Resultnumber, 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
var vAvg : integer
col = newCollection(10,20,"Monday",true,6)
vAvg = col.average() //12

Example 2

 var col : collection
var vAvg : integer
col = newCollection()
col.push(newObject("name","Smith","salary",10000))
col.push(newObject("name","Wesson","salary",50000))
col.push(newObject("name","Gross","salary",10500))
vAvg = col.average("salary") //23500

.clear()

.clear() : collection

ParameterTypeDescription
Resultcollection<-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 = newCollection(1,2,5)
col.clear()
//col.length: 0

.combine()

.combine( col2 : collection {, index : integer } ) : collection

ParameterTypeDescription
col2collection->collection to combine
indexinteger->Position to which insert elements to combine in collection (default = length+1)
Resultcollection<-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.

Example

var c, fruits : collection
c = newCollection(1,2,3,4,5,6)
fruits = newCollection("Orange","Banana","Apple","Grape")
c.combine(fruits,3) //[1,2,3,"Orange","Banana","Apple","Grape",4,5,6]

.concat()

.concat( value : any { ,...valueN } ) : collection

ParameterTypeDescription
valueinteger, number, string, object, collection, date, time, boolean, picture->Value(s) to concatenate. If value is a collection, all collection elements are added to the original collection
Resultcollection<-New collection with value(s) added to the original collection

Description

The .concat() function returns a new collection containing the elements of the original collection with all elements of the value parameter added to the end.

This function does not modify the original collection.

If value is a collection, all its elements are added as new elements at the end of the original collection. If value is not a collection, it is added itself as a new element.

Example

var c,c2, fruits : collection
c = newCollection(1,2,3,4,5)
fruits = newCollection("Orange","Banana","Apple","Grape")
fruits.push(newObject("Intruder","Tomato"))
c2 = c.concat(fruits) //[1,2,3,4,5,"Orange","Banana","Apple","Grape",{"Intruder":"Tomato"}]
c2 = c.concat(6,7,8) //[1,2,3,4,5,6,7,8]

.copy()

.copy() : collection
.copy( option : integer ) : collection
.copy( option : integer , groupWithCol : collection ) : collection
.copy( option : integer , groupWithObj : object ) : collection

ParameterTypeDescription
optioninteger->kShared: return a shared collection
groupWithColcollection->Shared collection to be grouped with the resulting collection
groupWithObjobject->Shared object to be grouped with the resulting collection
Resultcollection<-Deep copy of the original collection

Description

The .copy() function returns a deep copy of the collection instance.Deep copy means that objects or collections within the original collection are duplicated and do not share any reference with the returned collection.

This function does not modify the original collection.

If passed, the option parameter can contain the following constant:

optionDescription
kSharedBy default, copy() returns a regular (not shared) collection, even if the command is applied to a shared collection. Pass the kShared constant to create a shared collection. In this case, you can use the groupWith parameter to associate the shared collection with another collection or object (see below).

The groupWithCol or groupWithObj parameters allow you to designate a collection or an object with which the resulting collection should be associated.

note

Datastore, dataclass, and entity objects are not copiable. If .copy() is called with them, null values are returned.

Example 1

We want to copy the lastnames regular (non shared) collection into the sharedobject shared object. To do this, we must create a shared copy of the collection (sharedLastnames).

var sharedobject : object
var lastnames,sharedLastnames : collection
var text : string

sharedobject = newSharedObject

text = file("/SOURCES/lastnames.txt").getText()
lastnames = jsonParse(text) //lastnames is a regular collection

sharedLastnames = lastnames.copy(kShared) //sharedLastnames is a shared collection

//Now we can put sharedLastnames into sharedobject
use(sharedobject)
sharedobject.lastnames = sharedLastnames
end

Example 2

We want to combine sharedColl1 and sharedColl2. Since they belong to different shared groups, a direct combination would result in an error. Therefore, we must make a shared copy of sharedColl1 and designate sharedColl2 as a shared group for the copy.

var sharedColl1,sharedColl2,copyColl : collection

sharedColl1 = newSharedcollection(newSharedObject("lastname","Smith"))
sharedColl2 = newSharedcollection(newSharedObject("lastname","Brown"))

//copyColl belongs to the same shared group as sharedColl2
copyColl = sharedColl1.copy(kShared,sharedColl2)
use(sharedColl2)
sharedColl2.combine(copyColl)
end

Example 3

We have a regular collection (lastnames) and we want to put it in the Storage of the application. To do this, we must create a shared copy beforehand (sharedLastnames).

var lastnames,sharedLastnames : collection
var text : string

text = file("/SOURCES/lastnames.txt").getText()
lastnames = jsonParse(text) //lastnames is a regular collection

sharedLastnames = lastnames.copy(kShared) // shared copy

use(storage)
storage.lastnames = sharedLastnames
end

.count()

.count( { propertyPath : string } ) : number

ParameterTypeDescription
propertyPathstring->object property path to be used for calculation
Resultnumber<-Number of elements in the collection

Description

The .count() function returns the number of non-null elements in the collection.

If the collection contains objects, you can pass the propertyPath parameter. In this case, only elements that contain the propertyPath are taken into account.

Example

 var col : collection
var count1,count2 : number
col = newCollection(20,30,null,40)
col.push(newObject("name","Smith","salary",10000))
col.push(newObject("name","Wesson","salary",50000))
col.push(newObject("name","Gross","salary",10500))
col.push(newObject("lastName","Henry","salary",12000))
count1 = col.count() //count1: 7
count2 = col.count("name") //count2: 3

.countValues()

.countValues( value : any {, propertyPath : string } ) : number

ParameterTypeDescription
valuestring, Number, boolean, date, object, collection->Value to count
propertyPathstring->Object property path to be used for calculation
Resultnumber<-Number of occurrences of the value

Description

The .countValues() function returns the number of times value is found in the collection.

You can pass in value:

  • a scalar value (text, number, boolean, date),
  • an object or a collection reference.

For an element to be found, the type of value must be equivalent to the type of the element, the method uses the equality operator.

The optional propertyPath parameter allows you to count values inside a collection of objects: pass in propertyPath the path of the property whose values you want to count.

This function does not modify the original collection.

Example 1

 var col : collection
var vCount : integer
col = newCollection(1,2,5,5,5,3,6,4)
vCount = col.countValues(5) // vCount: 3

Example 2

 var col : collection
var vCount : integer
col = newCollection()
col.push(newObject("name","Smith","age",5))
col.push(newObject("name","Wesson","age",2))
col.push(newObject("name","Jones","age",3))
col.push(newObject("name","Henry","age",4))
col.push(newObject("name","Gross","age",5))
vCount = col.countValues(5,"age") //vCount = 2

Example 3

 var numbers, letters : collection
var vCount : integer

letters = newCollection("a","b","c")
numbers = newCollection(1,2,letters,3,4,5)

vCount = numbers.countValues(letters) //vCount: 1

.distinct()

.distinct( {options : integer} ) : collection
.distinct( propertyPath : string {, options : integer } ) : collection

ParameterTypeDescription
propertyPathstring->Path of attribute whose distinct values you want to get
optionsinteger->kDiacritical, kCountValues
Resultcollection<-New collection with only distinct values

Description

The .distinct() function returns a collection containing only distinct (different) values from the original collection.

This function does not modify the original collection.

The returned collection is automatically sorted. null values are not returned.

If the collection contains objects, you can pass the propertyPath parameter to indicate the object property whose distinct values you want to get.

In the options parameter, you can pass one or a combination of the following constants:

ConstantValueComment
kDiacritical8Evaluation is case sensitive and differentiates accented characters. By default if omitted, a non-diacritical evaluation is performed
kCountValues32Return the count of elements for every distinct value. When this option is passed, .distinct() returns a collection of objects containing a pair of {"value":value,"count":count} attributes.

Examples

 var c, c2, c3 : collection
c = newCollection()
c.push("a","b","c","A","B","c","b","b")
c.push(newObject("size",1))
c.push(newObject("size",3))
c.push(newObject("size",1))
c2 = c.distinct() //c2 = ["a","b","c",{"size":1},{"size":3},{"size":1}]
c2 = c.distinct(kDiacritical) //c2: ["a","A","b","B","c",{"size":1},{"size":3},{"size":1}]
c2 = c.distinct("size") //c2: [1,3]
c3 = c.distinct("size",kCountValues) //c3: [{value:1,count:2},{value:3,count:1}]

.equal()

.equal( collection2 : collection {, option : integer } ) : boolean

ParameterTypeDescription
collection2collection->collection to compare
optioninteger->kDiacritical: diacritical evaluation ("A" # "a" for example)
Resultboolean<-true if collections are identical, false otherwise

Description

The .equal() function compares the collection with collection2 and returns true if they are identical (deep comparison).

By default, a non-diacritical evaluation is performed. If you want the evaluation to be case sensitive or to differentiate accented characters, pass the kDiacritical constant in the option parameter.

Elements with null values are not equal to Undefined elements.

Example

 var c, c2 : collection
var b : boolean

c = newCollection(newObject("a",1,"b","orange"),2,3)
c2 = newCollection(newObject("a",1,"b","orange"),2,3,4)
b = c.equal(c2) // false

c = newCollection(newObject("1","a","b","orange"),2,3)
c2 = newCollection(newObject("a",1,"b","orange"),2,3)
b = c.equal(c2) // false

c = newCollection(newObject("a",1,"b","orange"),2,3)
c2 = newCollection(newObject("a",1,"b","ORange"),2,3)
b = c.equal(c2) // true

c = newCollection(newObject("a",1,"b","orange"),2,3)
c2 = newCollection(newObject("a",1,"b","ORange"),2,3)
b = c.equal(c2,kDiacritical) //false

.every()

.every( { startFrom : integer , } formula : 4D.Function { ,...param : any } ) : boolean
.every( { startFrom : integer , } methodName : string { ,...param : any } ) : boolean

ParameterTypeDescription
startFrominteger->Index to start the test at
formula4D.Function->formula object
methodNamestring->Name of a method
paramany->Parameter(s) to pass to formula or methodName
Resultboolean<-true if all elements successfully passed the test

Description

The .every() function returns true if all elements in the collection successfully passed a test implemented in the provided formula object or methodName name.

You designate the callback to be executed to evaluate collection elements using either:

  • formula (recommended syntax), a formula object that can encapsulate any executable expressions, including functions and project methods,
  • or methodName, the name of a project method (string).

The callback is called with the parameter(s) passed in param (optional). The callback can perform any test, with or without the parameter(s) and must return true for every element fulfilling the test. It receives an object in first parameter named $1.

The callback receives the following parameters:

  • in $1.value: element value to be evaluated
  • in $2: param
  • in $N...: paramN...

It can set the following parameter(s):

  • (mandatory if you used a method) $1.result (boolean): true if the element value evaluation is successful, false otherwise.
  • $1.stop (boolean, optional): true to stop the method callback. The returned value is the last calculated.

In all cases, at the point when the .every() function encounters the first collection element evaluated to false, it stops calling the callback and returns false.

By default, .every() tests the whole collection. Optionally, you can pass in startFrom the index of the element from which to start the test.

  • If startFrom >= the collection's length, false is returned, which means the collection is not tested.
  • If startFrom < 0, it is considered as the offset from the end of the collection ( startFrom = startFrom+length).
  • If startFrom == 0, the whole collection is searched (default).

Example 1

var c : collection  
var b : boolean
var f : 4D.Function

f = formula($1.value>0)
c = newCollection()
c.push(5,3,1,4,6,2)
b = c.every(f) //returns true
c.push(-1)
b = c.every(f) //returns false

Example 2

This example tests that all elements of a collection are of the number type:

var c : collection
var b : boolean
var f : 4D.Function

f = formula(valueType($1.value) == $2
c = newCollection()
c.push(5,3,1,4,6,2)
b = c.every(f,Is number) //b = true
c = c.push(newObject("name","Cleveland","zc",35049))
c = c.push(newObject("name","Blountsville","zc",35031))
b = c.every(f,Is number) //b = false

.extract()

.extract( propertyPath : string { , option : integer } ) : collection
.extract( propertyPath : string , targetPath : string { ,...propertyPathN : string ,... targetPathN : string } ) : collection

ParameterTypeDescription
propertyPathstring->Object property path whose values must be extracted to the new collection
targetpathstring->Target property path or property name

|option|integer|->|kKeepNull: include null properties in the returned collection (ignored by default). Parameter ignored if targetPath passed.| |Result|collection|<-|new collection containing extracted values|

Description

The .extract() function creates and returns a new collection containing propertyPath values extracted from the original collection of objects.

This function does not modify the original collection.

The contents of the returned collection depends on the targetPath parameter:

  • If the targetPath parameter is omitted, .extract() populates the new collection with the propertyPath values of the original collection.

    By default, elements for which propertyPath is null or undefined are ignored in the resulting collection. You can pass the kKeepNull constant in the option parameter to include these values as null elements in the returned collection.

  • If one or more targetPath parameter(s) are passed, .extract() populates the new collection with the propertyPath properties and each element of the new collection is an object with targetPath properties filled with the corresponding propertyPath properties. null values are kept (option parameter is ignored with this syntax).

Example 1

var c : collection
c = newCollection()
c.push(newObject("name","Cleveland"))
c.push(newObject("zip",5321))
c.push(newObject("name","Blountsville"))
c.push(42)
c2 = c.extract("name") // c2: [Cleveland,Blountsville]
c2 = c.extract("name",kKeepNull) //c2: [Cleveland,null,Blountsville,null]

Example 2

var c : collection
c = newCollection()
c.push(newObject("zc",35060))
c.push(newObject("name",null,"zc",35049))
c.push(newObject("name","Cleveland","zc",35049))
c.push(newObject("name","Blountsville","zc",35031))
c.push(newObject("name","Adger","zc",35006))
c.push(newObject("name","Clanton","zc",35046))
c.push(newObject("name","Clanton","zc",35045))
c2 = c.extract("name","City") //c2: [{City:null},{City:Cleveland},{City:Blountsville},{City:Adger},{City:Clanton},{City:Clanton}]
c2 = c.extract("name","City","zc","Zip") //c2: [{Zip:35060},{City:null,Zip:35049},{City:Cleveland,Zip:35049},{City:Blountsville,Zip:35031},{City:Adger,Zip:35006},{City:Clanton,Zip:35046},{City:Clanton,Zip:35045}]

.fill()

.fill( value : any ) : collection
.fill( value : any , startFrom : integer { , end : integer } ) : collection

ParameterTypeDescription
valuenumber, string, collection, object, date, boolean->Filling value
startFrominteger->Start index (included)
endinteger->End index (not included)
Resultcollection<-Original collection with filled values

Description

The .fill() function fills the collection with the specified value, optionally from startFrom index to end index, and returns the resulting collection.

This function modifies the original collection.

  • If the startFrom parameter is omitted, value is set to all collection elements (startFrom = 0).
  • If the startFrom parameter is passed and end omitted, value is set to collection elements starting at startFrom to the last element of the collection (end == length).
  • If both the startFrom parameter and end are passed, value is set to collection elements starting at startFrom to the element end.

In case of inconsistency, the following rules apply:

  • If startFrom < 0, it is recalculated as startFrom = startFrom+length (it is considered as the offset from the end of the collection). If the calculated value is negative, startFrom is set to 0.
  • If end < 0 , it is recalculated as end = end+length.
  • If end < startFrom (passed or calculated values), the method does nothing.

Example

 var c : collection
c = newCollection(1,2,3,"Lemon",null,"",4,5)
c.fill("2") // c:[2,2,2,2,2,2,2,2]
c.fill("Hello",5) // c:[2,2,2,2,2,Hello,Hello,Hello]
c.fill(0,1,5) // c:[2,0,0,0,0,Hello,Hello,Hello]
c.fill("world",1,-5) //-5+8 = 3 -> c:[2,"world","world",0,0,Hello,Hello,Hello]

.filter()

.filter( formula : 4D.Function { , ...param : any } ) : collection
.filter( methodName : string { , ...param : any } ) : collection

ParameterTypeDescription
formula4D.Function->formula object
methodNamestring->Name of a method
paramany->Parameter(s) to pass to formula or methodName
Resultcollection<-new collection containing filtered elements (shallow copy)

Description

The .filter() function returns a new collection containing all elements of the original collection for which the formula or methodName result is true. This function returns a shallow copy, which means that objects or collections in both collections share the same reference. If the original collection is a shared collection, the returned collection is also a shared collection.

This function does not modify the original collection.

You designate the callback to be executed to filter collection elements using either:

  • formula (recommended syntax), a formula object that can encapsulate any executable expressions, including functions and project methods,
  • or methodName, the name of a project method (string).

The callback is called with the parameter(s) passed in param (optional) and an object in first parameter ($1). The callback can perform any test, with or without the parameter(s) and must return true for each element fulfilling the condition and thus, to push to the new collection.

The callback receives the following parameters:

  • in $1.value: element value to be evaluated
  • in $2: param
  • in $N...: paramN...

It can set the following parameter(s):

  • $1.result (boolean): true if the element value matches the filter condition and must be kept, false otherwise.
  • $1.stop (boolean, optional): true to stop the method callback. The returned value is the last calculated.
note

When using methodName as callback, and if the method does not return any value, .filter() will look at the property $1.result that you must set to true for each element fulfilling the condition.

Example 1

You want to get the collection of text elements whose length is smaller than 6:

var col,colNew : collection
col = newCollection("hello","world","red horse",66,"tim","san jose","miami")
colNew = col.filter(formula((valueType($1.value) == Is text) && (length($1.value)<$2)), 6)
//colNew:["hello","world","tim","miami"]

Example 2

You want to filter elements according to their value type:

 var c,c2,c3 : collection
var f : 4D.Function

f = formula(valueType($1.value) == $2)
c = newCollection(5,3,1,4,6,2)
c.push(newObject("name","Cleveland","zc",35049))
c.push(newObject("name","Blountsville","zc",35031))
c2 = c.filter(f,Is number) // c2 = [5,3,1,4,6,2]
c3 = c.filter(f,Is object)
// c3 = [{name:Cleveland,zc:35049},{name:Blountsville,zc:35031}]

.find()

.find( { startFrom : integer , } formula : 4D.Function { , ...param : any } ) : any
.find( { startFrom : integer , } methodName : string { , ...param : any } ) : any

ParameterTypeDescription
startFrominteger->Index to start the search at
formula4D.Function->formula object
methodNamestring->Name of a method
paramany->Parameter(s) to pass to formula or methodName
Resultany<-First value found, or Undefined if not found

Description

The .find() function returns the first value in the collection for which formula or methodName result, applied on each element, returns true.

This function does not modify the original collection.

You designate the callback to be executed to evaluate collection elements using either:

  • formula (recommended syntax), a formula object that can encapsulate any executable expressions, including functions and project methods,
  • or methodName, the name of a project method (string).

The callback is called with the parameter(s) passed in param (optional). The callback can perform any test, with or without the parameter(s) and must return true for the first element fulfilling the condition. It receives an object in first parameter ($1).

The callback receives the following parameters:

  • in $1.value: element value to be evaluated
  • in $2: param
  • in $N...: paramN...

It can set the following parameter(s):

  • (mandatory if you used a method) $1.result (boolean): true if the element value matches the search condition, false otherwise.
  • $1.stop (boolean, optional): true to stop the method callback. The returned value is the last calculated.

By default, .find() searches in the whole collection. Optionally, you can pass in startFrom the index of element from which to start the search.

  • If startFrom >= the collection's length, -1 is returned, which means the collection is not searched.
  • If startFrom < 0, it is considered as the offset from the end of the collection (startFrom = startFrom+length). Note: Even if startFrom is negative, the collection is still searched from left to right.
  • If startFrom == 0, the whole collection is searched (default).

Example 1

You want to get the first text element with a length smaller than 5:

var col : collection
col = newCollection("hello","world",4,"red horse","tim","san jose")
value = col.find(formula((valueType($1.value) == Is text) && (length($1.value)<$2)), 5) //value: "tim"

Example 2

You want to find a city name within a collection:

var c : collection
var c2 : object
c = newCollection()
c.push(newObject("name", "Cleveland", "zc", 35049))
c.push(newObject("name", "Blountsville", "zc", 35031))
c.push(newObject("name", "Adger", "zc", 35006))
c.push(newObject("name", "Clanton", "zc", 35046))
c.push(newObject("name", "Clanton", "zc", 35045))

c2 = c.find(formula($1.value.name == $2), "Clanton") //c2 = {name:Clanton,zc:35046}

.findIndex()

.findIndex( { startFrom : integer , } formula : 4D.Function { , ...param : any } ) : integer
.findIndex( { startFrom : integer , } methodName : string { , ...param : any } ) : integer

ParameterTypeDescription
startFrominteger->Index to start the search at
formula4D.Function->formula object
methodNamestring->Name of a method
paramany->Parameter(s) to pass to formula or methodName
Resultinteger<-Index of first value found, or -1 if not found

Description

The .findIndex() function returns the index, in the collection, of the first value for which formula or methodName, applied on each element, returns true.

This function does not modify the original collection.

You designate the callback to be executed to evaluate collection elements using either:

  • formula (recommended syntax), a formula object that can encapsulate any executable expressions, including functions and project methods,
  • methodName, the name of a project method (string).

The callback is called with the parameter(s) passed in param (optional). The callback can perform any test, with or without the parameter(s) and must return true for the first element fulfilling the condition. It receives an object in the first parameter named $1.

The callback receives the following parameters:

  • in $1.value: element value to be evaluated
  • in $2: param
  • in $N...: paramN...

It can set the following parameter(s):

  • (mandatory if you used a method) $1.result (boolean): true if the element value matches the search condition, false otherwise.
  • $1.stop (boolean, optional): true to stop the method callback. The returned value is the last calculated.

By default, .findIndex() searches in the whole collection. Optionally, you can pass in startFrom the index of element from which to start the search.

  • If startFrom >= the collection's length, -1 is returned, which means the collection is not searched.
  • If startFrom < 0, it is considered as the offset from the end of the collection (startFrom = startFrom+length). Note: Even if startFrom is negative, the collection is still searched from left to right.
  • If startFrom == 0, the whole collection is searched (default).

Example

You want to find the position of the first city name within a collection:

var c : collection
var val2,val3 : integer
c = newCollection()
c.push(newObject("name","Cleveland","zc",35049))
c.push(newObject("name","Blountsville","zc",35031))
c.push(newObject("name","Adger","zc",35006))
c.push(newObject("name","Clanton","zc",35046))
c.push(newObject("name","Clanton","zc",35045))
val2 = c.findIndex(formula($1.value.name == $2),"Clanton") // val2: 3
val3 = c.findIndex(val2+1,formula($1.value.name == $2),"Clanton") //val3:4

.first()

.first() : any

ParameterTypeDescription
Resultany<-First element of collection

Description

The .first() function returns the first element of the collection.

This function does not modify the original collection.

The function returns Undefined if the collection is empty.

Example

var col, emptyCol : collection
var first : variant
col = newCollection(10, 20, 30, "hello", 50)
first = col.first() // 10

emptyCol = newCollection() //empty
// first = emptyCol[0] //would return error
first = emptyCol.first() // returns undefined

.flat()

.flat( { depth : integer } ) : collection

ParameterTypeDescription
depthinteger->How deep a nested collection structure should be flattened. Default = 1
Resultcollection<-Flattened collection

Description

The .flat() function creates a new collection with all sub-collection elements concatenated into it recursively up to the specified depth.

By default, if the depth parameter is omitted, only the first level of the nested collection structure will be flattened.

This function does not modify the original collection.

Example

col = newCollection(1, 2, newCollection(3, 4))
col.flat()
// [1, 2, 3, 4]

col = newCollection(1, 2, newCollection(3, 4, newCollection(5, 6)))
col.flat()
// [1, 2, 3, 4, [5, 6]]

col = newCollection(1, 2, newCollection(3, 4, newCollection(5, 6)))
col.flat(2)
// [1, 2, 3, 4, 5, 6]

col = newCollection(1, 2, newCollection(3, 4, 5, 6, newCollection(7, 8, newCollection(9, 10))))
col.flat(MAXLONG)
// [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

.flatMap()

.flatMap( formula : 4D.Function { , ...param : any } ) : collection
.flatMap( methodName : string { , ...param : any } ) : collection

ParameterTypeDescription
formula4D.Function->formula object
methodNamestring->Name of a method
paramany->Parameter(s) to pass to formula or methodName
Resultcollection<-Collection of transformed values and flattened by a depth of 1

Description

The .flatMap() function 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. Optionally, you can pass parameters to formula or methodName using the param parameter(s).

This function is identical to a map() call followed by a flat() call of depth 1.

This function does not modify the original collection.

You designate the callback to be executed to evaluate collection elements using either:

  • formula (recommended syntax), a formula object that can encapsulate any executable expressions, including functions and project methods,
  • or methodName, the name of a project method (string).

The callback is called with the parameter(s) passed in param (optional). The callback can perform any operation, with or without the parameter(s) and must return new transformed value to add to the resulting collection. It receives an object in first parameter named $1.

The callback receives the following parameters:

  • in $1.value: element value to be evaluated
  • in $2: param
  • in $N...: paramN...

It can set the following parameter(s):

  • (mandatory if you used a method) $1.result (any type): new transformed value to add to the resulting collection
  • $1.stop (boolean, optional): true to stop the method callback. The returned value is the last calculated.

Example 1

var col , result : collection
col = newCollection(1, 2, 3, 4)

result = col.map(formula(newCollection($1.value*2))
// [[2],[4],[6],[8]]

result = col.flatMap(formula(newCollection($1.value*2))
// [2,4,6,8]

Example 2

var col, result : collection
col = newCollection("Hello how", "", "are you ?")

result = col.map(formula(splitString($1.value, " ")))
// [["Hello", "how"], [], ["are", "you", "?"]]

result = col.flatMap(formula(splitString($1.value, " ")))
// ["Hello", "how", "are", "you", "?"]

Example 3

You want to compute the percentage of each value in the collection to the total:

var c, c2 : collection
var f : 4D.Function
c = newCollection(1, 4, 9, 10, 20)
f = formula(newCollection($1.value,round(($1.value/$2)*100, 2)))
c2 = c.flatMap(f, c.sum())
//c2: [1, 2.27, 4, 9.09,9, 20.45,10, 22.73, 20, 45.45]

.includes()

.includes( toSearch : expression { , startFrom : integer } ) : boolean

ParameterTypeDescription
toSearchexpression->Expression to search in the collection
startFrominteger->Index to start the search at
Resultboolean<-true if toSearch is found in the collection

Description

The .includes() function returns true if the toSearch expression is found among collection elements, otherwise False.

This function does not modify the original collection.

In toSearch, pass the expression to find in the collection. You can pass:

  • a scalar value (text, number, boolean, date),
  • the null value,
  • an object or a collection reference.

toSearch must match exactly the element to find (the same rules as for the equality operator of the data type are applied).

Optionally, you can pass the index of collection from which to start the search in startFrom.

  • If startFrom >= collection's length, False is returned, which means the collection is not searched.
  • If startFrom < 0, it is considered as the offset from the end of the collection (startFrom = startFrom+length). Note that even if startFrom is negative, the collection is still searched from left to right.
  • If startFrom == 0, the whole collection is searched (default).

Example

 var col : collection
var in : boolean
var obj : object
obj = newObject("value", 10)
col = newCollection(1,2,"Henry",5,3,"Albert",6,4,"Alan",5,obj)
in = col.includes(3) //true
in = col.includes(5,6) //true
in = col.includes("al@") //true
in = col.includes("Hello") //false
in = col.includes(obj) //true
in = col.includes(newObject("value", 10)) //false

.indexOf()

.indexOf( toSearch : expression { , startFrom : integer } ) : integer

ParameterTypeDescription
toSearchexpression->Expression to search in the collection
startFrominteger->Index to start the search at
Resultinteger<-Index of the first occurrence of toSearch in the collection, -1 if not found

Description

The .indexOf() function searches the toSearch expression among collection elements and returns the index of the first found occurrence, or -1 if it was not found.

This function does not modify the original collection.

In toSearch, pass the expression to find in the collection. You can pass:

  • a scalar value (string, number, boolean, date),
  • the null value,
  • an object or a collection reference.

toSearch must match exactly the element to find (the same rules as for the equality operator of the data type are applied).

Optionally, you can pass the index of collection from which to start the search in startFrom.

  • If startFrom >= the collection's length, -1 is returned, which means the collection is not searched.
  • If startFrom < 0, it is considered as the offset from the end of the collection (startFrom = startFrom+length). Note: Even if startFrom is negative, the collection is still searched from left to right.
  • If startFrom == 0, the whole collection is searched (default).

Example

 var col : collection
var i : integer
col = newCollection(1,2,"Henry",5,3,"Albert",6,4,"Alan",5)
i = col.indexOf(3) //i = 4
i = col.indexOf(5,5) //i = 9
i = col.indexOf("al@") //i = 5
i = col.indexOf("Hello") //i = -1

.indices()

.indices( queryString : string { , ...value : any } ) : collection

ParameterTypeDescription
queryStringstring->Search criteria
valueany->Value(s) to compare when using placeholder(s)
Resultcollection<-Element index(es) matching queryString in the collection

Description

The .indices() function works exactly the same as the .query() function but returns indexes, in the original collection, of object collection elements that match the queryString search conditions, and not elements themselves. Indexes are returned in ascending order.

This function does not modify the original collection.

The queryString parameter uses the following syntax:

propertyPath comparator value {logicalOperator propertyPath comparator value}

For a detailed description of the queryString and value parameters, please refer to the dataClass.query() function.

Example

 var c, icol : collection
c = newCollection()
c.push(newObject("name","Cleveland","zc",35049))
c.push(newObject("name","Blountsville","zc",35031))

c.push(newObject("name","Adger","zc",35006))
c.push(newObject("name","Clanton","zc",35046))
c.push(newObject("name","Clanton","zc",35045))
icol = c.indices("name = :1","Cleveland") // icol: [0]
icol = c.indices("zc > 35040") // icol: [0,3,4]

.insert()

.insert( index : integer , element : any ) : collection

ParameterTypeDescription
indexinteger->Where to insert the element
elementany->Element to insert in the collection
Resultcollection<-Original collection containing inserted element

Description

The .insert() function inserts element at the specified index position in the collection instance and returns the edited collection.

This function modifies the original collection.

In index, pass the position where you want the element to be inserted in the collection.

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

  • If index > the length of the collection, 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.

Any type of element accepted by a collection can be inserted, even another collection.

Example

 var col : collection
col = newCollection("a","b","c","d") //col:["a","b","c","d"]
col.insert(2,"X") //col:["a","b","X","c","d"]
col.insert(-2,"Y") //col:["a","b","X","Y","c","d"]
col.insert(-10,"Hi") //col:["Hi","a","b","X","Y","c","d"]

.join()

.join( delimiter : string { , option : integer } ) : string

ParameterTypeDescription
delimiterstring->Separator to use between elements
optioninteger->kIgnoreNullOrEmpty: ignore null and empty strings in the result
Resultstring<-String containing all elements of the collection, separated by delimiter

Description

The .join() function converts all elements of the collection to strings and concatenates them using the specified delimiter string as separator.The function returns the resulting string.

This function does not modify the original collection.

By default, null or empty elements of the collection are returned in the resulting string. Pass the kIgnoreNullOrEmpty constant in the option parameter if you want to remove them from the resulting string.

Example

 var c : collection
var t1,t2 : string
c = newCollection(1,2,3,"Paris",null,"",4,5)
t1 = c.join("|") //1|2|3|Paris|null||4|5
t2 = c.join("|",kIgnoreNullOrEmpty) //1|2|3|Paris|4|5

.last()

.last() : any

ParameterTypeDescription
Resultany<-Last element of collection

Description

The .last() function returns the last element of the collection.

This function does not modify the original collection.

The function returns undefined if the collection is empty.

Example

var col, emptyCol : collection
var last : variant
col = newCollection(10, 20, 30, "hello", 50)
last = col.last() // 50

emptyCol = newCollection() //empty
// last = emptyCol[emptyCol.length-1] //returns an error
last = emptyCol.last() // returns Undefined

.lastIndexOf()

.lastIndexOf( toSearch : expression { , startFrom : integer } ) : integer

ParameterTypeDescription
toSearchexpression->The element that is to be searched for within the collection
startFrominteger->Index to start the search at
Resultinteger<-Index of last occurrence of toSearch in the collection, -1 if not found

Description

The .lastIndexOf() function searches the toSearch expression among collection elements and returns the index of the last occurrence, or -1 if it was not found.

This function does not modify the original collection.

In toSearch, pass the expression to find in the collection. You can pass:

  • a scalar value (string, number, boolean, date),
  • the null value,
  • an object or a collection reference.

toSearch must match exactly the element to find (the same rules as for the equality operator are applied).

Optionally, you can pass the index of collection from which to start a reverse search in startFrom.

  • If startFrom >= the collection's length minus one (coll.length-1), the whole collection is searched (default).
  • If startFrom < 0, it is recalculated as startFrom = startFrom+length (it is considered as the offset from the end of the collection). If the calculated value is negative, -1 is returned (the collection is not searched). Note: Even if startFrom is negative, the collection is still searched from right to left.
  • If startFrom == 0, -1 is returned, which means the collection is not searched.

Example

 var col : collection
var pos1,pos2,pos3,pos4,pos5 : integer
col = splitString("a,b,c,d,e,f,g,h,i,j,e,k,e",",") //col.length: 13
pos1 = col.lastIndexOf("e") //returns 12
pos2 = col.lastIndexOf("e",6) //returns 4
pos3 = col.lastIndexOf("e",15) //returns 12
pos4 = col.lastIndexOf("e",-2) //returns 10
pos5 = col.lastIndexOf("x") //returns -1

.length

.length : integer

Description

The .length property returns the number of elements in the collection.

The .length property is initialized when the collection is created. Adding or removing elements updates the length, if necessary. This property is read-only (you cannot use it to set the size of the collection).

Example

 var col : collection //col.length initialized to 0
var vSize : integer
col = newCollection("one","two","three") //col.length updated to 3
col[4] = "five" //col.length updated to 5
vSize = col.remove(0,3).length //vSize: 2

.map()

.map( formula : 4D.Function { , ...param : any } ) : collection
.map( methodName : string { , ...param : any } ) : collection

ParameterTypeDescription
formula4D.Function->formula object
methodNamestring->Name of a method
paramany->Parameter(s) to pass to formula or methodName
Resultcollection<-collection of transformed values

Description

The .map() function 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. Optionally, you can pass parameters to formula or methodName using the param parameter(s). .map() always returns a collection with the same size as the original collection, except if $1.stop was used (see below).

This function does not modify the original collection.

You designate the callback to be executed to evaluate collection elements using either:

  • formula (recommended syntax), a formula object that can encapsulate any executable expressions, including functions and project methods,
  • or methodName, the name of a project method (text).

The callback is called with the parameter(s) passed in param (optional). The callback can perform any operation, with or without the parameter(s) and must return new transformed value to add to the resulting collection. It receives an object in first parameter, named $1.

The callback receives the following parameters:

  • in $1.value: element value to be evaluated
  • in $2: param
  • in $N...: paramN...

It can set the following parameter(s):

  • (mandatory if you used a method) $1.result (any type): new transformed value to add to the resulting collection
  • $1.stop (boolean, optional): true to stop the method callback. The returned value is the last calculated.

Example

var c, c2 : collection
c = newCollection(1, 4, 9, 10, 20)
c2 = c.map(formula(round(($1.value/$2)*100, 2)), c.sum())
//c2: [2.27,9.09,20.45,22.73,45.45]

.max()

.max( { propertyPath : string } ) : any

ParameterTypeDescription
propertyPathstring->object property path to be used for evaluation
Resultboolean, string, Number, collection, object, date<-Maximum value in the collection

Description

The .max() function returns the element with the highest value in the collection (the last element of the collection as it would be sorted in ascending order using the .sort() function).

This function does not modify the original collection.

If the collection contains different types of values, the .max() function will return the maximum value within the last element type in the type list order (see .sort() description).

If the collection contains objects, pass the propertyPath parameter to indicate the object property whose maximum value you want to get.

If the collection is empty, .max() returns undefined.

Example

 var col : collection
var max, maxSal, maxName : variant
col = newCollection(200,150,55)
col.push(newObject("name","Smith","salary",10000))
col.push(newObject("name","Wesson","salary",50000))
col.push(newObject("name","Alabama","salary",10500))
max = col.max() //{name:Alabama,salary:10500}
maxSal = col.max("salary") //50000
maxName = col.max("name") //"Wesson"

.min()

.min( { propertyPath : string } ) : any

ParameterTypeDescription
propertyPathstring->object property path to be used for evaluation
Resultboolean, string, Number, collection, object, date<-Minimum value in the collection

Description

The .min() function returns the element with the smallest value in the collection (the first element of the collection as it would be sorted in ascending order using the .sort() function).

This function does not modify the original collection.

If the collection contains different types of values, the .min() function will return the minimum value within the first element type in the type list order (see .sort() description).

If the collection contains objects, pass the propertyPath parameter to indicate the object property whose minimum value you want to get.

If the collection is empty, .min() returns undefined.

Example

 var col : collection
var min, minSal, minName : variant
col = newCollection(200,150,55)
col.push(newObject("name","Smith","salary",10000))
col.push(newObject("name","Wesson","salary",50000))
col.push(newObject("name","Alabama","salary",10500))
min = col.min() //55
minSal = col.min("salary") //10000
minName = col.min("name") //"Alabama"

.multiSort()

.multiSort() : collection
.multiSort( colsToSort : collection ) : collection
.multiSort( formula : 4D.Function , colsToSort : collection ) : collection

ParameterTypeDescription
formula4D.Function->Formula object
colsToSortcollection->Collection of collections and/or objects with {collection:colToSort,order:ck ascending or ck descending} properties
Resultcollection<-Original collection sorted

Description

The .multiSort() function enables you to carry out a multi-level synchronized sort on a set of collections.

This function modifies the original collection as well as all collections used in colsToSort parameter.

If .multiSort() is called with no parameters, the function has the same effect as the .sort() function: the collection is sorted (only scalar values) in ascending order by default, according to their type. If the collection contains values of different types, they are first grouped by type and sorted afterwards. Types are returned in the following order:

  1. null
  2. booleans
  3. strings
  4. numbers
  5. objects
  6. collections
  7. dates

Single-level synchronized sort

To sort several collections synchronously, just pass in colsToSort a collection of collections to sort. You can pass an unlimited number of collections. The original collection will be sorted in ascending order and all colsToSort collections will be sorted in a synchronized manner.

note

All colsToSort collections must have the same number of elements, otherwise an error is returned.

If you want to sort the collections in some other order than ascending, you must supply a formula (Formula object that defines the sort order. The return value should be a boolean that indicates the relative order of the two elements: true if $1.value is less than $1.value2, false if $1.value is greater than $1.value2. You can provide additional parameters to the formula if necessary.

The formula receives the following parameters:

  • $1 (object), where:
    • $1.value (any type): first element value to be compared
    • $1.value2 (any type): second element value to be compared
  • $2...$N (any type): extra parameters

Multi-level synchronized sort

Defining a multi-level synchronized sort requires that you pass an object containing {collection:colToSort,order:ck ascending or ck descending} properties instead of the colToSort itself for every collection to use as sub-level.

The sort levels are determined by the order in which the collections are passed in the colsToSort parameter: the position of a collection/order object in the syntax determines its sort level.

note

The .multiSort() function uses a stable sort algorithm.

Example 1

A simple synchronized sort of collections with different value types:

var col,col2,col3 : collection
col = ["A", "C", "B"]
col2 = [1, 2, 3]
col3 = [["Jim", "Philip", "Maria"], ["blue", "green"], ["11", 22, "33"]]

col.multiSort([col2 , col3])
//col : ["A","B","C"]
//col2 : [1,3,2]
//col3[0] : ["Jim","Philip","Maria"]
//col3[1] : ["11",22,"33"]
//col3[2] : ["blue","green"]

Example 2

You want to sort three synchronized collections: city, country, and continent. You want an ascending sort of the first and the third collections, and synchronization for the second collection:

var city, country, continent : collection

city = ["Paris", "Lyon", "Rabat", "Eching", "San Diego"]
country = ["France", "France", "Morocco", "Germany", "US"]
continent = ["Europe", "Europe", "Africa", "Europe", "America"]

continent.multiSort(country, {collection : city , order : ck ascending})
//continent : ["Africa", "America","Europe","Europe","Europe"]
//country : ["Morocco", "US","Germany","France","France"]
//city : ["Rabat","San Diego","Eching","Lyon","Paris"]

Example 3

You can also synchronize collections of objects.

var name, address : collection
name = []
name.push({firstname: "John", lastname: "Smith"})
name.push({firstname: "Alain", lastname: "Martin"})
name.push({firstname: "Jane", lastname: "Doe"})
name.push({firstname: "John", lastname: "Doe"})
address = []
address.push({city: "Paris", country: "France"})
address.push({city: "Lyon", country: "France"})
address.push({city: "Eching", country: "Germany"})
address.push({city: "Berlin", country: "Germany"})

name.multiSort(formula($1.value.firstname < $1.value2.firstname), [address])
//"Alain Martin","Jane Doe","John Smith","John Doe"
//"Lyon France","Eching Germany","Paris France","Berlin Germany"

.orderBy()

.orderBy() : collection
.orderBy( pathStrings : string ) : collection
.orderBy( pathobjects : collection ) : collection
.orderBy( ascOrDesc : integer ) : collection

ParameterTypeDescription
pathStringsstring->Property path(s) on which to order the collection
pathobjectscollection->collection of criteria objects
ascOrDescinteger->kAscending or kDescending (scalar values)
Resultcollection<-Ordered copy of the collection (shallow copy)

Description

The .orderBy() function returns a new collection containing all elements of the collection in the specified order.

This function returns a shallow copy, which means that objects or collections in both collections share the same reference. If the original collection is a shared collection, the returned collection is also a shared collection.

This function does not modify the original collection.

If you pass no parameter, the function orders scalar values in the collection in ascending order (other element types such as objects or collections are returned unordered). You can modify this automatic order by passing the kAscending or kDescending constants in the ascOrDesc parameter (see below).

You can also pass a criteria parameter to define how the collection elements must be sorted. Three syntaxes are supported for this parameter:

  • pathStrings: string (formula). Syntax: propertyPath1 {desc or asc}, propertyPath2 {desc or asc},... (default order: asc). pathStrings contains a formula made of 1 to x property paths and (optionally) sort orders, separated by commas. The order in which the properties are passed determines the sorting priority of the collection elements. By default, properties are sorted in ascending order. You can set the sort order of a property in the criteria string, separated from the property path by a single space: pass "asc" to sort in ascending order or "desc" in descending order.

  • pathobjects: collection. You can add as many objects in the pathobjects collection as necessary. By default, properties are sorted in ascending order ("descending" is false). Each element of the collection contains an object structured in the following way:

{
"propertyPath": string,
"descending": boolean
}
  • ascOrDesc: integer. You pass one of the following constants:

    ConstantValueComment
    kAscending0Elements are ordered in ascending order (default)
    kDescending1Elements are ordered in descending order

    This syntax orders scalar values in the collection only (other element types such as objects or collections are returned unordered).

If the collection contains elements of different types, they are first grouped by type and sorted afterwards. Types are returned in the following order:

  1. null
  2. booleans
  3. strings
  4. numbers
  5. objects
  6. collections
  7. dates

Example 1

Ordering a collection of numbers in ascending and descending order:

 var c, c2, c3 : collection
c = newCollection()
for(vCounter,1,10)
c.push(Random)
end
c2 = c.orderBy(kAscending)
c3 = c.orderBy(kDescending)

Example 2

Ordering a collection of objects based on a text formula with property names:

 var c, c2 : collection
c = newCollection()
for(vCounter,1,10)
c.push(newObject("id",vCounter,"value",random))
end
c2 = c.orderBy("value desc")
c2 = c.orderBy("value desc, id")
c2 = c.orderBy("value desc, id asc")

Ordering a collection of objects with a property path:

 var c, c2 : collection
c = newCollection()
c.push(newObject("name","Cleveland","phones",newObject("p1","01","p2","02")))
c.push(newObject("name","Blountsville","phones",newObject("p1","00","p2","03")))

c2 = c.orderBy("phones.p1 asc")

Example 3

Ordering a collection of objects using a collection of criteria objects:

 var crit, c, c2 : collection
crit = newCollection()
c = newCollection()
for(vCounter,1,10)
c.push(newObject("id",vCounter,"value",random))
end
crit.push(newObject("propertyPath","value","descending",true))
crit.push(newObject("propertyPath","id","descending",false))
c2 = c.orderBy(crit)

Ordering with a property path:

 var crit, c, c2 : collection
c = newCollection()
c.push(newObject("name","Cleveland","phones",newObject("p1","01","p2","02")))
c.push(newObject("name","Blountsville","phones",newObject("p1","00","p2","03")))
crit = newCollection(newObject("propertyPath","phones.p2","descending",true))
c2 = c.orderBy(crit)

.orderByMethod()

.orderByMethod( formula : 4D.Function { , ...extraParam : expression } ) : collection
.orderByMethod( methodName : string { , ...extraParam : expression } ) : collection

ParameterTypeDescription
formula4D.Function->formula object
methodNamestring->Name of a method
extraParamany->Parameter(s) to pass
Resultcollection<-Sorted copy of the collection (shallow copy)

Description

The .orderByMethod() function returns a new collection containing all elements of the collection in the order defined through the formula function or methodName method.

This function returns a shallow copy, which means that objects or collections in both collections share the same reference. If the original collection is a shared collection, the returned collection is also a shared collection.

This function does not modify the original collection.

You designate the callback to be executed to evaluate collection elements using either:

  • formula (recommended syntax), a formula object that can encapsulate any executable expressions, including functions and project methods,

  • or methodName, the name of a project method (string).

In the callback, pass some code that compares two values and returns true if the first value is lower than the second value. You can provide extraParam parameters to the callback if necessary.

The callback receives the following parameters:

  • $1 (object), where:
    • $1.value (any type): first element value to be compared
    • $1.value2 (any type): second element value to be compared
  • $2...$N (any type): extra parameters

If you used a method, it must set the following parameter:

  • $1.result (boolean): true if $1.value < $1.value2, false otherwise

Example 1

You want to sort a collection of strings in numerical order rather than alphabetical order:

 var c, c2, c3 : collection
c = newCollection()
c.push("33","4","1111","222")
c2 = c.orderBy() //c2: ["1111","222","33","4"], alphabetical order
c3 = c.orderByMethod(formula(num($1.value)<num($1.value2))) // c3: ["4","33","222","1111"]

Example 2

You want to sort a collection of strings on their length:

 var fruits, c2 : collection
fruits = newCollection("Orange","Apple","Grape","pear","Banana","fig","Blackberry","Passion fruit")
c2 = fruits.orderByMethod(formula(length(string($1.value))>length(string($1.value2))))
//c2:[Passion fruit,Blackberry,Orange,Banana,Apple,Grape,pear,fig]

Example 3

You want to sort a collection by character code or language:

var strings1, strings2 : collection
strings1 = newCollection("Alpha","Charlie","alpha","bravo","Bravo","charlie")

//using the character code:
strings2 = strings1.orderByMethod(formula(sortcollection),sk character codes)
// result : ["Alpha","Bravo","Charlie","alpha","bravo","charlie"]

//using the language:
strings2 = strings1.orderByMethod(formula(sortcollection),sk strict)
// result : ["alpha","Alpha","bravo","Bravo","charlie","Charlie"]

The sortcollection method:

var $1: object
var $2: integer // sort option

$1.result = (compareStrings($1.value,$1.value2,$2)<0)

.pop()

.pop() : any

ParameterTypeDescription
Resultany<-Last element of collection

Description

The .pop() function removes the last element from the collection and returns it as the function result.

This function modifies the original collection.

When applied to an empty collection, .pop() returns undefined.

Example

.pop(), used in conjunction with .push(), can be used to implement a first-in, last-out stack feature:

 var stack : collection
var result : variant
stack = newCollection() //stack:[]
stack.push(1,2) //[1,2]
result = stack.pop() //[1], returns 2
stack.push(newCollection(4,5)) //[1,[4,5]]
result = stack.pop() //[1], returns [4,5]
result = stack.pop() //[], returns 1

.push()

.push( element : any { ,...elementN } ) : collection

ParameterTypeDescription
elementany->Element(s) to add to the collection
Resultcollection<-Original collection containing added elements

Description

The .push() function appends one or more element(s) to the end of the collection instance and returns the edited collection.

This function modifies the original collection.

Example 1

 var col : collection
col = newCollection(1,2) //col:[1,2]
col.push(3) //[1,2,3]
col.push(6,newObject("firstname","John","lastname","Smith"))
//col:[1,2,3,6,{firstname:John,lastname:Smith}

Example 2

You want to sort the resulting collection:

 var col, sortedCol : collection
col = newCollection(5,3,9) //col:[5,3,9]
sortedCol = col.push(7,50).sort()
//col:[5,3,9,7,50]
//sortedCol:[3,5,7,9,50]

.query()

.query( queryString : string , ...value : any ) : collection
.query( queryString : string , querySettings : object ) : collection

ParameterTypeDescription
queryStringstring->Search criteria
valueany->Value(s) to compare when using placeholder(s)
querySettingsobject->Query options: parameters, attributes
Resultcollection<-Element(s) matching queryString in the collection

Description

The .query() function returns all elements of a collection of objects that match the search conditions defined by queryString and (optionally) value or querySettings. If the original collection is a shared collection, the returned collection is also a shared collection.

An empty collection is returned if the collection in which the query is executed does not contain the searched value.

This function does not modify the original collection.

queryString parameter

The queryString parameter uses the following syntax:

propertyPath comparator value {logicalOperator propertyPath comparator value}

where:

  • propertyPath: path of property on which you want to execute the query. This parameter can be a simple name (for example "country") or any valid attribute path (for example "country.name".) In case of an attribute path whose type is collection, [] notation is used to handle all the occurences (for example children[].age).
  • comparator: symbol that compares propertyPath and value. The following symbols are supported:

    ComparisonSymbol(s)Comment
    Equal to==, =Gets matching data, supports the wildcard (@), neither case-sensitive nor diacritic.
    ===, ISGets matching data, considers the @ as a standard character, neither case-sensitive nor diacritic
    Not equal to#, !=Supports the wildcard (@). Equivalent to "Not condition applied on a statement" (see below).
    !==, IS NOTConsiders the @ as a standard character
    Not condition applied on a statementNOTParenthesis are mandatory when NOT is used before a statement containing several operators. Equivalent to "Not equal to" (see below).
    Less than<
    Greater than>
    Less than or equal to<=
    Greater than or equal to>=
    Included inINGets data equal to at least one of the values in a collection or in a set of values, supports the wildcard (@)
  • value: the value to compare to the current value of the property of each element in the collection. It can be any constant value expression matching the element's data type property or a placeholder. When using a constant value, the following rules must be respected:

    • text type constant can be passed with or without simple quotes (see Using quotes below). To query a string within a string (a "contains" query), use the wildcard symbol (@) in value to isolate the string to be searched for as shown in this example: "@Smith@". The following keywords are forbidden for text constants: true, false.
    • boolean type constants: true or false (case sensitive).
    • numeric type constants: decimals are separated by a '.' (period).
    • date type constants: "YYYY-MM-DD" format
    • null constant: using the "null" keyword will find null and undefined properties.
    • in case of a query with an IN comparator, value must be a collection, or values matching the type of the attribute path between [] separated by commas (for strings, " characters must be escaped with \).
  • logicalOperator: used to join multiple conditions in the query (optional). You can use one of the following logical operators (either the name or the symbol can be used):

    ConjunctionSymbol(s)
    AND&, &&, and
    OR|,||, or

Using quotes

When you use quotes within queries, you must use single quotes ' ' inside the query and double quotes " " to enclose the whole query, otherwise an error is returned. For example:

"employee.name == 'smith' AND employee.firstname == 'john'"

Single quotes (') are not supported in searched values since they would break the query string. For example "comp.name == 'John's pizza' " will generate an error. If you need to search on values with single quotes, you may consider using placeholders (see below).

Using parenthesis

You can use parentheses in the query to give priority to the calculation. For example, you can organize a query as follows:

"(employee.age >= 30 OR employee.age <= 65) AND (employee.salary <= 10000 OR employee.status = 'Manager')"

Using placeholders

Qodly allows you to use placeholders for propertyPath and value arguments within the queryString parameter. A placeholder is a parameter that you insert in query strings and that is replaced by another value when the query string is evaluated. The value of placeholders is evaluated once at the beginning of the query; it is not evaluated for each element.

Two types of placeholders can be used: indexed placeholders and named placeholders.

  • Indexed placeholders: parameters are inserted as :paramIndex (for example ":1", ":2"...) in queryString and their corresponding values are provided by the sequence of value parameter(s). You can use up to 128 value parameters.

Example:

c = myCol.query(":1=:2" , "city" , "Chicago")
  • Named placeholders: parameters are inserted as :paramName (for example ":myparam") and their values are provided in the "attributes" and/or "parameters" objects in the querySettings parameter.

Example:

o.attributes = {att : "city"}
o.parameters = {name : "Chicago")
c = myCol.query(":att == :name" , o)

You can mix all argument kinds in queryString. A queryString can contain, for propertyPath and value parameters:

  • direct values (no placeholders),
  • indexed placeholders and/or named placeholders.

Using placeholders in queries is recommended for the following reasons:

  1. It prevents malicious code insertion: if you directly use user-filled variables within the query string, a user could modifiy the query conditions by entering additional query arguments. For example, imagine a query string like:
 vquery = "status == 'public' & name == "+myname //user enters their name
result = col.query(vquery)

This query seems secured since non-public data are filtered. However, if the user enters in the myname area something like "smith OR status='private', the query string would be modified at the interpretation step and could return private data.

When using placeholders, overriding security conditions is not possible:

 result = col.query("status == 'public' & name == :1" , myname)

In this case if the user enters smith OR status='private' in the myname area, it will not be interpreted in the query string, but only passed as a value. Looking for a person named "smith OR status='private'" will just fail.

  1. It prevents having to worry about formatting or character issues, especially when handling propertyPath or value parameters that might contain non-alphanumeric characters such as ".", "['...

  2. It allows the use of variables or expressions in query arguments. Examples:

result = col.query("address.city = :1 & name =:2" , city , myVar + "@")
result2 = col.query("company.name = :1" , "John's Pizzas")

Using a collection reference or object reference in the value parameter is not supported with this syntax. You must use the querySettings parameter.

Looking for null values

When you look for null values, you cannot use the placeholder syntax because the query engine considers null as an unexpected comparison value. For example, if you execute the following query:

vSingles = colPersons.query("spouse == :1" , null) // will NOT work

You will not get the expected result because the null value will be evaluated by Qodly as an error resulting from the parameter evaluation (for example, an attribute coming from another query). For these kinds of queries, you must use the direct query syntax:

vSingles = colPersons.query("spouse == null") //correct syntax

Object or collection reference as value

You can query a collection using an object reference or a collection reference as the value parameter to compare. The query will match objects in the collection that refer (point to) the same instance of object or collection.

The following comparators are supported:

ComparisonSymbol
Equal to==
Not equal to!=

To build a query with an object or a collection reference, you must use the querySettings parameter syntax. Example with an object reference:

var o1 = {a: 1}
var o2 = {a: 1} //same object but another reference
var o3 = o1 //same object and reference

var col, colResult : collection

col = [{o: o1} , {o: o2} , {o: o3}]
colResult = col.query("o = :v" , {parameters: {v: o3}})
//colResult.length=2
//colResult[0].o == o1 is true
//colResult[1].o == o1 is true

Example with a collection reference:


c1 = [1 , 2 , 3]
c2 = [1 , 2 , 3] //same collection but another reference
c3 = c1 //same collection and reference

col = [{c: c1} , {c: c2} , {c: c3}]
col2=col.query("c = :v" , {parameters: {v: c3}})
//col2.length=2
//col2[0].c == c1 is true
//col2[1].c == c1 is true

querySettings parameter

In the querySettings parameter, you can pass an object containing query placeholders as objects. The following properties are supported:

PropertyTypeDescription
parametersobjectNamed placeholders for values used in the queryString. Values are expressed as property / value pairs, where property is the placeholder name inserted for a value in the queryString (":placeholder") and value is the value to compare. You can mix indexed placeholders (values directly passed in value parameters) and named placeholder values in the same query.
attributesobjectNamed placeholders for attribute paths used in the queryString. Attributes are expressed as property / value pairs, where property is the placeholder name inserted for an attribute path in the queryString (":placeholder"), and value can be a string or a collection of strings. Each value is a path that can designate a property in an object of the collection
TypeDescription
stringattributePath expressed using the dot notation, e.g. "name" or "user.address.zipCode"
collection of stringsEach string of the collection represents a level of attributePath, e.g. ["name"] or ["user","address","zipCode"]. Using a collection allows querying on attributes with names that are not compliant with dot notation, e.g. ["Qodly1.1","en/fr"]
You can mix indexed placeholders (values directly passed in value parameters) and named placeholder values in the same query.

Using this parameter is mandatory if you want to query a collection using a collection reference or object reference.

Example 1

 var c, c2, c3 : collection
c = newCollection()
c.push(newObject("name","Cleveland","zc",35049))
c.push(newObject("name","Blountsville","zc",35031))
c.push(newObject("name","Adger","zc",35006))
c.push(newObject("name","Clanton","zc",35046))
c.push(newObject("name","Clanton","zc",35045))
c2 = c.query("name = :1","Cleveland") //c2:[{name:Cleveland,zc:35049}]
c3 = c.query("zc > 35040") //c3:[{name:Cleveland,zc:35049},{name:Clanton,zc:35046},{name:Clanton,zc:35045}]

Example 2

 var c : collection
c = newCollection()
c.push(newObject("name","Smith","dateHired",!22-05-2002!,"age",45))
c.push(newObject("name","Wesson","dateHired",!30-11-2017!))
c.push(newObject("name","Winch","dateHired",!16-05-2018!,"age",36))

c.push(newObject("name","Sterling","dateHired",!10-5-1999!,"age",null))
c.push(newObject("name","Mark","dateHired",!01-01-2002!))

This example returns persons whose name contains "in":

 col = c.query("name = :1","@in@")
//col:[{name:Winch...},{name:Sterling...}]

This example returns persons whose name does not begin with a string from a variable (entered by the user, for example):

 col = c.query("name  !=  :1",aString+"@")
//if astring = "W"
//col:[{name:Smith...},{name:Sterling...},{name:Mark...}]

This example returns persons whose age is not known (property set to null or undefined):

 col = c.query("age = null") //placeholders not allowed with "null"
//col:[{name:Wesson...},{name:Sterling...},{name:Mark...}]

This example returns persons hired more than 90 days ago:

 col = c.query("dateHired < :1",(currentDate-90))
//col:[{name:Smith...},{name:Sterling...},{name:Mark...}] if today is 01/10/2018
info

More examples of queries can be found in the dataClass.query() section.

.reduce()

.reduce( formula : 4D.Function { , initValue : any { , ...param : expression }} ) : any
.reduce( methodName : string { , initValue : any { , ...param : expression }} ) : any

ParameterTypeDescription
formula4D.Function->formula object
methodNamestring->Name of a method
initValuestring, Number, object, collection, date, boolean->Value to use as the first argument to the first call of formula or methodName
paramexpression->Parameter(s) to pass
Resultstring, Number, object, collection, date, boolean<-Result of the accumulator value

Description

The .reduce() function 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.

This function does not modify the original collection.

You designate the callback to be executed to evaluate collection elements using either:

  • formula (recommended syntax), a formula object that can encapsulate any executable expressions, including functions and project methods,
  • or methodName, the name of a project method (string).

The callback takes each collection element and performs any desired operation to accumulate the result into $1.accumulator, which is returned in $1.value.

You can pass the value to initialize the accumulator in initValue. If omitted, $1.accumulator starts with undefined.

The callback receives the following parameters:

  • in $1.value: element value to be processed
  • in $2: param
  • in $N...: paramN...

The callback sets the following parameter(s):

  • $1.accumulator: value to be modified by the function and which is initialized by initValue.
  • $1.stop (boolean, optional): true to stop the method callback. The returned value is the last calculated.

Example 1

var c : collection
c = newCollection(5,3,5,1,3,4,4,6,2,2)
r = c.reduce(formula($1.accumulator* = $1.value), 1) //returns 86400

Example 2

This example allows reducing several collection elements to a single one:

 var c,r : collection
c = newCollection()
c.push(newCollection(0,1))
c.push(newCollection(2,3))
c.push(newCollection(4,5))
c.push(newCollection(6,7))
r = c.reduce(formula(Flatten)) //r:[0,1,2,3,4,5,6,7]

With the following Flatten method:

 if($1.accumulator = null)
$1.accumulator = newCollection()
end
$1.accumulator.combine($1.value)

.reduceRight()

.reduceRight( formula : 4D.Function { , initValue : any { , ...param : expression }} ) : any
.reduceRight( methodName : string { , initValue : any { , ...param : expression }} ) : any

ParameterTypeDescription
formula4D.Function->formula object
methodNamestring->Name of a method
initValuestring, Number, object, collection, date, boolean->Value to use as the first argument to the first call of formula or methodName
paramexpression->Parameter(s) to pass
Resultstring, Number, object, collection, date, boolean<-Result of the accumulator value

Description

The .reduceRight() function 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.

This function does not modify the original collection.

You designate the callback to be executed to evaluate collection elements using either:

  • formula (recommended syntax), a formula object that can encapsulate any executable expressions, including functions and project methods,
  • or methodName, the name of a project method (string).

The callback takes each collection element and performs any desired operation to accumulate the result into $1.accumulator, which is returned in $1.value.

You can pass the value to initialize the accumulator in initValue. If omitted, $1.accumulator starts with undefined.

The callback receives the following parameters:

  • in $1.value: element value to be processed
  • in $2: param
  • in $N...: paramN...

The callback sets the following parameter(s):

  • $1.accumulator: value to be modified by the function and which is initialized by initValue.
  • $1.stop (boolean, optional): true to stop the method callback. The returned value is the last calculated.

Example 1

var c : collection
c = newCollection(5,3,5,1,3,4,4,6,2,2)
r = c.reduceRight(formula($1.accumulator* = $1.value), 1) //returns 86400

Example 2

This example allows reducing several collection elements to a single one:

 var c,r : collection
c = newCollection()
c.push(newCollection(0,1))
c.push(newCollection(2,3))
c.push(newCollection(4,5))
c.push(newCollection(6,7))
r = c.reduceRight(formula(Flatten)) //r:[6,7,4,5,2,3,0,1]

With the following Flatten method:

    //Flatten project method
if($1.accumulator = null)
$1.accumulator = newCollection()
end
$1.accumulator.combine($1.value)

.remove()

.remove( index : integer { , howMany : integer } ) : collection

ParameterTypeDescription
indexinteger->Element at which to start removal
howManyinteger->Number of elements to remove, or 1 element if omitted
Resultcollection<-Original collection without removed element(s)

Description

The .remove() function removes one or more element(s) from the specified index position in the collection and returns the edited collection.

This function modifies the original collection.

In index, pass the position where you want the element to be removed from the collection.

Warning: Keep in mind that collection elements are numbered from 0. If index is greater than the length of the collection, 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 < 0, index is set to 0.
  • If the calculated value > the length of the collection, index is set to the length.

In howMany, pass the number of elements to remove from index. If howMany is not specified, then one element is removed.

If you try to remove an element from an empty collection, the method does nothing (no error is generated).

Example

 var col : collection
col = newCollection("a","b","c","d","e","f","g","h")
col.remove(3) // ["a","b","c","e","f","g","h"]
col.remove(3,2) // ["a","b","c","g","h"]
col.remove(-8,1) // ["b","c","g","h"]
col.remove(-3,1) // ["b","g","h"]

.resize()

.resize( size : integer { , defaultValue : any } ) : collection

ParameterTypeDescription
sizeinteger->New size of the collection
defaultValueNumber, string, object, collection, date, boolean->Default value to fill new elements
Resultcollection<-Resized original collection

Description

The .resize() function sets the collection length to the specified new size and returns the resized collection.

This function modifies the original collection.

  • If size < collection length, exceeding elements are removed from the collection.
  • If size > collection length, the collection length is increased to size.

By default, new elements are filled will null values. You can specify the value to fill in added elements using the defaultValue parameter.

Example

 var c : collection
c = newCollection()
c.resize(10) // c:[null,null,null,null,null,null,null,null,null,null]

c = newCollection()
c.resize(10,0) // c:[0,0,0,0,0,0,0,0,0,0]

c = newCollection(1,2,3,4,5)
c.resize(10,newObject("name","X")) //c:[1,2,3,4,5,{name:X},{name:X},{name:X},{name:X},{name:X}]

c = newCollection(1,2,3,4,5)
c.resize(2) //c:[1,2]

.reverse()

.reverse() : collection

ParameterTypeDescription
Resultcollection<-Inverted copy of the collection

Description

The .reverse() function returns a deep copy of the collection with all its elements in reverse order. If the original collection is a shared collection, the returned collection is also a shared collection.

This function does not modify the original collection.

Example

 var c, c2 : collection
c = newCollection(1,3,5,2,4,6)
c2 = c.reverse() //c2:[6,4,2,5,3,1]

.shift()

.shift() : any

ParameterTypeDescription
Resultany<-First element of collection

Description

The .shift() function removes the first element of the collection and returns it as the function result.

This function modifies the original collection.

If the collection is empty, this function does nothing.

Example

 var c : collection
var val : variant
c = newCollection(1,2,4,5,6,7,8)
val = c.shift()
// val:1
// c:[2,4,5,6,7,8]

.slice()

.slice( startFrom : integer { , end : integer } ) : collection

ParameterTypeDescription
startFrominteger->Start index (included)
endinteger->End index (not included)
Resultcollection<-new collection containing sliced elements (shallow copy)

Description

The .slice() function returns a portion of a collection into a new collection, selected from startFrom index to end index (end not included). This function returns a shallow copy of the collection. If the original collection is a shared collection, the returned collection is also a shared collection.

This function does not modify the original collection.

The returned collection contains the element specified by startFrom and all subsequent elements up to, but not including, the element specified by end. If only the startFrom parameter is specified, the returned collection contains all elements from startFrom to the last element of the original collection.

  • If startFrom < 0, it is recalculated as startFrom = startFrom+length (it is considered as the offset from the end of the collection).
  • If the calculated value < 0, startFrom is set to 0.
  • If end < 0 , it is recalculated as end = end+length.
  • If end < startFrom (passed or calculated values), the method does nothing.

Example

 var c, nc : collection
c = newCollection(1,2,3,4,5)
nc = c.slice(0,3) //nc:[1,2,3]
nc = c.slice(3) //nc:[4,5]
nc = c.slice(1,-1) //nc:[2,3,4]
nc = c.slice(-3,-2) //nc:[3]

.some()

.some( { startFrom : integer , } formula : 4D.Function { , ...param : any } ) : boolean
.some( { startFrom : integer , } methodName : string { , ...param : any } ) : boolean

ParameterTypeDescription
startFrominteger->Index to start the test at
formula4D.Function->formula object
methodNamestring->Name of a method
paramMixed->Parameter(s) to pass
Resultboolean<-true if at least one element successfully passed the test

Description

The .some() function returns true if at least one element in the collection successfully passed a test implemented in the provided formula or methodName code.

You designate the QodlyScript code (callback) to be executed to evaluate collection elements using either:

  • formula (recommended syntax), a formula object that can encapsulate any executable expressions, including functions and project methods,
  • or methodName, the name of a project method (string).

The callback is called with the parameter(s) passed in param (optional). The callback can perform any test, with or without the parameter(s) and must return true for every element fulfilling the test. It receives an object in first parameter, named $1.

The callback receives the following parameters:

  • in $1.value: element value to be processed
  • in $2: param
  • in $N...: paramN...

It can set the following parameter(s):

  • (mandatory if you used a method) $1.result (boolean): true if the element value evaluation is successful, false otherwise.
  • $1.stop (boolean, optional): true to stop the method callback. The returned value is the last calculated.

In any case, at the point where .some() function encounters the first collection element returning true, it stops calling the callback and returns true.

By default, .some() tests the whole collection. Optionally, you can pass the index of an element from which to start the test in startFrom.

  • If startFrom >= the collection's length, False is returned, which means the collection is not tested.
  • If startFrom < 0, it is considered as the offset from the end of the collection.
  • If startFrom == 0, the whole collection is searched (default).

Example

You want to know if at least one collection value is >0.

 var c : collection
var b : boolean
c = newCollection()
c.push(-5,-3,-1,-4,-6,-2)
b = c.some(formula($1.value>0)) // b:false
c.push(1)
b = c.some(formula($1.value>0)) // b:true

c = newCollection()
c.push(1,-5,-3,-1,-4,-6,-2)
b = c.some(formula($1.value>0)) //b:true
b = c.some(1,formula($1.value>0)) //b:false

.sort()

.sort() : collection
.sort( formula : 4D.Function { , ...extraParam : any } ) : collection
.sort( methodName : string { , ...extraParam : any } ) : collection

ParameterTypeDescription
formula4D.Function->formula object
methodNamestring->Name of a method
extraParamany->Parameter(s) for the method
Resultcollection<-Original collection sorted

Description

The .sort() function sorts the elements of the original collection and also returns the sorted collection .

This function modifies the original collection.

If .sort() is called with no parameters, only scalar values (number, text, date, booleans) are sorted. Elements are sorted by default in ascending order, according to their type. If the collection contains elements of different types, they are first grouped by type and sorted afterwards. Types are returned in the following order:

  1. null
  2. booleans
  3. strings
  4. numbers
  5. objects
  6. collections
  7. dates

If you want to sort the collection elements in some other order or sort any type of element, you must supply in formula (formula object) or methodName (string) a callback that defines the sort order. The return value should be a boolean that indicates the relative order of the two elements: true if $1.value is less than $1.value2, false if $1.value is greater than $1.value2. You can provide additional parameters to the callback if necessary.

The callback receives the following parameters:

  • $1 (object), where:
    • $1.value (any type): first element value to be compared
    • $1.value2 (any type): second element value to be compared
  • $2...N (any type): extra parameters

If you used a method, you must set the following parameter:

  • $1.result (boolean): true if $1.value < $1.value2, false otherwise.

Example 1

 var col, col2 : collection
col = newCollection("Tom",5,"Mary",3,"Henry",1,"Jane",4,"Artie",6,"Chip",2)
col2 = col.sort() // col2:["Artie","Chip","Henry","Jane","Mary","Tom",1,2,3,4,5,6]
// col:["Artie","Chip","Henry","Jane","Mary","Tom",1,2,3,4,5,6]

Example 2

 var col, col2 : collection
col = newCollection(10,20)
col2 = col.push(5,3,1,4,6,2).sort() //col2:[1,2,3,4,5,6,10,20]

Example 3

var col, col2, col3 : collection
col = newCollection(33,4,66,1111,222)
col2 = col.sort() //numerical sort: [4,33,66,222,1111]
col3 = col.sort(formula(String($1.value)<String($1.value2))) //alphabetical sort: [1111,222,33,4,66]

.sum()

.sum( { propertyPath : string } ) : number

ParameterTypeDescription
propertyPathstring->object property path to be used for calculation
Resultnumber<-Sum of collection values

Description

The .sum() function returns the sum for all 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.

.sum() returns 0 if:

  • the collection is empty,
  • the collection does not contain numerical elements,
  • propertyPath is not found in the collection.

Example 1

 var col : collection
var vSum : number
col = newCollection(10,20,"Monday",true,2)
vSum = col.sum() //32

Example 2

 var col : collection
var vSum : number
col = newCollection()
col.push(newObject("name","Smith","salary",10000))
col.push(newObject("name","Wesson","salary",50000))
col.push(newObject("name","Gross","salary",10500,5))
vSum = col.sum("salary") //vSum:70500,5

.unshift()

.unshift( value : any { ,...valueN : any } ) : collection

ParameterTypeDescription
valuestring, Number, object, collection, date->Value(s) to insert at the beginning of the collection
Resultnumber<-collection containing added element(s)

|

Description

The .unshift() function inserts the given value(s) at the beginning of the collection and returns the modified collection.

This function modifies the original collection.

If several values are passed, they are inserted all at once, which means that they appear in the resulting collection in the same order as in the argument list.

Example

 var c : collection
c = newCollection(1,2)
c.unshift(4) // c:[4,1,2]
c.unshift(5) //c:[5,4,1,2]
c.unshift(6,7) // c:[6,7,5,4,1,2]