Syntax

bool
JS_LookupProperty(JSContext *cx, JS::HandleObject obj, const char *name,
                  JS::MutableHandleValue vp);

bool
JS_LookupUCProperty(JSContext *cx, JS::HandleObject obj,
                    const char16_t *name, size_t namelen,
                    JS::MutableHandleValue vp);

bool
JS_LookupPropertyById(JSContext *cx, JS::HandleObject obj, JS::HandleId id,
                      JS::MutableHandleValue vp); // Added in SpiderMonkey 1.8.1

bool
JS_LookupElement(JSContext *cx, JS::HandleObject obj, uint32_t index,
                 JS::MutableHandleValue vp);

// ---- Obsolete since SpiderMonkey 31 ----

bool
JS_LookupPropertyWithFlags(JSContext *cx, JS::HandleObject obj, const char *name,
                           unsigned flags, JS::MutableHandleValue vp);

bool
JS_LookupPropertyWithFlagsById(JSContext *cx, JS::HandleObject obj, JS::HandleId id,
                               unsigned flags, JS::MutableHandleObject objp, JS::MutableHandleValue vp); // Added in SpiderMonkey 1.8.1

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 true if the property has no stored value; and the return value is true.
• If neither obj nor any of its prototypes have such a property, *vp receives undefined and the return value is true (to indicate no error occurred).
• On error or exception (such as running out of memory during the search), the return value is 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.

See Also

• bug 547140 -- removed *WithFlags
• bug 1094176