JS_NewExternalString

  • Revision slug: SpiderMonkey/JSAPI_Reference/JS_NewExternalString
  • Revision title: JS_NewExternalString
  • Revision id: 88539
  • Created:
  • Creator: Sheppy
  • Is current revision? No
  • Comment 1 words added, 1 words removed

Revision Content

Creates a new JSString whose characters are stored in external memory, i.e., memory allocated by the application, not the JavaScript engine. Since the program allocated the memory, it will need to free it; this happens in an external string finalizer indicated by the type parameter.

JS_NewExternalStringWithClosure() works similarly, except it accepts an additional parameter, closure, which is saved in the string's internal data structure. It can be retrieved later by calling JS_GetExternalStringClosure().

Note: JS_NewExternalStringWithClosure() was added in JavaScript 1.8.7, which is used in Gecko 6.0 {{ geckoRelease("6.0") }}.

To determine if a string was created as an external string, you can call JS_IsExternalString().

Syntax

JSString * JS_NewExternalString(JSContext *cx, jschar *chars, size_t length, intN type);
JSString * JS_NewExternalStringWithClosure(JSContext *cx, jschar *chars, size_t length, intN type, void *closure);
Name Type Description
cx JSContext * The context in which to create the new string. {{ Jsapi-requires-request() }}
chars const jschar * Pointer to the first element of an array of jschars. This array is used as the character buffer of the JSString to be created. The array must be populated with the desired character data before JS_NewExternalString is called, and the array must remain in memory, with its contents unchanged, for as long as the JavaScript engine needs to hold on to it. (Ultimately, the string will be garbage collected, and the JavaScript engine will call the string finalizer callback, allowing the application to free the array.) The array does not need to be zero-terminated.
length size_t
The number of characters in the array chars.
type intN Indicates which string finalizer callback the JavaScript engine should use (later) to free the string buffer chars. This must be an id number previously returned by a successful call to JS_AddExternalStringFinalizer.
closure
void *
Arbitrary, application-defined data to include in the string object after it's created. If you use this as a pointer, you should clean it up in the external string finalizer that was previously set up using JS_AddExternalStringFinalizer().

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

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

Revision Source

<p>Creates a new <code><a href="/en/SpiderMonkey/JSAPI_Reference/JSString" title="en/JSString">JSString</a></code> whose characters are stored in external memory, i.e., memory allocated by the application, not the JavaScript engine. Since the program allocated the memory, it will need to free it; this happens in an <em>external string finalizer</em> indicated by the <code>type</code> parameter.</p>
<p><code>JS_NewExternalStringWithClosure()</code> works similarly, except it accepts an additional parameter, closure, which is saved in the string's internal data structure. It can be retrieved later by calling <a href="/en/SpiderMonkey/JSAPI_Reference/JS_GetExternalStringClosure" title="en/SpiderMonkey/JSAPI Reference/JS NewExternalString/JS GetExternalStringClosure"><code>JS_GetExternalStringClosure()</code></a>.</p>
<div class="note"><strong>Note:</strong> <code>JS_NewExternalStringWithClosure()</code> was added in JavaScript 1.8.7, which is used in Gecko 6.0 {{ geckoRelease("6.0") }}.</div>
<p>To determine if a string was created as an external string, you can call <a href="/en/SpiderMonkey/JSAPI_Reference/JS_IsExternalString" title="en/SpiderMonkey/JSAPI Reference/JS NewExternalString/JS IsExternalString"><code>JS_IsExternalString()</code></a>.</p>
<h2 name="Syntax">Syntax</h2>
<pre class="eval"><a href="/en/SpiderMonkey/JSAPI_Reference/JSString" title="en/JSString">JSString</a> * <strong>JS_NewExternalString</strong>(<a href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSContext</a> *cx, <a href="/en/SpiderMonkey/JSAPI_Reference/jschar" title="en/jschar">jschar</a> *chars, size_t length, <a href="/en/SpiderMonkey/JSAPI_Reference/jsint" title="en/jsint">intN</a> type);
<a href="/en/SpiderMonkey/JSAPI_Reference/JSString" title="en/JSString">JSString</a> * <strong>JS_NewExternalStringWithClosure</strong>(<a href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSContext</a> *cx, <a href="/en/SpiderMonkey/JSAPI_Reference/jschar" title="en/jschar">jschar</a> *chars, size_t length, <a href="/en/SpiderMonkey/JSAPI_Reference/jsint" title="en/jsint">intN</a> type, void *closure);</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 string. {{ Jsapi-requires-request() }}</td> </tr> <tr> <td><code>chars</code></td> <td><code>const <a href="/en/SpiderMonkey/JSAPI_Reference/jschar" title="en/jschar">jschar</a> *</code></td> <td>Pointer to the first element of an array of <code>jschar</code>s. This array is used as the character buffer of the <code>JSString</code> to be created. The array must be populated with the desired character data before <code>JS_NewExternalString</code> is called, and the array must remain in memory, with its contents unchanged, for as long as the JavaScript engine needs to hold on to it. (Ultimately, the string will be garbage collected, and the JavaScript engine will call the string finalizer callback, allowing the application to free the array.) The array does not need to be zero-terminated.</td> </tr> <tr> <td><code>length</code></td> <td><code>size_t<br> </code></td> <td>The number of characters in the array <code>chars</code>.</td> </tr> <tr> <td><code>type</code></td> <td><code><a href="/en/SpiderMonkey/JSAPI_Reference/jsint" title="en/jsint">intN</a></code></td> <td>Indicates which string finalizer callback the JavaScript engine should use (later) to free the string buffer <code>chars</code>. This must be an id number previously returned by a successful call to <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_AddExternalStringFinalizer" title="en/JS_AddExternalStringFinalizer">JS_AddExternalStringFinalizer</a></code>.</td> </tr> <tr> <td><code>closure<br> </code></td> <td><code>void *<br> </code></td> <td>Arbitrary, application-defined data to include in the string object after it's created. If you use this as a pointer, you should clean it up in the external string finalizer that was previously set up using <a href="/en/SpiderMonkey/JSAPI_Reference/JS_AddExternalStringFinalizer" title="en/SpiderMonkey/JSAPI Reference/JS AddExternalStringFinalizer"><code>JS_AddExternalStringFinalizer()</code></a>.</td> </tr> </tbody>
</table>
<p>{{ LXRSearch("ident", "i", "JS_NewExternalString") }}</p>
<p>{{ LXRSearch("ident", "i", "JS_NewExternalStringWithClosure") }}</p>
Revert to this revision