Version: 20 R6 BETA

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 compare récursivement le contenu de la collection et de collection2 (comparaison profonde)
.every( { startFrom : Integer ; } formula : 4D.Function { ;...param : any } ) : Boolean .every( { startFrom : Integer ; } methodName : Text { ;...param : any } ) : Boolean retourne true si tous les éléments de la collection ont été évalués à vrai par le test implémenté dans l'objet formula ou la méthode methodName
.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 renvoie les indices, dans la collection d'origine, des éléments de la collection d'objets qui correspondent aux conditions de recherche queryString
.insert( index : Integer ; element : any ) : Collection insère element à la position index spécifiée dans l'instance de collection et renvoie la collection modifiée
.join( delimiter : Text { ; option : Integer } ) : Text convertit tous les éléments de la collection en chaînes et les concatène en utilisant la chaîne delimiter spécifiée comme séparateur
.last() : any renvoie le dernier élément de la collection
.lastIndexOf( toSearch : expression { ; startFrom : Integer } ) : Integer recherche l'expression toSearch parmi les éléments de la collection et renvoie l'indice de la dernière occurrence
.length : Integer renvoie le nombre d'éléments de la collection
.map( formula : 4D.Function { ; ...param : any } ) : Collection .map( 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
.max( { propertyPath : Text } ) : any renvoie l'élément ayant la valeur la plus élevée dans la collection
.min( { propertyPath : Text } ) : any renvoie l'élément ayant la plus petite valeur dans la collection
.multiSort() : Collection .multiSort( colsToSort : Collection ) : Collection .multiSort( formula : 4D.Function ; colsToSort : Collection ) : Collection vous permet d'effectuer un tri synchronisé à plusieurs niveaux sur un ensemble de collections
.orderBy( ) : Collection .orderBy( pathStrings : Text ) : Collection .orderBy( pathObjects : Collection ) : Collection .orderBy( ascOrDesc : Integer ) : Collection renvoie une nouvelle collection contenant tous les éléments de la collection dans l'ordre spécifié
.orderByMethod( formula : 4D.Function { ; ...extraParam : expression } ) : Collection .orderByMethod( methodName : Text { ; ...extraParam : expression } ) : Collection renvoie une nouvelle collection contenant tous les éléments de la collection dans l'ordre défini par la fonction 4D formula ou la méthode methodName
.pop() : any supprime le dernier élément de la collection et le renvoie comme résultat de la fonction
.push( element : any { ;...elementN } ) : Collection ajoute un ou plusieurs element(s) à la fin de l'instance de collection et renvoie la collection modifiée
.query( queryString : Text ) : Collection .query( queryString : Text ; ...value : any ) : Collection .query( queryString : Text ; querySettings : Object ) : Collection renvoie tous les éléments d'une collection d'objets qui correspondent aux conditions de recherche
.reduce( formula : 4D.Function { ; initValue : any { ; ...param : expression }} ) : any .reduce( methodName : Text { ; initValue : any { ; ...param : expression }} ) : any applique la callback formula ou le methodName à un accumulateur et à chaque élément de la collection (de gauche à droite) pour les réduire à une seule valeur
.reduceRight( formula : 4D.Function { ; initValue : any { ; ...param : expression }} ) : any .reduceRight( methodName : Text { ; initValue : any { ; ...param : expression }} ) : any applique la callback formula ou methodName à un accumulateur et chaque élément de la collection (de droite à gauche) pour la réduire à une valeur unique
.remove( index : Integer { ; howMany : Integer } ) : Collection supprime un ou plusieurs élément(s) de la collection à partir de la position spécifiée dans index et renvoie la collection modifiée
.resize( size : Integer { ; defaultValue : any } ) : Collection redéfinit la longueur de la collection à la nouvelle taille spécifiée et renvoie la collection redimensionnée
.reverse( ) : Collection renvoie une copie profonde de la collection avec tous ses éléments dans l'ordre inverse
.shift() : any supprime le premier élément de la collection et le renvoie en tant que résultat de la fonction
.slice( startFrom : Integer { ; end : Integer } ) : Collection retourne une partie d'une collection dans une nouvelle collection
.some( { startFrom : Integer ; } formula : 4D.Function { ; ...param : any } ) : Boolean .some( { startFrom : Integer ; } methodName : Text { ; ...param : any } ) : Boolean retourne true si au moins un élément de la collection a réussi le test implémenté dans le code formula ou methodName fourni
.sort() : Collection .sort( formula : 4D.Function { ; ...extraParam : any } ) : Collection .sort( methodName : Text { ; ...extraParam : any } ) : Collection trie les éléments de la collection d'origine et retourne également la collection triée
.sum( { propertyPath : Text } ) : Real retourne la somme de toutes les valeurs de l'instance de collection
.unshift( value : any { ;...valueN : any } ) : Collection insère la/les value(s) donnée(s) au début de la 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	<-	$1.stop (booléen, optionnel) : true pour stopper le rétroappel.

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	<-	La nouvelle collection partagée

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
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.
$1.stop (booléen, optionnel) : true pour stopper le rétroappel de la méthode.

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.

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	Nouvelle option ck shared. Nouveaux paramètres groupWith
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	Prise en charge de `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

La fonction .equal() compare récursivement le contenu de la collection et de collection2 (comparaison profonde)et renvoie true si elles sont identiques.

Notes

La fonction .equal() ne vérifie l'égalité que pour les éléments de type chaîne, booléen, nombre et null dans les collections. Elle ne vérifie pas l'égalité pour les objets natifs.
Les éléments avec des valeurs null ne sont pas égaux aux éléments Undefined.

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.

tip

Une comparaison récursive de collections peut prendre beaucoup de temps si la collection est de grande taille et comporte de nombreux niveaux. Si vous souhaitez uniquement comparer deux références de collection, vous pouvez envisager d'utiliser l'opérateur de comparaison = pour les références de collection.

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

La fonction .every() retourne true si tous les éléments de la collection ont été évalués à vrai par le test implémenté dans l'objet formula ou la méthode methodName fourni(e).

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	->	Indice l'élément de départ (inclus)
end	Integer	->	Indice de fin (non inclus)
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	<-	Numéro(s) d'élément(s) de la collection répondant aux critères de queryString

Description

La fonction .indices() fonctionne exactement comme la fonction .query() mais renvoie les indices, dans la collection d'origine, des éléments de la collection d'objets qui correspondent aux conditions de recherche queryString, et non les éléments eux-mêmes. Les positions sont retournées dans un ordre croissant.

Le paramètre queryString doit respecter la syntaxe suivante :

propertyPath comparator value {logicalOperator propertyPath comparator value}

Pour une description détaillée de la construction de recherches à l'aide des paramètres queryString et value veuillez vous reporter à la description de la fonction dataclass.query().

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

La fonction .insert() insère element à la position index spécifiée dans l'instance de collection et renvoie la collection modifiée.

Dans index, passez le numéro de l'élément après lequel vous souhaitez que le paramètre element soit inséré.

Si index > la longueur de la collection, l'index de départ réel sera fixé à la longueur de la collection.
Si index < 0, il est recalculé comme index:=index+length (la fin de la collection est considérée comme point de départ du calcul de la position).
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` : ignorer les chaînes null ou vides dans le résultat
Résultat	Text	<-	Chaîne contenant tous les éléments de la collection, séparés par delimiter

Description

La fonction .join() convertit tous les éléments de la collection en chaînes et les concatène en utilisant la chaîne delimiter spécifiée comme séparateur. La fonction renvoie la chaîne résultante.

Par défaut, les éléments null ou vides de la collection sont inclus dans la chaîne résultante. Passez la constante ck ignore null or empty dans le paramètre option si vous souhaitez les exclure de la chaîne résultante.

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

La fonction .last() renvoie le dernier élément de la 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() //vide
// $last:=$emptyCol[$emptyCol.length-1] //retourne une erreur
$last:=$emptyCol.last() // retourne 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

La fonction .lastIndexOf() recherche l'expression toSearch parmi les éléments de la collection et renvoie l'indice de la dernière occurrence, ou -1 si elle n'a pas é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 recherché (les mêmes règles que pour l'opérateur d'égalité sont appliquées).

Optionnellement, vous pouvez passer le numéro de l'élément auquel démarrer la recherche inversée dans startFrom.

Si startFrom >= taille de la collection (coll.length-1), l'ensemble de la collection est évalué (défaut).
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 : Même si startFrom est négatif, la recherche est effectuée de la droite vers la gauche.
Si startFrom = 0, -1 est retourné, ce qui signifie que la recherche n'est pas effectuée.

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

La propriété .length renvoie le nombre d'éléments de la collection.

La propriété .length est initialisée à la création de la collection. Elle est automatiquement mise à jour en cas d'ajout ou de suppression d'éléments. Cette propriété est en lecture seulement (vous ne pouvez pas l'utiliser pour modifier la taille de la 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

La fonction .map() 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. Optionnellement, vous pouvez passer des paramètres à formula ou methodName en utilisant le(s) paramètre(s) param. .map() renvoie toujours une collection de la même taille que la collection originale, sauf si $1.stop a été utilisé (voir ci-dessous).

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

La fonction .max() renvoie l'élément ayant la valeur la plus élevée dans la collection (le dernier élément de la collection si elle était triée par ordre croissant à l'aide de la fonction .sort()).

Si la collection contient différents types de valeurs, la fonction .max() renverra la valeur maximale du dernier type d'élément dans l'ordre de la liste des types (voir la description de .sort()).

Si la collection contient des objets, passez le paramètre propertyPath pour indiquer la propriété d'objet dont vous souhaitez obtenir la valeur maximale.

Si la collection est vide, .max() retourne 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

La fonction .min() renvoie l'élément ayant la plus petite valeur dans la collection (le premier élément de la collection si elle était triée par ordre croissant à l'aide de la fonction .sort()).

Si la collection contient différents types de valeurs, la fonction .min() renverra la valeur minimale du premier type d'élément dans l'ordre de la liste des types (voir la description de .sort()).

Si la collection contient des objets, passez le paramètre propertyPath pour indiquer la propriété d'objet dont vous souhaitez obtenir la valeur minimum.

Si la collection est vide, .min() retourne 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 de collections et/ou d'objets ayant des propriétés {`collection`:colToSort;`order`:`ck ascendant` ou `ck descendant`}
Résultat	Collection	<-	Collection d'origine triée

Description

La fonction .multiSort() vous permet d'effectuer un tri synchronisé à plusieurs niveaux sur un ensemble de collections.

Si .multiSort() est appelé sans paramètres, la fonction a le même effet que la fonction .sort() : la collection est triée (uniquement les valeurs scalaires) par défaut dans l'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

Tri synchronisé à un niveau

Pour trier plusieurs collections de manière synchronisée, il suffit de passer dans colsToSort une collection de collections à trier. Vous pouvez passer un nombre illimité de collections. La collection originale sera triée par ordre croissant et toutes les collections colsToSort seront triées de manière synchronisée.

note

Toutes les collections colsToSort doivent avoir le même nombre d'éléments, sinon une erreur est renvoyée.

Si vous souhaitez trier les collections dans un ordre autre que croissant, vous devez fournir formula (objet Formula) qui définit l'ordre de tri. La valeur de retour doit être un booléen qui indique l'ordre relatif des deux éléments : True si $1.value est inférieur à $1.value2, False si $1.value est supérieur à $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 (tout type) : valeur du premier élément à comparer
- $1.value2 (tout type) : valeur du second élément à comparer
$2...$N (tout type) : paramètres supplémentaires (extraParam)

Tri synchronisé à plusieurs niveaux

Pour définir un tri synchronisé à plusieurs niveaux, vous devez transmettre un objet contenant les propriétés {collection:colToSort;order:ck ascending ou ck descending} au lieu d'une collection colToSort pour chaque collection à utiliser en ta

Les niveaux de tri sont déterminés par l'ordre dans lequel les collections sont passées dans le paramètre colsToSort : la position d'un objet collection/order dans la syntaxe détermine son niveau de tri.

note

La fonction .multiSort() utilise un algorithme de tri stable .

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` ou `ck descending` (valeurs scalaires)
Résultat	Collection	<-	Copiée triée de la collection (shallow copy)

Description

La fonction .orderBy() renvoie une nouvelle collection contenant tous les éléments de la collection dans l'ordre spécifié.

Cette fonction retourne une shallow copy (copie superficielle), 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.

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). Vous pouvez modifier ce tri automatique par défaut en passant la constante ck ascending ou ck descending dans le paramètre ascOrDesc (voir ci-dessous).

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 : Texte (formule). Syntaxe : propertyPath1 {desc ou asc}, propertyPath2 {desc ou asc},... (défaut : asc). pathStrings contient une formule constituée de 1 à N chemin(s) de propriété(s) et (optionnellement) ordres de tri, séparés par des virgules. 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. Vous pouvez ajouter autant d'objets dans la collection pathObjects que nécessaire. 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. Passez une des constantes suivantes du thème Objets et collections :

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

La fonction .orderByMethod() renvoie une nouvelle collection contenant tous les éléments de la collection dans l'ordre défini par la fonction 4D formula ou la méthode methodName.

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

Dans la callback, passez votre code qui compare deux valeurs et retourne true si la première valeur est inférieure à la seconde valeur. Vous pouvez fournir des paramètres extraParam à la callback si nécessaire.

La callback reçoit les paramètres suivants :

$1 (object), où :
- $1.value (tout type) : valeur du premier élément à comparer
- $1.value2 (tout type) : valeur du second élément à comparer
- $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 (booléen): true si $1.value < $1.value2, false sinon

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:=Newcollection
 $c.push("33" ; "4" ; "1111" ; "222")
 $c2:=$c.orderBy() //$c2=["1111", "222", "33", "4"], ordre alphabétique
 $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"]

La méthode sortCollection :

var $1 : Object
var $2: Integer // option de tri

$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

La fonction .pop() supprime le dernier élément de la collection et le renvoie comme résultat de la fonction.

Lorsqu'elle est appliquée à une collection vide, .pop() retourne undefined.

Exemple

.pop(), combinée à .push(), peut être utilisée pour implémenter une fonctionnalité first-in last-out de traitement de données empilées :

 var $stack : Collection
 $stack:=New collection //$stack=[]
 $stack.push(1;2) //$stack=[1,2]
 $stack.pop() //$stack=[1]  retourne 2
 $stack.push(New collection(4;5)) //$stack=[[1,[4,5]]
 $stack.pop() //$stack=[1]  retourne [4,5]
 $stack.pop() //$stack=[]  retourne 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

La fonction .push() ajoute un ou plusieurs element(s) à la fin de l'instance de collection et renvoie la collection modifiée.

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	Prise en charge des recherches utilisant des références d'objet ou de collection
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

La fonction .query() renvoie tous les éléments d'une collection d'objets qui correspondent aux conditions de recherche définies par queryString et (éventuellement) value ou querySettings. Si la collection d'origine est une collection partagée, la collection retournée est également une collection partagée.

Une collection vide est renvoyée si la collection dans laquelle la requête est exécutée ne contient pas la value recherchée.

paramètre queryString

Le paramètre queryString doit respecter la syntaxe suivante :

propertyPath comparator value {logicalOperator propertyPath comparator value}

où :

propertyPath : chemin de la propriété sur laquelle vous voulez exécuter la recherche. Ce paramètre peut contenir un nom simple (par exemple "pays") ou un chemin d'attribut valide (par exemple "pays.nom"). Dans le cas d'un chemin d'accès à un attribut dont le type est Collection, la notation [] est utilisée pour traiter toutes les occurrences (par exemple children[].age).
comparator : symbole qui compare propertyPath et 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 (@). Équivalent à "Condition Not appliquée à une assertion" (voir ci-dessous).
	!==, 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. Équivalent à "Not equal to" (voir ci-dessous).
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 (@)

valeur : valeur à comparer à la valeur actuelle de la propriété de chaque élément de la collection. Il peut s'agir de n'importe quelle valeur d'expression constante correspondant au type de données de l'élément ou d'un placeholder. Lorsque vous utilisez une valeur constante, les règles suivantes doivent être respectées :
- Les valeurs constantes de type texte peuvent être passées avec ou sans guillemets (voir Utilisation des guillemets ci-dessous). 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.
- Valeurs constantes de typebooléen: true or false (sensible à la casse).
- Valeurs constantes de type numérique : les décimales doivent être séparées par un '.'
- Constantes de type date : "YYYY-MM-DD" format
- Constantes null : en utilisant le mot-clé "null", la recherche trouvera les propriétés ayant la valeur null et undefined.
- Dans le cas d'une recherche avec un comparateur IN, valuedoit être une collection, ou des valeurs du même type que les données du chemin d'attribut, fournies entre [ ] et séparées par des virgules (pour les chaînes, les caractères " doivent être écha
logicalOperator : utilisé pour relier des conditions multiples dans la recherche (optionnel). 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 vous permet d'utiliser des placeholders pour les arguments propertyPath et value dans le paramètre queryString. 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.

Il existe deux types de placeholders : les placeholders indexés et les placeholders nommés.

Placeholders indexés : les paramètres sont insérés en tant que :paramIndex (par exemple ":1", ":2"...) dans queryString et leurs valeurs correspondantes sont fournies par la séquence de paramètres value. Vous pouvez utiliser jusqu'à 128 paramètres value.

Voici un exemple :

$c:=$myCol.query(":1=:2";"city";"Chicago")

placeholders nommés : les paramètres sont insérés en tant que :paramName (par exemple ":myparam") et leurs valeurs sont fournies dans les objets "attributes" et/ou "parameters" dans le paramètre querySettings.

Voici un exemple :

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

Vous pouvez combiner tous les types d'arguments dans queryString. Une queryString peut contenir, pour les paramètres propertyPath et value :

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

L'utilisation de placeholders dans les recherches est recommandée pour les raisons suivantes :

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 //l'utilisateur saisit son nom
 $result:=$col.query($vquery)

Cette recherche semble sécurisée puisque les données non publiques sont filtrées. Cependant, si l'utilisateur saisit dans la zone myname une chaîne du type "smith OR status='private', la chaîne de recherche sera modifiée à l'étape de l'interprétation et pourra retourner des données privées.

Lorsque vous utilisez des placeholders, le contournement des options de sécurité n'est pas possible :

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

Dans ce cas, si l'utilisateur saisit smith OR status='private' dans la zone myname, cela ne sera pas interprété dans la chaîne de recherche, mais uniquement passé en tant que valeur. La recherche d'une personne nommée "smith OR status='private"' échouera simplement.

Cela évite d'avoir à se préoccuper des problèmes de formatage ou de caractères, en particulier lors de la gestion des paramètres propertyPath ou value qui peuvent contenir des caractères non alphanumériques tels que ".", "['...
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) // ne fonctionnera PAS

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") //syntaxe correcte

Référence d'objet ou de collection comme value

Vous pouvez rechercher dans une collection en utilisant une référence d'objet ou une référence de collection comme paramètre value à comparer. La recherche fera correspondre les objets de la collection qui font référence à (pointent vers) la même instance d'objet ou de collection.

Les comparateurs suivants sont pris en charge :

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

Pour construire une recherche avec une référence d'objet ou de collection, vous devez utiliser la syntaxe du paramètre querySettings. Exemple avec une référence d'objet :

var $o1:={a: 1}
var $o2:={a: 1} //même objet mais autre référence
var $o3:=$o1 //même objet et même référence

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 est true
	//$colResult[1].o=$o1 est true

Exemple avec une référence de collection :

$c1:=[1 ; 2 ; 3]
$c2:=[1 ; 2 ; 3] //même collection mais autre référence
$c3:=$c1 //même collection et même référence

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

Paramètre querySettings

Dans le paramètre querySettings, vous pouvez passer un objet contenant des placeholders de recherche en tant qu'objets. Les propriétés suivantes sont prises en charge :

Propriété

Type

Description

parameters

Object

Placeholders nommés pour les valeurs utilisées dans queryString. Les valeurs sont exprimées sous forme de paires propriété / valeur, où propriété est le nom du placeholder inséré pour une valeur dans queryString (":placeholder") et où valeur correspond à la valeur à comparer. 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

Placeholders nommés pour les chemins d'attributs utilisés dans queryString. Les attributs sont exprimés sous forme de paires propriété / valeur, où propriété est le nom du placeholder inséré pour un chemin d'attribut dans queryString (":placeholder"), et où valeur peut être une chaine ou une collection de chaines. Chaque valeur est un chemin qui peut désigner une propriété dans un objet de la collection

Type d'objet	Description
Chaîne	Chemin d'accès de l'attribut exprimé à l'aide de la notation à point, par exemple "name" ou "user.address.zipCode"
Collection de chaînes	Chaque chaîne de la collection représente un niveau d'attributePath, par exemple ["name"] ou ["user", "address", "zipCode"]. L'utilisation d'une collection permet de rechercher des attributs dont les noms ne sont pas compatibles avec la notation à points, par exemple ["4Dv17.1", "en/fr"]

Vous pouvez mélanger des placeholders indexés (valeurs passées directement dans les paramètres value) et des valeurs de placeholders nommés dans la même requête.

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

Vous trouverez plus d'exemples de requêtes dans la page dataClass.query().

.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	->	Valeur à utiliser comme premier argument du premier appel de formula ou methodName
param	expression	->	Paramètre(s) à passer
Résultat	Text, Number, Object, Collection, Date, Boolean	<-	Résultat de la valeur de l'accumulateur

Description

La fonction .reduce() applique la callback formula ou le methodName à un accumulateur et à chaque élément de la collection (de gauche à droite) pour les réduire à une seule valeur.

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 prend chaque élément de la collection et effectue toutes les opérations souhaitées pour accumuler le résultat dans $1.accumulator, qui est retourné dans $1.value.

Vous pouvez passer la valeur pour initialiser l'accumulateur dans initValue. S'il est omis, $1.accumulator commence par Undefined.

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.accumulator: valeur à modifier par la fonction et qui est initialisée par initValue.
$1.stop (booléen, optionnel) : true pour stopper le rétroappel. 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]

Avec la méthode Flatten suivante :

 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	->	Valeur à utiliser comme premier argument du premier appel de formula ou methodName
param	expression	->	Paramètre(s) à passer
Résultat	Text, Number, Object, Collection, Date, Boolean	<-	Résultat de la valeur de l'accumulateur

Description

La fonction .reduceRight() applique la callback formula ou methodName à un accumulateur et chaque élément de la collection (de droite à gauche) pour la réduire à une valeur unique.

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 prend chaque élément de la collection et effectue toutes les opérations souhaitées pour accumuler le résultat dans $1.accumulator, qui est retourné dans $1.value.

Vous pouvez passer la valeur pour initialiser l'accumulateur dans initValue. S'il est omis, $1.accumulator commence par Undefined.

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.accumulator: valeur à modifier par la fonction et qui est initialisée par initValue.
$1.stop (booléen, optionnel) : true pour stopper le rétroappel. 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)  //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]

Avec la méthode Flatten suivante :

	//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 modifiée ne contenant plus les éléments supprimés

Description

La fonction .remove() supprime un ou plusieurs élément(s) de la collection à partir de la position spécifiée dans index et renvoie la collection modifiée.

Dans index, passez le numéro de l'élément à partir duquel la suppression doit débuter dans 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 recalculée est négative, index prend la valeur 0.
Si valeur recalculée > longueur de la collection, index prend comme valeur la taille de la collection.

Dans howMany, passez le nombre d'éléments à supprimer à partir de l'index. Si howMany n'est pas spécifié, un élément est supprimé.

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

La fonction .resize() redéfinit la longueur de la collection à la nouvelle taille spécifiée et renvoie la collection redimensionnée.

Si size est inférieure à la longueur de la collection, les éléments excédentaires sont retirés de la collection.
Si size > longueur de la collection, size est la nouvelle longueur de la collection.

Par défaut, les nouveaux éléments sont remplis par des valeurs null. Vous pouvez indiquer la valeur à remplir dans les éléments ajoutés à l'aide du paramètre defaultValue.

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

La fonction .reverse() renvoie une copie profonde de la collection avec tous ses éléments dans l'ordre inverse. 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

La fonction .shift() supprime le premier élément de la collection et le renvoie en tant que résultat de la fonction.

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	->	Indice l'élément de départ (inclus)
end	Integer	->	Indice de fin (non inclus)
Résultat	Collection	<-	Nouvelle collection contenant des éléments scindées (copie superficielle)

Description

La fonction .slice() retourne une partie d'une collection dans une nouvelle collection, sélectionnée de l'indice startFrom à l'indice end (end non inclus). Cette fonction retourne une copie superficielle de la collection. Si la collection d'origine est une collection partagée, la collection retournée est également une collection partagée.

La collection retournée contient l'élément spécifié par startFrom et tous les éléments suivants jusqu'à l'élément spécifié par end (mais non compris). Si seul le paramètre startFrom est spécifié, la collection retournée contient tous les éléments de startFrom au dernier élément de la collection d'origine.

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 prend la valeur 0.
Si end < 0 , il est recalculé comme end:=end+length.
Si end < startFrom (valeurs passées ou recalculées), la fonction ne fait rien.

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

La fonction .some() retourne true si au moins un élément de la collection a réussi le test implémenté dans le code formula ou methodName fourni.

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 :

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 (booléen) : true si l'évaluation de la valeur de l'élément est à vrai, false sinon.
$1.stop (booléen, optionnel) : true pour stopper le rétroappel. La valeur retournée est la dernière calculée.

Dans tous les cas, au moment où la fonction .some() rencontre le premier élément de la collection retournant true, elle arrête d'appeler la callback et retourne true.

Par défaut, .some() évalue l'ensemble de la collection. Optionnellement, vous pouvez passer le numéro de l'élément auquel démarrer la recherche dans startFrom.

Si startFrom >= la longueur de la collection, False est retourné, ce qui signifie que la collection n'est pas testée.
Si startFrom < 0, il est considéré comme le décalage depuis la fin de la collection.
Si startFrom = 0, l'ensemble de la collection est évalué (défaut).

Exemple

Vous voulez savoir si au moins une valeur de la collection est >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

La fonction .sort() trie les éléments de la collection d'origine et retourne également la collection triée .

Si .sort() est appelé sans paramètre, seules les valeurs scalaires (numérique, texte, date, booléens) sont triées. 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

Si vous souhaitez trier les éléments de la collection dans un autre ordre ou trier n'importe quel type d'élément, vous devez fournir dans *formula * (objet Formula) ou methodName (Text) un callback qui définit l'ordre de tri. La valeur de retour doit être un booléen qui indique l'ordre relatif des deux éléments : True si $1.value est inférieur à $1.value2, False si $1.value est supérieur à $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 (tout type) : valeur du premier élément à comparer
- $1.value2 (tout type) : valeur du second élément à comparer
$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 (booléen) : true si $1.value < $1.value2, false sinon.

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))) //tri alphabétique : [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

La fonction .sum() retourne la somme de toutes les valeurs de 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.

.sum() retourne 0 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
 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

La fonction .unshift() insère la/les value(s) donnée(s) au début de la collection et renvoie la collection modifiée.

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()