Version: Next

Collection

La classe Collection gère les variables de type Collection.

Une collection est initialisée avec :


New collection {( ...value : any )} : Collection crée une nouvelle collection vide ou préremplie
New shared collection {( ...value : any )} : Collection crée une nouvelle collection partagée vide ou préremplie

Exemple

 var $colVar : Collection //création d'une variable 4D de type collection
 $colVar:=New collection ///initialisation de la collection et assignation à la variable 4D

Sommaire


.at( index : Integer ) : any retourne l'élément à la position index, acceptant des entiers positifs et négatifs
.average( {propertyPath : Text } ) : Real retourne la moyenne arithmétique des valeurs définies dans l'instance de collection
.clear() : Collection supprime tous les éléments de l'instance de collection et retourne une collection vide
.combine( col2 : Collection {; index : Integer } ) : Collection insère col2 éléments à la fin ou à la position spécifiée par index dans l'instance de collection et retourne la collection modifiée
.concat( value : any { ;...valueN } ) : Collection retourne une nouvelle collection contenant les éléments de la collection d'origine avec tous les éléments du paramètre value ajoutés à la fin
.copy() : Collection .copy( option : Integer ) : Collection .copy( option : Integer ; groupWithCol : Collection ) : Collection .copy( option : Integer ; groupWithObj : Object ) : Collection renvoie une copie profonde (deep copy) de l'instance de collection
.count( { propertyPath : Text } ) : Real retourne le nombre d'éléments non nuls dans la collection
.countValues( value : any {; propertyPath : Text } ) : Real retourne le nombre d'occurences de value dans la collection
.distinct( {options : Integer} ) : Collection .distinct( propertyPath : Text {; options : Integer } ) : Collection renvoie une collection contenant uniquement les valeurs distinctes (différentes) de la collection originale
.equal( collection2 : Collection {; option : Integer } ) : Boolean recursively compares the contents of the collection and collection2 (deep comparison)
.every( { startFrom : Integer ; } formula : 4D.Function { ;...param : any } ) : Boolean .every( { startFrom : Integer ; } methodName : Text { ;...param : any } ) : Boolean returns true if all elements in the collection successfully passed a test implemented in the provided formula object or methodName method
.extract( propertyPath : Text { ; option : Integer } ) : Collection .extract( propertyPath : Text ; targetPath : Text { ;...propertyPathOrTargetPathN : Text } ) : Collection crée et renvoie une nouvelle collection contenant les valeurs propertyPath extraites de la collection originale d'objets
.fill( value : any ) : Collection .fill( value : any ; startFrom : Integer { ; end : Integer } ) : Collection remplit la collection avec la valeur spécifiée, éventuellement de l'index startFrom à l'index end, et renvoie la collection résultante
.filter( formula : 4D.Function { ; ...param : any } ) : Collection .filter( methodName : Text { ; ...param : any } ) : Collection retourne une nouvelle collection contenant tous les éléments de la collection d'origine pour lesquels le résultat de la formula ou de la méthode methodName est true
.find( { startFrom : Integer ; } formula : 4D.Function { ; ...param : any } ) : any .find( { startFrom : Integer ; } methodName : Text { ; ...param : any } ) : any retourne la première valeur dans la collection pour laquelle le résultat de formula ou de methodName, appliqué à chaque élément, retourne true
.findIndex( { startFrom : Integer ; } formula : 4D.Function { ; ...param : any } ) : Integer .findIndex( { startFrom : Integer ; } methodName : Text { ; ...param : any } ) : Integer retourne l'indice, dans la collection, du premier élément pour lequel formula ou methodName, appliqué à chaque élément, retourne true
.first() : any retourne le premier élément de la collection
.flat( { depth : Integer } ) : Collection crée une nouvelle collection avec tous les éléments des sous-collections concaténés de manière récursive jusqu'à la depth spécifiée
.flatMap( formula : 4D.Function { ; ...param : any } ) : Collection .flatMap( methodName : Text { ; ...param : any } ) : Collection crée une nouvelle collection basée sur le résultat de l'appel de la fonction 4D formula ou de la méthode methodName sur chaque élément de la collection d'origine et mise à plat sur une profondeur de 1
.includes( toSearch : expression { ; startFrom : Integer } ) : Boolean retourne True si l'expression toSearch est trouvée parmi les éléments de la collection, sinon False
.indexOf( toSearch : expression { ; startFrom : Integer } ) : Integer recherche l'expression toSearch parmi les éléments de la collection et retourne l'indice de la première occurrence trouvée, ou -1 si aucune occurrence n'a été trouvée
.indices( queryString : Text { ; ...value : any } ) : Collection returns indexes, in the original collection, of object collection elements that match the queryString search conditions
.insert( index : Integer ; element : any ) : Collection inserts element at the specified index position in the collection instance and returns the edited collection
.join( delimiter : Text { ; option : Integer } ) : Text converts all elements of the collection to strings and concatenates them using the specified delimiter string as separator
.last() : any returns the last element of the collection
.lastIndexOf( toSearch : expression { ; startFrom : Integer } ) : Integer searches the toSearch expression among collection elements and returns the index of the last occurrence
.length : Integer returns the number of elements in the collection
.map( formula : 4D.Function { ; ...param : any } ) : Collection .map( methodName : Text { ; ...param : any } ) : Collection creates a new collection based upon the result of the call of the formula 4D function or methodName method on each element of the original collection
.max( { propertyPath : Text } ) : any returns the element with the highest value in the collection
.min( { propertyPath : Text } ) : any returns the element with the smallest value in the collection
.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 : Text ) : Collection .orderBy( pathObjects : Collection ) : Collection .orderBy( ascOrDesc : Integer ) : Collection returns a new collection containing all elements of the collection in the specified order
.orderByMethod( formula : 4D.Function { ; ...extraParam : expression } ) : Collection .orderByMethod( methodName : Text { ; ...extraParam : expression } ) : Collection returns a new collection containing all elements of the collection in the order defined through the formula 4D function or methodName method
.pop() : any removes the last element from the collection and returns it as the function result
.push( element : any { ;...elementN } ) : Collection appends one or more element(s) to the end of the collection instance and returns the edited collection
.query( queryString : Text ) : Collection .query( queryString : Text ; ...value : any ) : Collection .query( queryString : Text ; querySettings : Object ) : Collection returns all elements of a collection of objects that match the search conditions
.reduce( formula : 4D.Function { ; initValue : any { ; ...param : expression }} ) : any .reduce( methodName : Text { ; initValue : any { ; ...param : expression }} ) : any applies the formula or methodName callback against an accumulator and each element in the collection (from left to right) to reduce it to a single value
.reduceRight( formula : 4D.Function { ; initValue : any { ; ...param : expression }} ) : any .reduceRight( methodName : Text { ; initValue : any { ; ...param : expression }} ) : any applies the formula or methodName callback against an accumulator and each element in the collection (from right to left) to reduce it to a single value
.remove( index : Integer { ; howMany : Integer } ) : Collection removes one or more element(s) from the specified index position in the collection and returns the edited collection
.resize( size : Integer { ; defaultValue : any } ) : Collection sets the collection length to the specified new size and returns the resized collection
.reverse( ) : Collection returns a deep copy of the collection with all its elements in reverse order
.shift() : any removes the first element of the collection and returns it as the function result
.slice( startFrom : Integer { ; end : Integer } ) : Collection returns a portion of a collection into a new collection
.some( { startFrom : Integer ; } formula : 4D.Function { ; ...param : any } ) : Boolean .some( { startFrom : Integer ; } methodName : Text { ; ...param : any } ) : Boolean returns true if at least one element in the collection successfully passed a test implemented in the provided formula or methodName code
.sort() : Collection .sort( formula : 4D.Function { ; ...extraParam : any } ) : Collection .sort( methodName : Text { ; ...extraParam : any } ) : Collection sorts the elements of the original collection and also returns the sorted collection
.sum( { propertyPath : Text } ) : Real returns the sum for all values in the collection instance
.unshift( value : any { ;...valueN : any } ) : Collection inserts the given value(s) at the beginning of the collection

`New collection`

New collection {( ...value : any )} : Collection

Paramètres	Type		Description
value	Number, Text, Date, Time, Boolean, Object, Collection, Picture, Pointer	->	Valeur(s) de collection
Résultat	Collection	<-	The new collection

Description

La commande New collection crée une nouvelle collection vide ou préremplie et retourne sa référence.

Si vous ne passez aucun paramètre, New collection crée une collection vide et retourne sa référence.

Vous devez affecter la référence retournée à une variable 4D de type Collection.

Optionnellement, vous pouvez préremplir la nouvelle collection en passant une ou plusieurs value(s) comme paramètre(s).

Sinon, vous pouvez ajouter ou modifier des éléments ultérieurement par affectation. Par exemple :

 myCol[10]:="Mon nouvel élément"

Si l'indice du nouvel élément est au-delà du dernier élément existant de la collection, la collection est automatiquement redimensionnée et tous les nouveaux éléments intermédiaires sont reçoivent la valeur null.

Vous pouvez passer n'importe quel nombre de valeurs de n'importe quel type pris en charge (number, text, date, picture, pointer, object, collection...). Contrairement aux tableaux, les collections peuvent mélanger des données de différents types.

Vous devez prêter attention aux problèmes de conversion suivants :

Si vous passez un pointeur, il est conservé "tel quel" ; il est évalué à l'aide de la commande JSON Stringify
Les dates sont stockées sous la forme de date « aaaa-mm-jj » ou des chaînes au format « AAAA-MM-JJTHH: ss.SSSZ: mm » , selon la configuration actuelle « dates à l'intérieur des objets » de la base de données. Lors de la conversion de dates 4D en texte avant de les stocker dans la collection, par défaut le programme prend en compte le fuseau horaire local. Vous pouvez modifier ce comportement en utilisant le sélecteur Dates inside objects de la commande SET DATABASE PARAMETER.
Si vous passez une heure, elle est stockée sous la forme d'un nombre de millisecondes (Réel).

Exemple 1

Vous souhaitez créer une nouvelle collection vide et l'assigner à une variable collection 4D :

 var $myCol : Collection
 $myCol:=New collection
  //$myCol=[]

Exemple 2

Vous souhaitez créer une collection pré-remplie :

 var $filledColl : Collection
 $filledColl:=New collection(33;"mike";"november";->myPtr;Current date)
  //$filledColl=[33,"mike","november","->myPtr","2017-03-28T22:00:00.000Z"]

Exemple 3

Vous souhaitez créer une nouvelle collection puis ajouter un élément :

 var $coll : Collection
 $coll:=New collection("a";"b";"c")
  //$coll=["a","b","c"]
 $coll[9]:="z" //ajouter un 10e élément avec la valeur "z"
 $vcolSize:=$coll.length //10
  //$coll=["a","b","c",null,null,null,null,null,null,"z"]

`New shared collection`

Historique

Release	Modifications
v16 R6	Ajout

New shared collection {( ...value : any )} : Collection

Paramètres	Type		Description
value	Number, Text, Date, Time, Boolean, Shared object, Shared collection	->	Valeur(s) de la collection partagée
Résultat	Collection	<-	The new shared collection

Description

La commande New shared collection crée une nouvelle collection partagée vide ou préremplie et retourne sa référence.

L'ajout d'un élément à cette collection à l'aide de l'opérateur d'assignation doit être entouré de la structure Use...End use, sinon une erreur est générée (cela n'est pas nécessaire lors de l'ajout d'éléments à l'aide de fonctions telles que push() ou map() car elles utilisent automatiquement une structure interne Use...End use). La lecture d'un élément sans structure Use...End use est cependant possible.

info

Pour plus d'informations sur les collections partagées, veuillez vous référer à la page Objets et collections partagés.

Si vous ne passez aucun paramètre, New shared collection crée une collection vide et retourne sa référence.

Vous devez affecter la référence retournée à une variable 4D de type Collection.

Optionnellement, vous pouvez préremplir la nouvelle collection partagée en passant une ou plusieurs value(s) comme paramètre(s). Sinon, vous pouvez ajouter ou modifier des éléments ultérieurement via l'assignation en notation objet (cf. exemple).

Si l'indice du nouvel élément est au-delà du dernier élément existant de la collection partagée, la collection est automatiquement redimensionnée et tous les nouveaux éléments intermédiaires reçoivent la valeur null.

Vous pouvez passer tout nombre de valeurs de n'importe quel type pris en charge :

nombre (réel, entier...). Les valeurs numériques sont toujours stockées sous forme de réels.
text
boolean
date
heure (stockée en nombre de milliseconds - réel)
Null
shared object(*)
shared collection(*)

note

Contrairement aux collections standard (non partagées), les collections partagées ne prennent pas en charge les images, les pointeurs et les objets ou collections non partagés.

(*)Lorsqu'un objet partagé ou une collection partagée est ajouté(e) à une collection partagée, ils partagent le même locking identifier. Pour plus d'informations sur ce point, reportez-vous à 4D Doc Center.

Exemple

 $mySharedCol:=New shared collection("alpha";"omega")
 Use($mySharedCol)
    $mySharedCol[1]:="beta"
 End use

.at()

Historique

Release	Modifications
20	Ajout

.at( index : Integer ) : any

Paramètres	Type		Description
index	Integer	->	Index de l'élément à renvoyer
Résultat	any	<-	L'élément à cet index

Description

La fonction .at() retourne l'élément à la position index, acceptant des entiers positifs et négatifs.

Les nombres entiers négatifs déterminent la position à partir du dernier élément de la collection.

La fonction renvoie Undefined si index est au-delà des limites de la collection.

Exemple

var $col : Collection
$col:=New collection(10; 20; 30; 40; 50)
$element:=$col.at(0) // 10
$element:=$col.at(1) // 20
$element:=$col.at(-1) // 50
$element:=$col.at(-2) // 40
$element:=$col.at(10) // undefined

.average()

Historique

Release	Modifications
v16 R6	Ajout

.average( {propertyPath : Text } ) : Real

Paramètres	Type		Description
propertyPath	Text	->	Chemin de propriété d'objet à utiliser pour évaluer les valeurs
Résultat	Real, Undefined	<-	Moyenne arithmétique des valeurs de la collection

Description

La fonction .average() retourne la moyenne arithmétique des valeurs définies dans l'instance de collection.

Seuls les éléments ayant une valeur numérique sont pris en compte pour le calcul (les autres types d'éléments sont ignorés).

Si la collection contient des objets, passez le paramètre propertyPath pour indiquer la propriété d'objet à prendre en compte.

.average() retourne undefined si:

la collection est vide,
la collection ne contient pas d'éléments numériques,
propertyPath n'est pas trouvé dans la collection.

Exemple 1

 var $col : Collection
 $col:=New collection(10;20;"Monday";True;6)
 $vAvg:=$col.average() //12

Exemple 2

 var $col : Collection
 $col:=New collection
 $col.push(New object("name";"Smith";"salary";10000))
 $col.push(New object("name";"Wesson";"salary";50000))
 $col.push(New object("name";"Gross";"salary";10500))
 $vAvg:=$col.average("salary") //23500

.clear()

Historique

Release	Modifications
v16 R6	Ajout

.clear() : Collection

Paramètres	Type		Description
Résultat	Collection	<-	Collection d'origine dont tous les éléments ont été supprimés

Description

La fonction .clear()supprime tous les éléments de l'instance de collection et retourne une collection vide.

Exemple

var $col : Collection
$col:=New collection(1;2;5)
$col.clear()
$vSize:=$col.length //$vSize=0

.combine()

Historique

Release	Modifications
v16 R6	Ajout

.combine( col2 : Collection {; index : Integer } ) : Collection

Paramètres	Type		Description
col2	Collection	->	Collection à combiner
index	Integer	->	Emplacement où insérer les éléments à combiner (défaut=length+1)
Résultat	Collection	<-	Collection d'origine incluant les éléments combinés

Description

La fonction .combine() insère col2 éléments à la fin ou à la position spécifiée par index dans l'instance de collection et retourne la collection modifiée. A la différence de la fonction .insert(), .combine() ajoute chaque valeur de col2 dans la collection d'origine, et non en tant qu'élément unique de collection.

Par défaut, les éléments col2 sont ajoutés à la fin de la collection originale. Vous pouvez passer dans index la position où vous souhaitez insérer les éléments col2 dans la collection.

Si index > la longueur de la collection, l'index de départ réel sera la longueur de la collection.
Si index < 0, il est recalculé comme index:=index+length (il est considéré comme décalage depuis la fin de la collection).
Si la valeur calculée est négative, index est défini à 0.

Exemple

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

.concat()

Historique

Release	Modifications
v16 R6	Ajout

.concat( value : any { ;...valueN } ) : Collection

Paramètres	Type		Description
value	Number, Text, Object, Collection, Date, Time, Boolean, Picture	->	Valeur(s) à concaténer. Si value est une collection, tous les éléments de la collection sont ajoutés à la collection d'origine
Résultat	Collection	<-	Nouvelle collection contenant les valeurs d'origine et les valeurs ajoutées

Description

La fonction .concat() retourne une nouvelle collection contenant les éléments de la collection d'origine avec tous les éléments du paramètre value ajoutés à la fin.

Si value est une collection, tous ses éléments sont ajoutés comme de nouveaux éléments à la fin de la collection d'origine. Si value n'est pas une collection, son contenu est ajouté comme nouvel élément.

Exemple

var $c : Collection
$c:=New collection(1;2;3;4;5)
$fruits:=New collection("Orange";"Banana";"Apple";"Grape")
$fruits.push(New object("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()

Historique

Release	Modifications
18 R3	New ck shared option. New groupWith parameters
v16 R6	Ajout

.copy() : Collection
.copy( option : Integer ) : Collection
.copy( option : Integer ; groupWithCol : Collection ) : Collection
.copy( option : Integer ; groupWithObj : Object ) : Collection

Paramètres	Type		Description
option	Integer	->	`ck resolve pointers`: résoudre les pointeurs avant la copie, `ck shared`: retourner une collection partagée
groupWithCol	Collection	->	Collection partagée à grouper avec la collection résultante
groupWithObj	Object	->	Objet partagé à grouper avec la collection résultante
Résultat	Collection	<-	Copie de la collection d'origine (deep copy)

Description

La fonction .copy() renvoie une copie profonde (deep copy) de l'instance de collection. Deep copy signifie que les objets ou les collections présents dans la collection d'origine sont dupliqués et ne partagent pas leur référence avec la collection qui est retournée.

S'il est passé, le paramètre option peut contenir l'une des constantes suivantes (ou les deux) :

option	Description
`ck resolve pointers`	Si la collection d'origine contient des valeurs de type pointeur, par défaut la copie contient également les pointeurs. Toutefois, vous pouvez résoudre les pointeurs au moment de la copie en passant la constante `ck resolve pointers`. Dans ce cas, chaque pointeur contenu dans la collection est évalué lors de la copie et sa valeur déréférencée est utilisée.
`ck shared`	Par défaut, `copy()` retourne une collection standard (non partagée), même si la commande est appliquée à une collection partagée. Passez la constante `ck shared` pour créer une collection partagée. Dans ce cas, vous pouvez utiliser le paramètre groupWith pour associer la collection partagée à une autre collection ou à un autre objet (voir ci-dessous).

Les paramètres groupWithCol ou groupWithObj vous permettent de désigner une collection ou un objet avec lequel la collection résultante doit être associée.

note

Les objets Datastore, dataclass et entity ne sont pas copiables. Si .copy() est appelé avec eux, les valeurs Null sont retournées.

Exemple 1

Nous souhaitons copier la collection régulière (non partagée) $lastnames dans l'objet partagé $sharedObject. Pour cela, nous devons créer une copie partagée de la collection ($sharedLastnames).

var $sharedObject : Object
var $lastnames;$sharedLastnames : Collection
var $text : Text

$sharedObject:=New shared object

$text:=Document to text(Get 4D folder(Current resources folder)+"lastnames.txt")
$lastnames:=JSON Parse($text) //$lastnames est un collection standard

$sharedLastnames:=$lastnames.copy(ck shared) //$sharedLastnames est une collection partagée

//Nous pouvons désormais placer $sharedLastnames dans $sharedObject
Use($sharedObject)
    $sharedObject.lastnames:=$sharedLastnames
End use

Exemple 2

Nous voulons combiner $sharedColl1 et $sharedColl2. Etant donné qu'ils appartiennent à différents groupes partagés, une combinaison directe pourrait générer une erreur. Par conséquent, nous devons faire une copie partagée de $sharedColl1 et désigner $sharedColl2 comme étant un groupe partagé pour la copie.

var $sharedColl1;$sharedColl2;$copyColl : Collection

$sharedColl1:=New shared collection(New shared object("lastname";"Smith"))
$sharedColl2:=New shared collection(New shared object("lastname";"Brown"))

//$copyColl appartient au nouveau groupe partagé comme $sharedColl2
 $copyColl:=$sharedColl1.copy(ck shared;$sharedColl2)
 Use($sharedColl2)
    $sharedColl2.combine($copyColl)
 End use

Exemple 3

Nous avons une collection standard ($lastnames) et nous souhaitons la placer dans le Storage de l'application. Pour cela, nous devons créer une copie partagée au préalable ($sharedLastnames).

var $lastnames;$sharedLastnames : Collection
var $text : Text

$text:=Document to text(Get 4D folder(Current resources folder)+"lastnames.txt")
$lastnames:=JSON Parse($text) //$lastnames est une collection standard

$sharedLastnames:=$lastnames.copy(ck shared) // copie partagée

Use(Storage)
    Storage.lastnames:=$sharedLastnames
End use

Exemple 4

Cet exemple illustre l'utilisation de l'option ck resolve pointers :

 var $col : Collection
 var $p : Pointer
 $p:=->$what

 $col:=New collection
 $col.push(New object("alpha";"Hello";"num";1))
 $col.push(New object("beta";"You";"what";$p))

 $col2:=$col.copy()
 $col2[1].beta:="World!"
 ALERT($col[0].alpha+" "+$col2[1].beta) //"Hello World!"

 $what:="You!"
 $col3:=$col2.copy(ck resolve pointers)
 ALERT($col3[0].alpha+" "+$col3[1].what) //"Hello You!"

.count()

Historique

Release	Modifications
v16 R6	Ajout

.count( { propertyPath : Text } ) : Real

Paramètres	Type		Description
propertyPath	Text	->	Chemin de propriété d'objet à utiliser pour évaluer les valeurs
Résultat	Real	<-	Nombre d'éléments dans la collection

Description

La fonction .count() retourne le nombre d'éléments non nuls dans la collection.

Si la collection contient des objets, vous pouvez passer le paramètre propertyPath. Dans ce cas, seuls les éléments qui contiennent le propertyPath sont pris en compte.

Exemple

 var $col : Collection
 var $count1;$count2 : Real
 $col:=New collection(20;30;Null;40)
 $col.push(New object("name";"Smith";"salary";10000))
 $col.push(New object("name";"Wesson";"salary";50000))
 $col.push(New object("name";"Gross";"salary";10500))
 $col.push(New object("lastName";"Henry";"salary";12000))
 $count1:=$col.count() //$count1=7
 $count2:=$col.count("name") //$count2=3

.countValues()

Historique

Release	Modifications
v16 R6	Ajout

.countValues( value : any {; propertyPath : Text } ) : Real

Paramètres	Type		Description
value	Text, Number, Boolean, Date, Object, Collection	->	Valeur à compter
propertyPath	Text	->	Chemin de propriété d'objet à utiliser pour évaluer les valeurs
Résultat	Real	<-	Nombre d'occurrences de la valeur

Description

La fonction .countValues() retourne le nombre d'occurences de value dans la collection.

Vous pouvez passer dans value :

une valeur scalaire (texte, numérique, booléen, date),
une référence d'objet ou de collection.

Pour qu'un élément soit comptabilisé, le type de value doit être égal à celui de l'élément ; la fonction utilise l'opérateur d'égalité.

Le paramètre optionnel propertyPath vous permet de compter des valeurs à l'intérieur d'une collection d'objets : passez dans propertyPath le chemin de la propriété dont vous souhaitez comptabiliser le nombre de valeurs.

Exemple 1

 var $col : Collection
 var $vCount : Integer
 $col:=New collection(1;2;5;5;5;3;6;4)
 $vCount:=$col.countValues(5) // $vCount=3

Exemple 2

 var $col : Collection
 var $vCount : Integer
 $col:=New collection
 $col.push(New object("name";"Smith";"age";5))
 $col.push(New object("name";"Wesson";"age";2))
 $col.push(New object("name";"Jones";"age";3))
 $col.push(New object("name";"Henry";"age";4))
 $col.push(New object("name";"Gross";"age";5))
 $vCount:=$col.countValues(5;"age") //$vCount=2

Exemple 3

 var $numbers; $letters : Collection
 var $vCount : Integer

 $letters:=New collection("a";"b";"c")
 $numbers:=New collection(1;2;$letters;3;4;5)

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

.distinct()

Historique

Release	Modifications
20	Support of `ck count values`
v16 R6	Ajout

.distinct( {options : Integer} ) : Collection
.distinct( propertyPath : Text {; options : Integer } ) : Collection

Paramètres	Type		Description
propertyPath	Text	->	Chemin de l'attribut dont vous souhaitez obtenir les valeurs distinctes
options	Integer	->	`ck diacritical`, `ck count values`
Résultat	Collection	<-	Nouvelle collection contenant uniquement les valeurs distinctes

Description

La fonction .distinct() renvoie une collection contenant uniquement les valeurs distinctes (différentes) de la collection originale.

La collection retournée est automatiquement triée. Les valeurs Null ne sont pas retournées.

Si la collection contient des objets, vous pouvez passer le paramètre propertyPath pour indiquer la propriété d'objet dont vous souhaitez obtenir les valeurs distinctes.

Dans le paramètre options, vous pouvez passer une ou une combinaison des constantes suivantes :

Constante	Valeur	Commentaire
`ck diacritical`	8	L'évaluation est sensible à la casse et différencie les caractères accentués. Par défaut si omis, une évaluation non diacritique est effectuée
`ck count values`	32	Renvoie le nombre d'éléments pour chaque valeur distincte. Lorsque cette option est passée, `.distinct()` renvoie une collection d'objets contenant une paire d'attributs `{"value":value;"count":count}`.

Exemples

 var $c; $c2; $c3 : Collection
 $c:=New collection
 $c.push("a";"b";"c";"A";"B";"c";"b";"b")
 $c.push(New object("size";1))
 $c.push(New object("size";3))
 $c.push(New object("size";1))
 $c2:=$c.distinct() //$c2=["a","b","c",{"size":1},{"size":3},{"size":1}]
 $c2:=$c.distinct(ck diacritical) //$c2=["a","A","b","B","c",{"size":1},{"size":3},{"size":1}]
 $c2:=$c.distinct("size") //$c2=[1,3]
 $c3:=$c.distinct("size";ck count values) //$c3=[{value:1,count:2},{value:3,count:1}]

.equal()

Historique

Release	Modifications
v16 R6	Ajout

.equal( collection2 : Collection {; option : Integer } ) : Boolean

Paramètres	Type		Description
collection2	Collection	->	Collection à comparer
option	Integer	->	`ck diacritical`: évaluation diacritique ("A" # "a" par exemple)
Résultat	Boolean	<-	Vrai si les collections sont identiques, sinon faux

Description

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

Par défaut, une évaluation non diacritique est effectuée. Si vous souhaitez que l'évaluation soit sensible à la casse ou pour différencier des caractères accentués, passez la constante ck diacritical dans le paramètre option.

note

A recursive comparison of collections can be time-consuming if the collection is large and deep. If you only want to compare two collection references, you may consider using the = comparison operator for collection references.

Exemple

 var $c; $c2 : Collection
 var $b : Boolean

 $c:=New collection(New object("a";1;"b";"orange");2;3)
 $c2:=New collection(New object("a";1;"b";"orange");2;3;4)
 $b:=$c.equal($c2) // false

 $c:=New collection(New object("1";"a";"b";"orange");2;3)
 $c2:=New collection(New object("a";1;"b";"orange");2;3)
 $b:=$c.equal($c2) // false

 $c:=New collection(New object("a";1;"b";"orange");2;3)
 $c2:=New collection(New object("a";1;"b";"ORange");2;3)
 $b:=$c.equal($c2) // true

 $c:=New collection(New object("a";1;"b";"orange");2;3)
 $c2:=New collection(New object("a";1;"b";"ORange");2;3)
 $b:=$c.equal($c2;ck diacritical) //false

.every()

Historique

Release	Modifications
19 R6	Prise en charge des formules
v16 R6	Ajout

.every( { startFrom : Integer ; } formula : 4D.Function { ;...param : any } ) : Boolean
.every( { startFrom : Integer ; } methodName : Text { ;...param : any } ) : Boolean

Paramètres	Type		Description
startFrom	Integer	->	Elément à partir duquel débuter l'évaluation
formula	4D.Function	->	Objet formule
methodName	Text	->	Nom de méthode
param	any	->	Paramètre(s) à passer à formula ou methodName
Résultat	Boolean	<-	Vrai si tous les éléments sont évalués à vrai

Description

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

Vous désignez le code de rétroappel (callback) à exécuter pour évaluer les éléments de la collection en utilisant soit :

formula (syntaxe recommandée), un objet Formula qui peut encapsuler toute expression exécutable, y compris des fonctions et des méthodes projet;
soit methodName, le nom d'une méthode projet (texte).

La callback est appelée avec le(s) paramètre(s) passé(s) dans param (facultatif). La callback peut effectuer n'importe quel test, avec ou sans le(s) paramètre(s) et doit retourner true pour chaque élément remplissant le test. Elle reçoit un Objet en premier paramètre ($1).

La callback reçoit les paramètres suivants :

dans $1.value : valeur de l'élément à évaluer
dans $2 : param
dans $N... : paramN...

Elle peut définir le(s) paramètre(s) suivant(s) :

(obligatoire si vous avez utilisé une méthode) $1.result (Boolean) : true si l'évaluation de la valeur de l'élément est réussie, false sinon.
$1.stop (booléen, optionnel) : true pour stopper le rétroappel de la méthode. La valeur retournée est la dernière calculée.

Dans tous les cas, au point où la fonction .every() rencontre le premier élément de la collection évalué à false, elle cesse d'appeler la callback et retourne false.

Par défaut, .every() évalue l'ensemble de la collection. Optionnellement, vous pouvez passer dans startFrom l'index de l'élément à partir duquel commencer le test.

Si startFrom >= la longueur de la collection, false est retourné, ce qui signifie que la collection n'est pas testée.
Si startFrom < 0, la fin de la collection est considérée comme point de départ du calcul de la position (startFrom:=startFrom+length).
Si startFrom = 0, l'ensemble de la collection est évalué (défaut).

Exemple 1

var $c : Collection  
var $b : Boolean
var $f : 4D.Function

$f:=Formula($1.value>0)
$c:=New collection
$c.push(5;3;1;4;6;2)
$b:=$c.every($f) // true
$c.push(-1)
$b:=$c.every($f) // false

Exemple 2

Cet exemple vérifie que tous les éléments de la collection sont de type réel :

var $c : Collection
var $b : Boolean
var $f : 4D.Function

$f:=Formula(Value type($1.value)=$2
$c:=New collection
$c.push(5;3;1;4;6;2)
$b:=$c.every($f;Is real) //$b=true
$c:=$c.push(New object("name";"Cleveland";"zc";35049))
$c:=$c.push(New object("name";"Blountsville";"zc";35031))
$b:=$c.every($f;Is real) //$b=false

.extract()

Historique

Release	Modifications
v16 R6	Ajout

.extract( propertyPath : Text { ; option : Integer } ) : Collection
.extract( propertyPath : Text ; targetPath : Text { ;...propertyPathOrTargetPathN : Text } ) : Collection

Paramètres	Type		Description
propertyPath	Text	->	Chemin de propriété d'objet dont les valeurs doivent être extraites dans la nouvelle collection
targetpath	Text	->	Chemin ou nom de propriété cible
option	Integer	->	`ck keep null` : inclure les propriétés null dans la collection retournée (ignorées par défaut). Paramètre ignoré si targetPath est passé.
Résultat	Collection	<-	Nouvelle collection contenant les valeurs extraites

Description

La fonction .extract() crée et renvoie une nouvelle collection contenant les valeurs propertyPath extraites de la collection originale d'objets.

Le contenu de la collection retournée dépend du paramètre targetPath :

Si le paramètre targetPath est omis, .extract() remplit la nouvelle collection avec les valeurs de propertyPath de la collection d'origine.
Par défaut, les éléments pour lesquels propertyPath est null ou indéfini sont ignorés dans la collection résultante. Vous pouvez passer la constante ck keep null dans le paramètre option pour inclure ces valeurs en tant qu'éléments null dans la collection retournée.
Si un ou plusieurs paramètre(s) targetPath sont passés (correspondant à un ou plusieurs paramètre(s) propertyPath), .extract() remplit la nouvelle collection avec les propriétés propertyPath et chaque élément de la nouvelle collection est un objet avec les propriétés targetPath remplies avec les propriétés propertyPath correspondantes. Les valeurs null sont conservées (le paramètre option est ignoré avec cette syntaxe).

Exemple 1

var $c : Collection
$c:=New collection
$c.push(New object("name";"Cleveland"))
$c.push(New object("zip";5321))
$c.push(New object("name";"Blountsville"))
$c.push(42)
$c2:=$c.extract("name") // $c2=[Cleveland,Blountsville]
$c2:=$c.extract("name";ck keep null) //$c2=[Cleveland,null,Blountsville,null]

Exemple 2

var $c : Collection
$c:=New collection
$c.push(New object("zc";35060))
$c.push(New object("name";Null;"zc";35049))
$c.push(New object("name";"Cleveland";"zc";35049))
$c.push(New object("name";"Blountsville";"zc";35031))
$c.push(New object("name";"Adger";"zc";35006))
$c.push(New object("name";"Clanton";"zc";35046))
$c.push(New object("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()

Historique

Release	Modifications
v16 R6	Ajout

.fill( value : any ) : Collection
.fill( value : any ; startFrom : Integer { ; end : Integer } ) : Collection

Paramètres	Type		Description
value	Number, Text, Object, Collection, Date, Boolean	->	Valeur de remplissage
startFrom	Integer	->	Numéro de l'élément de départ (inclus)
end	Integer	->	Position de fin (non incluse)
Résultat	collection	<-	Collection d'origine avec valeurs de remplissage

Description

La fonction .fill() remplit la collection avec la valeur spécifiée, éventuellement de l'index startFrom à l'index end, et renvoie la collection résultante.

Si le paramètre startFrom est omis, value est appliquée à tous les éléments de la collection (startFrom=0).
Si le paramètre startFrom est passé et end omis, value est appliquée aux éléments de la collection à partir de startFrom jusqu'au dernier élément de la collection (end=length).
Si à la fois le paramètre startFrom et end sont passés, value est appliquée aux éléments de la collection à partir de startFrom jusqu'à l'élément end.

En cas d'incohérence, les règles suivantes sont appliquées :

Si startFrom < 0, il est recalculé comme startFrom:=startFrom+length (il est considéré comme partant de la fin de la collection). Si la valeur calculée est négative, startFrom est défini à 0.
Si end < 0 , il est recalculé comme end:=end+length.
Si end < startFrom (valeurs passées ou recalculées), la méthode ne fait rien.

Exemple

 var $c : Collection
 $c:=New collection(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()

Historique

Release	Modifications
19 R6	Prise en charge des formules
v16 R6	Ajout

.filter( formula : 4D.Function { ; ...param : any } ) : Collection
.filter( methodName : Text { ; ...param : any } ) : Collection

Paramètres	Type		Description
formula	4D.Function	->	Objet formule
methodName	Text	->	Nom de méthode
param	any	->	Paramètre(s) à passer à formula ou methodName
Résultat	Collection	<-	Nouvelle collection contenant les éléments filtrés (shallow copy)

Description

La fonction .filter() retourne une nouvelle collection contenant tous les éléments de la collection d'origine pour lesquels le résultat de la formula ou de la méthode methodName est true. Cette fonction retourne une shallow copy, ce qui signifie que les objets ou les collections présents dans les deux collections partagent la même référence. Si la collection d'origine est une collection partagée, la collection retournée est également une collection partagée.

Vous désignez le code de rétroappel (callback) à exécuter pour filtrer les éléments de la collection en utilisant soit :

formula (syntaxe recommandée), un objet Formula qui peut encapsuler toute expression exécutable, y compris des fonctions et des méthodes projet;
soit methodName, le nom d'une méthode projet (texte).

La callback est appelée avec le(s) paramètre(s) passé(s) dans param (optionnel) et un objet en premier paramètre ($1). La callback peut effectuer n'importe quel test, avec ou sans le(s) paramètre(s) et doit retourner true pour chaque élément remplissant la condition et donc, devant être ajouté à la nouvelle collection.

La callback reçoit les paramètres suivants :

dans $1.value : valeur de l'élément à évaluer
dans $2 : param
dans $N... : paramN...

Elle peut définir le(s) paramètre(s) suivant(s) :

$1.result (Booléen) : true si la valeur de l'élément correspond à la condition de filtre et doit être conservée, false sinon.
$1.stop (booléen, optionnel) : true pour stopper le rétroappel de la méthode. La valeur retournée est la dernière calculée.

note

Lorsque vous utilisez methodName comme callback, et si la méthode ne renvoie aucune valeur, .filter() recherchera la propriété $1.result que vous devez définir à true pour chaque élément remplissant la condition.

Exemple 1

Vous voulez obtenir la collection des éléments de type texte dont la longueur est inférieure à 6 :

var $col;$colNew : Collection
$col:=New collection("hello";"world";"red horse";66;"tim";"san jose";"miami")
$colNew:=$col.filter(Formula((Value type($1.value)=Is text) && (Length($1.value)<$2)); 6)
  //$colNew=["hello","world","tim","miami"]

Exemple 2

Vous voulez filtrer les éléments de la collection en fonction de leur type :

 var $c;$c2;$c3 : Collection
 var $f : 4D.Function

 $f:=Formula(OB Get type($1;"value")=$2)
 $c:=New collection(5;3;1;4;6;2)
 $c.push(New object("name";"Cleveland";"zc";35049))
 $c.push(New object("name";"Blountsville";"zc";35031))
 $c2:=$c.filter($f;Is real) // $c2=[5,3,1,4,6,2]
 $c3:=$c.filter($f;Is object)
  // $c3=[{name:Cleveland,zc:35049},{name:Blountsville,zc:35031}]

.find()

Historique

Release	Modifications
19 R6	Prise en charge des formules
v16 R6	Ajout

.find( { startFrom : Integer ; } formula : 4D.Function { ; ...param : any } ) : any
.find( { startFrom : Integer ; } methodName : Text { ; ...param : any } ) : any

Paramètres	Type		Description
startFrom	Integer	->	Elément à partir duquel débuter la recherche
formula	4D.Function	->	Objet formule
methodName	Text	->	Nom de méthode
param	any	->	Paramètre(s) à passer à formula ou methodName
Résultat	any	<-	Première valeur trouvée (Undefined si non trouvée)

Description

La fonction .find() retourne la première valeur dans la collection pour laquelle le résultat de formula ou de methodName, appliqué à chaque élément, retourne true.

Vous désignez le code de rétroappel (callback) à exécuter pour évaluer les éléments de la collection en utilisant soit :

formula (syntaxe recommandée), un objet Formula qui peut encapsuler toute expression exécutable, y compris des fonctions et des méthodes projet;
soit methodName, le nom d'une méthode projet (texte).

La callback est appelée avec le(s) paramètre(s) passé(s) dans param (facultatif). La callback peut effectuer n'importe quel test, avec ou sans le(s) paramètre(s) et doit renvoyer true pour le premier élément qui satisfait la condition. Elle reçoit un Objet en premier paramètre ($1).

La callback reçoit les paramètres suivants :

dans $1.value : valeur de l'élément à évaluer
dans $2 : param
dans $N... : paramN...

Elle peut définir le(s) paramètre(s) suivant(s) :

(obligatoire si vous avez utilisé une méthode) $1.result (Boolean) : true si la valeur de l'élément correspond à la condition de recherche, false sinon.
$1.stop (booléen, optionnel) : true pour stopper le rétroappel de la méthode. La valeur retournée est la dernière calculée.

Par défaut, .find() effectue une recherche dans la totalité de la collection. Optionnellement, vous pouvez passer dans startFrom l'index de l'élément à partir duquel commencer la recherche.

Si startFrom >= la longueur de la collection, -1 est retourné, ce qui signifie que la recherche n'est pas effectuée.
Si startFrom < 0, la fin de la collection est considérée comme point de départ du calcul de la position (startFrom:=startFrom+length). Note: Même si startFrom est négatif, la collection est toujours recherchée de gauche à droite.
Si startFrom = 0, l'ensemble de la collection est évalué (défaut).

Exemple 1

Vous souhaitez obtenir le premier élément de texte dont la taille est inférieure à 5 caractères :

var $col : Collection
$col:=New collection("hello";"world";4;"red horse";"tim";"san jose")
$value:=$col.find(Formula((Value type($1.value)=Is text) && (Length($1.value)<$2)); 5) //$value="tim"

Exemple 2

Vous souhaitez trouver un nom de ville dans une collection :

var $c : Collection
var $c2 : Object
$c:=New collection
$c.push(New object("name"; "Cleveland"; "zc"; 35049))
$c.push(New object("name"; "Blountsville"; "zc"; 35031))
$c.push(New object("name"; "Adger"; "zc"; 35006))
$c.push(New object("name"; "Clanton"; "zc"; 35046))
$c.push(New object("name"; "Clanton"; "zc"; 35045))

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

.findIndex()

Historique

Release	Modifications
19 R6	Prise en charge des formules
v16 R6	Ajout

.findIndex( { startFrom : Integer ; } formula : 4D.Function { ; ...param : any } ) : Integer
.findIndex( { startFrom : Integer ; } methodName : Text { ; ...param : any } ) : Integer

Paramètres	Type		Description
startFrom	Integer	->	Elément à partir duquel débuter la recherche
formula	4D.Function	->	Objet formule
methodName	Text	->	Nom de méthode
param	any	->	Paramètre(s) à passer à formula ou methodName
Résultat	Integer	<-	Numéro du premier élément trouvé (-1 si non trouvé)

Description

La fonction .findIndex() retourne l'indice, dans la collection, du premier élément pour lequel formula ou methodName, appliqué à chaque élément, retourne true.

Vous désignez le code de rétroappel (callback) à exécuter pour évaluer les éléments de la collection en utilisant soit :

formula (syntaxe recommandée), un objet Formula qui peut encapsuler toute expression exécutable, y compris des fonctions et des méthodes projet;
soit methodName, le nom d'une méthode projet (texte).

La callback reçoit les paramètres suivants :

dans $1.value : valeur de l'élément à évaluer
dans $2 : param
dans $N... : paramN...

Elle peut définir le(s) paramètre(s) suivant(s) :

(obligatoire si vous avez utilisé une méthode) $1.result (Boolean) : true si la valeur de l'élément correspond à la condition de recherche, false sinon.
$1.stop (booléen, optionnel) : true pour stopper le rétroappel de la méthode. La valeur retournée est la dernière calculée.

Par défaut, .findIndex() effectue une recherche dans la totalité de la collection. Optionnellement, vous pouvez passer dans startFrom l'index de l'élément à partir duquel commencer la recherche.

Si startFrom >= la longueur de la collection, -1 est retourné, ce qui signifie que la recherche n'est pas effectuée.
Si startFrom < 0, la fin de la collection est considérée comme point de départ du calcul de la position (startFrom:=startFrom+length). Note: Même si startFrom est négatif, la collection est toujours recherchée de gauche à droite.
Si startFrom = 0, l'ensemble de la collection est évalué (défaut).

Exemple

Vous souhaitez trouver la position du premier nom de ville dans la collection :

var $c : Collection
var $val2;$val3 : Integer
$c:=New collection
$c.push(New object("name";"Cleveland";"zc";35049))
$c.push(New object("name";"Blountsville";"zc";35031))
$c.push(New object("name";"Adger";"zc";35006))
$c.push(New object("name";"Clanton";"zc";35046))
$c.push(New object("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()

Historique

Release	Modifications
20	Ajout

.first() : any

Paramètres	Type		Description
Résultat	any	<-	Premier élément de collection

Description

La fonction .first() retourne le premier élément de la collection.

La fonction renvoie Undefined si la collection est vide.

Exemple

var $col; $emptyCol : Collection
var $first : Variant
$col:=New collection(10; 20; 30; "hello"; 50)
$first:=$col.first() // 10

$emptyCol:=New collection() //vide
// $first:=$emptyCol[0] //retournerait une erreur
$first:=$emptyCol.first() // retourne Undefined

.flat()

Historique

Release	Modifications
20	Ajout

.flat( { depth : Integer } ) : Collection

Paramètres	Type		Description
depth	Integer	->	La profondeur à laquelle une structure de collection imbriquée doit être mise à plat. Par défaut=1
Résultat	Collection	<-	Collection mise à plat

Description

La fonction .flat() crée une nouvelle collection avec tous les éléments des sous-collections concaténés de manière récursive jusqu'à la depth spécifiée.

Par défaut, si le paramètre depth est omis, seul le premier niveau de la structure de la collection imbriquée sera mis à plat.

Exemple

$col:=New collection(1; 2; New collection(3; 4))
$col.flat()
// [1, 2, 3, 4]

$col:=New collection(1; 2; New collection(3; 4; New collection(5; 6)))
$col.flat()
// [1, 2, 3, 4, [5, 6]]

$col:=New collection(1; 2; New collection(3; 4; New collection(5; 6)))
$col.flat(2)
// [1, 2, 3, 4, 5, 6]

$col:=New collection(1; 2; New collection(3; 4; 5; 6; New collection(7; 8; New collection(9; 10))))
$col.flat(MAXLONG)
// [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

.flatMap()

Historique

Release	Modifications
20	Ajout

.flatMap( formula : 4D.Function { ; ...param : any } ) : Collection
.flatMap( methodName : Text { ; ...param : any } ) : Collection

Paramètres	Type		Description
formula	4D.Function	->	Objet formule
methodName	Text	->	Nom de méthode
param	any	->	Paramètre(s) à passer à formula ou methodName
Résultat	Collection	<-	Collection de valeurs transformées et mises à plat sur une profondeur de 1

Description

La fonction .flatMap() crée une nouvelle collection basée sur le résultat de l'appel de la fonction 4D formula ou de la méthode methodName sur chaque élément de la collection d'origine et mise à plat sur une profondeur de 1. Optionnellement, vous pouvez passer des paramètres à formula ou methodName en utilisant le(s) paramètre(s) param.

Cette fonction est identique à un appel à map() suivi d'un appel à flat() de profondeur 1.

Vous désignez le code de rétroappel (callback) à exécuter pour évaluer les éléments de la collection en utilisant soit :

formula (syntaxe recommandée), un objet Formula qui peut encapsuler toute expression exécutable, y compris des fonctions et des méthodes projet;
soit methodName, le nom d'une méthode projet (texte).

La callback est appelée avec le(s) paramètre(s) passé(s) dans param (facultatif). La callback peut effectuer n'importe quelle opération, avec ou sans le(s) paramètre(s), et doit renvoyer une nouvelle valeur transformée à ajouter à la collection résultante. Elle reçoit un Objet en premier paramètre ($1).

La callback reçoit les paramètres suivants :

dans $1.value : valeur de l'élément à évaluer
dans $2 : param
dans $N... : paramN...

Elle peut définir le(s) paramètre(s) suivant(s) :

(obligatoire si vous avez utilisé une méthode) $1.result (tout type) : nouvelle valeur transformée à ajouter à la collection résultante
$1.stop (booléen, optionnel) : true pour stopper le rétroappel de la méthode. La valeur retournée est la dernière calculée.

Exemple 1

var $col ; $result : Collection
$col:=New collection(1; 2; 3; 4)

$result:=$col.map(Formula(New collection($1.value*2))
 // [[2],[4],[6],[8]]

$result:=$col.flatMap(Formula(New collection($1.value*2))
// [2,4,6,8]

Exemple 2

var $col; $result : Collection
$col:=New collection("Hello how"; ""; "are you ?")

$result:=$col.map(Formula(Split string($1.value; " ")))
// [["Hello", "how"], [], ["are", "you", "?"]]

$result:=$col.flatMap(Formula(Split string($1.value; " ")))
// ["Hello", "how", "are", "you", "?"]

Exemple 3

Vous souhaitez calculer le pourcentage de chaque valeur de la collection par rapport au total :

var $c; $c2 : Collection
var $f : 4D.Function
$c:=New collection(1; 4; 9; 10; 20)
$f:=Formula(New collection($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()

Historique

Release	Modifications
20	Ajout

.includes( toSearch : expression { ; startFrom : Integer } ) : Boolean

Paramètres	Type		Description
toSearch	expression	->	Expression à rechercher dans la collection
startFrom	Integer	->	Elément à partir duquel débuter la recherche
Résultat	Boolean	<-	True si toSearch est trouvé dans la collection

Description

La fonction .includes() retourne True si l'expression toSearch est trouvée parmi les éléments de la collection, sinon False.

Dans toSearch, passez l'expression à trouver dans la collection. Vous pouvez passer :

une valeur scalaire (texte, numérique, booléen, date),
la valeur null,
une référence d'objet ou de collection.

toSearch doit correspondre exactement à l'élément à trouver (les mêmes règles que l'opérateur d'égalité du type de données sont appliquées).

Optionnellement, vous pouvez passer l'indice de la collection à partir duquel démarrer la recherche dans startFrom.

Si startFrom >= la longueur de la collection, False est retourné, ce qui signifie que la recherche n'est pas effectuée.
Si startFrom < 0, la fin de la collection est considérée comme point de départ du calcul de la position (startFrom:=startFrom+length). Notez que même si startFrom est négatif, la collection est toujours recherchée de gauche à droite.
Si startFrom = 0, l'ensemble de la collection est évalué (défaut).

Exemple

 var $col : Collection
 var $in : Boolean
 var $obj : Object
 $obj:=New object("value"; 10)
 $col:=New collection(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(New object("value"; 10)) //False

.indexOf()

Historique

Release	Modifications
v16 R6	Ajout

.indexOf( toSearch : expression { ; startFrom : Integer } ) : Integer

Paramètres	Type		Description
toSearch	expression	->	Expression à rechercher dans la collection
startFrom	Integer	->	Elément à partir duquel débuter la recherche
Résultat	Integer	<-	Numéro de la première occurrence de toSearch dans la collection, -1 si non trouvée

Description

La fonction .indexOf() recherche l'expression toSearch parmi les éléments de la collection et retourne l'indice de la première occurrence trouvée, ou -1 si aucune occurrence n'a été trouvée.

Dans toSearch, passez l'expression à trouver dans la collection. Vous pouvez passer :

une valeur scalaire (texte, numérique, booléen, date),
la valeur null,
une référence d'objet ou de collection.

toSearch doit correspondre exactement à l'élément à trouver (les mêmes règles que l'opérateur d'égalité du type de données sont appliquées).

Optionnellement, vous pouvez passer l'indice de la collection à partir duquel démarrer la recherche dans startFrom.

Si startFrom >= la longueur de la collection, -1 est retourné, ce qui signifie que la recherche n'est pas effectuée.
Si startFrom < 0, la fin de la collection est considérée comme point de départ du calcul de la position (startFrom:=startFrom+length). Note: Même si startFrom est négatif, la collection est toujours recherchée de gauche à droite.
Si startFrom = 0, l'ensemble de la collection est évalué (défaut).

Exemple

 var $col : Collection
 var $i : Integer
 $col:=New collection(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()

Historique

Release	Modifications
v16 R6	Ajout

.indices( queryString : Text { ; ...value : any } ) : Collection

Paramètres	Type		Description
queryString	Text	->	Critère(s) de recherche
value	any	->	Valeur(s) à comparer lors de l'utilisation de paramètre(s) dans la chaîne
Résultat	Collection	<-	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. Les positions sont retournées dans un ordre croissant.

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.

Exemple

 var $c; $icol : Collection
 $c:=New collection
 $c.push(New object("name";"Cleveland";"zc";35049))
 $c.push(New object("name";"Blountsville";"zc";35031))

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

.insert()

Historique

Release	Modifications
v16 R6	Ajout

.insert( index : Integer ; element : any ) : Collection

Paramètres	Type		Description
index	Integer	->	Où insérer l'élément
element	any	->	Elément à insérer dans la collection
Résultat	Collection	<-	Collection d'origine incluant l'élément inséré

Description

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

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

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).
Si la valeur recalculée est négative, index prend la valeur 0.

Vous pouvez passer tout type d'élément accepté par les collections, y compris une autre collection.

Exemple

 var $col : Collection
 $col:=New collection("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()

Historique

Release	Modifications
v16 R6	Ajout

.join( delimiter : Text { ; option : Integer } ) : Text

Paramètres	Type		Description
delimiter	Text	->	Séparateur à utiliser entre les éléments
option	Integer	->	`ck ignore null or empty`: ignore null and empty strings in the result
Résultat	Text	<-	Chaîne contenant tous les éléments de la collection, séparés par 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.

Par défaut, les éléments null ou vides de la collection sont inclus dans la chaîne résultante. Pass the ck ignore null or empty constant in the option parameter if you want to remove them from the resulting string.

Exemple

 var $c : Collection
 var $t1;$t2 : Text
 $c:=New collection(1;2;3;"Paris";Null;"";4;5)
 $t1:=$c.join("|") //1|2|3|Paris|null||4|5
 $t2:=$c.join("|";ck ignore null or empty) //1|2|3|Paris|4|5

.last()

Historique

Release	Modifications
20	Ajout

.last() : any

Paramètres	Type		Description
Résultat	any	<-	Dernier élément de collection

Description

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

La fonction renvoie Undefined si la collection est vide.

Exemple

var $col; $emptyCol : Collection
var $last : Variant
$col:=New collection(10; 20; 30; "hello"; 50)
$last:=$col.last() // 50

$emptyCol:=New collection() //empty
// $last:=$emptyCol[$emptyCol.length-1] //returns an error
$last:=$emptyCol.last() // returns Undefined

.lastIndexOf()

Historique

Release	Modifications
v16 R6	Ajout

.lastIndexOf( toSearch : expression { ; startFrom : Integer } ) : Integer

Paramètres	Type		Description
toSearch	expression	->	Elément à chercher dans la collection
startFrom	Integer	->	Elément à partir duquel débuter la recherche
Résultat	Integer	<-	Numéro de la dernière occurrence de toSearch dans la collection, -1 si non trouvé

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.

Dans toSearch, passez l'expression à trouver dans la collection. Vous pouvez passer :

une valeur scalaire (texte, numérique, booléen, date),
la valeur null,
une référence d'objet ou de collection.

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).
Si startFrom < 0, il est recalculé comme startFrom:=startFrom+length (il est considéré comme partant de la fin de la collection). Si la position calculée est négative, -1 est retourné (la collection n'est pas évaluée). 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.

Exemple

 var $col : Collection
 var $pos1;$pos2;$pos3;$pos4;$pos5 : Integer
 $col:=Split string("a,b,c,d,e,f,g,h,i,j,e,k,e";",") //$col.length=13
 $pos1:=$col.lastIndexOf("e") //retourne 12
 $pos2:=$col.lastIndexOf("e";6) //retourne 4
 $pos3:=$col.lastIndexOf("e";15) //retourne 12
 $pos4:=$col.lastIndexOf("e";-2) //retourne 10
 $pos5:=$col.lastIndexOf("x") //retourne -1

.length

Historique

Release	Modifications
v16 R5	Ajout

.length : Integer

Description

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

The .length property is initialized when the collection is created. Elle est automatiquement mise à jour en cas d'ajout ou de suppression d'éléments. This property is read-only (you cannot use it to set the size of the collection).

Exemple

 var $col : Collection //$col.length est initialisée à 0
 $col:=New collection("one";"two";"three") //$col.length est mise à jour et vaut 3
 $col[4]:="five" //$col.length vaut 5
 $vSize:=$col.remove(0;3).length //$vSize=2

.map()

Historique

Release	Modifications
19 R6	Prise en charge des formules
v16 R6	Ajout

.map( formula : 4D.Function { ; ...param : any } ) : Collection
.map( methodName : Text { ; ...param : any } ) : Collection

Paramètres	Type		Description
formula	4D.Function	->	Objet formule
methodName	Text	->	Nom de méthode
param	any	->	Paramètre(s) à passer à formula ou methodName
Résultat	Collection	<-	Collection de valeurs transformées

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. Optionnellement, vous pouvez passer des paramètres à formula ou methodName en utilisant le(s) paramètre(s) param. .map() always returns a collection with the same size as the original collection, except if $1.stop was used (see below).

Vous désignez le code de rétroappel (callback) à exécuter pour évaluer les éléments de la collection en utilisant soit :

formula (syntaxe recommandée), un objet Formula qui peut encapsuler toute expression exécutable, y compris des fonctions et des méthodes projet;
soit methodName, le nom d'une méthode projet (texte).

La callback reçoit les paramètres suivants :

dans $1.value : valeur de l'élément à évaluer
dans $2 : param
dans $N... : paramN...

Elle peut définir le(s) paramètre(s) suivant(s) :

(obligatoire si vous avez utilisé une méthode) $1.result (tout type) : nouvelle valeur transformée à ajouter à la collection résultante
$1.stop (booléen, optionnel) : true pour stopper le rétroappel de la méthode. La valeur retournée est la dernière calculée.

Exemple

var $c; $c2 : Collection
$c:=New collection(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()

Historique

Release	Modifications
v16 R6	Ajout

.max( { propertyPath : Text } ) : any

Paramètres	Type		Description
propertyPath	Text	->	Chemin de propriété d'objet à utiliser pour évaluer les valeurs
Résultat	Boolean, Text, Number, Collection, Object, Date	<-	Valeur maximum de la 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).

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.

Exemple

 var $col : Collection
 $col:=New collection(200;150;55)
 $col.push(New object("name";"Smith";"salary";10000))
 $col.push(New object("name";"Wesson";"salary";50000))
 $col.push(New object("name";"Alabama";"salary";10500))
 $max:=$col.max() //{name:Alabama,salary:10500}
 $maxSal:=$col.max("salary") //50000
 $maxName:=$col.max("name") //"Wesson"

.min()

Historique

Release	Modifications
v16 R6	Ajout

.min( { propertyPath : Text } ) : any

Paramètres	Type		Description
propertyPath	Text	->	Chemin de propriété d'objet à utiliser pour évaluer les valeurs
Résultat	Boolean, Text, Number, Collection, Object, Date	<-	Valeur minimum de la 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).

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.

Exemple

 var $col : Collection
 $col:=New collection(200;150;55)
 $col.push(New object("name";"Smith";"salary";10000))
 $col.push(New object("name";"Wesson";"salary";50000))
 $col.push(New object("name";"Alabama";"salary";10500))
 $min:=$col.min() //55
 $minSal:=$col.min("salary") //10000
 $minName:=$col.min("name") //"Alabama"

.multiSort()

Historique

Release	Modifications
20 R3	Ajout

.multiSort() : Collection
.multiSort( colsToSort : Collection ) : Collection
.multiSort( formula : 4D.Function ; colsToSort : Collection ) : Collection

Paramètres	Type		Description
formula	4D.Function	->	Objet formule
colsToSort	Collection	->	Collection of collections and/or objects with {`collection`:colToSort;`order`:`ck ascending` or `ck descending`} properties
Résultat	Collection	<-	Collection d'origine triée

Description

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

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. Si la collection contient des éléments de différents types, ils sont d'abord groupés par type et triés par la suite. Les types sont renvoyés dans l'ordre suivant :

Null
booléens
chaînes
nombres
objets
collections
dates

Tri synchronisé à un niveau

To sort several collections synchronously, just pass in colsToSort a collection of collections to sort. Vous pouvez passer un nombre illimité de 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. Vous pouvez passer des paramètres supplémentaires à la formule si nécessaire.

La formule reçoit les paramètres suivants :

$1 (object), où :
- $1.value (any type): first element value to be compared
- $1.value2 (any type): second element value to be compared
$2...$N (tout type) : paramètres supplémentaires (extraParam)

Tri synchronisé à plusieurs niveaux

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.

Exemple 1

Un simple tri synchronisé de collections avec différents types de valeurs :

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"]

Exemple 2

Vous souhaitez trier trois collections synchronisées : ville, pays et continent. Vous souhaitez un tri croissant des première et troisième collections, et une synchronisation pour la deuxième collection :

var $city : Collection
var $country : Collection
var $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","France","France","Germany"]
//$city=["Rabat","San Diego","Lyon","Paris","Eching"]

Exemple 3

Vous pouvez également synchroniser des collections d'objets.

var $name : Collection
var $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()

Historique

Release	Modifications
v16 R6	Ajout

.orderBy( ) : Collection
.orderBy( pathStrings : Text ) : Collection
.orderBy( pathObjects : Collection ) : Collection
.orderBy( ascOrDesc : Integer ) : Collection

Paramètres	Type		Description
pathStrings	Text	->	Chemin(s) de propriété(s) à utiliser pour trier la collection
pathObjects	Collection	->	Collection d'objets critère
ascOrDesc	Integer	->	`ck ascending` or `ck descending` (scalar values)
Résultat	Collection	<-	Copiée triée de la 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. Si la collection d'origine est une collection partagée, la collection retournée est également une collection partagée.

Si vous ne passez aucun paramètre, la fonction classe les valeurs scalaires de la collection dans un ordre croissant (les autres types d'éléments tels que les objets ou les collections sont renvoyés avec un ordre interne). You can modify this automatic order by passing the ck ascending or ck descending constants in the ascOrDesc parameter (see below).

Vous pouvez également passer des critères afin de configurer le tri des éléments de la collection. Trois syntaxes sont prises en charge pour ce paramètre :

pathStrings : Text (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. L'ordre dans lequel les propriétés sont passées détermine la priorité de tri des éléments de la collection. Par défaut, les propriétés sont triées pas ordre croissant. Vous pouvez définir l'ordre de tri de chaque propriété dans la formule de critère, séparée du chemin de propriété par un simple espace : passez "asc" pour trier par ordre croissant ou "desc" pour un ordre décroissant.
pathObjects : Collection. You can add as many objects in the pathObjects collection as necessary. Par défaut, les propriétés sont triées par ordre croissant ("descending" est faux). Chaque élément de la collection contient un objet structuré de la manière suivante :

{
    "propertyPath": string,

    "descending": boolean

}

ascOrDesc : Integer. You pass one of the following constants from the Objects and collections theme:
Constante Type Valeur Commentaire
ck ascending Longint 0 Les éléments sont triés par ordre croissant (défaut)
ck descending Longint 1 Les éléments sont triés par ordre décroissant
Cette syntaxe trie uniquement les valeurs scalaires de la collection (les autres types d'éléments comme les objets ou les collections sont retournés non triés).

Si la collection contient des éléments de différents types, ils sont d'abord groupés par type et triés par la suite. Les types sont renvoyés dans l'ordre suivant :

Null
booléens
chaînes
nombres
objets
collections
dates

Exemple 1

Tri d'une collection de nombres par ordre croissant ou décroissant :

 var $c; $c2; $c3 : Collection
 $c:=New collection
 For($vCounter;1;10)
    $c.push(Random)
 End for
 $c2:=$c.orderBy(ck ascending)
 $c3:=$c.orderBy(ck descending)

Exemple 2

Tri d'une collection d'objets basé sur une formule de texte avec noms de propriétés :

 var $c; $c2 : Collection
 $c:=New collection
 For($vCounter;1;10)
    $c.push(New object("id";$vCounter;"value";Random))
 End for
 $c2:=$c.orderBy("value desc")
 $c2:=$c.orderBy("value desc, id")
 $c2:=$c.orderBy("value desc, id asc")

Tri d'une collection d'objets sur des propriétés :

 var $c; $c2 : Collection
 $c:=New collection
 $c.push(New object("name";"Cleveland";"phones";New object("p1";"01";"p2";"02")))
 $c.push(New object("name";"Blountsville";"phones";New object("p1";"00";"p2";"03")))

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

Exemple 3

Tri d'une collection d'objets via une collection d'objets critères :

 var $crit; $c; $c2 : COllection
 $crit:=New collection
 $c:=New collection
 For($vCounter;1;10)
    $c.push(New object("id";$vCounter;"value";Random))
 End for
 $crit.push(New object("propertyPath";"value";"descending";True))
 $crit.push(New object("propertyPath";"id";"descending";False))
 $c2:=$c.orderBy($crit)

Tri avec un chemin de propriété :

 var $crit; $c; $c2 : Collection
 $c:=New collection
 $c.push(New object("name";"Cleveland";"phones";New object("p1";"01";"p2";"02")))
 $c.push(New object("name";"Blountsville";"phones";New object("p1";"00";"p2";"03")))
 $crit:=New collection(New object("propertyPath";"phones.p2";"descending";True))
 $c2:=$c.orderBy($crit)

.orderByMethod()

Historique

Release	Modifications
19 R6	Prise en charge des formules
v16 R6	Ajout

.orderByMethod( formula : 4D.Function { ; ...extraParam : expression } ) : Collection
.orderByMethod( methodName : Text { ; ...extraParam : expression } ) : Collection

Paramètres	Type		Description
formula	4D.Function	->	Objet formule
methodName	Text	->	Nom de méthode
extraParam	any	->	Paramètre(s) à passer
Résultat	Collection	<-	Copie triée de la collection (shallow copy)

Description

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

Vous désignez le code de rétroappel (callback) à exécuter pour évaluer les éléments de la collection en utilisant soit :

formula (syntaxe recommandée), un objet Formula qui peut encapsuler toute expression exécutable, y compris des fonctions et des méthodes projet;
soit methodName, le nom d'une méthode projet (texte).

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.

La callback reçoit les paramètres suivants :

$1 (object), où :
- $1.value (any type): first element value to be compared
- $1.value2 (any type): second element value to be compared
- $2...$N (tout type) : paramètres supplémentaires (extraParam)

Si vous avez utilisé une méthode, elle doit définir le paramètre suivant :

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

Exemple 1

Vous souhaitez trier une collection de chaînes contenant des nombres par valeur plutôt que par ordre alphabétique :

 var $c; $c2; $c3 : Collection
 $c:=New collection
 $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"]

Exemple 2

Vous souhaitez trier une collection de chaînes de caractères en fonction de leur longueur :

 var $fruits; $c2 : Collection
 $fruits:=New collection("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]

Exemple 3

Vous souhaitez trier une collection par code de caractère ou par langage :

var $strings1; $strings2 : Collection
$strings1:=New collection("Alpha";"Charlie";"alpha";"bravo";"Bravo";"charlie")

//utilisation du code de caractère:
$strings2:=$strings1.orderByMethod(Function(sortCollection);sk character codes)
// result : ["Alpha","Bravo","Charlie","alpha","bravo","charlie"]

//utilisation du langage:
$strings2:=$strings1.orderByMethod(Function(sortCollection);sk strict)
// result : ["alpha","Alpha","bravo","Bravo","charlie","Charlie"]

The sortCollection method:

var $1 : Object
var $2: Integer // sort option

$1.result:=(Compare strings($1.value;$1.value2;$2)<0)

.pop()

Historique

Release	Modifications
v16 R6	Ajout

.pop() : any

Paramètres	Type		Description
Résultat	any	<-	Dernier élément de collection

Description

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

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

Exemple

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

 var $stack : Collection
 $stack:=New collection //$stack=[]
 $stack.push(1;2) //$stack=[1,2]
 $stack.pop() //$stack=[1]  Returns 2
 $stack.push(New collection(4;5)) //$stack=[[1,[4,5]]
 $stack.pop() //$stack=[1]  Returns [4,5]
 $stack.pop() //$stack=[]  Returns 1

.push()

Historique

Release	Modifications
v16 R6	Ajout

.push( element : any { ;...elementN } ) : Collection

Paramètres	Type		Description
element	any	->	Élément(s) à ajouter à la collection
Résultat	Collection	<-	Collection originale contenant des éléments ajoutés

Description

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

Exemple 1

 var $col : Collection
 $col:=New collection(1;2) //$col=[1,2]
 $col.push(3) //$col=[1,2,3]
 $col.push(6;New object("firstname";"John";"lastname";"Smith"))
  //$col=[1,2,3,6,{firstname:John,lastname:Smith}

Exemple 2

Vous souhaitez trier la collection obtenue :

 var $col; $sortedCol : Collection
 $col:=New collection(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()

Historique

Release	Modifications
20 R6	Support of queries using object or collection references
17 R5	Prise en charge de querySettings
v16 R6	Ajout

.query( queryString : Text ) : Collection
.query( queryString : Text ; ...value : any ) : Collection
.query( queryString : Text ; querySettings : Object ) : Collection

Paramètres	Type		Description
queryString	Text	->	Critère(s) de recherche
value	any	->	Valeur(s) à comparer lors de l'utilisation de paramètre(s) dans la chaîne
querySettings	Object	->	Options de requête : paramètres, attributs
Résultat	Collection	<-	Élément(s) correspondant à queryString dans la 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. Si la collection d'origine est une collection partagée, la collection retournée est également une collection partagée.

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

paramètre queryString

The queryString parameter uses the following syntax:

propertyPath comparator value {logicalOperator propertyPath comparator value}

où :

propertyPath: path of property on which you want to execute the query. Ce paramètre peut contenir un nom simple (par exemple "pays") ou un chemin d'attribut valide (par exemple "pays.nom"). 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. Les symboles suivants sont pris en charge :

Comparaison	Symbole(s)	Commentaire
Egal à	=, ==	Retourne les données correspondantes, prend en charge le joker de recherche (@), ne tient pas compte de la casse et est non diacritique.
	===, IS	Retourne les données correspondantes, considère le @ comme un caractère standard, ne tient pas compte de la casse et est non diacritique
Différent de	#, !=	Prend en charge le joker de recherche (@). Equivalent to "Not condition applied on a statement" (see below).
	!==, IS NOT	Considère le @ comme un caractère standard
Condition Not appliquée à une assertion	NOT	Les parenthèses sont obligatoires lorsque NOT est utilisé avant une déclaration contenant plusieurs opérateurs. Equivalent to "Not equal to" (see below).
Inférieur à	<
Supérieur à	>
Inférieur ou égal à	<=
Supérieur ou égal à	> =
Inclus parmi	IN	Retourne les données égales à au moins une des valeurs d'une collection ou d'un ensemble de valeurs, prend en charge le joker de recherche (@)

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. Lorsque vous utilisez une valeur constante, les règles suivantes doivent être respectées :
- text type constant can be passed with or without simple quotes (see Using quotes below). Pour rechercher une chaîne dans une chaîne (recherche de type "contient"), utilisez le symbole joker (@) dans valeur pour isoler la chaîne à chercher, comme dans cet exemple : "@Smith@". Les mots-clés suivants sont interdits pour des constantes de type texte : 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). Vous pouvez utiliser un des opérateurs logiques suivants (le nom ou le symbole peut être passé) :

Conjonction	Symbole(s)
AND	&, &&, and
OU	\|,\|\|, or

Utilisation de guillemets

Lorsque vous utilisez des guillemets dans des recherches, vous devez utiliser des guillemets simples ' ' à l'intérieur de la requête et des guillemets doubles " " pour encadrer la requête, sinon une erreur est renvoyée. Par exemple :

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

Utilisation de parenthèses

Vous pouvez utiliser des parenthèses dans la recherche afin de prioriser les calculs. Par exemple, vous pouvez organiser une recherche de la manière suivante :

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

Utilisation de placeholders

4D allows you to use placeholders for propertyPath and value arguments within the queryString parameter. Un placeholder est un paramètre que vous insérez dans des chaines de recherche et qui est remplacé par une autre valeur au moment où la chaîne de recherche est évaluée. La valeur des placeholders est évaluée une seule fois, au début de la requête ; elle n'est pas évaluée pour chaque élément.

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.

Voici un exemple :

$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.

Voici un exemple :

$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:

des valeurs directes (pas de placeholders)
des placeholders indexés et/ou nommés.

Using placeholders in queries is recommended for the following reasons:

Cela empêche l'injection de code malveillant : si vous utilisez dans la chaîne de recherche des variables dont le contenu provient directement de la saisie de l'utilisateur, celui-ci pourrait modifier les conditions de recherche en saisissant des arguments de recherche supplémentaires. Par exemple, imaginez une chaîne de recherche du type :

 $vquery:="status = 'public' & name = "+myname //user enters their name
 $result:=$col.query($vquery)

Cette recherche semble sécurisée puisque les données non publiques sont filtrées. 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.

Lorsque vous utilisez des placeholders, le contournement des options de sécurité n'est pas 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. La recherche d'une personne nommée "smith OR status='private"' échouera simplement.

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 ".", "['...
Cela permet l'utilisation de variables ou d'expressions dans les arguments de recherche. Exemples :

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

Recherche de valeurs null

Lorsque vous recherchez les valeurs null, vous ne pouvez pas utiliser la syntaxe placeholder car le moteur de recherche considère la valeur null comme une valeur de comparaison invalide. Par exemple, si vous exécutez la recherche suivante :

$vSingles:=$colPersons.query("spouse = :1";Null) // will NOT work

Vous n'obtiendrez pas le résultat souhaité car la valeur null sera évaluée par 4D comme une erreur résultant de l'évaluation du paramètre (pouvant être, par exemple, un attribut provenant d'une autre recherche). Pour ce type de recherche, vous devez utiliser la syntaxe de recherche directe :

$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:

Comparaison	Symbole(s)
Egal à	=, ==
Différent de	#, !=

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

Paramètre querySettings

In the querySettings parameter, you can pass an object containing query placeholders as objects. Les propriétés suivantes sont prises en charge :

Propriété

Type

Description

parameters

Object

Named 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. Vous pouvez combiner, dans une même recherche, des placeholders indexés (valeurs passées directement dans les paramètres value) et les valeurs des placeholders nommés.

attributes

Object

Named 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

Type	Description
String	attributePath expressed using the dot notation, e.g. "name" or "user.address.zipCode"
Collection of strings	Each 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. ["4Dv17.1","en/fr"]

You can mix indexed placeholders (values directly passed in value parameters) and named placeholder values in the same query.

Exemple 1

 var $c; $c2; $c3 : Collection
 $c:=New collection
 $c.push(New object("name";"Cleveland";"zc";35049))
 $c.push(New object("name";"Blountsville";"zc";35031))
 $c.push(New object("name";"Adger";"zc";35006))
 $c.push(New object("name";"Clanton";"zc";35046))
 $c.push(New object("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}]

Exemple 2

 var $c : Collection
 $c:=New collection
 $c.push(New object("name";"Smith";"dateHired";!22-05-2002!;"age";45))
 $c.push(New object("name";"Wesson";"dateHired";!30-11-2017!))
 $c.push(New object("name";"Winch";"dateHired";!16-05-2018!;"age";36))

 $c.push(New object("name";"Sterling";"dateHired";!10-5-1999!;"age";Null))
 $c.push(New object("name";"Mark";"dateHired";!01-01-2002!))

Cet exemple renvoie les personnes dont le nom contient "in" :

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

Cet exemple retourne des personnes dont le nom ne commence pas par une chaine dont la valeur provient d'une variable (saisie par l'utilisateur, par exemple) :

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

Cet exemple retourne des personnes dont l'âge n'est pas connu (propriété définie sur null ou indéfinie) :

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

Cet exemple retourne des personnes embauchées il y a plus de 90 jours :

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

Exemple 3

Recherche avec des dates :

$entitySelection:=ds.Employee.query("birthDate > :1";"1970-01-01")
$entitySelection:=ds.Employee.query("birthDate <= :1";Current date-10950)

info

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

.reduce()

Historique

Release	Modifications
19 R6	Prise en charge des formules
v16 R6	Ajout

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

Paramètres	Type		Description
formula	4D.Function	->	Objet formule
methodName	Text	->	Nom de méthode
initValue	Text, Number, Object, Collection, Date, Boolean	->	Value to use as the first argument to the first call of formula or methodName
param	expression	->	Paramètre(s) à passer
Résultat	Text, Number, Object, Collection, Date, Boolean	<-	Résultat de la valeur de l'accumulateur

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.

Vous désignez le code de rétroappel (callback) à exécuter pour évaluer les éléments de la collection en utilisant soit :

formula (syntaxe recommandée), un objet Formula qui peut encapsuler toute expression exécutable, y compris des fonctions et des méthodes projet;
soit methodName, le nom d'une méthode projet (texte).

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.

La callback reçoit les paramètres suivants :

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

Elle peut définir le(s) paramètre(s) suivant(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. La valeur retournée est la dernière calculée.

Exemple 1

var $c : Collection
$c:=New collection(5;3;5;1;3;4;4;6;2;2)
$r:=$c.reduce(Formula($1.accumulator*=$1.value); 1)  //retourne 86400

Exemple 2

Cet exemple permet de réduire plusieurs éléments de collection à un seul :

 var $c;$r : Collection
 $c:=New collection
 $c.push(New collection(0;1))
 $c.push(New collection(2;3))
 $c.push(New collection(4;5))
 $c.push(New collection(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:=New collection
 End if
 $1.accumulator.combine($1.value)

.reduceRight()

Historique

Release	Modifications
20	Ajout

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

Paramètres	Type		Description
formula	4D.Function	->	Objet formule
methodName	Text	->	Nom de méthode
initValue	Text, Number, Object, Collection, Date, Boolean	->	Value to use as the first argument to the first call of formula or methodName
param	expression	->	Paramètre(s) à passer
Résultat	Text, Number, Object, Collection, Date, Boolean	<-	Résultat de la valeur de l'accumulateur

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.

Vous désignez le code de rétroappel (callback) à exécuter pour évaluer les éléments de la collection en utilisant soit :

formula (syntaxe recommandée), un objet Formula qui peut encapsuler toute expression exécutable, y compris des fonctions et des méthodes projet;
soit methodName, le nom d'une méthode projet (texte).

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.

La callback reçoit les paramètres suivants :

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

Elle peut définir le(s) paramètre(s) suivant(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. La valeur retournée est la dernière calculée.

Exemple 1

var $c : Collection
$c:=New collection(5;3;5;1;3;4;4;6;2;2)
$r:=$c.reduceRight(Formula($1.accumulator*=$1.value); 1)  //returns 86400

Exemple 2

Cet exemple permet de réduire plusieurs éléments de collection à un seul :

 var $c;$r : Collection
 $c:=New collection
 $c.push(New collection(0;1))
 $c.push(New collection(2;3))
 $c.push(New collection(4;5))
 $c.push(New collection(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:=New collection
 End if
 $1.accumulator.combine($1.value)

.remove()

Historique

Release	Modifications
v16 R6	Ajout

.remove( index : Integer { ; howMany : Integer } ) : Collection

Paramètres	Type		Description
index	Integer	->	Élément à partir duquel la suppression peut commencer
howMany	Integer	->	Nombre d'éléments à supprimer, ou 1 élément si omis
Résultat	Collection	<-	Collection d'origine sans élément(s) supprimé(s)

Description

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

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

Si index < 0, il est recalculé comme index:=index+length (il est considéré comme décalage depuis la fin de la 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.

Si vous essayez de supprimer un élément d'une collection vide, la méthode ne fait rien (aucune erreur n'est générée).

Exemple

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

.resize()

Historique

Release	Modifications
v16 R6	Ajout

.resize( size : Integer { ; defaultValue : any } ) : Collection

Paramètres	Type		Description
size	Integer	->	Nouvelle taille de la collection
defaultValue	Number, Text, Object, Collection, Date, Boolean	->	Valeur par défaut pour remplir de nouveaux éléments
Résultat	Collection	<-	Collection d'origine redimensionnée

Description

The .resize() function sets the collection length to the specified new size and returns the resized 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.

Exemple

 var $c : Collection
 $c:=New collection
 $c.resize(10) // $c=[null,null,null,null,null,null,null,null,null,null]

 $c:=New collection
 $c.resize(10;0) // $c=[0,0,0,0,0,0,0,0,0,0]

 $c:=New collection(1;2;3;4;5)
 $c.resize(10;New object("name";"X")) //$c=[1,2,3,4,5,{name:X},{name:X},{name:X},{name:X},{name:X}]

 $c:=New collection(1;2;3;4;5)
 $c.resize(2) //$c=[1,2]

.reverse()

Historique

Release	Modifications
v16 R6	Ajout

.reverse( ) : Collection

Paramètres	Type		Description
Résultat	Collection	<-	Copie inversée de la collection

Description

The .reverse() function returns a deep copy of the collection with all its elements in reverse order. Si la collection d'origine est une collection partagée, la collection retournée est également une collection partagée.

Exemple

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

.shift()

Historique

Release	Modifications
v16 R6	Ajout

.shift() : any

Paramètres	Type		Description
Résultat	any	<-	Premier élément de collection

Description

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

Si la collection est vide, cette méthode ne fait rien.

Exemple

 var $c : Collection
 var $val : Variant
 $c:=New collection(1;2;4;5;6;7;8)
 $val:=$c.shift()
  // $val=1
  // $c=[2,4,5,6,7,8]

.slice()

Historique

Release	Modifications
v16 R6	Ajout

.slice( startFrom : Integer { ; end : Integer } ) : Collection

Paramètres	Type		Description
startFrom	Integer	->	Numéro de l'élément de départ (inclus)
end	Integer	->	Position de fin (non incluse)
Résultat	Collection	<-	Nouvelle collection contenant des éléments scindées (copie superficielle)

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. Si la collection d'origine est une collection partagée, la collection retournée est également une collection partagée.

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.

Si startFrom < 0, il est recalculé comme startFrom:=startFrom+length (il est considéré comme partant de la fin de la collection).
If the calculated value < 0, startFrom is set to 0.
Si end < 0 , il est recalculé comme end:=end+length.
If end < startFrom (passed or calculated values), the method does nothing.

Exemple

 var $c; $nc : Collection
 $c:=New collection(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()

Historique

Release	Modifications
19 R6	Prise en charge des formules
v16 R6	Ajout

.some( { startFrom : Integer ; } formula : 4D.Function { ; ...param : any } ) : Boolean
.some( { startFrom : Integer ; } methodName : Text { ; ...param : any } ) : Boolean

Paramètres	Type		Description

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.

Vous désignez le code 4D de rétroappel (callback) à exécuter pour évaluer les éléments de la collection en utilisant soit :

formula (syntaxe recommandée), un objet Formula qui peut encapsuler toute expression exécutable, y compris des fonctions et des méthodes projet;
soit methodName, le nom d'une méthode projet (texte).

La callback reçoit les paramètres suivants :

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

Elle peut définir le(s) paramètre(s) suivant(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. La valeur retournée est la dernière calculée.

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.
Si startFrom = 0, l'ensemble de la collection est évalué (défaut).

Exemple

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

 var $c : Collection
 var $b : Boolean
 $c:=New collection
 $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:=New collection
 $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()

Historique

Release	Modifications
19 R6	Prise en charge des formules
v16 R6	Ajout

.sort() : Collection
.sort( formula : 4D.Function { ; ...extraParam : any } ) : Collection
.sort( methodName : Text { ; ...extraParam : any } ) : Collection

Paramètres	Type		Description
formula	4D.Function	->	Objet formule
methodName	Text	->	Nom de méthode
extraParam	any	->	Paramètre(s) à passer à la méthode
Résultat	Collection	<-	Collection d'origine triée

Description

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

If .sort() is called with no parameters, only scalar values (number, text, date, booleans) are sorted. Les éléments sont triés par défaut par ordre croissant, en fonction de leur type. Si la collection contient des éléments de différents types, ils sont d'abord groupés par type et triés par la suite. Les types sont renvoyés dans l'ordre suivant :

Null
booléens
chaînes
nombres
objets
collections
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 (Text) 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. Vous pouvez fournir des paramètres supplémentaires à la callback si nécessaire.

La callback reçoit les paramètres suivants :

$1 (object), où :
- $1.value (any type): first element value to be compared
- $1.value2 (any type): second element value to be compared
$2...$N (tout type) : paramètres supplémentaires (extraParam)

Si vous avez utilisé une méthode, elle doit définir le paramètre suivant :

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

Exemple 1

 var $col; $col2 : Collection
 $col:=New collection("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]

Exemple 2

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

Exemple 3

var $col; $col2; $col3 : Collection
$col:=New collection(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()

Historique

Release	Modifications
v16 R6	Ajout

.sum( { propertyPath : Text } ) : Real

Paramètres	Type		Description
propertyPath	Text	->	Chemin de propriété d'objet à utiliser pour évaluer les valeurs
Résultat	Real	<-	Somme des valeurs de collection

Description

The .sum() function returns the sum for all values in the collection instance.

Seuls les éléments ayant une valeur numérique sont pris en compte pour le calcul (les autres types d'éléments sont ignorés).

Si la collection contient des objets, passez le paramètre propertyPath pour indiquer la propriété d'objet à prendre en compte.

.sum() returns 0 if:

la collection est vide,
la collection ne contient pas d'éléments numériques,
propertyPath n'est pas trouvé dans la collection.

Exemple 1

 var $col : Collection
 var $vSum : Real
 $col:=New collection(10;20;"Monday";True;2)
 $vSum:=$col.sum() //32

Exemple 2

 var $col : Collection
 var $vSum : Real
 $col:=New collection
 $col.push(New object("name";"Smith";"salary";10000))
 $col.push(New object("name";"Wesson";"salary";50000))
 $col.push(New object("name";"Gross";"salary";10500,5))
 $vSum:=$col.sum("salary") //$vSum=70500,5

.unshift()

Historique

Release	Modifications
v16 R6	Ajout

.unshift( value : any { ;...valueN : any } ) : Collection

Paramètres	Type		Description
value	Text, Number, Object, Collection, Date	->	Valeur(s) à insérer au début de la collection
Résultat	Real	<-	Collection contenant des éléments ajoutés

Description

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

Si plusieurs valeurs sont passées, elles sont insérées toutes en même temps, ce qui signifie qu'elles apparaissent dans la collection résultante dans le même ordre que dans la liste d'arguments.

Exemple

 var $c : Collection
 $c:=New collection(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]

Constante	Type	Valeur	Commentaire
ck ascending	Longint	0	Les éléments sont triés par ordre croissant (défaut)
ck descending	Longint	1	Les éléments sont triés par ordre décroissant

Exemple​

Sommaire​

New collection​

Description​

Exemple 1​

Exemple 2​

Exemple 3​

New shared collection​

Description​

Exemple​

.at()​

Description​

Exemple​

.average()​

Description​

Exemple 1​

Exemple 2​

.clear()​

Description​

Exemple​

.combine()​

Description​

Exemple​

.concat()​

Description​

Exemple​

.copy()​

Description​

Exemple 1​

Exemple 2​

Exemple 3​

Exemple 4​

.count()​

Description​

Exemple​

.countValues()​

Description​

Exemple 1​

Exemple 2​

Exemple 3​

.distinct()​

Description​

Exemples​

.equal()​

Description​

Exemple​

.every()​

Description​

Exemple 1​

Exemple 2​

.extract()​

Description​

Exemple 1​

Exemple 2​

.fill()​

Description​

Exemple​

.filter()​

Description​

Exemple 1​

Exemple 2​

.find()​

Description​

Exemple 1​

Exemple 2​

.findIndex()​

Description​

Exemple​

.first()​

Description​

Exemple​

.flat()​

Description​

Exemple​

.flatMap()​

Description​

Exemple 1​

Exemple 2​

Exemple 3​

.includes()​

Exemple

Sommaire

`New collection`

Description

Exemple 1

Exemple 2

Exemple 3

`New shared collection`

Description

Exemple

.at()

Description

Exemple

.average()

Description

Exemple 1

Exemple 2

.clear()

Description

Exemple

.combine()

Description

Exemple

.concat()

Description

Exemple

.copy()

Description

Exemple 1

Exemple 2

Exemple 3

Exemple 4

.count()

Description

Exemple

.countValues()

Description

Exemple 1

Exemple 2

Exemple 3

.distinct()

Description

Exemples

.equal()

Description

Exemple

.every()

Description

Exemple 1

Exemple 2

.extract()

Description

Exemple 1

Exemple 2

.fill()

Description

Exemple

.filter()

Description

Exemple 1

Exemple 2

.find()

Description

Exemple 1

Exemple 2

.findIndex()

Description

Exemple

.first()

Description

Exemple

.flat()

Description

Exemple

.flatMap()

Description

Exemple 1

Exemple 2

Exemple 3

.includes()