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

Signatur

Number.prototype.valueOf()

Beschreibung

Number.prototype.valueOf() liefert den primitiven number-Wert, der in einem Number-Objekt steckt. Rufen Sie die Methode auf einer primitiven Zahl auf, gibt sie einfach diese Zahl zurück.

Im Alltag rufen Sie die Methode selten selbst auf. JavaScript nutzt sie intern, wenn ein Objekt in einen primitiven Wert umgewandelt werden muss, etwa bei arithmetischen Operatoren (+, -, *), Vergleichen (<, >) oder beim Aufruf von Number(obj). Deshalb lässt sich mit new Number(5) + 1 ganz normal rechnen.

Ein expliziter Aufruf hilft vor allem, wenn Sie ein Wrapper-Objekt (new Number(…)) sicher in eine primitive Zahl zurückverwandeln wollen, zum Beispiel für strikte Vergleiche mit === oder für typeof-Prüfungen.

Rückgabewert

Typ

number

Beschreibung

Der primitive Zahlenwert des Number-Objekts bzw. der Zahl.

Beispiele

Wrapper-Objekt in eine primitive Zahl umwandeln

const wrapped = new Number(42);
console.log(typeof wrapped);            // Objekt

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

object number 42

Strikter Vergleich mit Wrapper-Objekten

const a = new Number(10);
const b = new Number(10);

console.log(a === b);                     // zwei verschiedene Objekte
console.log(a.valueOf() === b.valueOf()); // primitive Werte vergleichen
console.log(a == 10);                     // implizites valueOf()

false true true

Implizite Nutzung bei Arithmetik

const price = new Number(19.99);
const quantity = 3;

// Der Operator * ruft intern valueOf() auf
const total = price * quantity;
console.log(total.toFixed(2));
console.log((5).valueOf());

59.97 5

Einheitliche Normalisierung in einer Hilfsfunktion

const toPrimitiveNumber = (value) =>
  value instanceof Number ? value.valueOf() : value;

const values = [1, new Number(2), 3, new Number(4)];
const normalized = values.map(toPrimitiveNumber);

console.log(normalized.every((v) => typeof v === 'number'));
console.log(normalized);

true [ 1, 2, 3, 4 ]

// Wichtig · Fallstricke

Kein fremdes this: Ist this weder eine Zahl noch ein Number-Objekt, wirft die Methode einen TypeError, z. B. Number.prototype.valueOf.call('5').
Keine Wrapper-Objekte verwenden: new Number(…) erzeugt Objekte. Die sind bei === nie gleich und immer truthy, auch new Number(0). Nutzen Sie stattdessen primitive Zahlen oder Number(wert) ohne new.
Syntax bei Zahlliteralen: 5.valueOf() ist ein Syntaxfehler, weil der Punkt als Dezimaltrennzeichen gelesen wird. Schreiben Sie (5).valueOf() oder 5..valueOf().
Wenn Sie die Methode in eigenen Objekten überschreiben, ändert das deren Verhalten bei Operatoren. Symbol.toPrimitive hat dabei Vorrang vor valueOf().
Die Methode wird in allen Browsern und in Node.js unterstützt.

Siehe auch

Number Number.prototype.toString() Object.prototype.valueOf() Symbol.toPrimitive Number.prototype.toFixed()