new BigInt64Array() — Methode · JavaScript-Referenz

Signatur

new BigInt64Array(length | typedArray | object | buffer, byteOffset, length)

Beschreibung

Der Konstruktor BigInt64Array() erzeugt ein typisiertes Array, dessen Elemente vorzeichenbehaftete 64-Bit-Ganzzahlen im Zweierkomplement sind (Wertebereich -2n ** 63n bis 2n ** 63n - 1n). Die Elemente werden als BigInt gelesen und geschrieben, nicht als Number. Die Bytereihenfolge entspricht der Plattform, meist Little-Endian.

Es gibt vier Aufrufvarianten:

new BigInt64Array(length) – legt einen neuen Puffer mit length Elementen an, alle mit 0n belegt.
new BigInt64Array(typedArray) – kopiert die Werte eines anderen BigInt-typisierten Arrays (BigInt64Array oder BigUint64Array).
new BigInt64Array(object) – übernimmt Werte aus einem iterierbaren oder array-ähnlichen Objekt. Jeder Wert wird mit BigInt-Semantik umgewandelt.
new BigInt64Array(buffer, byteOffset, length) – legt eine Sicht auf einen vorhandenen ArrayBuffer oder SharedArrayBuffer an, ohne die Daten zu kopieren.

Typische Einsatzfälle sind binäre Protokolle und Dateiformate mit 64-Bit-Feldern, etwa Zeitstempel in Nanosekunden, IDs oder Datenbank-Schlüssel. Weitere Anwendungen sind der Datenaustausch mit WebAssembly (i64) und atomare Operationen über Atomics auf einem SharedArrayBuffer.

Parameter

Name	Typ	Default	Beschreibung
$length	number	0	Anzahl der Elemente, wenn kein Objekt übergeben wird. Es werden `length * 8` Bytes reserviert, alle mit `0n` belegt.
$typedArray	BigInt64Array \| BigUint64Array		Ein anderes BigInt-typisiertes Array, dessen Werte in einen neuen Puffer kopiert werden. Werte aus einem `BigUint64Array` werden dabei als vorzeichenbehaftet neu gedeutet.
$object	Iterable<bigint> \| ArrayLike<bigint>		Iterierbares oder array-ähnliches Objekt, z. B. `[1n, 2n]`. Die Werte werden wie bei `BigInt()` umgewandelt, Strings wie `"42"` sind also erlaubt. `Number`-Werte lösen einen `TypeError` aus.
$buffer	ArrayBuffer \| SharedArrayBuffer		Vorhandener Puffer, auf den die neue Sicht zeigt. Es werden keine Daten kopiert.
$byteOffset	number	0	Startposition der Sicht in Bytes. Muss ein Vielfaches von `8` sein, sonst gibt es einen `RangeError`.
$length	number	(buffer.byteLength - byteOffset) / 8	Anzahl der Elemente in der Sicht. Ohne Angabe reicht die Sicht bis zum Pufferende. Der verbleibende Bereich muss dann ein Vielfaches von 8 Bytes sein.

Rückgabewert

Typ

BigInt64Array

Beschreibung

Ein neues BigInt64Array. Je nach Aufrufvariante hat es einen eigenen Puffer oder ist eine Sicht auf den übergebenen Puffer.

Beispiele

Leeres Array einer festen Länge anlegen

const ids = new BigInt64Array(3);
ids[0] = 9007199254740993n; // größer als Number.MAX_SAFE_INTEGER
ids[1] = -42n;
console.log(ids);
console.log(ids.byteLength);

BigInt64Array(3) [9007199254740993n, -42n, 0n] 24

Aus Iterable erzeugen und Überlauf beobachten

const werte = new BigInt64Array([1n, "123", 2n ** 63n]);
console.log(werte);

try {
  new BigInt64Array([1, 2]); // Number statt BigInt
} catch (err) {
  console.log(err.constructor.name);
}

BigInt64Array(3) [1n, 123n, -9223372036854775808n] TypeError

Sicht auf einen Binärpuffer (z. B. Nanosekunden-Zeitstempel)

const buffer = new ArrayBuffer(32);
// Die ersten 8 Bytes sind ein Header, danach folgen 3 Zeitstempel
const stamps = new BigInt64Array(buffer, 8, 3);
stamps[0] = process.hrtime.bigint?.() ?? 1700000000000000000n;

const bytes = new Uint8Array(buffer);
console.log(stamps.length, stamps.byteOffset);
console.log(bytes.slice(8, 16).some(b => b !== 0));

3 8 true

Atomarer Zähler über SharedArrayBuffer

const shared = new SharedArrayBuffer(8);
const counter = new BigInt64Array(shared);

Atomics.add(counter, 0, 5n);
Atomics.sub(counter, 0, 2n);
console.log(Atomics.load(counter, 0));

3n

// Wichtig · Fallstricke

Nur mit new: Ein Aufruf als normale Funktion, also BigInt64Array(2), wirft einen TypeError.
Keine Mischung mit Number: Zuweisungen wie arr[0] = 1 werfen einen TypeError. Verwende 1n oder BigInt(1). Auch ein Float64Array oder Int32Array lässt sich nicht direkt übergeben. Wandle die Werte vorher um, z. B. mit BigInt64Array.from(arr, BigInt).
Stiller Überlauf: Werte außerhalb von ±2⁶³ werden ohne Fehler modulo 2⁶⁴ abgeschnitten, so wie bei BigInt.asIntN(64, x).
Ausrichtung: byteOffset muss durch 8 teilbar sein. Andernfalls gibt es einen RangeError. Für nicht ausgerichtete Daten oder eine feste Bytereihenfolge nimm DataView.prototype.getBigInt64(offset, littleEndian).
Geteilter Speicher: Mit der Puffer-Variante entsteht keine Kopie. Änderungen sind in allen Sichten auf denselben ArrayBuffer sichtbar.
JSON: JSON.stringify kann BigInt nicht serialisieren. Wandle die Werte vorher um, z. B. mit Array.from(arr, String).
Kompatibilität: ES2020. Unterstützt in allen modernen Browsern (Chrome 67+, Firefox 68+, Safari 15+) und in Node.js ab 10.4. SharedArrayBuffer ist im Browser nur bei Cross-Origin-Isolation verfügbar (COOP/COEP-Header).

Siehe auch

BigInt64Array BigUint64Array BigInt TypedArray ArrayBuffer DataView.prototype.getBigInt64() Atomics