Obsolete since JSAPI 19
This feature is obsolete. Although it may still work in some browsers, its use is discouraged since it could be removed at any time. Try to avoid using it.
Convert a 16-bit string to an 8-bit string.
JSBool JS_EncodeCharacters(JSContext *cx, const jschar *src, size_t srclen, char *dst, size_t *dstlen);
||The pointer to 16-bit values of JSString. This can be obtained with
||The length of the source string, in 16-bit values.|
||The pointer to an array of bytes to be filled with encoded characters; or
||In/out parameter. On entry, if
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;
*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.