JS_ValueToNumber

Obsolete since JSAPI 24
This feature is obsolete. Although it may still work in some browsers, its use is discouraged since it could be removed at any time. Try to avoid using it.

Replaced by JS::ToNumber.

Convert any JavaScript value to a floating-point number of type jsdouble.

Syntax

JSBool
JS_ValueToNumber(JSContext *cx, jsval v, jsdouble *dp);
Name Type Description
cx JSContext * The context in which to perform the conversion. Requires request. In a JS_THREADSAFE build, the caller must be in a request on this JSContext.
v jsval The value to convert.
dp jsdouble * Out parameter. On success, *dp receives the converted floating-point value.

Description

JS_ValueToNumber converts a JavaScript value to a number. It implements the ToNumber operator described in ECMA 262-3 ยง9.3.

  • If v is already a number, conversion succeeds.
  • If v is undefined, null, false, or true, conversion succeeds, and the result is NaN, 0, 0, or 1 respectively.
  • If v is a string, conversion proceeds as specified in ECMA 262-3 ยง9.3.1. JS_ValueToNumber always succeeds in this case, returning JS_TRUE. If the string is not a numeric string, *dp is set to NaN.
  • Otherwise v is an object. JS_ValueToNumber carries out the following steps to convert it to a number. If at any step an error or exception occurs, or conversion succeeds, the rest of the steps are skipped. (This behavior is implemented by v's JSObjectOps.defaultValue hook, so host objects can override it all.)
    • First, the object's JSClass.convert callback is called. For objects of standard classes, this is JS_ConvertStub, which simply calls v.valueOf() if present. If the convert callback produces a primitive value, the value is converted to a number as described above and conversion succeeds.
    • Otherwise, the resulting object's toString method, if any, is called. If that produces a primitive value, the value is converted to a number as described above and conversion succeeds.
    • Otherwise conversion fails with a TypeError.

On success, JS_ValueToNumber stores the converted value in *dp and returns JS_TRUE. On error or exception, it returns JS_FALSE, and the value left in *dp is undefined.

See Also