BigInt.asIntN() — Methode · JavaScript-Referenz

Signatur

BigInt.asIntN(bits, bigint)

Beschreibung

Die statische Methode BigInt.asIntN() reduziert einen BigInt-Wert auf seine bits niederwertigsten Bits. Das Ergebnis wird als vorzeichenbehaftete Ganzzahl im Zweierkomplement gelesen. Ist das höchste der behaltenen Bits gesetzt, ist das Ergebnis also negativ. Mathematisch entspricht das bigint mod 2^bits, anschließend auf den Bereich -2^bits-1 bis 2^bits-1 - 1 verschoben.

Die Methode ist nützlich, wenn man in JavaScript das Überlaufverhalten fester Integer-Typen nachbilden muss, etwa int8, int32 oder int64 aus C, Rust, Java oder WebAssembly. Typische Einsatzfälle sind Hash-Funktionen, Prüfsummen, Emulatoren, binäre Protokolle und das Übergeben von 64-Bit-Werten an WebAssembly (i64).

Wenn der Wert schon im Zielbereich liegt, kommt er unverändert zurück. Für die Interpretation ohne Vorzeichen gibt es das Gegenstück BigInt.asUintN().

Parameter

Name	Typ	Default	Beschreibung
$bits Pflicht	number		Anzahl der Bits, die erhalten bleiben. Der Wert wird mit `ToIndex` in eine ganze Zahl von `0` bis `2⁵³ - 1` umgewandelt. Liegt er außerhalb dieses Bereichs, wird ein `RangeError` geworfen.
$bigint Pflicht	bigint		Der `BigInt`-Wert, der gekürzt wird. Andere Werte werden mit `ToBigInt` umgewandelt. Ein `number` führt dabei zu einem `TypeError`.

Rückgabewert

Typ

bigint

Beschreibung

Der Wert von bigint modulo 2^bits, gelesen als vorzeichenbehaftete Ganzzahl mit bits Bit im Zweierkomplement.

Beispiele

Grundverhalten: Überlauf in den negativen Bereich

// 8 Bit mit Vorzeichen: Bereich -128 bis 127
console.log(BigInt.asIntN(8, 127n));  // passt, bleibt unverändert
console.log(BigInt.asIntN(8, 128n));  // höchstes Bit gesetzt → negativ
console.log(BigInt.asIntN(8, 255n));
console.log(BigInt.asIntN(8, 256n));  // nur die unteren 8 Bits zählen
console.log(BigInt.asIntN(8, -129n)); // Unterlauf

127n -128n -1n 0n 127n

int64-Überlauf wie in C/Rust/Java nachbilden

const INT64_MAX = 2n ** 63n - 1n;

// Addition mit 64-Bit-Überlauf (wrapping add)
const addInt64 = (a, b) => BigInt.asIntN(64, a + b);

console.log(addInt64(INT64_MAX, 1n));
console.log(addInt64(-5n, 3n));

// Prüfen, ob ein Wert in int64 passt
const fitsInt64 = (x) => BigInt.asIntN(64, x) === x;
console.log(fitsInt64(2n ** 63n));
console.log(fitsInt64(-(2n ** 63n)));

-9223372036854775808n -2n false true

64-Bit-Hash (FNV-1a) mit vorzeichenbehaftetem Ergebnis

const fnv1a64 = (text) => {
  let hash = 0xcbf29ce484222325n;
  const prime = 0x100000001b3n;
  for (const byte of new TextEncoder().encode(text)) {
    hash ^= BigInt(byte);
    hash = BigInt.asUintN(64, hash * prime);
  }
  // Als signed int64 ausgeben, z. B. für eine Java-Long-Spalte in der Datenbank
  return BigInt.asIntN(64, hash);
};

console.log(fnv1a64("hallo"));
console.log(typeof fnv1a64("hallo"));

(ein 64-Bit-Wert mit Vorzeichen, z. B. negativ) bigint

Zusammenspiel mit BigInt64Array

const arr = new BigInt64Array(1);
arr[0] = 2n ** 63n; // wird intern genauso gekürzt

console.log(arr[0]);
console.log(arr[0] === BigInt.asIntN(64, 2n ** 63n));

-9223372036854775808n true

// Wichtig · Fallstricke

Kein number als zweites Argument: BigInt.asIntN(8, 255) wirft einen TypeError. Schreibe 255n oder BigInt(255).
Grenzen von bits: Negative Werte oder Werte über 2⁵³ - 1 lösen einen RangeError aus. Nachkommastellen werden abgeschnitten, NaN wird zu 0.
bits = 0 liefert immer 0n. Bei bits = 1 sind nur 0n und -1n möglich.
Signed oder unsigned: Für Werte ohne Vorzeichen, etwa uint64 oder Bitmasken, ist BigInt.asUintN() die richtige Wahl. Beim Verwechseln entstehen unerwartete negative Werte.
Performance: Moderne Engines (V8) optimieren asIntN(64, …) und asUintN(64, …) besonders. Damit lässt sich schnelle 64-Bit-Arithmetik schreiben. Für 32 Bit reicht bei number meist x | 0, das ist deutlich schneller.
Kompatibilität: Seit ES2020 in allen modernen Browsern und ab Node.js 10.4 verfügbar. Im Internet Explorer gibt es sie nicht, und BigInt lässt sich nicht vollständig nachrüsten (Polyfill).

Siehe auch

BigInt BigInt.asUintN() BigInt64Array BigUint64Array DataView.prototype.getBigInt64() new Uint8Array()