new Int32Array() — Methode · JavaScript-Referenz

Signatur

new Int32Array(lengthOrSourceOrBuffer, byteOffset, length)

Beschreibung

Mit new Int32Array() legst du ein typisiertes Array an, dessen Elemente vorzeichenbehaftete 32-Bit-Ganzzahlen im Bereich von -2147483648 bis 2147483647 sind. Jedes Element belegt genau 4 Byte. Alle Elemente werden mit 0 initialisiert, sofern keine Quelldaten angegeben sind.

Der Konstruktor kennt mehrere Aufrufvarianten:

new Int32Array() – leeres Array mit Länge 0.
new Int32Array(length) – neues Array mit length Elementen, alle mit 0 belegt.
new Int32Array(typedArray) – kopiert die Werte aus einem anderen typisierten Array und wandelt sie dabei um.
new Int32Array(object) – übernimmt Werte aus einem iterierbaren oder array-ähnlichen Objekt (z. B. einem normalen Array).
new Int32Array(buffer, byteOffset, length) – erzeugt eine Sicht auf einen vorhandenen ArrayBuffer oder SharedArrayBuffer, ohne Daten zu kopieren.

Typische Einsatzgebiete sind Binärprotokolle, WebGL (Integer-Attribute und Indizes), WebAssembly-Speicher, Audio- und Bildverarbeitung sowie Zähler, die zwischen Workern über SharedArrayBuffer und Atomics geteilt werden. Im Vergleich zu normalen Arrays sind typisierte Arrays kompakt und schnell, haben aber eine feste Länge und akzeptieren nur Zahlen.

Werte außerhalb des Wertebereichs werden nicht begrenzt, sondern modulo 2³² umgebrochen (Überlauf). Nachkommastellen werden in Richtung 0 abgeschnitten, NaN und Infinity werden zu 0.

Parameter

Name	Typ	Default	Beschreibung
$length	number	0	Anzahl der Elemente. Es werden `length * 4` Byte reserviert, alle Elemente sind `0`.
$typedArray	TypedArray		Ein anderes typisiertes Array (z. B. `Float64Array`). Die Werte werden kopiert und in 32-Bit-Ganzzahlen umgewandelt. `BigInt64Array` ist nicht zulässig (`TypeError`).
$object	Iterable\|ArrayLike		Ein iterierbares oder array-ähnliches Objekt, dessen Werte übernommen werden, z. B. `[1, 2, 3]` oder ein `Set`.
$buffer	ArrayBuffer\|SharedArrayBuffer		Vorhandener Speicherpuffer, auf den das neue Array als Sicht zugreift. Änderungen wirken sich auf alle Sichten desselben Puffers aus.
$byteOffset	number	0	Startposition im `buffer` in Byte. Muss ein Vielfaches von 4 sein, sonst wird ein `RangeError` geworfen.
$length	number	(buffer.byteLength - byteOffset) / 4	Anzahl der Elemente der Sicht (nur zusammen mit `buffer`). Ohne Angabe reicht die Sicht bis zum Ende des Puffers.

Rückgabewert

Typ

Int32Array

Beschreibung

Ein neues Int32Array-Objekt – entweder mit eigenem Puffer oder als Sicht auf den übergebenen ArrayBuffer.

Beispiele

Verschiedene Konstruktor-Varianten

const leer = new Int32Array(4);
const ausArray = new Int32Array([10, -20, 30]);
const ausSet = new Int32Array(new Set([1, 2, 2, 3]));
const ausFloat = new Int32Array(new Float64Array([1.9, -1.9, NaN]));

console.log(leer);
console.log(ausArray);
console.log(ausSet);
console.log(ausFloat);
console.log(leer.byteLength);

Int32Array(4) [0, 0, 0, 0] Int32Array(3) [10, -20, 30] Int32Array(3) [1, 2, 3] Int32Array(3) [1, -1, 0] 16

Überlauf-Verhalten verstehen

const werte = new Int32Array([2147483647, 2147483648, -2147483649, 4294967296]);
console.log(werte);

// Addition über das Maximum hinaus bricht um
const zaehler = new Int32Array(1);
zaehler[0] = 2147483647;
zaehler[0]++;
console.log(zaehler[0]);

Int32Array(4) [2147483647, -2147483648, 2147483647, 0] -2147483648

Sicht auf einen ArrayBuffer mit byteOffset

const buffer = new ArrayBuffer(16); // Platz für 4 Int32-Werte
const gesamt = new Int32Array(buffer);
const hintereHaelfte = new Int32Array(buffer, 8, 2);

hintereHaelfte[0] = 42;
hintereHaelfte[1] = -7;

// Beide Sichten teilen sich denselben Speicher
console.log(gesamt);

try {
  new Int32Array(buffer, 3); // kein Vielfaches von 4
} catch (err) {
  console.log(err.name);
}

Int32Array(4) [0, 0, 42, -7] RangeError

Geteilter Zähler zwischen Workern mit Atomics

// Im Hauptthread
const shared = new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT);
const counter = new Int32Array(shared);

// Threadsicher erhöhen (auch aus Workern, die denselben Puffer erhalten)
Atomics.add(counter, 0, 5);
Atomics.add(counter, 0, 1);
console.log(Atomics.load(counter, 0));

// Übergabe an einen Worker: worker.postMessage(shared);

6

// Wichtig · Fallstricke

Nur mit new: Ein Aufruf ohne new (Int32Array([1, 2])) wirft einen TypeError.
Stiller Überlauf: Werte außerhalb von −2³¹ bis 2³¹−1 werden ohne Fehlermeldung umgebrochen. Für begrenzte Werte (Clamping) musst du selbst prüfen oder bei Bytes Uint8ClampedArray verwenden.
Ausrichtung: byteOffset muss ein Vielfaches von 4 sein, und die Restlänge des Puffers muss durch 4 teilbar sein, wenn keine length angegeben ist – sonst entsteht ein RangeError. Für nicht ausgerichtete Zugriffe eignet sich DataView.
Endianness: Die Byte-Reihenfolge entspricht der Plattform (in der Praxis fast immer Little-Endian). Für Netzwerkprotokolle oder Dateiformate mit fester Byte-Reihenfolge solltest du DataView mit getInt32(offset, littleEndian) nutzen.
Kopie oder Sicht: Aus einem Array oder typisierten Array wird kopiert, aus einem ArrayBuffer dagegen nur eine Sicht erzeugt. Änderungen an der Sicht verändern den Puffer.
BigInt: BigInt-Werte oder BigInt64Array als Quelle führen zu einem TypeError.
Kompatibilität: In allen modernen Browsern und Node.js verfügbar. SharedArrayBuffer steht im Browser nur in „cross-origin isolated“ Kontexten zur Verfügung (Header COOP/COEP).

Siehe auch

Int32Array Uint32Array TypedArray ArrayBuffer SharedArrayBuffer DataView Atomics BigInt64Array