JS LookupUCProperty

Determine if a specified property exists.

Syntax

JSBool JS_LookupProperty(JSContext *cx, JSObject *obj,
    const char *name, jsval *vp);

JSBool JS_LookupUCProperty(JSContext *cx, JSObject *obj,
    const jschar *name, size_t namelen, jsval *vp);

JSBool JS_LookupPropertyById(JSContext *cx, JSObject *obj,
    jsid id, jsval *vp); Added in SpiderMonkey 1.8.1

JSBool JS_LookupPropertyWithFlags(JSContext *cx, JSObject *obj,
    const char *name, uintN flags, jsval *vp);

JSBool JS_LookupPropertyWithFlagsById(JSContext *cx, JSObject *obj,
    jsid id, uintN flags, JSObject **objp, jsval *vp); Added in SpiderMonkey 1.8.1
Name Type Description
cx JSContext * Pointer to a JS context from which to derive runtime information. Requires request. In a JS_THREADSAFE build, the caller must be in a request on this JSContext.
obj JSObject * Object to search on for the property.
name or id const char * or const jschar * or jsid Name of the property to look up.
namelen size_t (only in JS_LookupUCProperty) The length of name in characters; or -1 to indicate that name is null-terminated.
flags uintN (only in JS_LookupPropertyWithFlags) A combination of bits requesting special search behavior. See Flags below.
objp JSObject ** Out parameter. On success, *objp receives the object on which the property was found. This will be either obj or an element on obj's prototype chain.
vp jsval * Out parameter. On success, *vp receives the stored value of the property, if any.

Description

The functions JS_LookupProperty, JS_LookupUCProperty, JS_LookupPropertyById, JS_LookupPropertyWithFlags, and JS_LookupPropertyWithFlagsById search a specified object, obj, for a property with the given name. These functions all have similar behavior:

  • The search starts with obj and proceeds along the prototype chain.
  • If the property is found, *vp receives the property's stored value, or JSVAL_TRUE if the property has no stored value; and the return value is JS_TRUE.
  • If neither obj nor any of its prototypes have such a property, *vp receives JSVAL_VOID and the return value is JS_TRUE (to indicate no error occurred).
  • On error or exception (such as running out of memory during the search), the return value is JS_FALSE, and the value left in *vp is undefined.
  • There is no way to tell the difference between not finding any property and finding a property whose value is undefined. Sorry. Use JS_GetPropertyDescriptorById instead.

JS_LookupUCProperty is the Unicode version of JS_LookupProperty.

Flags

JS_LookupPropertyWithFlags and JS_LookupPropertyWithFlagsById allow the caller to specify flags requesting special lookup behavior.

When executing JavaScript code that uses properties, SpiderMonkey looks up properties using slightly different rules depending on the syntactic context in which the property name appears. (The JavaScript engine simply passes these flags through to the object when it calls the object's JSClass.resolve callback, so objects of a custom JSClass may interpret these flags however they like.)

If flags is 0, JS_LookupPropertyWithFlags uses the default lookup rules, the ones used by JS_LookupProperty. Otherwise, flags must be the logical OR of one or more of the following bits:

JSRESOLVE_QUALIFIED
Behave as though the property name appeared to the right of a dot, as in alert(obj.name).
JSRESOLVE_ASSIGNING
Behave as though the property name appeared on the left-hand side of an assignment.
JSRESOLVE_DETECTING
Behave as though the name appeared in an idiom like "if (obj.name) ..." or "obj.name ? ... : ...". Objects may pretend that the property does not exist when this flag is set. For example, Mozilla's document.all property is hidden in this way.
JSRESOLVE_DECLARING
Behave as though the name were being declared in a var, const, or function declaration.
JSRESOLVE_CLASSNAME
Search for the initial value of a standard class such as Object, Array, or Error. Do not automatically infer and enable other flags by looking at the currently executing bytecode.

Notes

JS_LookupProperty does not distinguish between a property with a value of undefined and a property that does not exist. Use JS_GetPropertyAttributes to distinguish these cases.

JS_LookupProperty differs from JS_GetProperty in that JS_LookupProperty does not invoke the get handler for the property.

Internally, property lookups are implemented by the JSObjectOps.lookupProperty callback.

MXR ID Search for JS_LookupProperty
MXR ID Search for JS_LookupUCProperty
MXR ID Search for JS_LookupPropertyById
MXR ID Search for JS_LookupPropertyWithFlags
MXR ID Search for JS_LookupPropertyWithFlagsById

Document Tags and Contributors

Contributors to this page: Nickolay, MMondor, Tservo, DBaron, Dria, Jorend
Last updated by: Jorend,