This article covers features introduced in SpiderMonkey 1.8.5

Flattens a string. This makes getting the characters of the string infallible.

Syntax

JSFlatString *
JS_FlattenString(JSContext *cx, JSString *str);
Name Type Description
cx JSContext * The context. Requires request. In a JS_THREADSAFE build, the caller must be in a request on this JSContext.
str JSString * The string to flatten.

Description

JS_FlattenString flattens a string str and returns a pointer to JSFlatString.

To catch errors, an opaque JSFlatString type is returned.

Note: The input and output of JS_FlattenString() are the same actual GC-thing so only one needs to be rooted.

If a JSString is known to be flat, you can use JS_ASSERT_STRING_IS_FLAT to make a debug-checked cast. Example:

// In a fallible situation

JSFlatString *fstr = JS_FlattenString(cx, str);
if (!fstr)
  return false;
JS_ASSERT(fstr == JS_ASSERT_STRING_IS_FLAT(str));

// in an infallible situation, for the same 'str'

const jschar *chars = JS_GetFlatStringChars(fstr)
JS_ASSERT(chars);

See Also