ArrayAppend |
Tableau d'ajout |
|---|---|
| Lucee | |
Syntaxe
| ArrayAppend( array=array, value=any, merge=boolean ); |
Paramètres
| Nom | Description |
|---|---|
| array | Ce paramètre permet de spécifier le tableau dans lequel un nouvel élément doit être ajouté. C'est la structure de données qui sera modifiée directement par la fonction. |
| value | Ce paramètre permet de définir la valeur à insérer à la fin du tableau. Cette valeur peut être de tout type (nombre, chaîne de caractères, objet, autre tableau,...). |
| merge | Ce paramètre permet d'indiquer si la valeur fournie doit être fusionnée avec le tableau existant. Si défini à true et que la valeur est un tableau, ses éléments sont ajoutés un par un dans le tableau cible. Si défini à false, la valeur est insérée comme un seul élément, même si c'est un tableau. |
Description
Cette fonction permet d'ajouter un élément de tableau à un tableau.
Remarques
- La fonction ArrayAppend() est utilisée pour ajouter un nouvel élément à la fin d'un tableau existant. Elle modifie directement le tableau fourni en paramètre, ce qui en fait une fonction à effet de bord. Cela signifie que la variable initiale du tableau est immédiatement mise à jour après l'exécution de la fonction.
- Le paramètre array est essentiel car il désigne la structure de données à modifier. Il doit déjà être initialisé avant d'être utilisé avec ArrayAppend(). Si le tableau n'existe pas encore, la fonction retournera une erreur, à moins qu'une logique conditionnelle ou une initialisation préalable ait été prévue.
- Le paramètre value offre une grande flexibilité : il peut contenir n'importe quel type de donnée, qu'il s'agisse d'un nombre, d'une chaîne de texte, d'un objet, d'une structure ou même d'un autre tableau. Cela permet d'utiliser ArrayAppend() dans une multitude de scénarios, notamment pour créer des listes dynamiques et hétérogènes.
- Le paramètre merge apporte un comportement avancé à la fonction. Lorsqu'il est défini sur true, et que la valeur passée est un tableau, les éléments de ce tableau sont ajoutés individuellement à la suite du tableau principal. Cela permet de fusionner facilement deux tableaux sans avoir à utiliser de boucle.
- En revanche, lorsque merge est défini sur false (ou omis), le tableau passé en paramètre est ajouté comme un seul élément à la fin du tableau cible. Cela donne un tableau imbriqué, ce qui peut être utile pour stocker des collections d'ensembles ou des structures à plusieurs niveaux.
- ArrayAppend() retourne la nouvelle longueur du tableau après l'ajout de l'élément. Cette particularité est pratique pour vérifier rapidement la taille du tableau ou pour l'utiliser dans des opérations séquentielles, sans avoir à appeler une fonction supplémentaire comme ArrayLen().
- En termes de performance, ArrayAppend() est optimisée pour les ajouts successifs en fin de tableau. Cependant, pour des manipulations plus complexes (ajouts multiples ou positionnés), il est souvent préférable d'utiliser des fonctions comme ArrayInsertAt() ou ArrayMerge() afin de maintenir la clarté du code.
- Lucee recommande l'usage de la syntaxe script moderne, ce qui rend ArrayAppend() particulièrement utile dans les blocs <cfscript> pour un code plus fluide et lisible. Cette fonction est très courante dans les opérations dynamiques, comme la construction d'ensembles de données, le traitement de résultats de requêtes ou la gestion d'API JSON.
Exemple
Voici des exemples typiques d'utilisation de cette fonction :
- <cfscript>
- numbers = [ 1, 2, 3, 4 ];
- ArrayAppend( numbers, 5 );
- Dump( numbers ); // Sorties [ 1, 2, 3, 4, 5 ]
- numbers = [ 1, 2, 3, 4 ];
- moreNumbers = [ 5, 6, 7, 8 ];
- ArrayAppend( numbers, moreNumbers );
- Dump( numbers ); // Sorties [ 1, 2, 3, 4, [ 5, 6, 7, 8 ] ]
- numbers = [ 1, 2, 3, 4, 5 ];
- moreNumbers = [ 6, 7, 8, 9, 10 ];
- ArrayAppend( numbers, moreNumbers, true );
- Dump( numbers ); // Sortie [ 1, 2, 3, 4, 5, 6, 7, 8 ]
-
- </cfscript>
Dernière mise à jour : Jeudi, le 14 Août 2025