JS_ConvertArguments

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 series of JS values, passed in an argument array, to their corresponding JS types.

Syntax

bool
JS_ConvertArguments(JSContext *cx, const JS::CallArgs &args,
                    const char *format, ...); // Added in SpiderMonkey 31
bool
JS_ConvertArguments(JSContext *cx, unsigned argc, jsval *argv,
                    const char *format, ...); // Obsolete since JSAPI 30
Name Type Description
cx JSContext * The context in which to perform any necessary conversions.

cx also affects the interpretation of format, if JS_AddArgumentFormatter has been called.

Requires request. In a JS_THREADSAFE build, the caller must be in a request on this JSContext.
args const JS::CallArgs &

Reference to the arguments to convert. Added in SpiderMonkey 31
argc unsigned The number of arguments to convert. Obsolete since JSAPI 30
argv jsval *

Pointer to the vector of arguments to convert. Obsolete since JSAPI 30

This must be an argv pointer created by the JS engine and passed to a JSNative or JSFastNative callback, not an array created by application code. In certain error cases, JS_ConvertArguments calls JS_ARGV_CALLEE(argv), which accesses memory outside the range [argv .. argv+argc).

JS_ConvertArguments may modify argv in place by replacing an argument with the converted value. (The purpose is to ensure GC safety.)
format const char * Null-terminated string describing the types of the out parameters and how to convert the values in argv.
... void *

Out parameters. Pointers to variables into which to store the converted values. There must be one pointer for each parameter described in format.

Variables for optional parameters must already be initialized, because if an optional parameter is not in argv, JS_ConvertArguments does not modify the corresponding variable.

The variables do not need to be rooted. (If conversion creates a new GC thing, the corresponding jsval is written back to argv, which is rooted.)

Description

JS_ConvertArguments provides a convenient way to translate a series of JS values into their corresponding JS types with a single function call. It saves you from having to write separate tests and elaborate if...else statements in your function code to retrieve and translate multiple JS values for use with your own functions.

cx is the context for the call. argc indicates the number of JS values you are passing in for conversion. argv is a pointer to the array of JS values to convert.

format is a null-terminated C string. Each element of the array indicates the C type into which to convert the next available JS value. format can contain one or more instances of the following characters, as appropriate:

Character C Type Description
b bool Boolean
c uint16_t ECMA uint16_t, Unicode character
i int32_t ECMA int32_t
j int32_t ECMA int32_t (used to be different, behaves like i now) Obsolete since JSAPI 28
u uint32_t ECMA uint32_t
d double IEEE double
I double Integral IEEE double
s char * (C string) bug 607292
S JSString * Unicode string, accessed by a JSString pointer
W char16_t * Unicode character vector, 0-terminated (W for wide)
o JSObject * Object reference
f JSFunction *

The argument is converted to a function as though by a call to JS_ValueToFunction.

Warning: This conversion is dangerous and almost entirely useless, because the resulting JSFunction is not a real function object and therefore cannot be safely passed to any other JSAPI function. That includes JS_CallFunction() and JS_GetFunctionObject(). A JSFunction represents only the compiled code and not the environment of the function. Unless the function happens to be a native function, this means it isn't attached to any global or enclosing scope, and therefore must not be treated like a real function. Instead, use JSVAL_IS_OBJECT and JS_ObjectIsFunction() to check whether a value is already a function, or use JS_ConvertValue() to convert a value to JSTYPE_FUNCTION safely.
v jsval Argument value (no conversion)
* N/A None. If an asterisk (*) is present in format, it tells the conversion routine to skip converting the current argument.
/ N/A None. Arguments after the slash are optional. If an optional argument is missing from argv, JS_ConvertArguments neither assigns anything to any variable nor reports an error.

This function also takes in consideration any additional custom types defined on cx using JS_AddArgumentFormatter.

For example, if format is "bIob", then JS_ConvertArguments converts the first JS value in argv into a bool, the second value into a double, the third value into a JSObject *, and the last value into a bool.

To skip a given argument, pass an asterisk in the corresponding position in format.

If argc is less than the number of arguments required by format, JS_ConvertArgument reports an error and returns false. If argc is greater than the number of arguments described in format, the extraneous arguments are ignored.

On success, JS_ConvertArgument returns true. If any argument conversion fails or there are not enough arguments, it returns false.

To perform the opposite conversion, converting values of various C types to an array of jsvals, use JS_PushArguments.

See Also

Document Tags and Contributors

Tags: 
 Contributors to this page: fscholz, arai, evilpie, Sheppy, Ms2ger, lw, Jorend, SylvainPasche, MMondor, Wladimir_Palant, Piers, Dria
 Last updated by: fscholz,