Array : mthode includes()

Exemple interactif

const array1 = [1, 2, 3];

console.log(array1.includes(2));
// Rsultat attendu : true

const pets = ['chat', 'chien', 'chauve-souris'];

console.log(pets.includes('chat'));
// Rsultat attendu : true

console.log(pets.includes('at'));
// Rsultat attendu : false

Syntaxe

includes(searchElement)
includes(searchElement, fromIndex)

Paramtres

searchElement

La valeur rechercher.

fromIndex Facultatif

La position (en partant de 0) dans le tableau partir de laquelle commencer la recherche. Cette valeur est convertie en entier.

• Un indice ngatif compte rebours depuis la fin du tableau si -array.length <= fromIndex < 0, fromIndex + array.length est utilis. Cependant, le tableau est tout de mme parcouru de l'avant vers l'arrire dans ce cas.
• Si fromIndex < -array.length ou si fromIndex est omis, 0 est utilis, ce qui fait que tout le tableau est parcouru.
• Si fromIndex >= array.length, le tableau n'est pas parcouru et false est retourn.

Valeur de retour

Une valeur boolenne qui vaut true si la valeur searchElement est trouve dans le tableau (ou dans la partie du tableau indique par l'indice fromIndex, si prcis).

Description

La mthode includes() compare un searchElement aux lments du tableau en utilisant l'algorithme SameValueZero. Cet algorithme fonctionne comme l'galit stricte === (o -0 et +0 sont considrs comme gaux), l'exception que NaN est considr comme gal lui-mme.

Lorsqu'elle est utilise sur un tableau creux, la mthode includes() parcourt les emplacements vides comme s'ils ont la valeur undefined.

La mthode includes() est gnrique : elle attend uniquement que la valeur de this possde une proprit length et des proprits cls entires.

Exemples

Utilisation d'includes()

[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
["1", "2", "3"].includes(3); // false

fromIndex suprieur ou gal la longueur du tableau

Si fromIndex est suprieur ou gal la longueur du tableau, false est retourn. Le tableau n'est pas parcouru.

const arr = ["a", "b", "c"];

arr.includes("c", 3); // false
arr.includes("c", 100); // false

L'indice calcul est infrieur 0

Si fromIndex est ngatif, l'indice calcul est utilis comme position dans le tableau partir de laquelle commencer la recherche de searchElement. Si l'indice calcul est infrieur ou gal 0, tout le tableau est parcouru.

// la longueur du tableau est 3
// fromIndex vaut -100
// l'indice calcul vaut 3 + (-100) = -97

const arr = ["a", "b", "c"];

arr.includes("a", -100); // true
arr.includes("b", -100); // true
arr.includes("c", -100); // true
arr.includes("a", -2); // false

Utilisation de includes() sur un tableau creux

Vous pouvez rechercher undefined dans un tableau creux et obtenir true.

console.log([1, , 3].includes(undefined)); // true

Appel de includes() sur des objets qui ne sont pas des tableaux

La mthode includes() lit la proprit length de this puis accde chaque proprit dont la cl est un entier non ngatif infrieur length.

const objetSimilaireTableau = {
  length: 3,
  0: 2,
  1: 3,
  2: 4,
  3: 1, // ignor par includes(), car length vaut 3
};
console.log(Array.prototype.includes.call(objetSimilaireTableau, 2));
// true
console.log(Array.prototype.includes.call(objetSimilaireTableau, 1));
// false

Spcifications

Compatibilit des navigateurs

Voir aussi

• Guide des collections indexes
• L'objet global Array
• La mthode Array.prototype.indexOf()
• La mthode Array.prototype.find()
• La mthode Array.prototype.findIndex()
• La mthode TypedArray.prototype.includes()
• La mthode String.prototype.includes()
• Prothse d'mulation de Array.prototype.includes dans core-js (angl.)
• Prothse d'mulation es-shims de Array.prototype.includes (angl.)