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. */
}

See Also