BigInt.asUintN() — Methode · JavaScript-Referenz

Signatur

BigInt.asUintN(bits, bigint)

Beschreibung

BigInt.asUintN() ist eine statische Methode des BigInt-Objekts. Sie berechnet bigint modulo 2^bits und liefert immer einen nicht-negativen Wert im Bereich 0n bis 2n ** BigInt(bits) - 1n. Bits oberhalb der angegebenen Breite werden verworfen. Das entspricht genau dem Verhalten eines vorzeichenlosen Ganzzahltyps fester Breite, etwa uint8_t oder uint64_t in C.

Da BigInt-Werte in JavaScript beliebig groß werden können, gibt es keinen automatischen Überlauf. Mit asUintN() lässt sich dieses Verhalten gezielt nachbilden. Typische Einsatzfälle sind 64-Bit-Hashfunktionen (z. B. FNV-1a), Pseudozufallsgeneratoren, Prüfsummen, Binärprotokolle sowie die Arbeit mit BigUint64Array und DataView.prototype.setBigUint64().

Negative Eingaben werden in ihre Zweierkomplement-Darstellung der gewünschten Breite umgewandelt: BigInt.asUintN(8, -1n) ergibt 255n. Das Gegenstück ist BigInt.asIntN(). Es interpretiert dieselben Bits als vorzeichenbehaftete Zahl.

Parameter

Name	Typ	Default	Beschreibung
$bits Pflicht	number		Anzahl der Bits, die erhalten bleiben sollen. Der Wert wird per `ToIndex` in eine ganze Zahl zwischen `0` und `2⁵³−1` umgewandelt. `0` liefert immer `0n`.
$bigint Pflicht	bigint		Der zu kürzende Wert. Er wird per `ToBigInt` umgewandelt. Erlaubt sind z. B. `BigInt`-Werte, Booleans und numerische Strings, aber keine `number`-Werte.

Rückgabewert

Typ

bigint

Beschreibung

Der Wert bigint modulo 2^bits als nicht-negativer BigInt.

Beispiele

Grundverhalten: Überlauf und negative Werte

console.log(BigInt.asUintN(8, 257n));  // 257 = 0b1_0000_0001 → nur die unteren 8 Bits
console.log(BigInt.asUintN(8, 255n));
console.log(BigInt.asUintN(8, -1n));   // Zweierkomplement
console.log(BigInt.asUintN(64, -1n));  // größter uint64-Wert
console.log(BigInt.asUintN(0, 12345n));

1n 255n 255n 18446744073709551615n 0n

Zweierkomplement-Darstellung als Hex-String

const toHex32 = (value) =>
  BigInt.asUintN(32, BigInt(value)).toString(16).padStart(8, '0');

console.log(toHex32(-42));
console.log(toHex32(255));

ffffffd6 000000ff

64-Bit-Hash FNV-1a mit Überlauf-Simulation

const FNV_OFFSET = 0xcbf29ce484222325n;
const FNV_PRIME = 0x100000001b3n;

const fnv1a64 = (text) => {
  let hash = FNV_OFFSET;
  for (const byte of new TextEncoder().encode(text)) {
    hash ^= BigInt(byte);
    // Multiplikation auf 64 Bit begrenzen wie bei uint64_t
    hash = BigInt.asUintN(64, hash * FNV_PRIME);
  }
  return hash;
};

console.log(fnv1a64('hello').toString(16));

a430d84680aabd0b

Vergleich mit BigInt.asIntN()

const raw = 200n;
console.log(BigInt.asUintN(8, raw)); // als uint8 gelesen
console.log(BigInt.asIntN(8, raw));  // als int8 gelesen

200n -56n

// Wichtig · Fallstricke

Kein number als zweites Argument: BigInt.asUintN(8, 257) wirft einen TypeError. Wandle den Wert vorher mit BigInt(257) um oder nutze das Literal 257n.
Ungültige Bitbreite: Ist bits negativ oder größer als 2⁵³−1, wird ein RangeError ausgelöst. Nachkommastellen werden abgeschnitten.
Große Bitbreiten: Ist bits größer als die tatsächliche Bitlänge eines positiven Werts, bleibt der Wert unverändert. Bei negativen Werten und sehr großen Bitbreiten, z. B. BigInt.asUintN(2 ** 40, -1n), müsste eine riesige Zahl entstehen. Das kann Speicherfehler oder RangeError auslösen.
Performance: Engines optimieren häufig asUintN(64, …). In Schleifen ist diese Methode meist schneller als ein manuelles % (1n << 64n), das bei negativen Werten ohnehin falsche Ergebnisse liefert.
Kompatibilität: Die Methode ist Teil von ES2020 und wird von allen modernen Browsern sowie von Node.js ab 10.4 unterstützt. Ein Polyfill ist praktisch unmöglich, weil BigInt eine Syntaxerweiterung ist.

Siehe auch

BigInt BigInt.asIntN() BigUint64Array DataView.prototype.setBigUint64() BigInt.prototype.toString() new Intl.DisplayNames()