Table of Contents | Previous | Next | Index

# Object

`Object` is the primitive JavaScript object type. All JavaScript objects are descended from `Object`. That is, all JavaScript objects have the methods defined for `Object`.

Core object
Implemented in | JavaScript 1.0: `toString` method JavaScript 1.1, NES 2.0: added `eval` and `valueOf` methods; `constructor` property JavaScript 1.2: deprecated `eval` method JavaScript 1.3: added `toSource` method
ECMA version | ECMA-262

#### Created by

The `Object` constructor:

    new Object()

#### Parameters

None

#### Property Summary

Property | Description
--- | ---

    constructor

Specifies the function that creates an object's prototype.

    prototype

Allows the addition of properties to all objects.

#### Method Summary

Method | Description
--- | ---

    eval

Deprecated. Evaluates a string of JavaScript code in the context of the specified object.

    toSource

Returns an object literal representing the specified object; you can use this value to create a new object.

    toString

Returns a string representing the specified object.

    unwatch

Removes a watchpoint from a property of the object.

    valueOf

Returns the primitive value of the specified object.

    watch

Adds a watchpoint to a property of the object.

## constructor

Specifies the function that creates an object's prototype. Note that the value of this property is a reference to the function itself, not a string containing the function's name.

Property of | `Object`
Implemented in | JavaScript 1.1, NES 2.0
ECMA version | ECMA-262

#### Description

All objects inherit a `constructor` property from their `prototype`:

    o = new Object  // or o = {} in JavaScript 1.2
    o.constructor == Object
    a = new Array   // or a = [] in JavaScript 1.2
    a.constructor == Array
    n = new Number(3)
    n.constructor == Number

Even though you cannot construct most HTML objects, you can do comparisons. For example,

    document.constructor == Document
    document.form3.constructor == Form

#### Examples

The following example creates a prototype, `Tree`, and an object of that type, `theTree`. The example then displays the `constructor` property for the object `theTree`.

    function Tree(name) {
       this.name=name
    }
    theTree = new Tree("Redwood")
    document.writeln("<B>theTree.constructor is</B> " +
       theTree.constructor + "<P>")

This example displays the following output:

    theTree.constructor is function Tree(name) { this.name = name; }

## eval

Deprecated. Evaluates a string of JavaScript code in the context of an object.

Method of | `Object`
Implemented in | JavaScript 1.1, NES 2.0 JavaScript 1.2, NES 3.0: deprecated as method of objects; retained as top-level function

#### Syntax

    eval(string)

#### Parameters

    string

Any string representing a JavaScript expression, statement, or sequence of statements. The expression can include variables and properties of existing objects.

#### Description

`eval` as a method of Object and every object derived from Object is deprecated. Use the top-level `eval` function.

#### Backward Compatibility

JavaScript 1.1. `eval` is a method of Object and every object derived from Object.

#### See also

`eval`

## prototype

Represents the prototype for this class. You can use the prototype to add properties or methods to all instances of a class. For more information, see `Function.prototype`.

Property of | `Object`
Implemented in | JavaScript 1.1
ECMA version | ECMA-262

## toSource

Returns a string representing the source code of the object.

Method of | `Object`
Implemented in | JavaScript 1.3

#### Syntax

    toSource()

#### Parameters

None

#### Description

The `toSource` method returns the following values:

- For the built-in `Object` object, `toSource` returns the following string indicating that the source code is not available:

       function Object() {
          [native code]
       }

- For instances of `Object`, `toSource` returns a string representing the source code.

- For custom objects, `toSource` returns the JavaScript source that defines the object as a string.

This method is usually called internally by JavaScript and not explicitly in code. You can call `toSource` while debugging to examine the contents of an object.

#### Examples

The following code defines the `Dog` object type and creates `theDog,` an object of type `Dog`:

    function Dog(name,breed,color,sex) {
       this.name=name
       this.breed=breed
       this.color=color
       this.sex=sex
    }
    theDog = new Dog("Gabby","Lab","chocolate","girl")

Calling the `toSource` method of `theDog` displays the JavaScript source that defines the object:

    theDog.toSource()
    //returns "{name:"Gabby", breed:"Lab", color:"chocolate", sex:"girl"}

#### See also

`Object.toString`

## toString

Returns a string representing the specified object.

Method of | `Object`
Implemented in | JavaScript 1.0
ECMA version | ECMA-262

#### Syntax

    toString()

#### Security

JavaScript 1.1: This method is tainted by default for the following objects: `Button`, `Checkbox`, `FileUpload`, `Hidden`, `History`, `Link`, `Location`, `Password`, `Radio`, `Reset`, `Select`, `Submit`, `Text`, and `Textarea`. For information on data tainting, see the Client-Side JavaScript Guide.

#### Description

Every object has a `toString` method that is automatically called when it is to be represented as a text value or when an object is referred to in a string concatenation. For example, the following examples require `theDog` to be represented as a string:

    document.write(theDog)
    document.write("The dog is " + theDog)

By default, the `toString` method is inherited by every object descended from `Object`. You can override this method for custom objects that you create. If you do not override `toString` in a custom object, `toString` returns `[object` `type``]`, where `type` is the object type or the name of the constructor function that created the object. For example:

    var o = new Object()
    o.toString // returns [object Object]

Built-in toString methods. Every built-in core JavaScript object overrides the `toString` method of `Object` to return an appropriate value. JavaScript calls this method whenever it needs to convert an object to a string. Some built-in client-side and server-side JavaScript objects do not override the toString method of Object. For example, for an `Image` object named `sealife` defined as shown below, `sealife.toString()` returns `[object Image]`.

    <IMG NAME="sealife" SRC="images\seaotter.gif" ALIGN="left" VSPACE="10">

Overriding the default toString method. You can create a function to be called in place of the default `toString` method. The `toString` method takes no arguments and should return a string. The `toString` method you create can be any value you want, but it will be most useful if it carries information about the object. The following code defines the `Dog` object type and creates `theDog,` an object of type `Dog`:

    function Dog(name,breed,color,sex) {
       this.name=name
       this.breed=breed
       this.color=color
       this.sex=sex
    }

    theDog = new Dog("Gabby","Lab","chocolate","girl")

If you call the `toString` method on this custom object, it returns the default value inherited from `Object`:

    theDog.toString() //returns [object Object]

The following code creates `dogToString,` the function that will be used to override the default `toString` method. This function generates a string containing each property, of the form `"property = value;"`.

    function dogToString() {
       var ret = "Dog " + this.name + " is [\n"
       for (var prop in this)
          ret += "  " + prop + " is " + this[prop] + ";\n"
       return ret + "]"
    }

The following code assigns the user-defined function to the object's `toString` method:

    Dog.prototype.toString = dogToString

With the preceding code in place, any time `theDog` is used in a string context, JavaScript automatically calls the `dogToString` function, which returns the following string:

    Dog Gabby is [
      name is Gabby;
      breed is Lab;
      color is chocolate;
      sex is girl;
    ]

An object's `toString` method is usually invoked by JavaScript, but you can invoke it yourself as follows:

    var dogString = theDog.toString()

#### Backward Compatibility

JavaScript 1.2. The behavior of the `toString` method depends on whether you specify `LANGUAGE="JavaScript1.2"` in the `<SCRIPT>` tag:

- If you specify `LANGUAGE="JavaScript1.2"` in the `<SCRIPT>` tag, the `toString` method returns an object literal.

- If you do not specify `LANGUAGE="JavaScript1.2"` in the `<SCRIPT>` tag, the `toString` method returns `[object` `type``]`, as with other JavaScript versions.

#### Examples

Example 1: The location object. The following example prints the string equivalent of the current location.

    document.write("location.toString() is " + location.toString() + "<BR>")

The output is as follows:

    location.toString() is file:///C|/TEMP/myprog.html

Example 2: Object with no string value. Assume you have an `Image` object named `sealife` defined as follows:

    <IMG NAME="sealife" SRC="images\seaotter.gif" ALIGN="left" VSPACE="10">

Because the `Image` object itself has no special `toString` method, `sealife.toString()` returns the following:

    [object Image]

Example 3: The radix parameter. The following example prints the string equivalents of the numbers 0 through 9 in decimal and binary.

    for (x = 0; x < 10; x++) {
       document.write("Decimal: ", x.toString(10), " Binary: ",
          x.toString(2), "<BR>")
    }

The preceding example produces the following output:

    Decimal: 0 Binary: 0
    Decimal: 1 Binary: 1
    Decimal: 2 Binary: 10
    Decimal: 3 Binary: 11
    Decimal: 4 Binary: 100
    Decimal: 5 Binary: 101
    Decimal: 6 Binary: 110
    Decimal: 7 Binary: 111
    Decimal: 8 Binary: 1000
    Decimal: 9 Binary: 1001

#### See also

`Object.toSource`, `Object.valueOf`

## unwatch

Removes a watchpoint set with the `watch` method.

Method of | `Object`
Implemented in | JavaScript 1.2, NES 3.0

#### Syntax

    unwatch(prop)

#### Parameters

`prop` | The name of a property of the object.

#### Description

The JavaScript debugger has functionality similar to that provided by this method, as well as other debugging options. For information on the debugger, see Getting Started with Netscape JavaScript Debugger. By default, this method is inherited by every object descended from `Object`.

#### Example

See `watch`.

## valueOf

Returns the primitive value of the specified object.

Method of | `Object`
Implemented in | JavaScript 1.1
ECMA version | ECMA-262

#### Syntax

    valueOf()

#### Parameters

None

#### Description

JavaScript calls the `valueOf` method to convert an object to a primitive value. You rarely need to invoke the `valueOf` method yourself; JavaScript automatically invokes it when encountering an object where a primitive value is expected. By default, the `valueOf` method is inherited by every object descended from `Object`. Every built-in core object overrides this method to return an appropriate value. If an object has no primitive value, `valueOf` returns the object itself, which is displayed as:

    [object Object]

You can use `valueOf` within your own code to convert a built-in object into a primitive value. When you create a custom object, you can override `Object.valueOf` to call a custom method instead of the default `Object` method. Overriding valueOf for custom objects. You can create a function to be called in place of the default `valueOf` method. Your function must take no arguments. Suppose you have an object type `myNumberType` and you want to create a `valueOf` method for it. The following code assigns a user-defined function to the object's `valueOf` method:

    myNumberType.prototype.valueOf = new Function(functionText)

With the preceding code in place, any time an object of type `myNumberType` is used in a context where it is to be represented as a primitive value, JavaScript automatically calls the function defined in the preceding code. An object's `valueOf` method is usually invoked by JavaScript, but you can invoke it yourself as follows:

    myNumber.valueOf()

> NOTE: Objects in string contexts convert via the `toString` method, which is different from `String` objects converting to string primitives using `valueOf`. All string objects have a string conversion, if only `"[object` `type``]"`. But many objects do not convert to number, boolean, or function.

#### See also

`parseInt`, `Object.toString`

## watch

Watches for a property to be assigned a value and runs a function when that occurs.

Method of | `Object`
Implemented in | JavaScript 1.2, NES 3.0

#### Syntax

    watch(prop, handler)

#### Parameters

`

`prop` | The name of a property of the object.
`handler` | A function to call.

`

#### Description

Watches for assignment to a property named `prop` in this object, calling `handler(prop, oldval, newval)` whenever `prop` is set and storing the return value in that property. A watchpoint can filter (or nullify) the value assignment, by returning a modified `newval` (or `oldval`). If you delete a property for which a watchpoint has been set, that watchpoint does not disappear. If you later recreate the property, the watchpoint is still in effect. To remove a watchpoint, use the `unwatch` method. By default, the `watch` method is inherited by every object descended from `Object`. The JavaScript debugger has functionality similar to that provided by this method, as well as other debugging options. For information on the debugger, see Getting Started with Netscape JavaScript Debugger.

#### Example

    <script language="JavaScript1.2">
    o = {p:1}
    o.watch("p",
       function (id,oldval,newval) {
          document.writeln("o." + id + " changed from "
             + oldval + " to " + newval)
          return newval
       })

    o.p = 2
    o.p = 3
    delete o.p
    o.p = 4

    o.unwatch('p')
    o.p = 5

    </script>

This script displays the following: o.p changed from 1 to 2
o.p changed from 2 to 3
o.p changed from 3 to 4

Table of Contents | Previous | Next | Index

Last Updated: 05/28/99 12:00:04

Copyright (c) 1999 Netscape Communications Corporation