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 sequential character array, where each element of the array indicates the JS 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 (16-bit, unsigned integer)
|
i |
int32 (32-bit, ECMA-compliant signed integer)
|
u |
uint32 (32-bit, ECMA-compliant, unsigned integer)
|
j |
int32 (32-bit, signed integer)
|
d |
jsdouble
|
I |
jsdouble (converted to an integer value)
|
s |
JSString (treated as an array of characters)
|
S |
JSString
|
o |
JSObject
|
f |
JSFunction
|
* |
None. If an asterisk (*) is present in format, it tells the conversion routine to skip converting the current argument.
|
/ |
None. If a slash (/) is present in format, it tells the conversion routine to turn off checking that the argument vector was passed to JS_ConvertArguments from a valid native JS function.
|
For example, if format is "bIfb", then JS_ConvertArguments converts the first JS value in argv into a JSBool, the second value into a jsdouble, 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. JS_ConvertArguments expects to be passed an argument vector that belongs to a native JS function, such that every argument passed is already a JS value. By default, when you first call JS_ConvertArguments, it automatically provides built-in error checking to guarantee that the proper number of arguments has been passed. If an improper number of arguments is passed in, JS_ConvertArguments reports an error and terminates. You can turn off this error-checking at any time by passing a slash (/) as a character any place in format where you no longer desire the argument number check to be made.
When you call JS_ConvertArguments, the arguments you pass in after format must be a series of pointers to storage. You must allocate one storage pointer for each converted value you expect.
If JS_ConvertArgument successfully converts all arguments, it returns JS_TRUE. Otherwise it returns JS_FALSE.
|