JS_InternString

  • Revision slug: SpiderMonkey/JSAPI_Reference/JS_InternString
  • Revision title: JS_InternString
  • Revision id: 120192
  • Created:
  • Creator: Jorend
  • Is current revision? Yes
  • Comment no wording changes

Revision Content

Get an interned string—a JSString that is protected from GC and automatically shared with other code that needs a JSString with the same value.

Syntax

JSString * JS_InternString(JSContext *cx, const char *s);

JSString * JS_InternUCString(JSContext *cx, const jschar *s);

JSString * JS_InternUCStringN(JSContext *cx, const jschar *s, size_t length);

 

Name Type Description
cx JSContext * A context. {{ Jsapi-requires-request() }}
s const char * or const jschar * Pointer to a character array containing the data for the string. In JS_InternString and JS_InternUCString, the string must be null-terminated.
length size_t (only in JS_InternUCStringN) The length of s in characters.

Description

JS_InternString returns an interned JavaScript string with a specified value, s. JS_InternUCString and JS_InternUCStringN are the Unicode versions of the function.

Each JSRuntime keeps a table of all existing interned strings. If an interned string already exists with the desired value, these functions return the existing string. Otherwise a new string is created and added to the table. Strings created with these functions are protected from garbage collection for the lifetime of the JSRuntime.

On success, these functions return a pointer to the interned string. Otherwise they report an error and return NULL.

See Also

{{ LXRSearch("ident", "i", "JS_InternString") }}
{{ LXRSearch("ident", "i", "JS_InternUCString") }}
{{ LXRSearch("ident", "i", "JS_InternUCStringN") }}

JS_GetEmptyStringValue, JS_NewString, JS_NewStringCopyN, JS_NewStringCopyZ, JS_NewUCString, JS_NewUCStringCopyN, JS_NewUCStringCopyZ, JS_ValueToString

Revision Source

<p>Get an interned string—a <code><a href="/en/SpiderMonkey/JSAPI_Reference/JSString" title="en/JSString">JSString</a></code> that is protected from GC and automatically shared with other code that needs a <code>JSString</code> with the same value.</p>
<h2 id="Syntax" name="Syntax">Syntax</h2>
<pre class="eval"><a href="/en/SpiderMonkey/JSAPI_Reference/JSString" title="en/JSString">JSString</a> * <strong>JS_InternString</strong>(<a href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSContext</a> *cx, const char *s);

<a href="/en/SpiderMonkey/JSAPI_Reference/JSString" title="en/JSString">JSString</a> * <strong>JS_InternUCString</strong>(<a href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSContext</a> *cx, const <a href="/en/SpiderMonkey/JSAPI_Reference/jschar" title="en/jschar">jschar</a> *s);

<a href="/en/SpiderMonkey/JSAPI_Reference/JSString" title="en/JSString">JSString</a> * <strong>JS_InternUCStringN</strong>(<a href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSContext</a> *cx, const <a href="/en/SpiderMonkey/JSAPI_Reference/jschar" title="en/jschar">jschar</a> *s, size_t length);
</pre>
<p> </p>
<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>A context. {{ Jsapi-requires-request() }}</td> </tr> <tr> <td><code>s</code></td> <td><code>const char *</code> <em>or</em> <code>const jschar *</code></td> <td>Pointer to a character array containing the data for the string. In <code>JS_InternString</code> and <code>JS_InternUCString</code>, the string must be null-terminated.</td> </tr> <tr> <td><code>length</code></td> <td><code>size_t</code></td> <td><em>(only in <code>JS_InternUCStringN</code>)</em> The length of <code>s</code> in characters.</td> </tr> </tbody>
</table>
<h2 id="Description" name="Description">Description</h2>
<p><code>JS_InternString</code> returns an interned JavaScript string with a specified value, <code>s</code>. <code>JS_InternUCString</code> and <code>JS_InternUCStringN</code> are the Unicode versions of the function.</p>
<p>Each <code>JSRuntime</code> keeps a table of all existing interned strings. If an interned string already exists with the desired value, these functions return the existing string. Otherwise a new string is created and added to the table. Strings created with these functions are protected from garbage collection for the lifetime of the <code>JSRuntime</code>.</p>
<p>On success, these functions return a pointer to the interned string. Otherwise they report an error and return <code>NULL</code>.</p><h2 id="See_Also" name="See_Also">See Also</h2>
<p>{{ LXRSearch("ident", "i", "JS_InternString") }}<br>
{{ LXRSearch("ident", "i", "JS_InternUCString") }}<br>
{{ LXRSearch("ident", "i", "JS_InternUCStringN") }}</p>
<p><a href="/en/SpiderMonkey/JSAPI_Reference/JS_GetEmptyStringValue" title="en/JS_GetEmptyStringValue">JS_GetEmptyStringValue</a>, <a href="/en/SpiderMonkey/JSAPI_Reference/JS_NewString" title="en/JS_NewString">JS_NewString</a>, <a href="/en/SpiderMonkey/JSAPI_Reference/JS_NewStringCopyN" title="en/JS_NewStringCopyN">JS_NewStringCopyN</a>, <a href="/en/SpiderMonkey/JSAPI_Reference/JS_NewStringCopyZ" title="en/JS_NewStringCopyZ">JS_NewStringCopyZ</a>, <a href="/en/SpiderMonkey/JSAPI_Reference/JS_NewString" title="en/JS_NewString">JS_NewUCString</a>, <a href="/en/SpiderMonkey/JSAPI_Reference/JS_NewStringCopyN" title="en/JS_NewStringCopyN">JS_NewUCStringCopyN</a>, <a href="/en/SpiderMonkey/JSAPI_Reference/JS_NewStringCopyZ" title="en/JS_NewStringCopyZ">JS_NewUCStringCopyZ</a>, <a href="/en/SpiderMonkey/JSAPI_Reference/JS_ValueToString" title="en/JS_ValueToString">JS_ValueToString</a></p>
Revert to this revision