JS_ValueToString

Obsolete since JSAPI 28
This feature is obsolete. Although it may still work in some browsers, its use is discouraged since it could be removed at any time. Try to avoid using it.

Convert a jsval to a JSString.

Syntax

JSString *
JS_ValueToString(JSContext *cx, jsval v);
Name Type Description
cx JSContext * The context in which to perform the conversion. Requires request. In a JS_THREADSAFE build, the caller must be in a request on this JSContext.
v jsval The value to convert.

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