ArrayContains |
Contient un tableau |
|---|---|
| Lucee | |
Syntaxe
| ArrayContains( haystack=array, needle=object, substringMatch=boolean ); |
Paramètres
| Nom | Description |
|---|---|
| haystack | Ce paramètre permet de spécifier le tableau dans lequel la fonction va rechercher un élément particulier. C'est le tableau "cible" de la recherche. |
| needle | Ce paramètre permet de définir l'élément que l'on souhaite trouver dans le tableau. Il peut s'agir d'une valeur simple (nombre, chaîne de caractères, booléen) ou d'un objet, selon le contenu du tableau. |
| substringMatch | Ce paramètre permet d'indiquer si la recherche doit inclure les correspondances partielles. Si défini à true, un élément du tableau contenant la valeur recherchée comme sous-chaîne sera considéré comme une correspondance. Si défini à false, seule une correspondance exacte sera acceptée. |
Description
Cette fonction permet de renvoyer la position du premier élément du tableau correspondant à l'élément recherché, ou 0 si l'élément n'est pas trouvé.
Remarques
- La fonction ArrayContains() permet de rechercher la présence d'un élément spécifique dans un tableau. Elle retourne la position (index) de la première occurrence trouvée, ce qui la rend utile non seulement pour vérifier l'existence d'une valeur, mais aussi pour déterminer son emplacement exact dans le tableau. Si aucune correspondance n'est trouvée, la fonction renvoie 0, indiquant une absence de résultat.
- Le premier paramètre, haystack, représente le tableau dans lequel la recherche s'effectue. Il peut contenir des valeurs simples (numériques, textuelles) ou des objets complexes. Cette souplesse permet d'utiliser ArrayContains() aussi bien dans des contextes simples (comme une liste de nombres) que dans des structures de données avancées, par exemple des tableaux d'objets.
- Le paramètre needle correspond à l'élément à rechercher. Lucee compare cet élément à ceux du tableau selon la nature du contenu (chaîne, nombre, booléen, objet). La comparaison est généralement stricte : pour qu'une correspondance soit trouvée, la valeur et le type doivent correspondre exactement, sauf si le paramètre substringMatch est activé.
- Le paramètre substringMatch apporte une flexibilité importante dans la recherche. Lorsqu'il est défini à true, la fonction effectue une recherche partielle dans les chaînes de caractères. Cela signifie qu'un élément du tableau contenant la valeur recherchée comme sous-chaîne sera considéré comme une correspondance valide, ce qui est pratique pour rechercher des fragments de texte.
- Il est essentiel de noter que la fonction retourne la position de la première occurrence uniquement. Si le tableau contient plusieurs éléments identiques, ArrayContains() ne renverra pas toutes les positions correspondantes, mais seulement celle du premier match. Pour trouver plusieurs correspondances, il faudrait combiner cette fonction avec une boucle ou utiliser ArrayFilter().
- ArrayContains() est souvent utilisée dans des conditions logiques pour vérifier la présence d'une valeur avant d'effectuer une action. Par exemple, on peut écrire if (ArrayContains(myArray, "test")) { ... } pour exécuter un bloc de code uniquement si "test" est trouvé. Cela en fait un outil utile pour contrôler les flux logiques dans les scripts CFML.
- Lorsque substringMatch est activé, la recherche peut devenir moins performante pour les tableaux volumineux, car Lucee doit parcourir chaque élément et effectuer une comparaison de sous-chaînes. Pour les tableaux contenant des milliers d'éléments, il est donc conseillé de l'utiliser avec précaution et uniquement lorsque cela est nécessaire.
- Enfin, ArrayContains() permet de simplifier considérablement le code, notamment par rapport à une approche manuelle utilisant des boucles for ou while. Elle rend la recherche plus expressive et plus lisible tout en conservant un bon équilibre entre clarté et performance. C'est une fonction essentielle pour tout traitement de liste ou de collection dans Lucee.
Exemple
Voici des exemples typiques d'utilisation de cette fonction :
- <cfscript>
- numbers = [ 4, 3, 2, 1 ];
- dump(var=numbers, label="nombres");
- positionOfThree = ArrayContains( numbers, 3);
- echo("Position de 3: " & positionOfThree & "<br>"); // sorties 2
- words = [ 'Bonjour' , 'le monde' ];
- dump(var=words, label="Mots");
- positionOfWorld = ArrayContains( words, 'le monde' );
- positionOfSubstring = ArrayContains( words, 'jo', true ); // correspondance de sous-chaînes
- echo("Position de la sous-chaine 'jo': " & positionOfSubstring & "<br>" ); // sorties 1
- echo("Position de 'monde': " & positionOfWorld); // sorties 2
- </cfscript>
Dernière mise à jour : Jeudi, le 14 Août 2025