JS_GetPropertyAttributes

  • Revision slug: SpiderMonkey/JSAPI_Reference/JS_GetPropertyAttributes
  • Revision title: JS_GetPropertyAttributes
  • Revision id: 85816
  • Created:
  • Creator: Jorend
  • Is current revision? No
  • Comment 3 words added, 27 words removed

Revision Content

Get the attributes of a specified property.

Syntax

JSBool JS_GetPropertyAttributes(JSContext *cx, JSObject *obj,
    const char *name, uintN *attrsp, JSBool *foundp);

JSBool JS_GetUCPropertyAttributes(JSContext *cx, JSObject *obj,
    const jschar *name, size_t namelen,
    uintN *attrsp, JSBool *foundp);
Name Type Description
cx JSContext * The context in which to look up property attributes. {{ Jsapi-requires-request() }}
obj JSObject * The object that has the property to be queried.
name const char * or const jschar * Name of the property from which to retrieve attributes.
namelen size_t (only in JS_GetUCPropertyAttributes) The length of name in characters; or (size_t) -1 to indicate that name is null-terminated.
attrsp uintN * Out parameter. If the specified property is found on obj, *attrsp receives its attributes.
foundp JSBool * Out parameter. If no error occurs, *foundp receives JS_TRUE if the specified property is found and JS_FALSE if it is not found. If an error occurs, the value left in *foundp is unspecified.

Description

JS_GetPropertyAttributes retrieves the property attributes of the property with the given name on a given object, obj. JS_GetUCPropertyAttributes is the Unicode version of the function.

If an error occurs, the return value is JS_FALSE, and the values left in *attrsp and *foundp are unspecified.

If obj does not have the specified property, or if it inherits it from some other object (on its prototype chain, for example), then *foundp is set to JS_FALSE. The value left in *attrsp is unspecified. The return value is JS_TRUE (to indicate that no error occurred).

If the property exists and belongs to obj, then *foundp is set to JS_TRUE, *attrsp is set to the logical OR of zero or more property attribute flags (described below), and the function returns JS_TRUE.

Property attributes

Any object property can have zero or more property attributes set. Some property attributes are defined in the ECMAScript standard, in {{ Es3_spec("8.6.1") }}. SpiderMonkey additionally defines several non-standard property attributes.

The JSAPI expresses property attributes as a value of type uintN, the bitwise OR of zero or more of the JSPROP flags described below.

Flag Description

JSPROP_ENUMERATE

The property is visible to JavaScript forin and for eachin loops, as well as to JS_Enumerate.

This is the inverse of the ECMA standard DontEnum attribute.

{{ LXRSearch("ident", "i", "JSPROP_ENUMERATE") }}

JSPROP_READONLY

The property's value cannot be set. In JavaScript 1.2 and lower, it is an error to attempt to assign a value to a read-only property. In JavaScript 1.3 and higher, as in ECMAScript, attempts to set a value on a read-only property are ignored.

This is the ECMA standard ReadOnly attribute.

{{ LXRSearch("ident", "i", "JSPROP_READONLY") }}

JSPROP_PERMANENT

The property cannot be deleted. In JavaScript 1.2 and lower, it is an error to attempt to delete a permanent property. In JavaScript 1.3 and higher, as in ECMAScript, such attempts are ignored.

This is the ECMA standard DontDelete attribute.

The JavaScript language does not provide any way for a script to delete a permanent property. C/C++ code can do this by making the property non-permanent, using JS_SetPropertyAttributes, before deleting it.

{{ LXRSearch("ident", "i", "JSPROP_PERMANENT") }}

JSPROP_GETTER

The property's getter is a JavaScript Function, not a C/C++ function. See JS_DefineProperty and JS_GetPropertyAttrsGetterAndSetter for details.

{{ LXRSearch("ident", "i", "JSPROP_GETTER") }}

JSPROP_SETTER

The property's setter is a JavaScript Function, not a C/C++ function. See JS_DefineProperty and JS_GetPropertyAttrsGetterAndSetter for details.

{{ LXRSearch("ident", "i", "JSPROP_SETTER") }}

JSPROP_SHARED

The property is shared. The JavaScript engine does not allocate memory for the property's stored value. This attribute is appropriate for custom properties that are implemented as fields of a native C/C++ data structure or as C++ Get/Set method pairs. In such cases, the stored value slot is redundant at best and could entrain garbage.

Implementation note: A property with both JSPROP_SHARED and JSPROP_PERMANENT triggers a SpiderMonkey optimization: the property is not physically copied to an object that inherits it, as it normally would be in certain cases. The optimization is almost completely transparent, but JS_AlreadyHasOwnProperty can expose it.

{{ LXRSearch("ident", "i", "JSPROP_SHARED") }}

JSPROP_INDEX

The property's id is represented internally as an integer, not a string.

This flag has an additional special meaning when used with JS_DefineProperty, JS_FS, and other APIs that define properties: it means that the name parameter is actually an integer unsafely cast to a pointer type, not a string.

{{ LXRSearch("ident", "i", "JSPROP_INDEX") }}

An application can set property attributes when creating a property. See JS_DefineProperty, JS_FS, and JS_FN. To modify the attributes of an existing property, use JS_SetPropertyAttributes.

{{ LXRSearch("ident", "i", "JS_GetPropertyAttributes") }}
{{ LXRSearch("ident", "i", "JS_GetUCPropertyAttributes") }}

Revision Source

<p>Get the attributes of a specified property.</p>
<h2 name="Syntax">Syntax</h2>
<pre class="eval"><a href="/En/SpiderMonkey/JSAPI_Reference/JSBool" title="en/JSBool">JSBool</a> <strong>JS_GetPropertyAttributes</strong>(<a href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSContext</a> *cx, <a href="/en/SpiderMonkey/JSAPI_Reference/JSObject" title="en/JSObject">JSObject</a> *obj,
    const char *name, <a href="/en/SpiderMonkey/JSAPI_Reference/jsint" title="en/jsint">uintN</a> *attrsp, <a href="/En/SpiderMonkey/JSAPI_Reference/JSBool" title="en/JSBool">JSBool</a> *foundp);

<a href="/En/SpiderMonkey/JSAPI_Reference/JSBool" title="en/JSBool">JSBool</a> <strong>JS_GetUCPropertyAttributes</strong>(<a href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSContext</a> *cx, <a href="/en/SpiderMonkey/JSAPI_Reference/JSObject" title="en/JSObject">JSObject</a> *obj,
    const <a href="/en/SpiderMonkey/JSAPI_Reference/jschar" title="en/jschar">jschar</a> *name, size_t namelen,
    <a href="/en/SpiderMonkey/JSAPI_Reference/jsint" title="en/jsint">uintN</a> *attrsp, <a href="/En/SpiderMonkey/JSAPI_Reference/JSBool" title="en/JSBool">JSBool</a> *foundp);
</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/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSContext</a> *</code></td> <td>The context in which to look up property attributes. {{ Jsapi-requires-request() }}</td> </tr> <tr> <td><code>obj</code></td> <td><code><a href="/en/SpiderMonkey/JSAPI_Reference/JSObject" title="en/JSObject">JSObject</a> *</code></td> <td>The object that has the property to be queried.</td> </tr> <tr> <td><code>name</code></td> <td><code>const char *</code> <em>or</em> <code>const <a href="/en/SpiderMonkey/JSAPI_Reference/jschar" title="en/jschar">jschar</a> *</code></td> <td>Name of the property from which to retrieve attributes.</td> </tr> <tr> <td><code>namelen</code></td> <td><code>size_t</code></td> <td><em>(only in <code>JS_GetUCPropertyAttributes</code>)</em> The length of <code>name</code> in characters; or <code>(size_t) -1</code> to indicate that <code>name</code> is null-terminated.</td> </tr> <tr> <td><code>attrsp</code></td> <td><code><a href="/en/SpiderMonkey/JSAPI_Reference/jsint" title="en/jsint">uintN</a> *</code></td> <td>Out parameter. If the specified property is found on <code>obj</code>, <code>*attrsp</code> receives its attributes.</td> </tr> <tr> <td><code>foundp</code></td> <td><code><a href="/En/SpiderMonkey/JSAPI_Reference/JSBool" title="en/JSBool">JSBool</a> *</code></td> <td>Out parameter. If no error occurs, <code>*foundp</code> receives <code>JS_TRUE</code> if the specified property is found and <code>JS_FALSE</code> if it is not found. If an error occurs, the value left in <code>*foundp</code> is unspecified.</td> </tr> </tbody>
</table>
<h2 name="Description">Description</h2>
<p><strong><code>JS_GetPropertyAttributes</code></strong> retrieves the property attributes of the property with the given <code>name</code> on a given object, <code>obj</code>. <strong><code>JS_GetUCPropertyAttributes</code></strong> is the Unicode version of the function.</p>
<p>If an error occurs, the return value is <code>JS_FALSE</code>, and the values left in <code>*attrsp</code> and <code>*foundp</code> are unspecified.</p>
<p>If <code>obj</code> does not have the specified property, or if it inherits it from some other object (on its prototype chain, for example), then <code>*foundp</code> is set to <code>JS_FALSE</code>. The value left in <code>*attrsp</code> is unspecified. The return value is <code>JS_TRUE</code> (to indicate that no error occurred).</p>
<p>If the property exists and belongs to <code>obj</code>, then <code>*foundp</code> is set to <code>JS_TRUE</code>, <code>*attrsp</code> is set to the logical OR of zero or more property attribute flags (described below), and the function returns <code>JS_TRUE</code>.</p>
<h3 name="Property_attributes">Property attributes</h3>
<p>Any object property can have zero or more <em>property attributes</em> set. Some property attributes are defined in the ECMAScript standard, in {{ Es3_spec("8.6.1") }}. SpiderMonkey additionally defines several non-standard property attributes.</p>
<p>The JSAPI expresses property attributes as a value of type <code><a href="/en/SpiderMonkey/JSAPI_Reference/jsint" title="en/jsint">uintN</a></code>, the bitwise OR of zero or more of the <code>JSPROP</code> flags described below.</p>
<table class="fullwidth-table"> <tbody> <tr> <th>Flag</th> <th>Description</th> </tr> <tr> <td> <p><code><strong>JSPROP_ENUMERATE</strong></code></p> </td> <td> <p>The property is visible to JavaScript <code>for</code>…<code>in</code> and <code>for each</code>…<code>in</code> loops, as well as to <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_Enumerate" title="en/JS_Enumerate">JS_Enumerate</a></code>.</p> <p>This is the inverse of the ECMA standard DontEnum attribute.</p> <p>{{ LXRSearch("ident", "i", "JSPROP_ENUMERATE") }}</p> </td> </tr> <tr> <td> <p><code><strong>JSPROP_READONLY</strong></code></p> </td> <td> <p>The property's value cannot be set. In JavaScript 1.2 and lower, it is an error to attempt to assign a value to a read-only property. In JavaScript 1.3 and higher, as in ECMAScript, attempts to set a value on a read-only property are ignored.</p> <p>This is the ECMA standard ReadOnly attribute.</p> <p>{{ LXRSearch("ident", "i", "JSPROP_READONLY") }}</p> </td> </tr> <tr> <td> <p><code><strong>JSPROP_PERMANENT</strong></code></p> </td> <td> <p>The property cannot be deleted. In JavaScript 1.2 and lower, it is an error to attempt to delete a permanent property. In JavaScript 1.3 and higher, as in ECMAScript, such attempts are ignored.</p> <p>This is the ECMA standard DontDelete attribute.</p> <p>The JavaScript language does not provide any way for a script to delete a permanent property. C/C++ code can do this by making the property non-permanent, using <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_SetPropertyAttributes" title="en/JS_SetPropertyAttributes">JS_SetPropertyAttributes</a></code>, before deleting it.</p> <p>{{ LXRSearch("ident", "i", "JSPROP_PERMANENT") }}</p> </td> </tr> <tr> <td> <p><code><strong>JSPROP_GETTER</strong></code></p> </td> <td> <p>The property's getter is a JavaScript <code>Function</code>, not a C/C++ function. See <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_DefineProperty" title="en/JS_DefineProperty">JS_DefineProperty</a></code> and <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_GetPropertyAttrsGetterAndSetter" title="en/JS_GetPropertyAttrsGetterAndSetter">JS_GetPropertyAttrsGetterAndSetter</a></code> for details.</p> <p>{{ LXRSearch("ident", "i", "JSPROP_GETTER") }}</p> </td> </tr> <tr> <td> <p><code><strong>JSPROP_SETTER</strong></code></p> </td> <td> <p>The property's setter is a JavaScript <code>Function</code>, not a C/C++ function. See <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_DefineProperty" title="en/JS_DefineProperty">JS_DefineProperty</a></code> and <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_GetPropertyAttrsGetterAndSetter" title="en/JS_GetPropertyAttrsGetterAndSetter">JS_GetPropertyAttrsGetterAndSetter</a></code> for details.</p> <p>{{ LXRSearch("ident", "i", "JSPROP_SETTER") }}</p> </td> </tr> <tr> <td> <p><code><strong>JSPROP_SHARED</strong></code></p> </td> <td> <p>The property is shared. The JavaScript engine does not allocate memory for the property's <a href="/En/SpiderMonkey/JSAPI_Reference/Stored_value" title="en/JSAPI/Stored_value">stored value</a>. This attribute is appropriate for custom properties that are implemented as fields of a native C/C++ data structure or as C++ <code>Get</code>/<code>Set</code> method pairs. In such cases, the stored value slot is redundant at best and could entrain garbage.</p> <p>Implementation note: A property with both <code>JSPROP_SHARED</code> and <code>JSPROP_PERMANENT</code> triggers a SpiderMonkey optimization: the property is not physically copied to an object that inherits it, as it normally would be in certain cases. The optimization is almost completely transparent, but <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_AlreadyHasOwnProperty" title="en/JS_AlreadyHasOwnProperty">JS_AlreadyHasOwnProperty</a></code> can expose it.</p> <p>{{ LXRSearch("ident", "i", "JSPROP_SHARED") }}</p> </td> </tr> <tr> <td> <p><code><strong>JSPROP_INDEX</strong></code></p> </td> <td> <p>The property's id is represented internally as an integer, not a string.</p> <p>This flag has an additional special meaning when used with <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_DefineProperty" title="en/JS_DefineProperty">JS_DefineProperty</a></code>, <code><a href="/en/JS_FS" title="en/JS_FS">JS_FS</a></code>, and other APIs that define properties: it means that the <code>name</code> parameter is actually an integer unsafely cast to a pointer type, not a string.</p> <p>{{ LXRSearch("ident", "i", "JSPROP_INDEX") }}</p> </td> </tr> </tbody>
</table>
<p>An application can set property attributes when creating a property. See <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_DefineProperty" title="en/JS_DefineProperty">JS_DefineProperty</a></code>, <code><a href="/en/JS_FS" title="en/JS_FS">JS_FS</a></code>, and <code><a href="/en/JS_FN" title="en/JS_FN">JS_FN</a></code>. To modify the attributes of an existing property, use <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_SetPropertyAttributes" title="en/JS_SetPropertyAttributes">JS_SetPropertyAttributes</a></code>.</p>
<p>{{ LXRSearch("ident", "i", "JS_GetPropertyAttributes") }}<br>
{{ LXRSearch("ident", "i", "JS_GetUCPropertyAttributes") }}</p>
Revert to this revision