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

Signatur

DataView.prototype.getBigInt64(byteOffset, littleEndian)

Beschreibung

Die Methode getBigInt64() liest 8 aufeinanderfolgende Bytes ab einer beliebigen Byte-Position eines DataView und interpretiert sie als vorzeichenbehafteten 64-Bit-Integer im Zweierkomplement. Das Ergebnis ist ein BigInt, denn der normale Typ Number kann Ganzzahlen nur bis 2⁵³ − 1 exakt darstellen. Der Wertebereich reicht von -9223372036854775808n bis 9223372036854775807n.

Gebraucht wird die Methode vor allem beim Auslesen von Binärformaten und Netzwerkprotokollen mit 64-Bit-Feldern, zum Beispiel für Zeitstempel in Nano- oder Mikrosekunden, Datei-Offsets, IDs aus Datenbanken, Datensätze aus WebAssembly-Speicher oder Nachrichten, die mit Protobuf oder MessagePack kodiert sind.

Anders als bei BigInt64Array muss der Offset nicht an 8 Bytes ausgerichtet sein. Die Bytereihenfolge (Endianness) legst du bei jedem Aufruf ausdrücklich fest. Ohne Angabe gilt Big-Endian – das ist ein häufiger Grund für falsche Werte, weil x86- und ARM-Systeme sowie viele Dateiformate Little-Endian verwenden.

Parameter

Name	Typ	Default	Beschreibung
$byteOffset Pflicht	number		Position in Bytes, gezählt vom Anfang der Ansicht (nicht des zugrunde liegenden Puffers), ab der gelesen wird. Der Wert wird in eine Ganzzahl umgewandelt.
$littleEndian	boolean	false	Bei `true` wird der Wert als Little-Endian gelesen, bei `false` oder ohne Angabe als Big-Endian.

Rückgabewert

Typ

bigint

Beschreibung

Ein BigInt im Bereich von -2⁶³ bis 2⁶³ − 1.

Beispiele

Grundlegendes Lesen mit beiden Bytereihenfolgen

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

// Wert als Little-Endian schreiben
view.setBigInt64(0, -123456789012345678n, true);

console.log(view.getBigInt64(0, true));  // korrekt
console.log(view.getBigInt64(0));        // falsche Bytereihenfolge

-123456789012345678n -5655004895749591043n

64-Bit-Zeitstempel aus einem Binär-Header lesen

// Header: 4 Bytes Magic, 8 Bytes Zeitstempel (µs, Little-Endian)
const header = new Uint8Array([
  0x42, 0x49, 0x4e, 0x31,
  0x00, 0x40, 0x8a, 0x6d, 0x3f, 0x10, 0x06, 0x00
]);

const view = new DataView(header.buffer);
const micros = view.getBigInt64(4, true); // Offset 4 muss nicht ausgerichtet sein

// Für Date in Millisekunden als Number umwandeln
const date = new Date(Number(micros / 1000n));
console.log(micros, date.toISOString());

1718000000000000n 2024-06-10T06:13:20.000Z

Mehrere Datensätze aus einer fetch-Antwort auslesen

const readIds = async (url) => {
  const response = await fetch(url);
  const buffer = await response.arrayBuffer();
  const view = new DataView(buffer);
  const ids = [];
  for (let offset = 0; offset + 8 <= view.byteLength; offset += 8) {
    ids.push(view.getBigInt64(offset, true));
  }
  return ids;
};

// Aufruf: readIds('/api/ids.bin').then(ids => console.log(ids.map(String)));

RangeError bei zu großem Offset

const view = new DataView(new ArrayBuffer(10));
try {
  view.getBigInt64(4); // bräuchte die Bytes 4–11, es gibt aber nur 0–9
} catch (err) {
  console.log(err.name);
}

RangeError

// Wichtig · Fallstricke

Standardmäßig Big-Endian: Ohne littleEndian = true wird Big-Endian gelesen. Die meisten Plattformen und viele Formate (etwa WebAssembly-Speicher) arbeiten mit Little-Endian.
RangeError: Wird geworfen, wenn byteOffset negativ ist oder byteOffset + 8 über byteLength der Ansicht hinausgeht.
Keine Vermischung mit Number: Das Ergebnis ist ein BigInt. Ausdrücke wie value + 1 werfen einen TypeError, richtig ist value + 1n. Beim Umwandeln mit Number(value) geht oberhalb von 2⁵³ Genauigkeit verloren.
JSON: JSON.stringify kann BigInt nicht serialisieren und wirft einen TypeError. Wandle den Wert vorher mit String(value) um.
Vorzeichenlose Werte: Für Werte ohne Vorzeichen nimmst du getBigUint64(). Andernfalls erscheinen Werte ab 2⁶³ als negative Zahlen.
Kompatibilität: Verfügbar in Chrome 67+, Firefox 68+, Safari 15+ und Node.js 10.4+. Im Internet Explorer gibt es die Methode nicht, und ein Polyfill ist nicht möglich, weil dort BigInt fehlt.

Siehe auch

DataView.prototype.setBigInt64() DataView.prototype.getBigUint64() DataView.prototype.getInt32() DataView BigInt64Array BigInt ArrayBuffer