Availability

Navigator 3.0

Description

The valueOf() method of an object returns the primitive value associated with that object, if there is one. For objects of type Object, and for the client-side JavaScript objects, there is no primitive value, and this method simply returns the object itself.

For objects of type Number, however, valueOf() returns the primitive numeric value represented by the object. Similarly, it returns the primitive Boolean value associated with a Boolean object, the string associated with a String object, and the function associated with a Function object.

It is rarely, if ever, necessary to invoke the valueOf() method yourself. JavaScript does this automatically whenever an object is used where a primitive value is expected. In fact, because of this automatic invocation of the valueOf() method, it is difficult to even distinguish between primitive values and their corresponding objects. The typeof operator will show you the difference between strings and String objects and functions and Function objects, for example, but in practical terms, you can use them equivalently in your JavaScript code.

The valueOf() methods of the Number, Boolean, String, and Function objects convert these "wrapper" objects to the primitive values they represent. The Object() constructor performs the opposite operation when invoked with a number, Boolean, string, or function argument: it wraps the primitive value in an appropriate object wrapper. JavaScript performs this primitive to object conversion for you in almost all circumstances, so it is rarely, if ever, necessary to invoke the Object() constructor in this way.

Usage

In some circumstances, you may want to define a custom valueOf() method for your own objects. For example, you might define a JavaScript object type to represent complex numbers (a real number plus an imaginary number). As part of this object type, you'd probably define methods for performing complex addition, multiplication, and so on. But you might also want the ability to treat your complex numbers like ordinary real numbers by discarding the imaginary part. You might do something like the following:

Complex.prototype.valueOf = new Function("return this.real");

With this valueOf() method defined for your Complex object type, you could then do things like pass one of your complex number objects to Math.sqrt(), which would compute the square root of the real portion of the complex number.

See Also

"Object", "Object.toString()"