JS_NewStringCopyN

  • Revision slug: SpiderMonkey/JSAPI_Reference/JS_NewStringCopyN
  • Revision title: JS_NewStringCopyN
  • Revision id: 135640
  • Created:
  • Creator: Jorend
  • Is current revision? No
  • Comment Requires request (and other minor changes)

Revision Content

{{template.Jsapiref()}}

Allocates a new JS string.

Syntax

JSString * JS_NewStringCopyN(JSContext *cx, const char *s, size_t n);
Name Type Description
cx JSContext * Pointer to a JS context from which to derive runtime information. {{wiki.template('Jsapi-requires-request')}}
s const char * Pointer to the character array containing the text for the JS string to create.
n size_t Maximum number of characters to copy from s into the JS string.

Description

JS_NewStringCopyN allocates space for a JS string and its underlying storage, and copies as many characters from a C character array, s, as possible, up to n bytes, into the new JSString. If the number of bytes in s is greater than the number of characters specified in n, the new JS string contains a truncated version of the original string. If the number of characters in s is less than the number of bytes specified in n, the new JS string is padded with nulls to the specified length.

You can use JS_NewStringCopyN to copy binary data, which may contain ASCII 0 characters ('\0'). You can also use this function when you want to copy only a certain portion of a C string into a JS string.

If the allocation is successful, JS_NewStringCopyN returns a pointer to the JS string. Otherwise it returns NULL.

See Also

Groups Functions
Documents {{template.LXRSearch("ident", "i", "JS_NewStringCopyN", "LXR ID Search")}}
Entries

JS_CompareStrings, JS_ConvertValue, JS_GetEmptyStringValue, JS_GetStringBytes, JS_GetStringChars, JS_GetStringLength, JS_InternString, JS_InternUCString, JS_InternUCStringN, JS_NewArrayObject, JS_NewDouble, JS_NewFunction, JS_NewObject, JS_NewString, JS_NewStringCopyZ, JS_NewUCString, JS_NewUCStringCopyN, JS_NewUCStringCopyZ, JS_ValueToString, JS_malloc

Revision Source

<p> 
{{template.Jsapiref()}}
</p><p>Allocates a new JS string.
</p>
<h2 name="Syntax"> Syntax </h2>
<pre class="eval">JSString * <b>JS_NewStringCopyN</b>(JSContext *cx, const char *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>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>s</code></td>
<td><code>const char *</code></td>
<td>Pointer to the character array containing the text for the JS string to create.</td>
</tr>
<tr>
<td><code>n</code></td>
<td><code>size_t</code></td>
<td>Maximum number of characters to copy from s into the JS string.</td>
</tr>
</tbody></table>
<h2 name="Description"> Description </h2>
<p><code>JS_NewStringCopyN</code> allocates space for a JS string and its underlying storage, and copies as many characters from a C character array, <code>s</code>, as possible, up to <code>n</code> bytes, into the new <code>JSString</code>. If the number of bytes in <code>s</code> is greater than the number of characters specified in <code>n</code>, the new JS string contains a truncated version of the original string. If the number of characters in <code>s</code> is less than the number of bytes specified in <code>n</code>, the new JS string is padded with <code>null</code>s to the specified length.
</p><p>You can use <code>JS_NewStringCopyN</code> to copy binary data, which may contain ASCII <code>0</code> characters (<code>'\0'</code>). You can also use this function when you want to copy only a certain portion of a C string into a JS string.
</p><p>If the allocation is successful, <code>JS_NewStringCopyN</code> returns a pointer to the JS string. Otherwise it returns <code>NULL</code>.
</p>
<h2 name="See_Also"> See Also </h2>
<table class="fullwidth-table">
<tbody><tr>
<td>Groups</td>
<td><a href="en/JSAPI_Reference#Functions">Functions</a></td>
</tr>
<tr>
<td>Documents</td>
<td>{{template.LXRSearch("ident", "i", "JS_NewStringCopyN", "LXR ID Search")}}</td>
</tr>
<tr>
<td>Entries</td>
<td>
<p><a href="en/JS_CompareStrings">JS_CompareStrings</a>,
<a href="en/JS_ConvertValue">JS_ConvertValue</a>,
<a href="en/JS_GetEmptyStringValue">JS_GetEmptyStringValue</a>,
<a href="en/JS_GetStringBytes">JS_GetStringBytes</a>,
<a href="en/JS_GetStringChars">JS_GetStringChars</a>,
<a href="en/JS_GetStringLength">JS_GetStringLength</a>,
<a href="en/JS_InternString">JS_InternString</a>,
<a href="en/JS_InternUCString">JS_InternUCString</a>,
<a href="en/JS_InternUCStringN">JS_InternUCStringN</a>,
<a href="en/JS_NewArrayObject">JS_NewArrayObject</a>,
<a href="en/JS_NewDouble">JS_NewDouble</a>,
<a href="en/JS_NewFunction">JS_NewFunction</a>,
<a href="en/JS_NewObject">JS_NewObject</a>,
<a href="en/JS_NewString">JS_NewString</a>,
<a href="en/JS_NewStringCopyZ">JS_NewStringCopyZ</a>,
<a href="en/JS_NewUCString">JS_NewUCString</a>,
<a href="en/JS_NewUCStringCopyN">JS_NewUCStringCopyN</a>,
<a href="en/JS_NewUCStringCopyZ">JS_NewUCStringCopyZ</a>,
<a href="en/JS_ValueToString">JS_ValueToString</a>,
<a href="en/JS_malloc">JS_malloc</a>
</p>
</td>
</tr>
</tbody></table>
Revert to this revision