mozilla
Your Search Results

    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

    Document Tags and Contributors

    Contributors to this page: fscholz, Petermichaux, arai, MMondor, Dria, Jorend
    Last updated by: arai,
    Hide Sidebar