Availability

Navigator 2.0, Internet Explorer 3.0

Description

The toString() method is not one you usually call directly in your JavaScript programs. Instead, you define this method in your objects, and the system calls it whenever it needs to convert your object to a string.

The JavaScript system invokes the toString() method to convert an object to a string whenever the object is used in a "string context." For example, if an object is converted to a string when it is passed to a function that expects a string argument:

alert(my_object);

Similarly, objects are converted to strings when they are concatenated to strings with the + operator:

alert('My object is: ' + my_object);

The toString() method will be invoked without arguments, and should return a string. To be useful, the string you return should be based, in some way, on the value of the object for which the method was invoked.

Usage

The toString() method can be quite useful when you are debugging JavaScript programs--it allows you to print objects and see their value. For this reason alone, it is a good idea to define a toString() method for every object class you create.

The string returned by toString() can be as complex as you like, and this method need not be restricted to use in debugging, of course. For example, a toString() method could be defined to return HTML formatted text. If the wording and formatting are chosen appropriately, then you could use document.write() to output a string representation of an object directly into an HTML document!

Although the toString() method is usually invoked automatically by the system, there are times when you may invoke it yourself. For example, you might want to do an explicit conversion of an object to a string in a situation where JavaScript will not do it automatically for you:

y = Math.sqrt(x);
ystr = y.toString();

Note in this example that numbers have a built-in toString() method that you can use to force a conversion.

In other circumstances, you might choose to use a toString() call even in a context where JavaScript would do the conversion automatically. Using toString() explicitly can help to make your code clearer:

alert(my_obj.toString());

It does not generally make sense to define a toString() method for only a single object, so you will usually assign this method to a prototype object so that it is available to all objects in a class of objects.

Example

You might define a simple class of Circle objects and specify a toString() method for it as follows. (In Navigator 3.0, you could use a prototype object to define the method rather that setting it each time the constructor function is called.)

function Circle_toString() { 
    return "[A circle of radius " + this.r + "]";
}
function Circle(r) { 
    this.r = r;
    this.toString = Circle_toString();
}

See Also

"Object"