JS::CallArgs

This article covers features introduced in SpiderMonkey 17

Helper class encapsulating access to the callee, this value, arguments, and argument count for a function call.

Syntax

JS::CallArgs
JS::CallArgsFromVp(unsigned argc, JS::Value *vp);
Name Type Description
args unsigned Number of argument. (2nd argument of JSNative)
vp JS::Value * A pointer to the argument value array. (3nd argument of JSNative)

Methods

Methods of JS::CallArgs

Method Description
bool requireAtLeast(JSContext *cx, const char *fnname, unsigned required) Returns true if there are at least required arguments passed in. If false, it reports an error message on the context.

Methods inherited from JS::CallArgsBase

Method Description
unsigned length() const Returns the number of arguments..
JS::MutableHandleValue operator[](unsigned i) const Returns the i-th zero-indexed argument.
JS::HandleValue get(unsigned i) const Returns the i-th zero-indexed argument, or undefined if there's no such argument.
bool hasDefined(unsigned i) const Returns true if the i-th zero-indexed argument is present and is not undefined.

Methods inherited from JS::detail::CallReceiverBase

Method Description
JSObject &callee() const Returns the function being called, as an object. Must not be called after rval() has been used!
JS::HandleValue calleev() const Returns the function being called, as a value. Must not be called after rval() has been used!
JS::HandleValue thisv() const Returns the this value passed to the function. This method must not be called when the function is being called as a constructor via new. The value may or may not be an object: it is the individual function's responsibility to box the value if needed.
JS::Value computeThis(JSContext *cx) const Returns the this value if this is an object, otherwise calls JS_ComputeThis and returns it.
bool isConstructing() const Returns true if the function is called via new.
MutableHandleValue rval() const

Returns the currently-set return value. The initial contents of this value are unspecified. Once this method has been called, callee() and calleev() can no longer be used. (If you're compiling against a debug build of SpiderMonkey, these methods will assert to aid debugging.)

If the method you're implementing succeeds by returning true, you *must* set this. (SpiderMonkey doesn't currently assert this, but it will do so eventually.) You don't need to use or change this if your method fails.

Description

JS::CallArgs is helper class encapsulating access to the callee, this value, arguments, and argument count for a function call.

The intent of JS::CallArgs is that they be used to encapsulate access to the un-abstracted unsigned argc, Value *vp arguments to a function. New code should use CallArgs instead of JS_CALLEE etc. whenever possible.

The eventual plan is to change JSNative to take const CallArgs& directly, for automatic assertion of correct use and to make calling functions more efficient. Embedders should start internally switching away from using argc and vp directly, except to create a CallArgs. Then, when an eventual release making that change occurs, porting efforts will require changing methods' signatures but won't require invasive changes to the methods' implementations, potentially under time pressure.

JS::CallArgs encapsulates access to the callee, this, the function call's arguments, and eventual return value for a function call. The principal way to create a CallArgs is like so, using JS::CallArgsFromVp:

static bool
FunctionReturningArgcTimesArg0(JSContext *cx, unsigned argc, JS::Value *vp)
{
    JS::CallArgs args = JS::CallArgsFromVp(argc, vp);
    // Guard against no arguments or a non-numeric arg0.
    if (args.length() == 0 || !args[0].isNumber()) {
        args.rval().setInt32(0);
        return true;
    }
    // Access to the callee must occur before accessing/setting
    // the return value.
    JSObject &callee = rec.callee();
    // It's always fine to access thisv().
    HandleValue thisv = rec.thisv();
    args.rval().set(JS::NumberValue(args.length() * args[0].toNumber()));
    // callee() and calleev() will now assert.
    return true;
}

See Also

Document Tags and Contributors

Tags: 
 Contributors to this page: kscarfone, arai
 Last updated by: kscarfone,