JS_ConvertArguments

Converts a series of JS values, passed in an argument array, to their corresponding JS types.

Syntax

JSBool JS_ConvertArguments(JSContext *cx,
    uintN argc, jsval *argv, const char *format, ...);
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.
argc uintN The number of arguments to convert.
argv jsval *

Pointer to the vector of arguments to convert.

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 Corresponding JS type to which to convert the value
b JSBool
c uint16_t / jschar (16-bit, unsigned integer / 16-bit character)
i int32_t (32-bit, ECMA-compliant signed integer)
u uint32_t (32-bit, ECMA-compliant, unsigned integer)
j int32_t (behaves like i now) Obsolete since JSAPI 28
d double
I double (converted to an integer value)
s char * (C string) bug 607292
S JSString * (Unicode string)
W jschar * (Unicode null-terminated string)
o JSObject *
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.

* None. If an asterisk (*) is present in format, it tells the conversion routine to skip converting the current argument.
/ 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 JSBool, the second value into a double, the third value into a JSObject *, and the last value into a JSBool.

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 JS_FALSE.  If argc is greater than the number of arguments described in format, the extraneous arguments are ignored.

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

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

MXR ID Search for JS_ConvertArguments

Document Tags and Contributors

Last updated by: evilpie,