JS_LookupProperty

Obsolete since JSAPI 37
This feature is obsolete. Although it may still work in some browsers, its use is discouraged since it could be removed at any time. Try to avoid using it.

Determine if a specified property exists.

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
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 JS::HandleObject Object to search on for the property.
name or id const char * or const char16_t *or JS::HandleId 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 unsigned (only in JS_LookupPropertyWithFlags) A combination of bits requesting special search behavior. See Flags below.
objp JS::MutableHandleObject 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 JS::MutableHandleObject 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 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

Document Tags and Contributors

Tags: 
 Contributors to this page: arai, fscholz, Dmandelin, Jorend, Gwurk, Ttocsmij, Nickolay, Dria, MMondor, Tservo
 Last updated by: arai,