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

Signatur

DataView.prototype.getBigUint64(byteOffset, littleEndian)

Beschreibung

Die Methode getBigUint64() liest acht aufeinanderfolgende Byte aus dem zugrunde liegenden ArrayBuffer (oder SharedArrayBuffer). Sie beginnt am angegebenen byteOffset relativ zum Anfang des DataView und deutet die Byte als vorzeichenlose 64-Bit-Ganzzahl. Das Ergebnis liegt im Bereich von 0n bis 2n ** 64n - 1n (18.446.744.073.709.551.615) und wird deshalb als BigInt zurückgegeben, nicht als Number.

Gebraucht wird die Methode vor allem beim Verarbeiten von Binärformaten und Protokollen, die 64-Bit-Werte enthalten. Beispiele sind Zeitstempel in Nanosekunden, Dateigrößen und Offsets in Containerformaten (ZIP64, MP4, SQLite), Hash-Werte, IDs oder Zähler in Netzwerkprotokollen. Mit einem Number ginge hier Genauigkeit verloren, denn exakt darstellbar sind nur Ganzzahlen bis Number.MAX_SAFE_INTEGER (2⁵³ − 1).

Anders als bei typisierten Arrays wie BigUint64Array muss der Offset nicht ausgerichtet sein, er kann also ein beliebiger Byte-Offset sein. Die Byte-Reihenfolge legst du selbst fest: Standard ist Big-Endian. Für Little-Endian übergibst du true als zweites Argument. Das ist wichtig, weil die meisten modernen Prozessoren (x86, ARM) und viele Dateiformate Little-Endian verwenden.

Parameter

Name	Typ	Default	Beschreibung
$byteOffset Pflicht	number		Offset in Byte vom Anfang des `DataView`, ab dem gelesen wird. Wird in eine Ganzzahl umgewandelt. Es müssen mindestens 8 Byte ab dieser Position verfügbar sein.
$littleEndian	boolean	false	Bei `true` werden die Daten als Little-Endian gelesen, bei `false` oder `undefined` als Big-Endian.

Rückgabewert

Typ

bigint

Beschreibung

Ein BigInt im Bereich von 0n bis einschließlich 18446744073709551615n.

Beispiele

Grundlagen: Wert schreiben und lesen

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

// Größter möglicher uint64-Wert
view.setBigUint64(0, 2n ** 64n - 1n);
console.log(view.getBigUint64(0));

// Dieselben Byte als vorzeichenbehafteter Wert gelesen
console.log(view.getBigInt64(0));

18446744073709551615n -1n

Byte-Reihenfolge: Big-Endian vs. Little-Endian

const bytes = new Uint8Array([0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x00]);
const view = new DataView(bytes.buffer);

console.log(view.getBigUint64(0));        // Big-Endian (Standard)
console.log(view.getBigUint64(0, true));  // Little-Endian

256n 72057594037927936n

Praxis: Nanosekunden-Zeitstempel aus einem Binär-Header lesen

// Header: 4 Byte Magic, danach 8 Byte Zeitstempel (ns, Little-Endian)
const header = new ArrayBuffer(12);
const writer = new DataView(header);
writer.setUint32(0, 0x4c4f4721);                     // "LOG!"
writer.setBigUint64(4, 1700000000123456789n, true); // nicht ausgerichteter Offset 4

const parseHeader = (buf) => {
  const view = new DataView(buf);
  const ns = view.getBigUint64(4, true);
  const ms = Number(ns / 1_000_000n); // passt sicher in Number
  return { ns, date: new Date(ms).toISOString() };
};

console.log(parseHeader(header));

{ ns: 1700000000123456789n, date: '2023-11-14T22:13:20.123Z' }

Fehlerbehandlung bei zu kurzem Puffer

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

try {
  view.getBigUint64(4); // bräuchte Byte 4–11, es gibt nur 0–9
} catch (err) {
  console.log(err instanceof RangeError, err.name);
}

true RangeError

// Wichtig · Fallstricke

Rückgabe ist BigInt: BigInt und Number lassen sich nicht direkt verrechnen (view.getBigUint64(0) + 1 wirft einen TypeError). Wandle bei Bedarf mit Number(wert) um. Werte über Number.MAX_SAFE_INTEGER verlieren dabei Genauigkeit.
JSON: JSON.stringify() kann BigInt nicht serialisieren und wirft einen TypeError. Wandle den Wert vorher z. B. mit wert.toString() um.
RangeError: wenn byteOffset negativ ist oder byteOffset + 8 über die byteLength des Views hinausgeht.
Endianness: Standard ist Big-Endian. Wer das zweite Argument vergisst, liest Little-Endian-Daten (z. B. aus Windows-, ZIP- oder WebAssembly-Speicher) falsch.
Vorzeichen: Für vorzeichenbehaftete 64-Bit-Werte ist getBigInt64() die richtige Methode. Dieselben Byte ergeben je nach Methode unterschiedliche Werte.
Kompatibilität: Seit ES2020 in allen modernen Browsern verfügbar (Chrome 67, Firefox 68, Safari 15) sowie in Node.js ab 10.4. Im Internet Explorer gibt es die Methode nicht, und ein Polyfill ist ohne native BigInt-Unterstützung nicht möglich.

Siehe auch

DataView DataView.prototype.setBigUint64() DataView.prototype.getBigInt64() DataView.prototype.getUint32() BigUint64Array BigInt ArrayBuffer