JS::CallArgs

This is an archived page. It's not actively maintained.

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