JS_EncodeCharacters

  • Revision slug: SpiderMonkey/JSAPI_Reference/JS_EncodeCharacters
  • Revision title: JS_EncodeCharacters
  • Revision id: 139234
  • Created:
  • Creator: Jorend
  • Is current revision? No
  • Comment 4 words added

Revision Content

Convert a 16-bit string to an 8-bit string.

Syntax

JSBool JS_EncodeCharacters(JSContext *cx, const jschar *src, size_t srclen, char *dst, size_t *dstlen);
Name Type Description
cx JSContext * A context.
src const jschar * The pointer to 16-bit values of JSString. This can be obtained with JS_GetStringChars.
srclen size_t The length of the source string, in 16-bit values.
dst char * The pointer to an array of bytes to be filled with encoded characters; or NULL. The caller is responsible for allocating and freeing this buffer.
dstlenp size_t * In/out parameter. On entry, if dst is non-null, *dstlenp must be the length of the destination string in 16-bit units. On success, *dstlenp receives the length of the converted string, in bytes. On failure, *dstlenp receives the number of bytes written to dst before the error occurred.

     

Description

JS_EncodeCharacters copies the characters of a jschar array into a char array, converting the 16-bit values to 8-bit values. If SpiderMonkey was built with JS_C_STRINGS_ARE_UTF8 defined or JS_SetCStringsAreUTF8 was called, the string is converted to UTF-8.  Otherwise each character is simply truncated to 8 bits.

If UTF-8 is turned on, the length of the encoded string may vary.  To calculate the number of bytes needed, call JS_EncodeCharacters twice, like this:

    /* Determine how many bytes to allocate. */
    size_t dstlen = 0;
    if (!JS_EncodeCharacters(cx, src, srclen, NULL, &dstlen))
        return JS_FALSE;

    /* Allocate. */
    char *dst = (char *) JS_malloc(cx, dstlen);
    if (dst == NULL)
        return JS_FALSE;

    /* Convert characters to bytes. */
    JS_EncodeCharacters(cx, src, srclen, dst, &dstlen);

    /* Use the converted bytes for something. */
    ...

    /* Remember to free the bytes afterwards. */
    JS_free(cx, dst);
    return JS_TRUE;

On success, JS_EncodeCharacters sets *dstlenp to the real result length and returns JS_TRUE. Otherwise it reports an error and returns JS_FALSE.  This happens if the destination is too small for the resulting string or if the source buffer isn't proper UTF-16 because it contains unpaired surrogate values.

The user is responsible for allocating and freeing the memory of the destination string.

JS_EncodeCharacters never adds a trailing null character. To obtain a null-terminated string, allocate an extra byte for the null character and set it manually.

To convert bytes to jschars, the opposite conversion, use JS_DecodeBytes. To convert a JSString to a C char string, use JS_EncodeString or JS_GetStringBytes.

See Also

{{ LXRSearch("ident", "i", "JS_EncodeCharacters") }}

JS_CompareStrings, JS_GetStringBytes

Revision Source

 <p>Convert a 16-bit string to an 8-bit string.</p>
<h2 name="Syntax">Syntax</h2>
<pre class="eval"><a class="internal" href="/En/SpiderMonkey/JSAPI_Reference/JSBool" title="en/JSBool">JSBool</a> <strong>JS_EncodeCharacters</strong>(<a class="internal" href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSContext</a> *cx, const <a class="internal" href="/en/SpiderMonkey/JSAPI_Reference/jschar" title="en/jschar">jschar</a> *src, size_t srclen, char *dst, size_t *dstlen);</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/JSContext">JSContext</a> *</code></td> <td>A context.</td> </tr> <tr> <td><code>src</code></td> <td><code>const <a class="internal" href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="En/JSContext">jschar</a> *</code></td> <td>The pointer to 16-bit values of JSString. This can be obtained with <code><a href="/en/JS_GetStringChars" rel="internal">JS_GetStringChars</a></code>.</td> </tr> <tr> <td><code>srclen</code></td> <td><code>size_t</code></td> <td>The length of the source string, in 16-bit values.</td> </tr> <tr> <td><code>dst</code></td> <td><code>char *</code></td> <td>The pointer to an array of bytes to be filled with encoded characters; or <code>NULL</code>. The caller is responsible for allocating and freeing this buffer.</td> </tr> <tr> <td><code>dstlenp</code></td> <td><code>size_t *</code></td> <td>In/out parameter. On entry, if <code>dst</code> is non-null, <code>*dstlenp</code> must be the length of the destination string in 16-bit units. On success, <code>*dstlenp</code> receives the length of the converted string, in bytes. On failure, <code>*dstlenp</code> receives the number of bytes written to <code>dst</code> before the error occurred.</td> </tr> </tbody>
</table>
<p>     </p><h2 name="Description">Description</h2>
<p><code>JS_EncodeCharacters</code> copies the characters of a <code>jschar</code> array into a <code>char</code> array, converting the 16-bit values to 8-bit values. If SpiderMonkey was built with <code><a href="/JS_C_STRINGS_ARE_UTF8" title="JS_C_STRINGS_ARE_UTF8">JS_C_STRINGS_ARE_UTF8</a></code> defined or <a class="internal" href="/en/SpiderMonkey/JSAPI_Reference/JS_CStringsAreUTF8"><code>JS_SetCStringsAreUTF8</code></a> was called, the string is converted to UTF-8.  Otherwise each character is simply truncated to 8 bits.</p>
<p>If UTF-8 is turned on, the length of the encoded string may vary.  To calculate the number of bytes needed, call <code>JS_EncodeCharacters</code> twice, like this:</p>
<pre>    /* Determine how many bytes to allocate. */
    size_t dstlen = 0;
    if (!JS_EncodeCharacters(cx, src, srclen, NULL, &amp;dstlen))
        return JS_FALSE;

    /* Allocate. */
    char *dst = (char *) <a class="internal" href="mks://localhost/En/JS%20malloc" title="En/JS malloc">JS_malloc</a>(cx, dstlen);
    if (dst == NULL)
        return JS_FALSE;

    /* Convert characters to bytes. */
    JS_EncodeCharacters(cx, src, srclen, dst, &amp;dstlen);

    /* Use the converted bytes for something. */
    ...

    /* Remember to free the bytes afterwards. */
    <a class="internal" href="mks://localhost/En/JS%20free" title="En/JS free">JS_free</a>(cx, dst);
    return JS_TRUE;
</pre>
<p>On success, <code>JS_EncodeCharacters</code> sets <code>*dstlenp</code> to the real result length and returns <code>JS_TRUE</code>. Otherwise it reports an error and returns <code>JS_FALSE</code>.  This happens if the destination is too small for the resulting string or if the source buffer isn't proper UTF-16 because it contains unpaired surrogate values.</p>
<p>The user is responsible for allocating and freeing the memory of the destination string.</p>
<p><code>JS_EncodeCharacters</code> never adds a trailing null character. To obtain a null-terminated string, allocate an extra byte for the null character and set it manually.</p>
<p>To convert bytes to <code>jschar</code>s, the opposite conversion, use <a class="internal" href="/JS_DecodeBytes" title="JS_DecodeBytes"><code>JS_DecodeBytes</code></a>. To convert a <a class="internal" href="/en/SpiderMonkey/JSAPI_Reference/JSString" title="En/JSString"><code>JSString</code></a> to a C <code>char</code> string, use <a class="internal" href="/JS_EncodeString" title="JS_EncodeString"><code>JS_EncodeString</code></a> or <a class="internal" href="/en/SpiderMonkey/JSAPI_Reference/JS_GetStringBytes" title="En/JS GetStringBytes"><code>JS_GetStringBytes</code></a>.</p><h2 name="See_Also">See Also</h2>
<p>{{ LXRSearch("ident", "i", "JS_EncodeCharacters") }}</p>
<p><a href="/en/SpiderMonkey/JSAPI_Reference/JS_CompareStrings" title="en/JS_CompareStrings">JS_CompareStrings</a>, <a href="/en/SpiderMonkey/JSAPI_Reference/JS_GetStringBytes" title="en/SpiderMonkey/JSAPI_Reference/JS_GetStringBytes">JS_GetStringBytes</a></p>
Revert to this revision