JS_InternString

  • Revision slug: SpiderMonkey/JSAPI_Reference/JS_InternString
  • Revision title: JS_InternString
  • Revision id: 120189
  • Created:
  • Creator: Jorend
  • Is current revision? No
  • Comment no wording changes; page display name changed to 'JS_InternString'

Revision Content

{{ Jsapi_ref_header("JS_InternString") }}

Get an interned string—a JSString that is 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. (Note that this table does not protect interned strings from garbage collection. If an interned string is collected, it is removed from the table.)

The JavaScript engine automatically interns many strings. For example, when a script is compiled, all string literals and property names in the script are interned.

On success, these functions return a pointer to the interned string. Otherwise they 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>{{ Jsapi_ref_header("JS_InternString") }}
</p><p>Get an interned string—a <code><a href="/en/JSString" title="en/JSString">JSString</a></code> that is automatically shared with other code that needs a <code>JSString</code> with the same value.
</p>
<h2 name="Syntax"> Syntax </h2>
<pre class="eval"><a href="/en/JSString" title="en/JSString">JSString</a> * <strong>JS_InternString</strong>(<a href="/en/JSRuntime" title="en/JSRuntime">JSContext</a> *cx, const char *s);

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

<a href="/en/JSString" title="en/JSString">JSString</a> * <strong>JS_InternUCStringN</strong>(<a href="/en/JSRuntime" title="en/JSRuntime">JSContext</a> *cx, const <a href="/en/jschar" title="en/jschar">jschar</a> *s, size_t length);
</pre>
<p><br>
</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/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 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. (Note that this table does not protect interned strings from garbage collection. If an interned string is collected, it is removed from the table.) </p><p>The JavaScript engine automatically interns many strings. For example, when a script is compiled, all string literals and property names in the script are interned.
</p><p>On success, these functions return a pointer to the interned string. Otherwise they return <code>NULL</code>.
</p>
<h2 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/JS_GetEmptyStringValue" title="en/JS_GetEmptyStringValue">JS_GetEmptyStringValue</a>,
<a href="/en/JS_NewString" title="en/JS_NewString">JS_NewString</a>,
<a href="/en/JS_NewStringCopyN" title="en/JS_NewStringCopyN">JS_NewStringCopyN</a>,
<a href="/en/JS_NewStringCopyZ" title="en/JS_NewStringCopyZ">JS_NewStringCopyZ</a>,
<a href="/en/JS_NewString" title="en/JS_NewString">JS_NewUCString</a>,
<a href="/en/JS_NewStringCopyN" title="en/JS_NewStringCopyN">JS_NewUCStringCopyN</a>,
<a href="/en/JS_NewStringCopyZ" title="en/JS_NewStringCopyZ">JS_NewUCStringCopyZ</a>,
<a href="/en/JS_ValueToString" title="en/JS_ValueToString">JS_ValueToString</a>
</p>
Revert to this revision