JS_NewExternalString

  • Revision slug: SpiderMonkey/JSAPI_Reference/JS_NewExternalString
  • Revision title: JS_NewExternalString
  • Revision id: 88530
  • Created:
  • Creator: Jorend
  • Is current revision? No
  • Comment finish args; also add jsapi-requires-request.

Revision Content

{{template.Jsapiref("JS_NewExternalString")}}

Creates a new JSString whose characters are stored in external memory, i.e., memory requiring special, type-specific finalization. The type code must be a nonnegative return value from an earlier call to JS_AddExternalStringFinalizer.

Syntax

JSString * JS_NewExternalString(JSContext *cx, jschar *chars, size_t length, intN type);
Name Type Description
cx JSContext * Pointer to a JS context from which to derive runtime information. {{wiki.template('Jsapi-requires-request')}}
chars jschar * Pointer to 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.

See Also

Revision Source

<p>{{template.Jsapiref("JS_NewExternalString")}}
</p><p>Creates a new <a href="en/JSString">JSString</a> whose characters are stored in external memory, i.e., memory requiring special, type-specific finalization.  The type code must be a nonnegative return value from an earlier call to <a href="en/JS_AddExternalStringFinalizer">JS_AddExternalStringFinalizer</a>.
</p>
<h2 name="Syntax"> Syntax </h2>
<pre class="eval">JSString * JS_NewExternalString(JSContext *cx, jschar *chars, size_t length, intN type);
</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>JSContext *</code></td>
<td>Pointer to a JS context from which to derive runtime information.
{{wiki.template('Jsapi-requires-request')}}</td>
</tr>
<tr>
<td><code>chars</code></td>
<td><code>jschar *</code></td>
<td>Pointer to 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</code></td>
<td>The number of characters in the array <code>chars</code>.</td>
</tr>
<tr>
<td><code>type</code></td>
<td><code>intN</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/JS_AddExternalStringFinalizer">JS_AddExternalStringFinalizer</a></code>.</td>
</tr>
</tbody></table>
<h2 name="See_Also"> See Also </h2>
<ul><li><a href="en/JS_AddExternalStringFinalizer">JS_AddExternalStringFinalizer</a>
</li><li><a href="en/JS_RemoveExternalStringFinalizer">JS_RemoveExternalStringFinalizer</a>
</li></ul>
Revert to this revision