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

Signatur

DataView.prototype.setInt8(byteOffset, value)

Beschreibung

setInt8() schreibt genau ein Byte in den zugrunde liegenden ArrayBuffer (bzw. SharedArrayBuffer) eines DataView. Der übergebene Wert wird in eine Zahl umgewandelt und als vorzeichenbehaftete 8-Bit-Ganzzahl im Zweierkomplement abgelegt. Gültig sind also Werte von -128 bis 127.

Weil nur ein einzelnes Byte geschrieben wird, spielt die Byte-Reihenfolge (Endianness) keine Rolle. Deshalb gibt es anders als bei setInt16() oder setInt32() keinen Parameter littleEndian.

Typische Einsatzfälle sind Binärprotokolle, Dateiformate (z. B. WAV mit 8 Bit, eigene Header-Formate) oder Netzwerkpakete. Dort stehen vorzeichenbehaftete Bytes oft neben Feldern mit anderer Breite, etwa Temperaturwerte, Deltas oder Offsets. Mit DataView lassen sich solche Strukturen gemischt und byte-genau beschreiben.

Werte außerhalb des Bereichs werden nicht gekappt, sondern modulo 2⁸ umgebrochen. Nachkommastellen werden abgeschnitten (Richtung Null). NaN und Infinity werden zu 0.

Parameter

Name	Typ	Default	Beschreibung
$byteOffset Pflicht	number		Position in Bytes, gemessen vom Anfang der View (nicht des Buffers). Muss zwischen `0` und `byteLength - 1` liegen, sonst wird ein `RangeError` ausgelöst.
$value Pflicht	number		Zu schreibender Wert. Er wird mit `ToInt8` umgewandelt: Nachkommastellen werden abgeschnitten, dann wird modulo 256 in den Bereich −128…127 umgebrochen.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Die Methode schreibt direkt in den zugrunde liegenden Buffer.

Beispiele

Grundlagen: Wert schreiben und wieder lesen

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

view.setInt8(0, 127);
view.setInt8(1, -128);
view.setInt8(2, -1);

console.log(view.getInt8(0));  // 127
console.log(view.getInt8(1));  // -128
console.log(view.getInt8(2));  // -1
// Dasselbe Byte ohne Vorzeichen gelesen:
console.log(view.getUint8(2)); // 255

127 -128 -1 255

Überlauf und Umwandlung von Werten

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

view.setInt8(0, 128);   // bricht um auf -128
view.setInt8(1, 300);   // 300 - 256 = 44
view.setInt8(2, -3.9);  // Nachkommastellen abgeschnitten -> -3
view.setInt8(3, NaN);   // -> 0
view.setInt8(4, '42');  // String wird in Zahl umgewandelt

console.log([0, 1, 2, 3, 4].map(i => view.getInt8(i)));

[ -128, 44, -3, 0, 42 ]

Praxis: Sensor-Paket mit gemischten Feldern bauen

// Format: [Typ: Uint8][Temperatur: Int8][Luftfeuchte: Uint8][Zeit: Uint32 LE]
const buildPacket = ({ type, tempC, humidity, timestamp }) => {
  const view = new DataView(new ArrayBuffer(7));
  view.setUint8(0, type);
  view.setInt8(1, Math.max(-128, Math.min(127, Math.round(tempC)))); // selbst begrenzen!
  view.setUint8(2, humidity);
  view.setUint32(3, timestamp, true);
  return new Uint8Array(view.buffer);
};

const packet = buildPacket({ type: 1, tempC: -12.4, humidity: 65, timestamp: 1700000000 });
console.log(Array.from(packet, b => b.toString(16).padStart(2, '0')).join(' '));

01 f4 41 00 f1 53 65

Fehlerfall: Offset außerhalb der View

const buffer = new ArrayBuffer(8);
const view = new DataView(buffer, 4, 2); // View über Bytes 4 und 5

view.setInt8(1, -5);                      // schreibt in Byte 5 des Buffers
console.log(new Int8Array(buffer)[5]);    // -5

try {
  view.setInt8(2, 1); // liegt außerhalb der View
} catch (err) {
  console.log(err.name);
}

-5 RangeError

// Wichtig · Fallstricke

Kein Kappen: Werte außerhalb von −128…127 werden stillschweigend umgebrochen (128 → -128). Wenn du einen gekappten Wert brauchst, begrenze ihn vorher selbst mit Math.min/Math.max. Anders als Uint8ClampedArray klemmt DataView nichts.
Offset relativ zur View: byteOffset zählt ab dem Anfang der View, nicht ab dem Anfang des Buffers. Ein negativer Offset oder einer ≥ byteLength löst einen RangeError aus.
Abgetrennte Buffer: Wurde der Buffer abgetrennt (detached), etwa durch postMessage mit Transfer oder ArrayBuffer.prototype.transfer(), wirft der Aufruf einen TypeError.
BigInt nicht erlaubt: Ein BigInt als value führt zu einem TypeError. Für 64-Bit-Werte gibt es setBigInt64().
Einen Parameter littleEndian gibt es nicht. Wird trotzdem ein drittes Argument übergeben, wird es ignoriert.
Kompatibilität: wird seit Jahren von allen modernen Browsern und von Node.js unterstützt. Bei vielen gleichartigen Bytes ist ein Int8Array meist schneller und bequemer.

Siehe auch

DataView DataView.prototype.getInt8() DataView.prototype.setUint8() DataView.prototype.setInt16() Int8Array ArrayBuffer