TypedArray.prototype.values() — Methode · JavaScript-Referenz

Signatur

TypedArray.prototype.values()

Beschreibung

Die Methode values() gibt es auf allen typisierten Arrays, also etwa Uint8Array, Int16Array, Float32Array oder BigInt64Array. Sie liefert ein Array-Iterator-Objekt, das die Elementwerte in Index-Reihenfolge zurückgibt. Sie verhält sich genau wie Array.prototype.values().

TypedArray.prototype.values ist dieselbe Funktion wie TypedArray.prototype[Symbol.iterator]. Deshalb nutzen for...of, der Spread-Operator ([...ta]), Array.from() und die Destrukturierung intern genau diesen Iterator. Einen expliziten Aufruf von values() braucht man vor allem, wenn man den Iterator manuell mit next() steuern oder an eine Funktion weitergeben will, die ein Iterator-Objekt erwartet.

Der Iterator ist lazy (bedarfsgesteuert): Er liest jeden Wert erst beim Aufruf von next() aus dem zugrunde liegenden Speicher. Ändert man das Array während der Iteration, sieht der Iterator diese Änderungen. Ist der Iterator einmal am Ende angekommen, kann man ihn nicht zurücksetzen. Für einen neuen Durchlauf ruft man values() erneut auf.

Rückgabewert

Typ

Iterator<number> | Iterator<bigint>

Beschreibung

Ein neues, iterierbares Array-Iterator-Objekt. Jeder Aufruf von next() liefert { value, done }. Bei BigInt64Array und BigUint64Array sind die Werte vom Typ bigint, sonst vom Typ number.

Beispiele

Werte mit for...of durchlaufen

const pixel = new Uint8Array([255, 128, 0, 255]);

for (const channel of pixel.values()) {
  console.log(channel);
}

255 128 0 255

Iterator manuell mit next() steuern

const samples = new Float32Array([0.5, -0.25, 1]);
const it = samples.values();

console.log(it.next()); // erster Wert
console.log(it.next());
console.log(it.next());
console.log(it.next()); // Ende erreicht

{ value: 0.5, done: false } { value: -0.25, done: false } { value: 1, done: false } { value: undefined, done: true }

Summe über einen Datenpuffer berechnen

const buffer = new ArrayBuffer(8);
const view = new Int16Array(buffer);
view.set([100, -20, 300, 5]);

const sum = (iterable) => {
  let total = 0;
  for (const v of iterable) total += v;
  return total;
};

console.log(sum(view.values()));

385

Iterator ist nach einem Durchlauf erschöpft

const bytes = new Uint8Array([1, 2, 3]);
const it = bytes.values();

console.log([...it]); // erster Durchlauf
console.log([...it]); // leer – Iterator verbraucht
console.log([...bytes.values()]); // neuer Iterator

[ 1, 2, 3 ] [] [ 1, 2, 3 ]

// Wichtig · Fallstricke

Einmal verbraucht: Ein Iterator lässt sich nur ein einziges Mal durchlaufen. Soll mehrfach iteriert werden, entweder values() erneut aufrufen oder direkt das typisierte Array selbst iterieren.
Änderungen während der Iteration: Der Iterator liest die Werte live aus dem Speicher. Werden Elemente während des Durchlaufs geändert, erscheinen die neuen Werte.
Abgelöster oder verkleinerter Puffer: Wird der zugrunde liegende ArrayBuffer abgelöst (z. B. durch postMessage mit Transfer oder durch ArrayBuffer.prototype.transfer()), wirft ein weiterer Aufruf von next() einen TypeError. Bei in der Größe veränderbaren Puffern endet die Iteration früher, wenn der Puffer schrumpft.
Typen: BigInt64Array und BigUint64Array liefern bigint-Werte. Diese lassen sich nicht ohne Weiteres mit number-Werten verrechnen.
Performance: In sehr heißen Schleifen ist eine klassische for-Schleife mit Indexzugriff oft etwas schneller als der Umweg über einen Iterator.
Kompatibilität: Wird von allen modernen Browsern und von Node.js unterstützt. Der Internet Explorer unterstützt die Methode nicht.

Siehe auch

TypedArray.prototype.keys() TypedArray.prototype.entries() Array.prototype.values() for...of TypedArray