JS_NewStringCopyN

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

Revision Content

{{ Jsapi_ref_header("JS_NewStringCopyN") }}

Create a new JS string.

Syntax

JSString * JS_NewStringCopyN(JSContext *cx, const char *s, size_t n);

JSString * JS_NewUCStringCopyN(JSContext *cx, const jschar *s, size_t n);
Name Type Description
cx JSContext * Pointer to a JS context from which to derive runtime information. {{ Jsapi-requires-request() }}
s const char * or const jschar * Pointer to the array of characters containing the text for the JS string to create.
n size_t Number of characters to copy from s into the new string.

Description

JS_NewStringCopyN allocates space for a JavaScript string and its underlying storage, and copies n characters from a C character array, s, into the new JSString. JS_NewUCStringCopyN is the Unicode version of the function. The two functions differ only in the type of the character array s; both functions create ordinary JavaScript strings, and all JavaScript strings are made up of 16-bit characters.

If the array s contains more than n characters, the new string contains a truncated version of the original string. The string may contain null characters ('\0'). They are copied into the new string like any other character.

You can use JS_NewStringCopyN to copy binary data or to copy only a certain portion of a C string into a JavaScript string.

On success, JS_NewStringCopyN and JS_NewUCStringCopyN return a pointer to the new JS string. Otherwise they return NULL.

See Also

{{ LXRSearch("ident", "i", "JS_NewStringCopyN") }} {{ LXRSearch("ident", "i", "JS_NewUCStringCopyN") }}

JS_CompareStrings, JS_ConvertValue, JS_GetEmptyStringValue, JS_GetStringBytes, JS_GetStringChars, JS_GetStringLength, JS_InternString, JS_InternUCString, JS_InternUCStringN, JS_NewString, JS_NewStringCopyZ, JS_NewUCString, JS_NewUCStringCopyZ, JS_ValueToString, JS_malloc

Revision Source

<p>{{ Jsapi_ref_header("JS_NewStringCopyN") }}
</p><p>Create a new JS string.
</p>
<h2 name="Syntax"> Syntax </h2>
<pre class="eval"><a href="/en/JSString" title="en/JSString">JSString</a> * <strong>JS_NewStringCopyN</strong>(<a href="/en/JSRuntime" title="en/JSRuntime">JSContext</a> *cx, const char *s, size_t n);

<a href="/en/JSString" title="en/JSString">JSString</a> * <strong>JS_NewUCStringCopyN</strong>(<a href="/en/JSRuntime" title="en/JSRuntime">JSContext</a> *cx, const <a href="/en/jschar" title="en/jschar">jschar</a> *s, size_t n);
</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/JSRuntime" title="en/JSRuntime">JSContext</a> *</code></td>
<td>Pointer to a JS context from which to derive runtime information.
{{ Jsapi-requires-request() }}</td>
</tr>
<tr>
<td><code>s</code></td>
<td><code>const char *</code> <em>or</em> <code>const <a href="/en/jschar" title="en/jschar">jschar</a> *</code></td>
<td>Pointer to the array of characters containing the text for the JS string to create.</td>
</tr>
<tr>
<td><code>n</code></td>
<td><code>size_t</code></td>
<td>Number of characters to copy from <code>s</code> into the new string.</td>
</tr>
</tbody></table>
<h2 name="Description"> Description </h2>
<p><code>JS_NewStringCopyN</code> allocates space for a JavaScript string and its underlying storage, and copies <code>n</code> characters from a C character array, <code>s</code>, into the new <code>JSString</code>. <code>JS_NewUCStringCopyN</code> is the Unicode version of the function. The two functions differ only in the type of the character array <code>s</code>; both functions create ordinary JavaScript strings, and all JavaScript strings are made up of 16-bit characters.
</p><p>If the array <code>s</code> contains more than <code>n</code> characters, the new string contains a truncated version of the original string. The string may contain null characters (<code>'\0'</code>). They are copied into the new string like any other character.
</p><p>You can use <code>JS_NewStringCopyN</code> to copy binary data or to copy only a certain portion of a C string into a JavaScript string.
</p><p>On success, <code>JS_NewStringCopyN</code> and <code>JS_NewUCStringCopyN</code> return a pointer to the new JS string. Otherwise they return <code>NULL</code>.
</p>
<h2 name="See_Also"> See Also </h2>
<p>{{ LXRSearch("ident", "i", "JS_NewStringCopyN") }}
{{ LXRSearch("ident", "i", "JS_NewUCStringCopyN") }}
</p><p><a href="/en/JS_CompareStrings" title="en/JS_CompareStrings">JS_CompareStrings</a>,
<a href="/en/JS_ConvertValue" title="en/JS_ConvertValue">JS_ConvertValue</a>,
<a href="/en/JS_GetEmptyStringValue" title="en/JS_GetEmptyStringValue">JS_GetEmptyStringValue</a>,
<a href="/en/JS_GetStringBytes" title="en/JS_GetStringBytes">JS_GetStringBytes</a>,
<a href="/en/JS_GetStringChars" title="en/JS_GetStringChars">JS_GetStringChars</a>,
<a href="/en/JS_GetStringLength" title="en/JS_GetStringLength">JS_GetStringLength</a>,
<a href="/en/JS_InternString" title="en/JS_InternString">JS_InternString</a>,
<a href="/en/JS_InternString" title="en/JS_InternString">JS_InternUCString</a>,
<a href="/en/JS_InternString" title="en/JS_InternString">JS_InternUCStringN</a>,
<a href="/en/JS_NewString" title="en/JS_NewString">JS_NewString</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_NewStringCopyZ" title="en/JS_NewStringCopyZ">JS_NewUCStringCopyZ</a>,
<a href="/en/JS_ValueToString" title="en/JS_ValueToString">JS_ValueToString</a>,
<a href="/en/JS_malloc" title="en/JS_malloc">JS_malloc</a>
</p>
Revert to this revision