new BigUint64Array() — Methode · JavaScript-Referenz

Signatur

new BigUint64Array(lengthOrSourceOrBuffer, byteOffset, length)

Beschreibung

Der Konstruktor BigUint64Array() legt ein typisiertes Array an, dessen Elemente vorzeichenlose 64-Bit-Ganzzahlen im Wertebereich 0n bis 2n ** 64n - 1n sind. Die Werte werden in der Byte-Reihenfolge der Plattform gespeichert, meist Little-Endian. Brauchen Sie eine bestimmte Byte-Reihenfolge, verwenden Sie stattdessen DataView.prototype.getBigUint64() bzw. setBigUint64().

Den Konstruktor kann man auf mehrere Arten aufrufen:

new BigUint64Array() bzw. new BigUint64Array(length): erzeugt ein neues Array der angegebenen Länge, gefüllt mit 0n.
new BigUint64Array(typedArray): kopiert die Werte eines anderen typisierten Arrays. Das Quell-Array muss selbst BigInt-Werte enthalten (BigInt64Array oder BigUint64Array).
new BigUint64Array(object): übernimmt die Werte aus einem iterierbaren oder Array-ähnlichen Objekt. Jeder Wert wird mit ToBigInt umgewandelt.
new BigUint64Array(buffer, byteOffset, length): erzeugt eine Sicht auf einen vorhandenen ArrayBuffer oder SharedArrayBuffer, ohne Daten zu kopieren.

Typische Einsatzgebiete sind 64-Bit-IDs und Zeitstempel in Nanosekunden, Hashes (z. B. FNV-1a/64), Bitmasken sowie binäre Protokolle und WebAssembly-Speicher, in denen u64-Werte vorkommen. Ein gewöhnliches Number kann solche Werte ab 2 ** 53 nicht mehr exakt darstellen.

Parameter

Name	Typ	Default	Beschreibung
$length	number	0	Anzahl der Elemente. Das Array belegt `length * 8` Byte, alle Elemente werden mit `0n` initialisiert.
$typedArray	BigInt64Array \| BigUint64Array		Ein typisiertes Array mit BigInt-Werten, dessen Werte in ein neues Array kopiert werden. Negative Werte werden modulo 2⁶⁴ umgerechnet.
$object	Iterable<bigint> \| ArrayLike<bigint>		Ein iterierbares oder Array-ähnliches Objekt. Jedes Element muss sich in `bigint` umwandeln lassen (z. B. `bigint`, `boolean`, numerischer String), sonst wird ein Fehler geworfen.
$buffer	ArrayBuffer \| SharedArrayBuffer		Ein vorhandener Puffer, auf den das Array als Sicht zugreift. Es werden keine Daten kopiert.
$byteOffset	number	0	Start-Offset in Byte innerhalb von `buffer`. Muss ein Vielfaches von `8` sein.
$length	number	(buffer.byteLength - byteOffset) / 8	Anzahl der Elemente der Sicht, wenn ein `buffer` übergeben wird.

Rückgabewert

Typ

BigUint64Array

Beschreibung

Eine neue BigUint64Array-Instanz, entweder mit eigenem Speicher oder als Sicht auf den übergebenen Puffer.

Beispiele

Array fester Länge anlegen und befüllen

const ids = new BigUint64Array(3);
ids[0] = 18446744073709551615n; // größter u64-Wert
ids[1] = 42n;
ids[2] = -1n; // wird modulo 2^64 umgerechnet

console.log(ids);
console.log(ids.byteLength);

BigUint64Array(3) [18446744073709551615n, 42n, 18446744073709551615n] 24

Aus einem Iterable erzeugen

const timestampsNs = new BigUint64Array([
  1_700_000_000_000_000_000n,
  1_700_000_000_500_000_000n
]);

const deltaNs = timestampsNs[1] - timestampsNs[0];
console.log(`${deltaNs / 1_000_000n} ms`);

500 ms

Sicht auf einen ArrayBuffer (z. B. Binärprotokoll)

const buffer = new ArrayBuffer(24);
const header = new Uint8Array(buffer, 0, 8);
header.set([0xCA, 0xFE]);

// Nutzdaten ab Byte 8: zwei u64-Werte
const payload = new BigUint64Array(buffer, 8, 2);
payload[0] = 123456789012345678n;
payload[1] = 2n ** 63n;

console.log(payload.length, payload.byteOffset);
console.log(new BigUint64Array(buffer)[1] === payload[0]);

2 8 true

64-Bit-Hash (FNV-1a) mit Überlauf-Arithmetik

const fnv1a64 = (text) => {
  const h = new BigUint64Array([0xcbf29ce484222325n]);
  for (const byte of new TextEncoder().encode(text)) {
    h[0] ^= BigInt(byte);
    h[0] *= 0x100000001b3n; // Speichern kürzt automatisch auf 64 Bit
  }
  return h[0].toString(16);
};

console.log(fnv1a64('hallo'));

(16-stelliger Hexadezimal-Hash von "hallo")

// Wichtig · Fallstricke

Nur mit new aufrufbar: BigUint64Array(3) ohne new wirft einen TypeError.
Keine Number-Werte: new BigUint64Array([1, 2]) oder arr[0] = 5 wirft einen TypeError („Cannot convert 1 to a BigInt“). Verwenden Sie Literale wie 1n oder BigInt(1). Aus demselben Grund lässt sich z. B. ein Uint32Array nicht direkt übergeben. Wandeln Sie es vorher um: new BigUint64Array(Array.from(u32, BigInt)).
Stiller Überlauf: Werte außerhalb von 0 bis 2⁶⁴−1 werden ohne Fehlermeldung modulo 2⁶⁴ umgerechnet (-1n wird zu 18446744073709551615n).
Ausrichtung: byteOffset muss ein Vielfaches von 8 sein, und die Restlänge des Puffers muss ohne Rest durch 8 teilbar sein. Andernfalls wird ein RangeError geworfen.
Byte-Reihenfolge: Es gilt immer die Reihenfolge der Plattform. Für Netzwerk- oder Dateiformate mit fester Byte-Reihenfolge verwenden Sie DataView.
JSON: JSON.stringify kann BigInt-Werte nicht umwandeln und wirft einen TypeError. Wandeln Sie die Werte vorher in Strings um.
Kompatibilität: Baseline seit 2021 (Chrome 67, Firefox 68, Safari 15, Node.js 10.4). Ältere Browser unterstützen es nicht, und eine vollwertige Polyfill gibt es nicht.

Siehe auch

BigUint64Array BigInt64Array BigInt TypedArray ArrayBuffer Uint32Array