JS_LookupProperty

  • Revision slug: SpiderMonkey/JSAPI_Reference/JS_LookupProperty
  • Revision title: JS_LookupProperty
  • Revision id: 71965
  • Created:
  • Creator: Jorend
  • Is current revision? No
  • Comment

Revision Content

{{template.Jsapi_ref_header("JS_LookupProperty")}}

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_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. {{wiki.template('Jsapi-requires-request')}}
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. *vp receives the last retrieved value of the property, if it exists. If not, *vp is set to JSVAL_VOID.

Description

The JS_LookupProperty functions examine a specified JS object, obj, for a property named name. On success, these functions set vp to the last retrieved value of the property if it exists, or to JSVAL_VOID if it does not, and return JS_TRUE. On error, such as running out of memory during the search, these functions return JS_FALSE, and the value left in *vp is undefined.

JS_LookupUCProperty is the Unicode version of the function.

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 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.

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

{{template.LXRSearch("ident", "i", "JS_LookupProperty")}}
{{template.LXRSearch("ident", "i", "JS_LookupUCProperty")}}
{{template.LXRSearch("ident", "i", "JS_LookupPropertyWithFlags")}}

JS_AliasProperty, JS_DefineProperty, JS_DefinePropertyWithTinyId, JS_GetProperty, JS_GetPropertyAttributes, JS_HasProperty

Revision Source

<p>{{template.Jsapi_ref_header("JS_LookupProperty")}}
</p><p>Determine if a specified property exists.
</p>
<h2 name="Syntax"> Syntax </h2>
<pre class="eval"><a href="en/JSBool">JSBool</a> <b>JS_LookupProperty</b>(<a href="en/JSContext">JSContext</a> *cx, <a href="en/JSObject">JSObject</a> *obj,
    const char *name, <a href="en/Jsval">jsval</a> *vp);

<a href="en/JSBool">JSBool</a> <b>JS_LookupUCProperty</b>(<a href="en/JSContext">JSContext</a> *cx, <a href="en/JSObject">JSObject</a> *obj,
    const <a href="en/Jschar">jschar</a> *name, size_t namelen, <a href="en/Jsval">jsval</a> *vp);

<a href="en/JSBool">JSBool</a> <b>JS_LookupPropertyWithFlags</b>(<a href="en/JSContext">JSContext</a> *cx, <a href="en/JSObject">JSObject</a> *obj,
    const char *name, uintN flags, <a href="en/Jsval">jsval</a> *vp);
</pre>
<table class="fullwidth-table">
<tbody><tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
<tr>
<td><code>cx</code></td>
<td><code><a href="en/JSContext">JSContext</a> *</code></td>
<td>Pointer to a JS context from which to derive runtime information.
{{wiki.template('Jsapi-requires-request')}}</td>
</tr>
<tr>
<td><code>obj</code></td>
<td><code><a href="en/JSObject">JSObject</a> *</code></td>
<td>Object to search on for the property.</td>
</tr>
<tr>
<td><code>name</code></td>
<td><code>const char *</code> <i>or</i> <code>const <a href="en/Jschar">jschar</a> *</code></td>
<td>Name of the property to look up.</td>
</tr>
<tr>
<td><code>namelen</code></td>
<td><code>size_t</code></td>
<td><i>(only in <code>JS_LookupUCProperty</code>)</i> The length of <code>name</code> in characters; or <code>-1</code> to indicate that <code>name</code> is null-terminated.</td>
</tr>
<tr>
<td><code>flags</code></td>
<td><code><a href="en/UintN">uintN</a></code></td>
<td><i>(only in <code>JS_LookupPropertyWithFlags</code>)</i> A combination of bits requesting special search behavior.  See <a href="en/JS_LookupProperty#Flags">Flags</a> below.</td>
</tr>
<tr>
<td><code>vp</code></td>
<td><code><a href="en/Jsval">jsval</a> *</code></td>
<td>Out parameter.  <code>*vp</code> receives the last retrieved value of the property, if it exists. If not, <code>*vp</code> is set to <code><a href="en/JSVAL_VOID">JSVAL_VOID</a></code>.</td>
</tr>
</tbody></table>
<h2 name="Description"> Description </h2>
<p>The <code>JS_LookupProperty</code> functions examine a specified JS object, <code>obj</code>, for a property named <code>name</code>. On success, these functions set <code>vp</code> to the last retrieved value of the property if it exists, or to <code><a href="en/JSVAL_VOID">JSVAL_VOID</a></code> if it does not, and return <code>JS_TRUE</code>. On error, such as running out of memory during the search, these functions return <code>JS_FALSE</code>, and the value left in <code>*vp</code> is undefined.
</p><p><code>JS_LookupUCProperty</code> is the Unicode version of the function.
</p>
<h3 name="Flags"> Flags </h3>
<p><code>JS_LookupPropertyWithFlags</code> allows the caller to specify flags requesting special lookup behavior.
</p><p>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 <code>resolve</code> callback, so objects of a custom <code><a href="en/JSClass">JSClass</a></code> may interpret these flags however they like.)
</p><p>If <code>flags</code> is <code>0</code>, <code>JS_LookupPropertyWithFlags</code> uses the default lookup rules, the ones used by <code>JS_LookupProperty</code>.  Otherwise, <code>flags</code> must be the logical OR of one or more of the following bits:
</p>
<dl><dt><code>JSRESOLVE_QUALIFIED</code>
</dt><dd>Behave as though the property name appeared to the right of a dot, as in <code>alert(obj.name)</code>.
</dd><dt><code>JSRESOLVE_ASSIGNING</code>
</dt><dd>Behave as though the property name appeared on the left-hand sign of an assignment.
</dd><dt><code>JSRESOLVE_DETECTING</code>
</dt><dd>Behave as though the name appeared in an idiom like "<code>if (obj.name) ...</code>" or "<code>obj.name ? ... : ...</code>".  Objects may pretend that the property does not exist when this flag is set.  For example, Mozilla's <code>document.all</code> property is hidden in this way.
</dd><dt><code>JSRESOLVE_DECLARING</code>
</dt><dd>Behave as though the name were being declared in a <code>var</code>, <code>const</code>, or <code>function</code> declaration.
</dd><dt><code>JSRESOLVE_CLASSNAME</code>
</dt><dd>Do <i>not</i> automatically infer and enable other flags by looking at the currently executing bytecode.
</dd></dl>
<h3 name="Notes"> Notes </h3>
<p><code>JS_LookupProperty</code> does not distinguish between a property with a value of <code>undefined</code> and a property that does not exist.  Use <code>JS_GetPropertyAttributes</code> to distinguish these cases.
</p><p><code>JS_LookupProperty</code> differs from <code><a href="en/JS_GetProperty">JS_GetProperty</a></code> in that <code>JS_LookupProperty</code> does not invoke the get handler for the property.
</p><p>Internally, property lookups are implemented by the <code><a href="en/JSObjectOps.lookupProperty">JSObjectOps.lookupProperty</a></code> callback.
</p>
<h2 name="See_Also"> See Also </h2>
<p>{{template.LXRSearch("ident", "i", "JS_LookupProperty")}}<br>
{{template.LXRSearch("ident", "i", "JS_LookupUCProperty")}}<br>
{{template.LXRSearch("ident", "i", "JS_LookupPropertyWithFlags")}}
</p><p><a href="en/JS_AliasProperty">JS_AliasProperty</a>, <a href="en/JS_DefineProperty">JS_DefineProperty</a>, <a href="en/JS_DefinePropertyWithTinyId">JS_DefinePropertyWithTinyId</a>, <a href="en/JS_GetProperty">JS_GetProperty</a>, <a href="en/JS_GetPropertyAttributes">JS_GetPropertyAttributes</a>, <a href="en/JS_HasProperty">JS_HasProperty</a>
</p>
Revert to this revision