Signatur
Beschreibung
BigUint64Array ist ein typisiertes Array (Typed Array), das 64-Bit-Ganzzahlen ohne Vorzeichen als BigInt-Werte speichert. Jedes Element belegt genau 8 Byte im zugrundeliegenden ArrayBuffer. Die Byte-Reihenfolge entspricht der Plattform-Endianness (in der Praxis bei allen gängigen Architekturen Little-Endian). Es wurde mit ECMAScript 2020 zusammen mit BigInt eingeführt.
Das Array eignet sich besonders dann, wenn sehr große positive Ganzzahlen (z. B. kryptografische Hashes, Dateigrößen, Zeitstempel in Nanosekunden oder 64-Bit-Zähler aus WebAssembly) präzise ohne Gleitkomma-Rundungsfehler verarbeitet werden müssen. Klassische Uint32Array- oder Number-basierte Ansätze verlieren bei Werten über 2⁵³ an Präzision — BigUint64Array löst dieses Problem.
Die API ist identisch mit anderen Typed-Array-Klassen wie Uint8Array oder Float64Array: Es stehen Methoden wie set(), subarray(), fill(), map() und slice() zur Verfügung. Alle Lese- und Schreiboperationen auf Elementen liefern bzw. erwarten BigInt-Werte — das Mischen mit normalen number-Werten führt zu einem TypeError.
- Zugriff:
arr[0]liefert einenBigInt. - Zuweisung:
arr[0] = 42n— dasn-Suffix ist Pflicht. - Werte außerhalb des Bereichs werden still gekürzt (Modulo 2⁶⁴).
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $length | number | Anzahl der Elemente (jedes 8 Byte groß). Erstellt ein neues, mit 0n gefülltes Array. |
|
| $typedArray | BigUint64Array|BigInt64Array | Ein anderes Big-Integer-Typed-Array, dessen Werte kopiert werden. | |
| $object | Iterable|ArrayLike | Ein iterierbares Objekt oder Array-ähnliches Objekt mit BigInt-Werten, z. B. ein normales Array wie [1n, 2n, 3n]. |
|
| $buffer | ArrayBuffer|SharedArrayBuffer | Ein vorhandener Puffer, auf dem das Array aufgebaut wird. Kann mit byteOffset und length kombiniert werden. |
|
| $byteOffset | number | 0 | Byte-Offset innerhalb des buffer, ab dem das Array beginnt. Muss ein Vielfaches von 8 sein. |
Rückgabewert
BigUint64Array-Instanz, die einen ArrayBuffer mit 64-Bit-Integer-Werten ohne Vorzeichen kapselt.Beispiele
Grundlegende Erstellung und Zugriff
// Neues Array mit 4 Elementen
const arr = new BigUint64Array(4);
arr[0] = 0n;
arr[1] = 9999999999999999999n;
arr[2] = 2n ** 64n - 1n; // Maximalwert: 18446744073709551615n
arr[3] = 42n;
console.log(arr[0]); // 0n
console.log(arr[1]); // 9999999999999999999n
console.log(arr[2]); // 18446744073709551615n
console.log(arr.length); // 4
console.log(arr.byteLength); // 32Initialisierung aus einem Array und Iteration
const values = [100n, 200n, 300n, 400n, 500n];
const arr = new BigUint64Array(values);
// Summieren mit reduce
const sum = arr.reduce((acc, val) => acc + val, 0n);
console.log(sum); // 1500n
// Mit for...of iterieren
for (const val of arr) {
console.log(val.toString());
}Gemeinsamer ArrayBuffer mit DataView
const buffer = new ArrayBuffer(16);
const view = new DataView(buffer);
const uint64 = new BigUint64Array(buffer);
// Wert über DataView schreiben (Little-Endian)
view.setBigUint64(0, 0xDEADBEEFCAFEBABEn, true);
console.log(uint64[0].toString(16)); // 'deadbeefcafebabe'
console.log(uint64[1]); // 0n (zweites Element noch leer)Überlauf durch Modulo-Kürzung
const arr = new BigUint64Array(1);
arr[0] = 2n ** 64n; // Überlauf: entspricht 0n
console.log(arr[0]); // 0n
arr[0] = 2n ** 64n + 1n; // entspricht 1n
console.log(arr[0]); // 1n// Wichtig · Fallstricke
Nur BigInt-Werte: Jede Zuweisung eines normalen number-Werts (z. B. arr[0] = 42) wirft einen TypeError. Das n-Suffix ist bei Literalen obligatorisch.
Browser-Kompatibilität: BigUint64Array ist seit Chrome 67, Firefox 68, Safari 14 und Node.js 10.4 verfügbar. Internet Explorer unterstützt es nicht. In sehr alten Umgebungen gibt es kein sinnvolles Polyfill, da BigInt selbst nicht polyfillfähig ist.
Kein Mischen mit anderen Typed Arrays: Eine Zuweisung von einem Uint32Array an ein BigUint64Array über set() schlägt fehl, da die Typen inkompatibel sind. Nur BigInt64Array und BigUint64Array können untereinander Werte austauschen.
Performance: Arithmetische Operationen mit BigInt sind generell langsamer als mit number. Für hochfrequente Berechnungen sollte man abwägen, ob ein Split in zwei Uint32Array (Hi/Lo) schneller wäre.