JS LookupProperty

From MDC

Determine if a specified property exists.

Contents 1 Syntax 2 Description 2.1 Flags 2.2 Notes 3 See Also

[edit] 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_LookupPropertyWithFlags(JSContext *cx, JSObject *obj,
    const char *name, uintN flags, jsval *vp);

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	const char * or const jschar *	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.
vp	jsval *	Out parameter. On success, *vp receives the stored value of the property, if any.

[edit] Description

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

• If the property is found, the function sets *vp to the property's stored value, or JSVAL_TRUE if the property has no stored value; and returns JS_TRUE.
• If obj has no such property, the function sets *vp to JSVAL_VOID and returns 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.

JS_LookupUCProperty is the Unicode version of JS_LookupProperty.

[edit] Flags

JS_LookupPropertyWithFlags allows 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 sign 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

Do not automatically infer and enable other flags by looking at the currently executing bytecode.

[edit] 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.

[edit] See Also

LXR ID Search for JS_LookupProperty
LXR ID Search for JS_LookupUCProperty
LXR ID Search for JS_LookupPropertyWithFlags

JS_DefineProperty, JS_DefinePropertyWithTinyId, JS_GetProperty, JS_GetPropertyAttributes, JS_HasProperty