Obsolete since JSAPI 28
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.
Convert a JavaScript value to a 32-bit signed integer.
Syntax
JSBool JS_ValueToInt32(JSContext *cx, jsval v, int32 *ip);
| 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. |
ip |
int32 * |
Out parameter. On success, *ip receives the converted integer value. |
Description
JS_ValueToInt32 converts a specified JS value, v, to a 32-bit signed integer (-2147483648 to 2147483647). First it converts v to a floating-point number as if by calling JS::ToNumber. If the result is NaN, an infinity, or a number outside the 32-bit range, JS_ValueToInt32 reports an error and conversion fails. Otherwise, the floating-point number is rounded to the nearest integer value.
On success, JS_ValueToInt32 stores the converted value in *ip and returns JS_TRUE. On error or exception, it returns JS_FALSE, and the value left in *ip is undefined.
JS_ValueToInt32 is pre-ECMA-262 Edition 1, and rounds differently than JS_ValueToECMAInt32 and JS::ToInt32. This routine was added for layers-based graphics programming in Netscape 4, but unless you know you need its rounding behavior, it is best to avoid it in favour of JS::ToInt32. JS::ToInt32 rounds as specified in ECMA 262-3 §9.5, while this routine rounds by adding 0.5 to the converted float-point number and truncating the result at the decimal point. JS::ToInt32 will also convert NaN (and anything that converts to NaN, such as an array of strings) to 0, whereas this routine would report an error.