Signatur
Beschreibung
BigInt64Array ist ein typisiertes Array (TypedArray), das ausschließlich 64-Bit vorzeichenbehaftete Ganzzahlen speichert. Jeder Eintrag belegt genau 8 Byte im Speicher. Im Gegensatz zu gewöhnlichen JavaScript-Zahlen (number) werden die Werte als BigInt gelesen und geschrieben, wodurch der gesamte 64-Bit-Bereich von −9.223.372.036.854.775.808 bis 9.223.372.036.854.775.807 präzise abgedeckt wird.
Typische Einsatzgebiete sind die Kommunikation mit nativen Bibliotheken über WebAssembly, die Verarbeitung von Binärprotokollen oder Dateiformaten, die 64-Bit-Integer verwenden, sowie hochperformante numerische Berechnungen, bei denen der 53-Bit-Bereich von Number nicht ausreicht. Die Byte-Reihenfolge (Endianness) richtet sich nach der jeweiligen Plattform; soll eine definierte Reihenfolge (z. B. für Netzwerkprotokolle) garantiert werden, bietet sich DataView an.
BigInt64Array teilt die gesamte TypedArray-API: Konstruktoren mit Länge, ArrayBuffer, anderem TypedArray oder Iterable, sowie Methoden wie map(), filter(), set(), subarray() und sort(). Zu beachten ist, dass alle Lese- und Schreiboperationen BigInt-Werte erwarten — das Übergeben gewöhnlicher number-Werte löst einen TypeError aus.
- Elementgröße: 8 Byte pro Element (
BigInt64Array.BYTES_PER_ELEMENT === 8). - Wertebereich: −263 bis 263−1.
- Alle Werte müssen
BigIntsein, keine implizite Konvertierung vonnumber.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $length | number | Anzahl der Elemente im Array. Erzeugt einen neuen, mit 0n initialisierten Puffer der Größe length × 8 Byte. |
|
| $typedArray | TypedArray | Ein anderes typisiertes Array, dessen Werte kopiert werden. Jeder Wert wird in BigInt konvertiert. |
|
| $object | object|Iterable | Ein Array-ähnliches oder iterierbares Objekt, dessen Einträge (als BigInt) in das neue Array übernommen werden. |
|
| $buffer | ArrayBuffer|SharedArrayBuffer | Ein bestehender Puffer, auf den das Array als Sicht (View) zeigt. | |
| $byteOffset | number | 0 | Byte-Offset innerhalb des buffer, ab dem die Sicht beginnt. Muss ein Vielfaches von 8 sein. |
| $length | number | Anzahl der Elemente der Sicht innerhalb des buffer (optionaler dritter Parameter bei Buffer-Konstruktion). |
Rückgabewert
BigInt64Array-Instanz, die auf einen ArrayBuffer zeigt und 64-Bit-Ganzzahlen als BigInt bereitstellt.Beispiele
Einfaches Erstellen und Befüllen
// Array mit 4 Elementen anlegen
const arr = new BigInt64Array(4);
arr[0] = 100n;
arr[1] = -9_223_372_036_854_775_808n; // Minimum
arr[2] = 9_223_372_036_854_775_807n; // Maximum
arr[3] = 42n;
console.log(arr[0]); // 100n
console.log(arr[1]); // -9223372036854775808n
console.log(arr[2]); // 9223372036854775807n
console.log(arr.length); // 4
console.log(BigInt64Array.BYTES_PER_ELEMENT); // 8Aus Iterable erzeugen und map/reduce verwenden
const source = [1n, 2n, 3n, 4n, 5n];
const arr = new BigInt64Array(source);
// Alle Werte verdoppeln
const doubled = arr.map(v => v * 2n);
console.log([...doubled]); // [2n, 4n, 6n, 8n, 10n]
// Summe bilden
const sum = arr.reduce((acc, v) => acc + v, 0n);
console.log(sum); // 15nGemeinsamer ArrayBuffer mit DataView (definierte Byte-Reihenfolge)
// Einen Puffer für 2 × 64-Bit-Werte anlegen
const buffer = new ArrayBuffer(16);
const view = new DataView(buffer);
// Big-Endian-Schreiben mit DataView
view.setBigInt64(0, 1000n, false); // big-endian
view.setBigInt64(8, -1n, false);
// Plattformabhängig lesen via BigInt64Array
const typed = new BigInt64Array(buffer);
console.log(typed[0]); // 1000n (auf Little-Endian-Plattform evtl. anderem Wert)
console.log(typed[1]); // -1n// Wichtig · Fallstricke
Nur BigInt-Werte: Das Zuweisen eines gewöhnlichen number (z. B. arr[0] = 5) wirft einen TypeError. Immer das n-Suffix verwenden oder explizit mit BigInt() konvertieren.
Endianness: Die Byte-Reihenfolge folgt der CPU-Architektur der Plattform (fast immer Little-Endian in modernen Desktops/Browsern). Für netzwerktaugliche oder plattformunabhängige Serialisierung sollte stattdessen DataView.setBigInt64()/getBigInt64() mit explizitem Endianness-Flag genutzt werden.
Browser-Kompatibilität: BigInt64Array ist seit Chrome 67, Firefox 68, Safari 14 und Node.js 10.3 verfügbar. Internet Explorer wird nicht unterstützt.
Kein implizites Wrapping: Bei Überschreitung des Bereichs wird nicht geworfen — stattdessen wird bitweise abgeschnitten (Modulo 264), analog zu anderen typisierten Arrays.