JS_GetStringBytes

Convert a JavaScript string to a C string.

Syntax

char * JS_GetStringBytes(JSString *str); Obsolete since JavaScript 1.8.5

const char * JS_GetStringBytesZ(JSContext *cx, JSString *str);Added in SpiderMonkey 1.8.2 Obsolete since JavaScript 1.8.5

char * JS_EncodeString(JSContext *cx, JSString *str);Added in SpiderMonkey 1.8

size_t JS_GetStringEncodingLength(JSContext *cx, JSString *str); Added in SpiderMonkey 1.8.5 

size_t JS_EncodeStringToBuffer(JSString *str, char *buffer, size_t length); Added in SpiderMonkey 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

MXR ID Search for JS_GetStringBytes
MXR ID Search for JS_GetStringBytesZ
MXR ID Search for JS_EncodeString

JS_CompareStrings, JS_GetStringLength, JS_ValueToString

Document Tags and Contributors

Last updated by: tschneidereit,