JS_NewObject

  • Revision slug: SpiderMonkey/JSAPI_Reference/JS_NewObject
  • Revision title: JS_NewObject
  • Revision id: 287466
  • Created:
  • Creator: Sheppy
  • Is current revision? No
  • Comment 32 words added, 3 words removed

Revision Content

Creates a new JavaScript object.

Syntax

JSObject * JS_NewObject(JSContext *cx, JSClass *clasp, JSObject *proto,
    JSObject *parent);

JSObject * JS_NewObjectWithGivenProto(JSContext *cx, JSClass *clasp, JSObject *proto,
    JSObject *parent);{{ Jsapi_minversion_inline(1.8) }}
Name Type Description
cx JSContext * The context in which to create the new object. {{ Jsapi-requires-request() }}
clasp JSClass * Pointer to the class to use for the new object. If this is NULL, an ordinary JavaScript Object is created.

The JSClass may be used to override low-level object behavior, including such details as the physical memory layout of the object and how property lookups are done.

{{ Jsapi_minversion_inline("1.8.1") }} clasp->flags must not have the JSCLASS_GLOBAL_FLAGS bits set (use JS_NewGlobalObject instead).

If clasp is non-null, the caller must ensure that the JSClass remains alive throughout the lifetime of the new object, including the garbage collection cycle that finally frees it. The usual way to do this is to make JSClasses global or static.
proto JSObject *

Pointer to the prototype object to use for the new object. The new object will inherit all of the prototype object's properties and methods, and the new object's __proto__ property will be a reference to the prototype object.

JS_NewObject: If this is NULL, a default prototype object is used.

JS_NewObjectWithGivenProto: If this is NULL, the new object has no prototype; its __proto__ property is undefined.

parent JSObject * Pointer to the parent of the new object. The new object's __parent__ property will be a reference to this object. If parent is NULL, a default parent object is used.

Description

JS_NewObject creates a new object based on a specified class, prototype, and parent object. cx is a pointer to a context associated with the runtime in which to establish the new object. clasp is a pointer to an existing class to use for internal methods, such as finalize. proto is an optional pointer to the prototype object with which to associate the new object.

If proto is NULL, the JavaScript engine selects a prototype object for you. In this case, JS_NewObject attempts to assign the new object the prototype object belonging to clasp, if one is defined there. Otherwise, it creates an empty object stub for the prototype.

parent is an optional pointer to an existing object to which to set the new object's parent object property. You can set parent to NULL if you do not want to set the __parent__ property. See JS_GetParent for details on what the parent property does.

On success, JS_NewObject returns a pointer to the new object. Otherwise it returns NULL.

{{ Jsapi_minversion_inline(1.8) }} JS_NewObjectWithGivenProto behaves exactly the same, except that if proto is NULL, it creates an object with no prototype.

If clasp has a constructor (JSClass.construct), use JS_ConstructObject instead to ensure that the constructor is called.

To create a new object as a property of an existing object, use JS_DefineObject, a convenience function that combines JS_NewObject and JS_DefineProperty.

Starting with Gecko 8.0 {{ geckoRelease("8.0") }}, you can create a new object in a specific compartment using the Components.utils.createInObject() method.

Choosing a default prototype

Like many JSAPI functions, JS_NewObject selects an appropriate prototype for the newly created object if you don't supply one yourself.  In each case, the choice is driven by the new object's class (here, clasp), its parent scope (here, parent), and perhaps the context (here, cx).  Roughly speaking, we use the parent or the context to find a global object, find the given class's constructor in that global object, and then use that constructor's prototype.

Here's how the process works in detail:

First, we must identify a global object.  If the parent is non-NULL, we assume it is part of a scope chain, walk to the end of that chain, and use the global object we find there.  If the parent is NULL, we use the global object at the end of the scope chain in which the context is currently executing. In other words, the context's current scope acts as a default parent.  If the context is not currently executing any code, we use JS_GetGlobalObject to find a global object associated with the context.

Next, we must find the given class's constructor in that global object. Normally we simply use the class's name as the name of the property of the global object to fetch. However, although JavaScript code can freely redefine constructors, the ECMAScript standard requires us in certain cases to use the original constructors' prototypes.  If the global object's class's flags include JSCLASS_GLOBAL_FLAGS, then the global object always retains the original constructors for each standard class; we use these original constructors when they are available.

Finally, we must find a prototype.  If the constructor has a prototype property, we use its value.  Otherwise, we use Object.prototype, looking up the constructor for Object as described above.

See Also

{{ LXRSearch("ident", "i", "JS_NewObject") }}
{{ LXRSearch("ident", "i", "JS_NewObjectWithGivenProto") }}

JS_NewGlobalObject, JS_NewArrayObject, JS_ValueToObject

{{ languages( { "ja": "ja/JS_NewObject" } ) }}

Revision Source

<p>Creates a new JavaScript object.</p>
<h2 id="Syntax" name="Syntax">Syntax</h2>
<pre class="eval"><a href="/en/SpiderMonkey/JSAPI_Reference/JSObject" title="en/JSObject">JSObject</a> * <strong>JS_NewObject</strong>(<a href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSContext</a> *cx, <a href="/en/SpiderMonkey/JSAPI_Reference/JSClass" title="en/JSClass">JSClass</a> *clasp, <a href="/en/SpiderMonkey/JSAPI_Reference/JSObject" title="en/JSObject">JSObject</a> *proto,
    <a href="/en/SpiderMonkey/JSAPI_Reference/JSObject" title="en/JSObject">JSObject</a> *parent);

<a href="/en/SpiderMonkey/JSAPI_Reference/JSObject" title="en/JSObject">JSObject</a> * <strong>JS_NewObjectWithGivenProto</strong>(<a href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSContext</a> *cx, <a href="/en/SpiderMonkey/JSAPI_Reference/JSClass" title="en/JSClass">JSClass</a> *clasp, <a href="/en/SpiderMonkey/JSAPI_Reference/JSObject" title="en/JSObject">JSObject</a> *proto,
    <a href="/en/SpiderMonkey/JSAPI_Reference/JSObject" title="en/JSObject">JSObject</a> *parent);{{ Jsapi_minversion_inline(1.8) }}
</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 create the new object. {{ Jsapi-requires-request() }}</td> </tr> <tr> <td><code>clasp</code></td> <td><code><a href="/en/SpiderMonkey/JSAPI_Reference/JSClass" title="en/JSClass">JSClass</a> *</code></td> <td>Pointer to the class to use for the new object. If this is <code>NULL</code>, an ordinary JavaScript <code>Object</code> is created.<br> <br> <p>The <code><a href="/en/SpiderMonkey/JSAPI_Reference/JSClass" title="en/JSClass">JSClass</a></code> may be used to override low-level object behavior, including such details as the physical memory layout of the object and how property lookups are done.</p> <p>{{ Jsapi_minversion_inline("1.8.1") }} <code>clasp-&gt;flags</code> must not have the <a href="/en/SpiderMonkey/JSAPI_Reference/JS_SetGlobalObject" title="en/SpiderMonkey/JSAPI Reference/JS SetGlobalObject"><code>JSCLASS_GLOBAL_FLAGS</code></a> bits set (use <a href="/en/SpiderMonkey/JSAPI_Reference/JS_NewGlobalObject" title="en/SpiderMonkey/JSAPI Reference/JS NewGlobalObject"><code>JS_NewGlobalObject</code></a> instead).</p> If <code>clasp</code> is non-null, the caller must ensure that the <code>JSClass</code> remains alive throughout the lifetime of the new object, including the garbage collection cycle that finally frees it. The usual way to do this is to make <code>JSClass</code>es global or <code>static</code>.</td> </tr> <tr> <td><code>proto</code></td> <td><code><a href="/en/SpiderMonkey/JSAPI_Reference/JSObject" title="en/JSObject">JSObject</a> *</code></td> <td> <p>Pointer to the prototype object to use for the new object. The new object will inherit all of the prototype object's properties and methods, and the new object's <code>__proto__</code> property will be a reference to the prototype object.</p> <p><code>JS_NewObject</code>: If this is <code>NULL</code>, a default prototype object is used.</p> <p><code>JS_NewObjectWithGivenProto</code>: If this is <code>NULL</code>, the new object has no prototype; its <code>__proto__</code> property is <code>undefined</code>.</p> </td> </tr> <tr> <td><code>parent</code></td> <td><code><a href="/en/SpiderMonkey/JSAPI_Reference/JSObject" title="en/JSObject">JSObject</a> *</code></td> <td>Pointer to the parent of the new object. The new object's <code>__parent__</code> property will be a reference to this object. If <code>parent</code> is <code>NULL</code>, a default parent object is used.</td> </tr> </tbody>
</table>
<h2 id="Description" name="Description">Description</h2>
<p><strong><code>JS_NewObject</code></strong> creates a new object based on a specified class, prototype, and parent object. <code>cx</code> is a pointer to a context associated with the runtime in which to establish the new object. <code>clasp</code> is a pointer to an existing class to use for internal methods, such as <code>finalize</code>. <code>proto</code> is an optional pointer to the prototype object with which to associate the new object.</p>
<p>If <code>proto</code> is <code>NULL</code>, the JavaScript engine selects a prototype object for you. In this case, <code>JS_NewObject</code> attempts to assign the new object the prototype object belonging to <code>clasp</code>, if one is defined there. Otherwise, it creates an empty object stub for the prototype.</p>
<p><code>parent</code> is an optional pointer to an existing object to which to set the new object's parent object property. You can set parent to <code>NULL</code> if you do not want to set the <code>__parent__</code> property. See <a class="internal" href="/en/SpiderMonkey/JSAPI_Reference/JS_GetParent" title="En/SpiderMonkey/JSAPI Reference/JS GetParent">JS_GetParent</a> for details on what the parent property does.</p>
<p>On success, <code>JS_NewObject</code> returns a pointer to the new object. Otherwise it returns <code>NULL</code>.</p>
<p>{{ Jsapi_minversion_inline(1.8) }} <strong><code>JS_NewObjectWithGivenProto</code></strong> behaves exactly the same, except that if <code>proto</code> is <code>NULL</code>, it creates an object with no prototype.</p>
<p>If <code>clasp</code> has a constructor (<code><a href="/en/JSClass.construct" title="en/JSClass.construct">JSClass.construct</a></code>), use <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_ConstructObject" title="en/JS_ConstructObject">JS_ConstructObject</a></code> instead to ensure that the constructor is called.</p>
<p>To create a new object as a property of an existing object, use <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_DefineObject" title="en/JS_DefineObject">JS_DefineObject</a></code>, a convenience function that combines <code>JS_NewObject</code> and <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_DefineProperty" title="en/JS_DefineProperty">JS_DefineProperty</a></code>.</p>
<p>Starting with Gecko 8.0 {{ geckoRelease("8.0") }}, you can create a new object in a specific compartment using the <a href="/en/Components.utils.createInObject" title="en/Components.utils.createInObject"><code>Components.utils.createInObject()</code></a> method.</p>
<h2 id="See_Also" name="See_Also">Choosing a default prototype</h2>
<p>Like many JSAPI functions, JS_NewObject selects an appropriate prototype for the newly created object if you don't supply one yourself.  In each case, the choice is driven by the new object's class (here, <code>clasp</code>), its parent scope (here, <code>parent</code>), and perhaps the context (here, <code>cx</code>).  Roughly speaking, we use the parent or the context to find a global object, find the given class's constructor in that global object, and then use that constructor's prototype.</p>
<p>Here's how the process works in detail:</p>
<p>First, we must identify a global object.  If the parent is non-NULL, we assume it is part of a scope chain, walk to the end of that chain, and use the global object we find there.  If the parent is NULL, we use the global object at the end of the scope chain in which the context is currently executing. In other words, the context's current scope acts as a default parent.  If the context is not currently executing any code, we use <code>JS_GetGlobalObject</code> to find a global object associated with the context.</p>
<p>Next, we must find the given class's constructor in that global object. Normally we simply use the class's name as the name of the property of the global object to fetch. However, although JavaScript code can freely redefine constructors, the ECMAScript standard requires us in certain cases to use the original constructors' prototypes.  If the global object's class's flags include JSCLASS_GLOBAL_FLAGS, then the global object always retains the original constructors for each standard class; we use these original constructors when they are available.</p>
<p>Finally, we must find a prototype.  If the constructor has a <code>prototype</code> property, we use its value.  Otherwise, we use <code>Object.prototype</code>, looking up the constructor for <code>Object</code> as described above.</p>
<h2 id="See_Also" name="See_Also">See Also</h2>
<p>{{ LXRSearch("ident", "i", "JS_NewObject") }}<br>
{{ LXRSearch("ident", "i", "JS_NewObjectWithGivenProto") }}</p>
<p><a href="/en/SpiderMonkey/JSAPI_Reference/JS_NewGlobalObject" title="en/JS_NewArrayObject">JS_NewGlobalObject</a>, <a href="/en/SpiderMonkey/JSAPI_Reference/JS_NewArrayObject" title="en/JS_NewArrayObject">JS_NewArrayObject</a>, <a href="/en/SpiderMonkey/JSAPI_Reference/JS_ValueToObject" title="en/JS_ValueToObject">JS_ValueToObject</a></p>
<p>{{ languages( { "ja": "ja/JS_NewObject" } ) }}</p>
Revert to this revision