This article needs a technical review. How you can help.
This article covers features introduced in SpiderMonkey 17
Take ownership of a string and free it later.
Syntax
JSAutoByteString str; JSAutoByteString(JSContext *cx, JSString *str);
| Name | Type | Description |
|---|---|---|
cx |
JSContext * |
The context in which to add the root. Requires request. In a JS_THREADSAFE build, the caller must be in a request on this JSContext. |
str |
JSString * |
A pointer to JSString to get initial content by calling JS_EncodeString(cx, str). |
Methods
| Method | Description |
|---|---|
void initBytes(char *bytes) |
Take ownership of the given byte array. |
char *encodeLatin1(JSContext *cx, JSString *str) |
Call JS_EncodeString and take ownership of the returned string, and return the string. |
char *encodeLatin1(js::ExclusiveContext *cx, JSString *str) |
Call JS::LossyTwoByteCharsToNewLatin1CharsZ, or allocate string and copy the content of JSLinearString::latin1Chars, and take the ownership of the string. This may fail if str is not linear. |
char *encodeUtf8(JSContext *cx, JS::HandleString str) |
Call JS_EncodeStringToUTF8 and take ownership of the returned string, and return the string. |
void clear() |
Free the owned string. You should call this before calling encode* methods or initBytes method if a string is already owned, otherwise the string will never be freed. |
char *ptr() const |
Return a pointer to the owned string. This could be NULL if no string is owned. |
bool operator!() const |
Return true if no string is owned. |
size_t length() const |
Return the length of the owned string. Return 0 if no string is owned. |
Description
JSAutoByteString takes the ownership of string and frees it in destructor.
If JSAutoByteString instance is initialized with JSAutoByteString bytes(cx, str); style, it calls JS_EncodeString(cx, str) to get the string to take ownership.
If JSAutoByteString instance is initialized with JSAutoByteString bytes; style, it does not own any string. You can call some methods to take ownership of other string.
Note that the JS_EncodeString call in constructor and some encode* methods may fail and get NULL. So ensure the string is returned by operator!() before using ptr() method.
Examples
Use constructor arguments
{
JSString *str = JS::ToString(cx, strVal);
if (!str)
return false;
JSAutoByteString bytes(cx, str); /* calls JS_EncodeString internally */
if (!bytes)
return false;
/* ...do something with bytes... */
/* when leaving this scope, the string returned by JS_EncodeString is freed. */
}
Use method to encode string
{
JS::RootedString str(cx, JS::ToString(cx, strVal));
if (!str)
return false;
JSAutoByteString bytes;
if (!bytes.encodeUtf8(cx, str)) /* calls JS_EncodeStringToUTF8 internally */
return false;
/* ...do something with bytes... */
/* when leaving this scope, the string returned by JS_EncodeStringToUTF8 is freed. */
}
Take ownership of other buffer
{
char *buff = cx->pod_malloc<char>(length + 1);
if (!buff)
return false;
memcpy(buff, other_buff, length + 1)
JSAutoByteString bytes;
bytes.initBytes(buff);
/* ...do something with bytes... */
/* when leaving this scope, buff is freed. */
}