Array.prototype.includes()
La méthode includes()
permet de déterminer si un tableau contient une valeur et renvoie true
si c'est le cas, false
sinon.
Exemple interactif
Note : Cette méthode utilise l'algorithme de comparaison SameValueZero qui fonctionne comme l'égalité stricte, à la différence que NaN
est ici égal à lui même.
Syntaxe
js
array.includes(élémentRecherché);
array.includes(élémentRecherché, indiceDépart);
Paramètres
élémentRecherché
-
La valeur qu'on souhaite trouver dans le tableau (lorsqu'on manipule des caractères et des chaînes, la comparaison est sensible à la casse).
indiceDépart
Facultatif-
La position du tableau à partir de laquelle commencer à chercher
élémentRecherché
. Si on utilise une valeur négative, la recherche commencera à partir de la fin du tableau (autrement dit à l'indicearray.length - indiceDépart
). La valeur par défaut est 0.
Valeur de retour
Un booléen qui vaut true
si élémentRecherché
est trouvé dans le tableau (à partir de l'indiceDépart
si celui-ci est indiqué). Les valeurs -0, +0 et 0 sont considérées comme équivalentes mais false
n'est pas considéré comme équivalent à 0.
Note : Pour être tout à fait précis, includes()
utilise l'algorithme SameValueZero afin de déterminer si un élément donné est trouvé.
Exemples
js
[1, 2, 3].includes(2); // true
[1, 2, 3].includes(4); // false
[1, 2, 3].includes(3, 3); // false
[1, 2, 3].includes(3, -1); // true
[1, 2, NaN].includes(NaN); // true
["a", "b", "c"].includes("c", 5); // false
["a", "b", "c"].includes("c", -100); // true
indiceDépart
supérieur ou égal à la longueur du tableau
SI indiceDépart
est supérieur ou égal à la longueur du tableau, la méthode retourne false
. Le tableau n'est pas parcouru.
js
var arr = ["a", "b", "c"];
arr.includes("c", 3); // false
arr.includes("c", 100); // false
indiceDépart
strictement négatif
Si indiceDépart
est strictement négatif, l'indice de départ effectif est la somme entre la taille du tableau et indiceDépart
. Si cette somme est toujours négative, le tableau est intégralement parcouru.
js
// Le tableau a une taille de 3
// indiceDépart vaut -2
// L'indice de départ effectif vaut is 3 + (-2) = 1
var arr = ["a", "b", "c"];
arr.includes("a", -2); // false
arr.includes("b", -2); // true
arr.includes("c", -100); // true
Utilisation d'includes()
comme méthode générique
includes()
est une méthode générique : l'objet sur lequel elle est appelée ne doit pas nécessairement être un tableau. On peut l'utiliser sur des objets semblables à des tableaux (ex. arguments
ou des chaînes de caractères) :
js
function argumentsContientA() {
return [].includes.call(arguments, "a");
}
console.log(argumentsContientA("a", "b", "c")); // true
console.log(argumentsContientA("d", "e", "f")); // false
Spécifications
Specification |
---|
ECMAScript Language Specification # sec-array.prototype.includes |
Compatibilité des navigateurs
BCD tables only load in the browser