BigInt.prototype.valueOf() — Methode · JavaScript-Referenz

Signatur

BigInt.prototype.valueOf()

Beschreibung

BigInt.prototype.valueOf() liefert den primitiven Wert vom Typ bigint. Wird die Methode auf einem Primitiv wie 42n aufgerufen, kommt derselbe Wert zurück. Bei einem Wrapper-Objekt, das mit Object(42n) erzeugt wurde, wird der darin eingeschlossene Wert ausgepackt.

Im normalen Code ruft man valueOf() selten direkt auf. JavaScript verwendet die Methode intern, wenn ein Objekt in ein Primitiv umgewandelt werden muss, zum Beispiel bei arithmetischen Operatoren (+, *, -), bei Vergleichen oder bei ==.

Einen direkten Aufruf braucht man vor allem, wenn man mit Wrapper-Objekten arbeitet. Das kommt etwa vor bei Werten, die über Object() umgewandelt wurden, oder bei generischem Code, der beliebige Werte in Primitive auspacken will. Mit typeof lassen sich beide Formen unterscheiden: Das Objekt ergibt "object", der Rückgabewert von valueOf() dagegen "bigint".

Rückgabewert

Typ

bigint

Beschreibung

Der primitive BigInt-Wert, der im Objekt steckt (bzw. der Wert selbst, wenn er schon ein Primitiv ist).

Beispiele

Wrapper-Objekt auspacken

const wrapped = Object(123n);
console.log(typeof wrapped);

const primitive = wrapped.valueOf();
console.log(typeof primitive, primitive);

object bigint 123n

Aufruf auf einem Primitiv

const id = 9007199254740993n;
console.log(id.valueOf() === id);

true

Strikter Vergleich mit Wrapper-Objekten

const a = Object(10n);
const b = 10n;

console.log(a === b);           // Objekt vs. Primitiv
console.log(a.valueOf() === b); // nach dem Auspacken
console.log(a == b);            // == ruft valueOf() implizit auf

false true true

Generische Hilfsfunktion zum Auspacken

const unwrapBigInt = (value) =>
  typeof value === 'bigint' || value instanceof BigInt
    ? BigInt.prototype.valueOf.call(value)
    : null;

console.log(unwrapBigInt(Object(5n)) * 2n);
console.log(unwrapBigInt(5));

10n null

// Wichtig · Fallstricke

Ruft man die Methode mit einem this auf, das weder ein BigInt-Primitiv noch ein BigInt-Objekt ist, wirft sie einen TypeError. Beispiel: BigInt.prototype.valueOf.call(5).
new BigInt(1n) ist nicht erlaubt und wirft einen TypeError. Wrapper-Objekte entstehen nur über Object(1n). In der Praxis sollte man Wrapper-Objekte ganz vermeiden, weil === sie nie mit Primitiven gleichsetzt und sie immer als truthy gelten, auch Object(0n).
Auch der ausgepackte Wert lässt sich nicht mit number mischen. Object(1n).valueOf() + 1 wirft einen TypeError. Man muss explizit mit Number() oder BigInt() umwandeln.
Wird die Methode auf BigInt.prototype überschrieben, ändert das die implizite Umwandlung überall im Programm. Das sollte man unterlassen.
Kompatibilität: Die Methode ist in allen modernen Browsern verfügbar (Baseline seit 2020) sowie ab Node.js 10.4.

Siehe auch

BigInt BigInt.prototype.toString() BigInt.prototype.toLocaleString() Object.prototype.valueOf() Number.prototype.valueOf()