JS_ValueToString

Syntax

JSString *
JS_ValueToString(JSContext *cx, jsval v);

Description

JS_ValueToString converts a specified JavaScript value, v, to a string. It implements the ToString operator specified in ECMA 262-3 §9.8. The result is like the JavaScript expression ""+v.

• If v is already a string, conversion succeeds.
• If v is true, false, null, or undefined, conversion succeeds, and the result is the string "true", "false", "null", or "undefined", accordingly.
• If v is a number, conversion succeeds, and the result is a string representation of that number as specified in ECMA 262-3 §9.8.1. This might be "NaN", "Infinity", or "-Infinity". Otherwise the result is a decimal representation of the number, possibly using exponential notation.
• Otherwise v is an object. JS_ValueToString uses the steps below to convert it to a string. If at any point an error or exception occurs, or conversion succeeds, the rest of the steps are skipped. (This behavior is implemented by v's JSObjectOps.defaultValue method, so host objects can override it all.)
  • If v.toString() is a function, it is called. If that method returns a primitive value, the value is converted to a string as described above and conversion succeeds.
  • Otherwise, the resulting object's JSClass.convert callback is called. For standard classes, this is  JS_ConvertStub, which simply calls v.valueOf() if present. If the convert callback produces a primitive value, the value is converted to a string as described above and conversion succeeds.
  • Otherwise conversion fails with a TypeError.

On success, JS_ValueToString returns a pointer to a string. On error or exception, it returns NULL. This happens, for example, if v is an object and v.toString() throws an exception.

The resulting JSString is subject to garbage collection. Protect it using a local root, an object property, or the JS_AddRoot function.

See Also

• bug 933834
• JS::ToString