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
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
[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.
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.
// 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) :
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