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

Signatur

TypedArray.prototype.includes(searchElement, fromIndex)

Beschreibung

includes() durchsucht ein typisiertes Array (z. B. Uint8Array, Float64Array, BigInt64Array) nach einem Wert und liefert einen Wahrheitswert. Der Algorithmus ist derselbe wie bei Array.prototype.includes(), allerdings arbeitet die Methode nur auf typisierten Arrays und ist nicht generisch: this muss eine TypedArray-Instanz sein.

Der Vergleich verwendet SameValueZero. Das bedeutet: NaN wird gefunden (anders als bei indexOf()), und +0 und -0 gelten als gleich. Der Suchwert wird nicht umgewandelt – ein String wie "10" passt also nie auf das Element 10.

Mit dem optionalen Parameter fromIndex legst du fest, ab welcher Position gesucht wird. Negative Werte zählen vom Ende aus. Typische Einsatzfälle sind das Prüfen von Binärdaten auf bestimmte Bytes (z. B. Nullbytes oder Trennzeichen), das Validieren von Messwerten oder schnelle Existenzprüfungen, bei denen die Position selbst nicht interessiert – dafür gibt es indexOf() bzw. findIndex().

Parameter

Name	Typ	Default	Beschreibung
$searchElement Pflicht	number \| bigint		Der gesuchte Wert. Bei `BigInt64Array`/`BigUint64Array` muss ein `bigint` übergeben werden, sonst ein `number`. Es findet keine Typumwandlung statt.
$fromIndex	number	0	Startindex der Suche (wird in eine Ganzzahl umgewandelt). Negative Werte zählen vom Ende (`length + fromIndex`). Ist der Wert ≥ `length`, wird `false` zurückgegeben, ohne zu suchen.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn der Wert im durchsuchten Bereich vorkommt, sonst false.

Beispiele

Grundlegende Suche mit und ohne fromIndex

const bytes = new Uint8Array([10, 20, 30, 40]);

console.log(bytes.includes(20));     // vorhanden
console.log(bytes.includes(50));     // nicht vorhanden
console.log(bytes.includes(20, 2));  // Suche ab Index 2
console.log(bytes.includes(40, -1)); // nur das letzte Element

true false false true

Binärdaten auf ein Nullbyte prüfen

const hasNullByte = (text) => new TextEncoder().encode(text).includes(0);

console.log(hasNullByte('Hallo Welt'));
console.log(hasNullByte('Hallo\0Welt'));

false true

NaN finden – Unterschied zu indexOf()

const messwerte = new Float64Array([21.5, NaN, 22.1]);

console.log(messwerte.includes(NaN)); // SameValueZero
console.log(messwerte.indexOf(NaN));  // strikte Gleichheit
console.log(messwerte.includes(-0) === messwerte.includes(0));

true -1 true

Typische Fallstricke: Typen, Wertebereich, Genauigkeit

const u8 = new Uint8Array([10, 44]);
console.log(u8.includes('10'));  // keine Typumwandlung
console.log(u8.includes(300));   // wurde beim Speichern zu 44, Suche nach 300 schlägt fehl

const big = new BigInt64Array([5n, 7n]);
console.log(big.includes(5));    // number statt bigint
console.log(big.includes(5n));

const f32 = new Float32Array([0.1]);
console.log(f32.includes(0.1));             // 32-Bit-Rundung
console.log(f32.includes(Math.fround(0.1)));

false false false true false true

// Wichtig · Fallstricke

Keine Typumwandlung: "1" findet nicht 1, und bei BigInt-Arrays findet 5 nicht 5n.
Gleitkomma-Genauigkeit: In Float32Array werden Werte auf 32 Bit gerundet gespeichert. new Float32Array([0.1]).includes(0.1) ergibt deshalb false. Nutze Math.fround() für den Suchwert oder vergleiche mit Toleranz über some().
Überlauf beim Speichern: Werte außerhalb des Wertebereichs werden beim Schreiben umgebrochen oder begrenzt (Uint8ClampedArray). Die Suche nach dem Originalwert schlägt dann fehl.
Nicht generisch: Anders als Array.prototype.includes wirft ein Aufruf mit einem normalen Array als this einen TypeError.
Bei einem abgetrennten (detached) ArrayBuffer ist die Länge 0 und das Ergebnis immer false.
Laufzeit ist linear (O(n)). Für viele Abfragen auf großen Daten lohnt sich ein Set.
Kompatibilität: in allen modernen Browsern verfügbar, nicht im Internet Explorer.

Siehe auch

TypedArray.prototype.indexOf() TypedArray.prototype.lastIndexOf() TypedArray.prototype.find() TypedArray.prototype.some() Array.prototype.includes() TypedArray