Iterator.prototype.flatMap()

Syntax

flatMap(callbackFn)

Parameter

callbackFn

Eine Funktion, die für jedes vom Iterator erzeugte Element ausgeführt wird. Sie muss einen Iterator oder ein Iterable zurückgeben, dessen Elemente von flatMap() geliefert werden. Anders als bei Array.prototype.flatMap() können Sie keine einzelnen Werte zurückgeben, die weder Iteratoren noch Iterables sind. Die Funktion wird mit den folgenden Argumenten aufgerufen:

element

Das aktuelle Element, das verarbeitet wird.

index

Der Index des aktuellen Elements, das verarbeitet wird.

Rückgabewert

Ein neues Iterator-Hilfsobjekt. Beim ersten Aufruf der next()-Methode des Iterator-Hilfsobjekts wird callbackFn mit dem ersten Element aufgerufen, das der zugrunde liegende Iterator erzeugt. Die Elemente des Rückgabewerts, der ein Iterator oder Iterable sein muss, werden vom Iterator-Hilfsobjekt nacheinander geliefert (wie bei yield*). Das nächste Element wird erst dann vom zugrunde liegenden Iterator abgerufen, wenn der zuvor von callbackFn zurückgegebene Iterator oder das Iterable vollständig durchlaufen wurde. Ist der zugrunde liegende Iterator vollständig durchlaufen, ist auch das Iterator-Hilfsobjekt vollständig durchlaufen (die next()-Methode gibt { value: undefined, done: true } zurück).

Ausnahmen

TypeError

Wird ausgelöst, wenn callbackFn einen Wert zurückgibt, der weder ein Iterator noch ein Iterable ist, oder einen primitiven String-Wert.

Beschreibung

flatMap akzeptiert zwei Arten von Rückgabewerten von callbackFn: Iteratoren und Iterables. Sie werden genauso behandelt wie bei Iterator.from(): Ist der Rückgabewert ein Iterable, wird dessen [Symbol.iterator]()-Methode aufgerufen und deren Rückgabewert verwendet. Andernfalls wird der Rückgabewert als Iterator behandelt und dessen next()-Methode aufgerufen.

[1, 2, 3]
  .values()
  .flatMap((x) => {
    let itDone = false;
    const it = {
      next() {
        if (itDone) {
          return { value: undefined, done: true };
        }
        itDone = true;
        return { value: x, done: false };
      },
    };
    switch (x) {
      case 1:
        // An iterable that's not an iterator
        return { [Symbol.iterator]: () => it };
      case 2:
        // An iterator that's not an iterable
        return it;
      case 3:
        // An iterable iterator is treated as an iterable
        return {
          ...it,
          [Symbol.iterator]() {
            console.log("Symbol.iterator called");
            return it;
          },
        };
      default:
        return undefined;
    }
  })
  .toArray();
// Logs "Symbol.iterator called"
// Returns [1, 2, 3]

Beispiele

Maps zusammenführen

Das folgende Beispiel führt zwei Map-Objekte zu einem zusammen:

const map1 = new Map([
  ["a", 1],
  ["b", 2],
  ["c", 3],
]);
const map2 = new Map([
  ["d", 4],
  ["e", 5],
  ["f", 6],
]);

const merged = new Map([map1, map2].values().flatMap((x) => x));
console.log(merged.get("a")); // 1
console.log(merged.get("e")); // 5

Dabei werden keine temporären Kopien der Inhalte der Maps erstellt. Beachten Sie, dass das Array [map1, map2] zuerst in einen Iterator umgewandelt werden muss (mithilfe von Array.prototype.values()), da Array.prototype.flatMap() nur Arrays abflacht, nicht aber Iterables.

new Map([map1, map2].flatMap((x) => x)); // Map(1) {undefined => undefined}

Strings zurückgeben

Strings sind iterierbar, aber flatMap() weist primitive String-Werte, die von callbackFn zurückgegeben werden, ausdrücklich zurück. Der Grund dafür ist, dass eine Iteration über Codepoints oft nicht das gewünschte Verhalten ist.

[1, 2, 3]
  .values()
  .flatMap((x) => String(x))
  .toArray(); // TypeError: Iterator.prototype.flatMap called on non-object

Sie können den String stattdessen in ein Array einschließen, damit er als Ganzes geliefert wird:

[1, 2, 3]
  .values()
  .flatMap((x) => [String(x)])
  .toArray(); // ['1', '2', '3']

Wenn Sie dagegen über die Codepoints iterieren möchten, können Sie den String mit Iterator.from() in einen Iterator umwandeln:

[1, 2, 3]
  .values()
  .flatMap((x) => Iterator.from(String(x * 10)))
  .toArray();
// ['1', '0', '2', '0', '3', '0']

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Polyfill für Iterator.prototype.flatMap in core-js
• Polyfill für Iterator.prototype.flatMap von es-shims