JS_ConvertValue

Obsolete since JSAPI 38
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.

Converts a JavaScript value to a value of a specific JavaScript type.

Syntax

bool
JS_ConvertValue(JSContext *cx, JS::HandleValue v, JSType type, JS::MutableHandleValue vp);
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 JS::HandleValue The value to convert.
type JSType The type to which the value is to be converted. type must be one of JSTYPE_VOID, JSTYPE_OBJECT, JSTYPE_FUNCTION, JSTYPE_STRING, JSTYPE_NUMBER, or JSTYPE_BOOLEAN. Otherwise JS_ConvertValue reports an error.
vp JS::MutableHandleValue Out parameter. On success, *vp receives the converted value.

Description

JS_ConvertValue converts a JavaScript value, v, to the specified type. On success, the converted value is stored in *vp. Typically users of this function set vp to point to v, so that if conversion is successful, v now contains the converted value.

JS_ConvertValue calls other, type-specific conversion routines based on the type argument.

  • Converting any value to JSTYPE_VOID always succeeds. The result is undefined value.
  • Converting to JSTYPE_OBJECT works exactly like JS::ToObject if v.isNullOrUndefined() is false, otherwise the result is nullptr.
  • Converting to JSTYPE_FUNCTION works like JS_ValueToFunction, but better: the result is a function object that has not been stripped of its lexical scope. It is safe to call the result (e.g. using JS_CallFunctionValue).
  • Converting to JSTYPE_STRING works like JS::ToString.
  • Converting to JSTYPE_NUMBER works exactly like JS::ToNumber.
  • Converting to JSTYPE_BOOLEAN works exactly like JS::ToBoolean.

On success, JS_ConvertValue stores the converted value in *vp and returns true. On error or exception, it returns false, and the value left in *vp is undefined.

See Also