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

Signatur

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

Beschreibung

setBigUint64() speichert einen BigInt-Wert als vorzeichenlose 64-Bit-Ganzzahl (Wertebereich 0 bis 2⁶⁴ − 1) in acht aufeinanderfolgende Bytes des zugrunde liegenden ArrayBuffer bzw. SharedArrayBuffer. Da gewöhnliche Number-Werte nur Ganzzahlen bis 2⁵³ − 1 exakt darstellen, braucht man für volle 64-Bit-Werte zwingend BigInt.

Typische Anwendungsfälle sind Binärprotokolle und Dateiformate mit 64-Bit-Feldern: Zeitstempel in Nano- oder Mikrosekunden, Dateigrößen und -offsets (z. B. ZIP64, MP4-Boxen), Hashwerte, IDs aus Datenbanken oder Snowflake-IDs sowie der Datenaustausch mit WebAssembly-Speicher.

Anders als bei typisierten Arrays wie BigUint64Array steuerst du mit DataView die Bytereihenfolge ausdrücklich. Ohne dritten Parameter wird Big-Endian (Netzwerk-Bytereihenfolge) verwendet. Außerdem muss der Offset nicht an 8 Bytes ausgerichtet sein, sodass du 64-Bit-Werte an beliebigen Stellen eines Puffers ablegen kannst.

Werte außerhalb des Bereichs werden modulo 2⁶⁴ umgebrochen. So wird z. B. -1n zu 18446744073709551615n. Einen Fehler gibt es dabei nicht.

Parameter

Name	Typ	Default	Beschreibung
$byteOffset Pflicht	number		Offset in Bytes vom Anfang des Views, ab dem geschrieben wird. Muss so gewählt sein, dass `byteOffset + 8 <= view.byteLength` gilt.
$value Pflicht	bigint		Zu speichernder Wert. Er wird per `ToBigInt` umgewandelt und modulo `2⁶⁴` umgebrochen. Ein `Number`-Wert löst einen `TypeError` aus.
$littleEndian	boolean	false	Mit `true` wird im Little-Endian-Format geschrieben, mit `false` oder ohne Angabe im Big-Endian-Format.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Die Methode verändert den zugrunde liegenden Puffer direkt.

Beispiele

Größten 64-Bit-Wert schreiben und zurücklesen

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

view.setBigUint64(0, 2n ** 64n - 1n);
console.log(view.getBigUint64(0));

18446744073709551615n

Big-Endian und Little-Endian im Vergleich

const buffer = new ArrayBuffer(16);
const view = new DataView(buffer);
const value = 0x0102030405060708n;

view.setBigUint64(0, value);        // Big-Endian (Standard)
view.setBigUint64(8, value, true);  // Little-Endian

const bytes = new Uint8Array(buffer);
console.log([...bytes.slice(0, 8)].join(' '));
console.log([...bytes.slice(8)].join(' '));

1 2 3 4 5 6 7 8 8 7 6 5 4 3 2 1

Nachrichten-Header für ein Binärprotokoll bauen

// Aufbau: [Typ: 1 Byte][Zeitstempel ns: 8 Bytes][Nutzer-ID: 8 Bytes]
const encodeHeader = (type, userId) => {
  const view = new DataView(new ArrayBuffer(17));
  const timestampNs = BigInt(Date.now()) * 1_000_000n;

  view.setUint8(0, type);
  view.setBigUint64(1, timestampNs);          // Offset 1: nicht ausgerichtet, aber erlaubt
  view.setBigUint64(9, BigInt(userId));
  return view.buffer;
};

const header = encodeHeader(3, '9007199254740993'); // > Number.MAX_SAFE_INTEGER
const check = new DataView(header);
console.log(check.getBigUint64(9));

9007199254740993n

Umbruch bei negativen Werten und TypeError bei Number

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

view.setBigUint64(0, -1n);
console.log(view.getBigUint64(0)); // umgebrochen

try {
  view.setBigUint64(0, 42); // Number statt BigInt
} catch (err) {
  console.log(err.name);
}

18446744073709551615n TypeError

// Wichtig · Fallstricke

Nur BigInt: view.setBigUint64(0, 42) löst einen TypeError aus. Schreibe 42n oder BigInt(42). Strings wie '123' werden über ToBigInt angenommen, ungültige Strings lösen einen SyntaxError aus.
Kein Bereichsfehler beim Wert: Negative oder zu große Werte werden stillschweigend modulo 2⁶⁴ umgebrochen. Prüfe den Wertebereich bei Bedarf selbst oder nutze BigInt.asUintN(64, v), damit das Verhalten ausdrücklich im Code steht.
RangeError: Ein negativer byteOffset oder byteOffset + 8 > byteLength löst einen RangeError aus. Das gilt auch, wenn der Buffer vorher übertragen bzw. abgekoppelt wurde (hier ist es ein TypeError).
Bytereihenfolge: Standard ist Big-Endian. Die meisten Prozessoren (x86, ARM) und WebAssembly arbeiten dagegen mit Little-Endian. Vergisst man true, führt das zu schwer auffindbaren Fehlern.
Kompatibilität: Verfügbar seit ES2020 (Chrome 67, Firefox 68, Safari 15, Node.js 10.4). In älteren Umgebungen fehlt BigInt komplett, und ein Polyfill ist praktisch nicht möglich.

Siehe auch

DataView.prototype.getBigUint64() DataView.prototype.setBigInt64() DataView.prototype.setUint32() DataView BigUint64Array BigInt BigInt.asUintN() ArrayBuffer