Entry: JS_ConvertArguments (Function)
Summary: 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, ...);
Argument Type Description
cx JSContext * Pointer to a JS context from which to derive runtime information.
argc uintN The number of arguments to convert.
argv jsval * Pointer to the vector of arguments to convert.
format char * Character array containing the recognized format to which to convert
... void * A variable number of pointers into which to store the converted types. There should be one pointer for each converted value.
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: TABLE BORDER="0" TRTD VALIGN='baseline' ALIGN='left' BCharacter /B/TDTD VALIGN='baseline' ALIGN='left' BCorresponding JS type to which to convert the value /B /TD/TRTR TD VALIGN='baseline' ALIGN='left'P CODEb/CODE/TDTD VALIGN='baseline' ALIGN='left'P CODEJSBool/CODE/P /TD/TRTR TD VALIGN='baseline' ALIGN='left'P CODEc/CODE/TDTD VALIGN='baseline' ALIGN='left'P CODEuint16 (16-bit, unsigned integer)/CODE/P /TD/TRTR TD VALIGN='baseline' ALIGN='left'P CODEi/CODE/TDTD VALIGN='baseline' ALIGN='left'P CODEint32 (32-bit, ECMA-compliant signed integer)/CODE/P /TD/TRTR TD VALIGN='baseline' ALIGN='left'P CODEu/CODE/TDTD VALIGN='baseline' ALIGN='left'P CODEuint32 (32-bit, ECMA-compliant, unsigned integer)/CODE/P /TD/TRTR TD VALIGN='baseline' ALIGN='left'P CODEj/CODE/TDTD VALIGN='baseline' ALIGN='left'P CODEint32 (32-bit, signed integer)/CODE/P /TD/TRTR TD VALIGN='baseline' ALIGN='left'P CODEd/CODE/TDTD VALIGN='baseline' ALIGN='left'P CODEjsdouble/CODE/P /TD/TRTR TD VALIGN='baseline' ALIGN='left'P I/TDTD VALIGN='baseline' ALIGN='left'P CODEjsdouble (converted to an integer value)/CODE/P /TD/TRTR TD VALIGN='baseline' ALIGN='left'P s/TDTD VALIGN='baseline' ALIGN='left'P JSString (treated as an array of characters)/P /TD/TRTR TD VALIGN='baseline' ALIGN='left'P S/TDTD VALIGN='baseline' ALIGN='left'P JSString/P /TD/TRTR TD VALIGN='baseline' ALIGN='left'P o/TDTD VALIGN='baseline' ALIGN='left'P JSObject/P /TD/TRTR TD VALIGN='baseline' ALIGN='left'P f/TDTD VALIGN='baseline' ALIGN='left'P JSFunction/P /TD/TRTR TD VALIGN='baseline' ALIGN='left'P */TDTD VALIGN='baseline' ALIGN='left'P None. If an asterisk (*) is present in CODEformat/CODE, it tells the conversion routine to skip converting the current argument./P /TD/TRTR TD VALIGN='baseline' ALIGN='left'P //TDTD VALIGN='baseline' ALIGN='left'P None. If a slash (/) is present in CODEformat/CODE, it tells the conversion routine to turn off checking that the argument vector was passed to JS_ConvertArguments from a valid native JS function./P /TD/TR/TABLE
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.
See also:
[sh-index] Back to list of manuals
|
| |
