Array : mthode flatMap()

Exemple interactif

const arr = [1, 2, 1];

const result = arr.flatMap((num) => (num === 2 ? [2, 2] : 1));

console.log(result);
// sortie attendue : Array [1, 2, 2, 1]

Syntaxe

flatMap(callbackFn)
flatMap(callbackFn, thisArg)

Paramtres

callbackFn

La fonction excuter pour chaque lment du tableau. Elle doit retourner un tableau contenant les nouveaux lments du nouveau tableau, ou une seule valeur qui n'est pas un tableau ajouter au nouveau tableau. La fonction est appele avec les arguments suivants :

element

L'lment en cours de traitement dans le tableau.

index

L'indice de l'lment en cours de traitement dans le tableau.

array

Le tableau sur lequel flatMap() a t appele.

thisArg Facultatif

La valeur utiliser comme this lors de l'excution de callbackFn. Voir les mthodes itratives.

Valeur de retour

Un nouveau tableau avec chaque lment tant le rsultat de la fonction de rappel (callback en anglais) et aplati d'un niveau.

Description

La mthode flatMap() est une mthode itrative. Voir Array.prototype.map() pour une description dtaille de la fonction de rappel. La mthode flatMap() est identique map(callbackFn, thisArg) suivie de flat(1) : pour chaque lment, elle produit un tableau de nouveaux lments et concatne les tableaux rsultants pour former un nouveau tableau. Lire la section mthodes itratives pour plus d'informations sur le fonctionnement gnral de ces mthodes.

La mthode flatMap() est gnrique. Elle attend seulement que la valeur de this possde une proprit length et des proprits cls entires. Cependant, la valeur retourne par callbackFn doit tre un tableau pour tre aplatie.

Alternative

Pr-allouer et itrer explicitement

const arr = [1, 2, 3, 4];

arr.flatMap((x) => [x, x * 2]);
// est quivalent 
const n = arr.length;
const acc = new Array(n * 2);
for (let i = 0; i < n; i++) {
  const x = arr[i];
  acc[i * 2] = x;
  acc[i * 2 + 1] = x * 2;
}
// [1, 2, 2, 4, 3, 6, 4, 8]

Notez que dans ce cas particulier, l'approche avec flatMap est plus lente que l'approche avec une boucle for en raison de la cration de tableaux temporaires qui doivent tre collects par le ramasse-miettes, et parce que le tableau retourn n'a pas besoin d'tre redimensionn frquemment. Cependant, flatMap peut rester la solution approprie dans les cas o sa flexibilit et sa lisibilit sont souhaites.

Exemples

map() et flatMap()

var arr1 = [1, 2, 3, 4];

arr1.map((x) => [x * 2]);
// [[2], [4], [6], [8]]

arr1.flatMap((x) => [x * 2]);
// [2, 4, 6, 8]

// seul un niveau est aplati
arr1.flatMap((x) => [[x * 2]]);
// [[2], [4], [6], [8]]

Bien que ce qui prcde aurait pu tre obtenu en utilisant simplement map, voici un exemple qui met mieux en valeur l'utilisation de flatMap().

Gnrons une liste de mots partir d'une liste de phrases.

let tableau = ["Coucou comment", "", "a va ?"];

tableau.map((x) => x.split(" "));
// [["Coucou", "comment"], [""], ["a", "va", "?"]]

tableau.flatMap((x) => x.split(" "));
// ["Coucou", "comment", "", "a", "va", "?"]

On notera que la longueur de la liste obtenue avec flatMap est diffrente de la longueur de la liste originale.

Ajouter et supprimer des lments lors d'un map()

flatMap peut tre utilis pour ajouter et supprimer des lments (modifier le nombre d'lments) lors d'un map. Autrement dit, cela permet de faire correspondre plusieurs lments plusieurs lments (en traitant chaque lment d'entre sparment), plutt que toujours un--un. En ce sens, cela fonctionne comme l'oppos de filter. Retournez un tableau 1 lment pour conserver l'lment, un tableau plusieurs lments pour en ajouter, ou un tableau 0 lment pour le supprimer.

// Supposons que nous voulons supprimer tous les nombres ngatifs
// et dcouper les nombres impairs en un nombre pair et un 1
const a = [5, 4, -3, 20, 17, -33, -4, 18];
//         |\  \  x   |  | \   x   x   |
//        [4,1, 4,   20, 16, 1,       18]

const resultat = a.flatMap((n) => {
  if (n < 0) {
    return [];
  }
  return n % 2 === 0 ? [n] : [n - 1, 1];
});
console.log(resultat); // [4, 1, 4, 20, 16, 1, 18]

Utiliser le troisime argument de callbackFn

L'argument array est utile si vous souhaitez accder un autre lment du tableau, en particulier lorsque vous n'avez pas de variable existante qui fait rfrence au tableau. L'exemple suivant utilise d'abord filter() pour extraire les stations en service puis utilise flatMap() pour crer un nouveau tableau o chaque lment contient une station et la station suivante. Pour la dernire station, il retourne un tableau vide afin de l'exclure du tableau final.

const stations = ["New Haven", "West Haven", "Milford (ferm)", "Stratford"];
const line = stations
  .filter((name) => !name.endsWith("(ferm)"))
  .flatMap((name, idx, arr) => {
    // Sans l'argument arr, il n'y a aucun moyen d'accder facilement
    // au tableau intermdiaire sans le stocker dans une variable.
    if (idx === arr.length - 1) return []; // la dernire station n'a pas de suivante
    return [`${name} - ${arr[idx + 1]}`];
  });
console.log(line); // ['New Haven - West Haven', 'West Haven - Stratford']

L'argument array n'est pas le tableau en cours de construction il n'existe aucun moyen d'accder au tableau en cours de construction depuis la fonction de rappel.

Utiliser flatMap() sur des tableaux creux

callbackFn ne sera pas appele pour les trous dans le tableau source car map() ne le fait pas, tandis que flat() ignore les trous dans les tableaux retourns.

console.log([1, 2, , 4, 5].flatMap((x) => [x, x * 2])); // [1, 2, 2, 4, 4, 8, 5, 10]
console.log([1, 2, 3, 4].flatMap((x) => [, x * 2])); // [2, 4, 6, 8]

Appeler flatMap() sur des objets qui ne sont pas des tableaux

La mthode flatMap() lit la proprit length de this puis accde chaque proprit dont la cl est un entier non ngatif infrieur length. Si la valeur de retour de la fonction de rappel n'est pas un tableau, elle est toujours ajoute directement au tableau rsultat.

const objetSimilaireTableau = {
  length: 3,
  0: 1,
  1: 2,
  2: 3,
  3: 4, // ignor par flatMap() car length vaut 3
};
console.log(
  Array.prototype.flatMap.call(objetSimilaireTableau, (x) => [x, x * 2]),
);
// [1, 2, 2, 4, 3, 6]

// Les objets de type tableau retourns par la fonction de rappel ne seront pas aplats
console.log(
  Array.prototype.flatMap.call(objetSimilaireTableau, (x) => ({
    length: 1,
    0: x,
  })),
);
// [ { '0': 1, length: 1 }, { '0': 2, length: 1 }, { '0': 3, length: 1 } ]

Spcifications

Compatibilit des navigateurs

Voir aussi

• Guide des collections indexes
• L'objet global Array
• La mthode Array.prototype.concat()
• La mthode Array.prototype.flat()
• La mthode Array.prototype.map()
• La mthode Array.prototype.reduce()
• Prothse d'mulation de Array.prototype.flatMap dans corejs (angl.)
• Prothse d'mulation de Array.prototype.flatMap dans esshims (angl.)