Object.prototype.valueOf()

BaselineWidely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

valueOf() はObject インスタンスのメソッドで、this 値をオブジェクトに変換します。このメソッドは、派生オブジェクトでは独自の型変換ロジックのためにオーバーライドされるためのものです。

試してみましょう

function MyNumberType(n) {  this.number = n;}MyNumberType.prototype.valueOf = function () {  return this.number;};const object1 = new MyNumberType(4);console.log(object1 + 3);// Expected output: 7

構文

valueOf()

返値

指定されたオブジェクトのプリミティブ値を返します。

メモ:型変換の際にvalueOf が有益であるためには、プリミティブを返す必要があります。すべてのプリミティブ型は自分自身でvalueOf() メソッドを持っているので、一般的にaPrimitiveValue.valueOf() を呼び出してもObject.prototype.valueOf() は呼び出されません。

解説

JavaScript はvalueOf メソッドを、オブジェクトをプリミティブな値に変換するときに呼び出します。あなたが自分でvalueOf メソッドを実行する必要はほとんどなく、プリミティブな値が期待される場面にオブジェクトが出くわしたとき JavaScript が自動的に実行します。

このメソッドは数値変換とプリミティブ変換で優先的に呼び出されますが、文字列変換ではtoString() が優先的に呼び出され、toString() は文字列値を返す可能性がとても高いので（Object.prototype.toString() の基本実装でも）、この場合valueOf() は通常呼び出されません。

Object.prototype 継承するすべてのオブジェクト（つまり、null プロトタイプオブジェクトを除くすべてのオブジェクト）はtoString() メソッドを継承しています。Object.prototype.valueOf() の基本実装は、意図的に有益なものになっていません。オブジェクトを返すことで、その返値はどのようなプリミティブ変換アルゴリズムでも使用することはありません。多くの組み込みオブジェクトは、適切なプリミティブ値を返すためにこのメソッドを上書きします。独自オブジェクトを作成する場合は、valueOf() を上書きして独自メソッドを呼び出すことで、独自オブジェクトをプリミティブ値に変換することができます。一般的に、valueOf() はオブジェクトにとって最も意味のある値を返すために使用します。toString() とは異なり、文字列である必要はありません。また、@@toPrimitive メソッドを追加することもできます。このメソッドでは、変換処理をさらに制御することができ、型変換の際には常にvalueOf やtoString よりも優先されます。

例

valueOf() の使用

基本のvalueOf() メソッドは、this の値自身を返しますが、まだオブジェクトに変換されていない場合はオブジェクトに変換されます。そのため、その返り値はどのようなプリミティブ変換アルゴリズムでも使用されることはありません。

const obj = { foo: 1 };console.log(obj.valueOf() === obj); // trueconsole.log(Object.prototype.valueOf.call("primitive"));// [String: 'primitive'] (a wrapper object)

独自オブジェクトにおける valueOf のオーバーライド

既定のvalueOf メソッドの代わりに呼び出される関数を作成することができます。型変換中に呼び出されるときには引数を渡されないので、関数は引数として取るべきではありません。

例えば、独自クラスBox にvalueOf メソッドを追加するには次のようにします。

class Box {  #value;  constructor(value) {    this.#value = value;  }  valueOf() {    return this.#value;  }}

先のコードにおいて、Box 型のオブジェクトがプリミティブ値（特に文字列ではない）として表現されるコンテキストで使用されるとき、 JavaScript で自動的に先のコードで定義されている関数が呼び出されます。

const box = new Box(123);console.log(box + 456); // 579console.log(box == 123); // true

オブジェクトのvalueOf メソッドは通常 JavaScript によって呼び出されますが、従うこと以下で自分で呼び出すこともできます。

box.valueOf();

単項プラスの使用

単項プラスは、オペランドに対して数値変換を行います。これは、@@toPrimitive を持たないほとんどのオブジェクトでは、valueOf() を呼び出すことを意味しています。しかし、オブジェクトに独自のvalueOf() メソッドがない場合、基本実装ではvalueOf() は無視され、代わりにtoString() の返値が使用されます。

+new Date(); // 現在のタイムスタンプ。 new Date().getTime() と同じ+{}; // NaN （toString() は "[object Object]" を返す）+[]; // 0 （toString() は空の文字列リストを返す）+[1]; // 1 （toString() は "1" を返す）+[1, 2]; // NaN （toString() は "1,2" を返す）+new Set([1]); // NaN （toString() は "[object Set]" を返す）+{ valueOf: () => 42 }; // 42