JS_GetStringBytes

  • Revision slug: SpiderMonkey/JSAPI_Reference/JS_GetStringBytes
  • Revision title: JS_GetStringBytes
  • Revision id: 73744
  • Created:
  • Creator: MarkGiffin
  • Is current revision? No
  • Comment 1 words added, 4 words removed

Revision Content

Convert a JavaScript string to a C string.

Syntax

char * JS_GetStringBytes(JSString *str); {{ obsolete_inline() }}

const char * JS_GetStringBytesZ(JSContext *cx, JSString *str);{{ jsapi_minversion_inline("1.8.2") }} {{ obsolete_inline() }}

char * JS_EncodeString(JSContext *cx, JSString *str);{{ jsapi_minversion_inline("1.8") }}

size_t JS_GetStringEncodingLength(JSContext *cx, JSString *str); {{ jsapi_minversion_inline("1.8.5") }} 

size_t JS_EncodeStringToBuffer(JSString *str, char *buffer, size_t length); {{ jsapi_minversion_inline("1.8.5") }}
Name Type Description
cx JSContext * (JS_GetStringBytesZ and JS_EncodeString only) A context.
str JSString * String to retrieve bytes from.
buffer char * (JS_EncodeStringToBuffer only) A character buffer to receive the string in UTF-8 format.
length
size_t
(JS_EncodeStringToBuffer only) The size of the buffer in bytes.

Description

JS_GetStringBytes, JS_GetStringBytesZ, and JS_EncodeString convert the specified JavaScript string, str, to a C string (an array of 8-bit chars). If JS_CStringsAreUTF8 is true, then the returned string is UTF-8, and the conversion is lossless. Otherwise the high byte is simply dropped from each jschar. On success, the return value is a pointer to the char array, which is null-terminated. On failure, JS_GetStringBytes returns a pointer to a null-terminated empty string; JS_GetStringBytesZ and JS_EncodeString return NULL.

Note: JS_GetStringBytes() and JS_GetStringBytesZ() have both been removed as of JavaScript 1.8.5 (Firefox 4). Instead, you should use JS_EncodeString(), JS_GetStringEncodingLength(), and JS_EncodeStringToBuffer().

The array returned by JS_GetStringBytes or JS_GetStringBytesZ is automatically freed when str is finalized by the JavaScript garbage collection mechanism. The application must not modify the contents of the array.

The array returned by JS_EncodeString on success is allocated as though by a call to JS_malloc. The caller may modify it and is responsible for freeing it.

Note that for non-ASCII strings, if JS_CStringsAreUTF8 is false, these functions can return a corrupted copy of the contents of the string. Use JS_GetStringChars to access the 16-bit characters of a JavaScript string without conversions or copying.

JS_GetStringEncodingLength() returns the length of the specified string in bytes, regardless of its encoding. You can use this value to create a buffer to encode the string into using the JS_EncodeStringToBuffer() function, which fills the specified buffer with up to length bytes of the string in UTF-8 format. It returns the length of the whole string encoding or -1 if the string can't be encoded as bytes. If the returned value is greater than the length you specified, the string was truncated.

See Also

{{ LXRSearch("ident", "i", "JS_GetStringBytes") }}
{{ LXRSearch("ident", "i", "JS_GetStringBytesZ") }}
{{ LXRSearch("ident", "i", "JS_EncodeString") }}

JS_CompareStrings, JS_GetStringLength, JS_ValueToString

Revision Source

<p>Convert a JavaScript string to a C string.</p>
<h2 id="Syntax" name="Syntax">Syntax</h2>
<pre class="eval">char * <strong>JS_GetStringBytes</strong>(<a href="/en/SpiderMonkey/JSAPI_Reference/JSString" title="en/JSString">JSString</a> *str); {{ obsolete_inline() }}

const char * <strong>JS_GetStringBytesZ</strong>(<a class="internal" href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSContext</a> *cx, <a href="/en/SpiderMonkey/JSAPI_Reference/JSString" title="en/JSString">JSString</a> *str);{{ jsapi_minversion_inline("1.8.2") }} {{ obsolete_inline() }}

char * <strong>JS_EncodeString</strong>(<a class="internal" href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSContext</a> *cx, <a href="/en/SpiderMonkey/JSAPI_Reference/JSString" title="en/JSString">JSString</a> *str);{{ jsapi_minversion_inline("1.8") }}

size_t <strong>JS_GetStringEncodingLength</strong>(<a class="internal" href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSContext</a> *cx, <a href="/en/SpiderMonkey/JSAPI_Reference/JSString" title="en/JSString">JSString</a> *str); {{ jsapi_minversion_inline("1.8.5") }} 

size_t <strong>JS_EncodeStringToBuffer</strong>(<a href="/en/SpiderMonkey/JSAPI_Reference/JSString" title="en/JSString">JSString</a> *str, char *buffer, size_t length); {{ jsapi_minversion_inline("1.8.5") }}
</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 class="internal" href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSContext</a> *</code></td> <td>(<em><code>JS_GetStringBytesZ</code> </em>and<em> <code>JS_EncodeString</code> </em>only) A context.</td> </tr> <tr> <td><code>str</code></td> <td><code><a href="/en/SpiderMonkey/JSAPI_Reference/JSString" title="en/JSString">JSString</a> *</code></td> <td>String to retrieve bytes from.</td> </tr> <tr> <td><code>buffer</code></td> <td><code>char *</code></td> <td>(<code>JS_<span id="1290541487742E" style="display: none;"> </span>EncodeStringToBuffer</code> only) A character buffer to receive the string in UTF-8 format.</td> </tr> <tr> <td><code>length<br> </code></td> <td><code>size_t<br> </code></td> <td>(<code>JS_<span id="1290541482673E" style="display: none;"> </span>EncodeStringToBuffer</code> only) The size of the buffer in bytes.</td> </tr> </tbody>
</table><h2 id="Description" name="Description">Description</h2>
<p><strong><code>JS_GetStringBytes</code></strong>, <strong><code>JS_GetStringBytesZ</code></strong>, and <strong><code>JS_EncodeString</code></strong> convert the specified JavaScript string, <code>str</code>, to a C string (an array of 8-bit <code>char</code>s). If <code><a class="internal" href="/En/SpiderMonkey/JSAPI_Reference/JS_CStringsAreUTF8" title="/en/JS CStringsAreUTF8">JS_CStringsAreUTF8</a></code> is true, then the returned string is UTF-8, and the conversion is lossless. Otherwise the high byte is simply dropped from each <code>jschar</code>. On success, the return value is a pointer to the char array, which is null-terminated. On failure, <code>JS_GetStringBytes</code> returns a pointer to a null-terminated empty string; <code>JS_GetStringBytesZ</code> and <code>JS_EncodeString</code> return <code>NULL</code>.</p>
<div class="note"><strong>Note:</strong> <code>JS_GetStringBytes()</code> and <code>JS_GetStringBytesZ()</code> have both been removed as of JavaScript 1.8.5 (Firefox 4). Instead, you should use <code>JS_EncodeString()</code>, <code>JS_GetStringEncodingLength()</code>, and <code>JS_EncodeStringToBuffer()</code>.</div>
<p>The array returned by <code>JS_GetStringBytes</code> or <code>JS_GetStringBytesZ</code> is automatically freed when <code>str</code> is finalized by the JavaScript garbage collection mechanism. The application must not modify the contents of the array.</p>
<p>The array returned by <code>JS_EncodeString</code> on success is allocated as though by a call to <a class="internal" href="/en/SpiderMonkey/JSAPI_Reference/JS_malloc" title="En/SpiderMonkey/JSAPI Reference/JS malloc"><code>JS_malloc</code></a>. The caller may modify it and is responsible for freeing it.</p>
<p>Note that for non-ASCII strings, if <code>JS_CStringsAreUTF8</code> is false, these functions can return a corrupted copy of the contents of the string. Use <a class="internal" href="/en/SpiderMonkey/JSAPI_Reference/JS_GetStringChars" title="En/SpiderMonkey/JSAPI Reference/JS GetStringChars"><code>JS_GetStringChars</code></a> to access the 16-bit characters of a JavaScript string without conversions or copying.</p>
<p><code>JS_GetStringEncodingLength()</code> returns the length of the specified string in bytes, regardless of its encoding. You can use this value to create a buffer to encode the string into using the <code>JS_EncodeStringToBuffer()</code> function, which fills the specified <code>buffer</code> with up to <code>length</code> bytes of the string in UTF-8 format. It returns the length of the whole string encoding or -1 if the string can't be encoded as bytes. If the returned value is greater than the <code>length</code> you specified, the string was truncated.</p>
<h2 id="See_Also" name="See_Also">See Also</h2>
<p>{{ LXRSearch("ident", "i", "JS_GetStringBytes") }}<br>
{{ LXRSearch("ident", "i", "JS_GetStringBytesZ") }}<br>
{{ LXRSearch("ident", "i", "JS_EncodeString") }}</p>
<p><a href="/en/SpiderMonkey/JSAPI_Reference/JS_CompareStrings" title="en/JS_CompareStrings">JS_CompareStrings</a>, <a href="/en/SpiderMonkey/JSAPI_Reference/JS_GetStringLength" title="en/JS_GetStringLength">JS_GetStringLength</a>, <a href="/en/SpiderMonkey/JSAPI_Reference/JS_ValueToString" title="en/JS_ValueToString">JS_ValueToString</a></p>
Revert to this revision