mozilla
Your Search Results

    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

    Contributors to this page: Jorend
    Last updated by: Jorend,