new Int8Array() — Methode · JavaScript-Referenz

Signatur

new Int8Array(lengthOrSourceOrBuffer, byteOffset, length)

Beschreibung

Mit new Int8Array() legst du ein typisiertes Array an, dessen Elemente jeweils genau ein Byte belegen und als vorzeichenbehaftete Ganzzahl im Zweierkomplement gelesen werden. Der Wertebereich reicht von -128 bis 127. Solche Arrays nimmt man für Binärdaten, etwa Audio-Samples, Netzwerkprotokolle, WebGL-Puffer oder WebAssembly-Speicher.

Welche Form der Konstruktor verwendet, hängt vom ersten Argument ab:

Ohne Argument oder mit einer Zahl: Es entsteht ein neues, mit Nullen gefülltes Array der angegebenen Länge.
Typisiertes Array: Die Werte werden in einen neuen Puffer kopiert und dabei nach Int8 umgewandelt.
Iterierbares Objekt oder array-ähnliches Objekt (z. B. Array, Set): Die Elemente werden kopiert und umgewandelt.
ArrayBuffer bzw. SharedArrayBuffer: Es entsteht eine Ansicht auf den vorhandenen Speicher. Dabei wird nichts kopiert, Änderungen wirken sich also direkt auf den Puffer aus.

Werte außerhalb des Wertebereichs werden nicht begrenzt, sondern modulo 2⁸ umgebrochen. So wird aus 128 der Wert -128. Nachkommastellen fallen weg (Richtung 0), und NaN wird zu 0. Den Konstruktor musst du immer mit new aufrufen.

Parameter

Name	Typ	Default	Beschreibung
$length	number	0	Anzahl der Elemente. Das Array wird mit `0` vorbelegt.
$typedArray	TypedArray		Ein anderes typisiertes Array, dessen Werte kopiert und nach Int8 umgewandelt werden.
$object	Iterable\|ArrayLike		Ein iterierbares oder array-ähnliches Objekt, dessen Elemente kopiert werden.
$buffer	ArrayBuffer\|SharedArrayBuffer		Ein vorhandener Puffer, auf den das neue Array als Ansicht zugreift. Es wird nichts kopiert.
$byteOffset	number	0	Nur zusammen mit `buffer`: der Byte-Versatz, ab dem die Ansicht beginnt.
$length	number	bis zum Pufferende	Nur zusammen mit `buffer`: die Anzahl der Elemente in der Ansicht.

Rückgabewert

Typ

Int8Array

Beschreibung

Eine neue Int8Array-Instanz.

Beispiele

Leeres Array fester Länge und Überlauf

const werte = new Int8Array(4);
werte[0] = 100;
werte[1] = 127;
werte[2] = 128;   // Überlauf: wird umgebrochen
werte[3] = -3.9;  // Nachkommastellen fallen weg
console.log(werte);

Int8Array(4) [100, 127, -128, -3]

Aus Array oder Set erzeugen

const ausArray = new Int8Array([1, -2, 300]);
console.log(ausArray);

const ausSet = new Int8Array(new Set([5, 5, 6]));
console.log(ausSet.length);

Int8Array(3) [1, -2, 44] 2

Vorzeichenbehaftete Bytes aus einem ArrayBuffer lesen

const buffer = new ArrayBuffer(8);
const bytes = new Uint8Array(buffer);
bytes.set([0xff, 0x80, 0x7f, 0x01]);

// Ansicht ab Byte 0 mit 4 Elementen, ohne Kopie
const signed = new Int8Array(buffer, 0, 4);
console.log(signed);

signed[0] = 10; // ändert auch den Puffer
console.log(bytes[0]);

Int8Array(4) [-1, -128, 127, 1] 10

Kopie aus einem anderen typisierten Array

const floats = new Float32Array([1.7, -129, 42.2]);
const ints = new Int8Array(floats);
console.log(ints);

Int8Array(3) [1, 127, 42]

// Wichtig · Fallstricke

Wenn du den Konstruktor ohne new aufrufst (Int8Array(4)), wird ein TypeError ausgelöst.
Negative Längen oder solche jenseits der Maximalgröße führen zu einem RangeError. Dasselbe gilt, wenn byteOffset oder length über den Puffer hinausreichen.
Werte außerhalb von -128 bis 127 werden umgebrochen, nicht begrenzt: 300 wird zu 44, -129 zu 127. Wenn du begrenzte Werte brauchst, nimm Uint8ClampedArray (nur 0–255) oder begrenze die Werte vorher selbst.
Eine Ansicht auf einen ArrayBuffer teilt sich den Speicher mit dem Puffer. Eine Kopie entsteht nur bei Arrays, Iterables oder anderen typisierten Arrays.
Seit ES2024 können Puffer in der Größe veränderbar sein (new ArrayBuffer(n, { maxByteLength })). Eine Ansicht ohne length wächst dann mit dem Puffer mit.
Browser-Kompatibilität: Der Konstruktor wird von allen modernen Browsern und von Node.js unterstützt. Die Form mit Iterable-Argument ist seit ES2015 standardisiert.

Siehe auch

Int8Array Uint8Array Uint8ClampedArray ArrayBuffer DataView TypedArray.from() new BigInt64Array()