DataView.prototype.setInt32() — Methode · JavaScript-Referenz

Signatur

DataView.prototype.setInt32(byteOffset, value, littleEndian)

Beschreibung

setInt32() speichert einen Zahlenwert als 32-Bit-Ganzzahl mit Vorzeichen (Zweierkomplement, Wertebereich -2147483648 bis 2147483647) in den 4 Bytes ab dem angegebenen Byte-Offset des zugrunde liegenden ArrayBuffer. Anders als bei einem Int32Array muss der Offset nicht an 4 Bytes ausgerichtet sein, und Sie legen die Byte-Reihenfolge selbst fest.

Typische Einsatzgebiete sind das Erzeugen binärer Dateiformate (z. B. BMP- oder WAV-Header), Netzwerkprotokolle über WebSocket oder fetch, WebAssembly-Speicher sowie jede Situation, in der mehrere Datentypen unterschiedlicher Größe in einem Puffer gemischt werden.

Der Wert wird zunächst per ToInt32 umgewandelt: Nachkommastellen werden abgeschnitten, Werte außerhalb des Bereichs laufen modulo 2³² über, NaN und Infinity werden zu 0. Ohne dritten Parameter wird Big-Endian geschrieben – das ist die Netzwerk-Byte-Reihenfolge, aber nicht die native Reihenfolge der meisten Rechner (x86, ARM sind Little-Endian).

Parameter

Name	Typ	Default	Beschreibung
$byteOffset Pflicht	number		Offset in Bytes vom Anfang der DataView (nicht des Buffers), ab dem geschrieben wird. Muss so gewählt sein, dass `byteOffset + 4 <= byteLength` gilt.
$value Pflicht	number		Der zu speichernde Wert. Wird per `ToInt32` in eine 32-Bit-Ganzzahl mit Vorzeichen umgewandelt.
$littleEndian	boolean	false	`true` schreibt im Little-Endian-Format, `false` oder weggelassen im Big-Endian-Format.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert; die Methode verändert den zugrunde liegenden ArrayBuffer direkt.

Beispiele

Wert schreiben und in beiden Byte-Reihenfolgen prüfen

const buffer = new ArrayBuffer(8);
const view = new DataView(buffer);

view.setInt32(0, -2);          // Big-Endian (Standard)
view.setInt32(4, -2, true);    // Little-Endian

console.log(new Uint8Array(buffer));
console.log(view.getInt32(0), view.getInt32(4, true));

Uint8Array(8) [255, 255, 255, 254, 254, 255, 255, 255] -2 -2

Nachrichten-Header für ein Binärprotokoll bauen

// Aufbau: [Typ: Int32][Länge: Int32][Nutzdaten...] in Netzwerk-Byte-Reihenfolge
const buildMessage = (type, payload) => {
  const bytes = new TextEncoder().encode(payload);
  const buffer = new ArrayBuffer(8 + bytes.length);
  const view = new DataView(buffer);
  view.setInt32(0, type);          // Big-Endian
  view.setInt32(4, bytes.length);
  new Uint8Array(buffer, 8).set(bytes);
  return buffer;
};

const msg = buildMessage(42, 'Hallo');
console.log(new Uint8Array(msg, 0, 8));

Uint8Array(8) [0, 0, 0, 42, 0, 0, 0, 5]

Überlauf, Nachkommastellen und Bereichsfehler

const view = new DataView(new ArrayBuffer(4));

view.setInt32(0, 2147483648);   // 2^31 läuft über
console.log(view.getInt32(0));

view.setInt32(0, 3.99);         // wird abgeschnitten
console.log(view.getInt32(0));

try {
  view.setInt32(1, 7);          // 1 + 4 > 4 Bytes
} catch (err) {
  console.log(err.name);
}

-2147483648 3 RangeError

// Wichtig · Fallstricke

Standard ist Big-Endian: Wer das dritte Argument vergisst, schreibt Daten, die ein Int32Array auf derselben Maschine falsch liest. Beim Lesen mit getInt32() immer dieselbe Byte-Reihenfolge verwenden.
RangeError, wenn byteOffset negativ ist oder byteOffset + 4 über das Ende der View hinausgeht.
Stiller Überlauf: Werte außerhalb von −2³¹…2³¹−1 erzeugen keinen Fehler, sondern werden modulo 2³² umgebrochen. Bei Bedarf vorher selbst prüfen.
BigInt-Werte lösen einen TypeError aus – dafür gibt es setBigInt64().
Bei einem abgetrennten (detached) ArrayBuffer, z. B. nach Übertragung per postMessage, wird ein TypeError geworfen.
Seit ES2015 in allen modernen Browsern und Node.js verfügbar.

Siehe auch

DataView DataView.prototype.getInt32() DataView.prototype.setUint32() DataView.prototype.setInt16() DataView.prototype.setBigInt64() Int32Array ArrayBuffer