JS_FlattenString

This article is in need of a technical review.

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

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 JS_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);

Document Tags and Contributors

Contributors to this page: Sheppy, ethertank, MarkGiffin, kscarfone
Last updated by: kscarfone,