Table of Contents | Previous | Next | Index

# Number

Lets you work with numeric values. The `Number` object is an object wrapper for primitive numeric values.

Core object
Implemented in | JavaScript 1.1, NES 2.0 JavaScript 1.2: modified behavior of `Number` constructor JavaScript 1.3: added `toSource` method
ECMA version | ECMA-262

#### Created by

The `Number` constructor:

    new Number(value)

#### Parameters

    value
| The numeric value of the object being created.

#### Description

The primary uses for the `Number` object are:

- To access its constant properties, which represent the largest and smallest representable numbers, positive and negative infinity, and the Not-a-Number value.

- To create numeric objects that you can add properties to. Most likely, you will rarely need to create a `Number` object.

The properties of `Number` are properties of the class itself, not of individual `Number` objects. JavaScript 1.2: `Number(x)` now produces `NaN` rather than an error if `x` is a string that does not contain a well-formed numeric literal. For example,

    x=Number("three");

    document.write(x + "<BR>");

prints `NaN` You can convert any object to a number using the top-level `Number` function.

#### Property Summary

Property | Description
--- | ---
    constructor
| Specifies the function that creates an object's prototype.
    MAX_VALUE
| The largest representable number.
    MIN_VALUE
| The smallest representable number.
    NaN
| Special "not a number" value.
    NEGATIVE_INFINITY
| Special value representing negative infinity; returned on overflow.
    POSITIVE_INFINITY
| Special value representing infinity; returned on overflow.
    prototype
| Allows the addition of properties to a `Number` object.

#### Method Summary

Method | Description
--- | ---
    toSource
| Returns an object literal representing the specified Number object; you can use this value to create a new object. Overrides the `Object.toSource` method.
    toString
| Returns a string representing the specified object. Overrides the `Object.toString` method.
    valueOf
| Returns the primitive value of the specified object. Overrides the `Object.valueOf` method.

In addition, this object inherits the `watch` and `unwatch` methods from `Object`.

#### Examples

Example 1. The following example uses the `Number` object's properties to assign values to several numeric variables:

    biggestNum = Number.MAX_VALUE
    smallestNum = Number.MIN_VALUE
    infiniteNum = Number.POSITIVE_INFINITY
    negInfiniteNum = Number.NEGATIVE_INFINITY
    notANum = Number.NaN

Example 2. The following example creates a `Number` object, `myNum`, then adds a `description` property to all `Number` objects. Then a value is assigned to the `myNum` object's `description` property.

    myNum = new Number(65)
    Number.prototype.description=null
    myNum.description="wind speed"

## 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 | `Number`
Implemented in | JavaScript 1.1, NES 2.0
ECMA version | ECMA-262

#### Description

See `Object.constructor`.

## MAX_VALUE

The maximum numeric value representable in JavaScript.

Property of | `Number`
Static, Read-only
Implemented in | JavaScript 1.1, NES 2.0
ECMA version | ECMA-262

#### Description

The `MAX_VALUE` property has a value of approximately 1.79E+308. Values larger than `MAX_VALUE` are represented as `"Infinity"`. Because `MAX_VALUE` is a static property of `Number`, you always use it as `Number.MAX_VALUE`, rather than as a property of a `Number` object you created.

#### Examples

The following code multiplies two numeric values. If the result is less than or equal to `MAX_VALUE`, the `func1` function is called; otherwise, the `func2` function is called.

    if (num1 * num2 <= Number.MAX_VALUE)
       func1()
    else
       func2()

## MIN_VALUE

The smallest positive numeric value representable in JavaScript.

Property of | `Number`
Static, Read-only
Implemented in | JavaScript 1.1, NES 2.0
ECMA version | ECMA-262

#### Description

The `MIN_VALUE` property is the number closest to 0, not the most negative number, that JavaScript can represent. `MIN_VALUE` has a value of approximately 5e-324. Values smaller than `MIN_VALUE` ("underflow values") are converted to 0. Because `MIN_VALUE` is a static property of `Number`, you always use it as `Number.MIN_VALUE`, rather than as a property of a `Number` object you created.

#### Examples

The following code divides two numeric values. If the result is greater than or equal to `MIN_VALUE`, the `func1` function is called; otherwise, the `func2` function is called.

    if (num1 / num2 >= Number.MIN_VALUE)
       func1()
    else
       func2()

## NaN

A special value representing Not-A-Number. This value is represented as the unquoted literal NaN.

Property of | `Number`
Read-only |
Implemented in | JavaScript 1.1, NES 2.0
ECMA version | ECMA-262

#### Description

JavaScript prints the value `Number.NaN` as `NaN`. `NaN` is always unequal to any other number, including NaN itself; you cannot check for the not-a-number value by comparing to `Number.NaN`. Use the `isNaN` function instead. You might use the `NaN` property to indicate an error condition for a function that should return a valid number.

#### Examples

In the following example, if `month` has a value greater than 12, it is assigned NaN, and a message is displayed indicating valid values.

    var month = 13
    if (month < 1 || month > 12) {
       month = Number.NaN
       alert("Month must be between 1 and 12.")
    }

#### See also

`NaN`, `isNaN`, `parseFloat`, `parseInt`

## NEGATIVE_INFINITY

A special numeric value representing negative infinity. This value is represented as the unquoted literal `"-Infinity"`.

Property of | `Number`
Static, Read-only
Implemented in | JavaScript 1.1, NES 2.0
ECMA version | ECMA-262

#### Description

This value behaves slightly differently than mathematical infinity:

- Any positive value, including `POSITIVE_INFINITY`, multiplied by `NEGATIVE_INFINITY` is `NEGATIVE_INFINITY`.
- Any negative value, including `NEGATIVE_INFINITY`, multiplied by `NEGATIVE_INFINITY` is `POSITIVE_INFINITY`.
- Zero multiplied by `NEGATIVE_INFINITY` is `NaN`.
- `NaN` multiplied by `NEGATIVE_INFINITY` is `NaN`.
- `NEGATIVE_INFINITY`, divided by any negative value except `NEGATIVE_INFINITY`, is `POSITIVE_INFINITY`.
- `NEGATIVE_INFINITY`, divided by any positive value except `POSITIVE_INFINITY`, is `NEGATIVE_INFINITY`.
- `NEGATIVE_INFINITY`, divided by either `NEGATIVE_INFINITY` or `POSITIVE_INFINITY`, is `NaN`.
- Any number divided by `NEGATIVE_INFINITY` is Zero.

Because `NEGATIVE_INFINITY` is a static property of `Number`, you always use it as `Number.NEGATIVE_INFINITY`, rather than as a property of a `Number` object you created.

#### Examples

In the following example, the variable `smallNumber` is assigned a value that is smaller than the minimum value. When the `if` statement executes, `smallNumber` has the value `"-Infinity"`, so the `func1` function is called.

    var smallNumber = -Number.MAX_VALUE*10
    if (smallNumber == Number.NEGATIVE_INFINITY)
       func1()
    else
       func2()

#### See also

`Infinity`, `isFinite`

## POSITIVE_INFINITY

A special numeric value representing infinity. This value is represented as the unquoted literal `"Infinity"`.

Property of | `Number`
Static, Read-only
Implemented in | JavaScript 1.1, NES 2.0
ECMA version | ECMA-262

#### Description

This value behaves slightly differently than mathematical infinity:

- Any positive value, including `POSITIVE_INFINITY`, multiplied by `POSITIVE_INFINITY` is `POSITIVE_INFINITY`.
- Any negative value, including `NEGATIVE_INFINITY`, multiplied by `POSITIVE_INFINITY` is `NEGATIVE_INFINITY`.
- Zero multiplied by `POSITIVE_INFINITY` is `NaN`.
- `NaN` multiplied by `POSITIVE_INFINITY` is `NaN`.
- `POSITIVE_INFINITY`, divided by any negative value except `NEGATIVE_INFINITY`, is `NEGATIVE_INFINITY`.
- `POSITIVE_INFINITY`, divided by any positive value except `POSITIVE_INFINITY`, is `POSITIVE_INFINITY`.
- `POSITIVE_INFINITY`, divided by either `NEGATIVE_INFINITY` or `POSITIVE_INFINITY`, is `NaN`.
- Any number divided by `POSITIVE_INFINITY` is Zero.

Because `POSITIVE_INFINITY` is a static property of `Number`, you always use it as `Number.POSITIVE_INFINITY`, rather than as a property of a `Number` object you created.

#### Examples

In the following example, the variable `bigNumber` is assigned a value that is larger than the maximum value. When the `if` statement executes, `bigNumber` has the value `"Infinity"`, so the `func1` function is called.

    var bigNumber = Number.MAX_VALUE * 10
    if (bigNumber == Number.POSITIVE_INFINITY)
       func1()
    else
       func2()

#### See also

`Infinity`, `isFinite`

## prototype

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

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

## toSource

Returns a string representing the source code of the object.

Method of | `Number`
Implemented in | JavaScript 1.3

#### Syntax

    toSource()

#### Parameters

None

#### Description

The `toSource` method returns the following values:

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

       function Number() {
          [native code]
       }

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

This method is usually called internally by JavaScript and not explicitly in code.

#### See also

`Object.toSource`

## toString

Returns a string representing the specified Number object.

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

#### Syntax

    toString()
    toString([radix])

#### Parameters

    radix
| An integer between 2 and 36 specifying the base to use for representing numeric values.

#### Description

The `Number` object overrides the `toString` method of the `Object` object; it does not inherit `Object.toString`. For `Number` objects, the `toString` method returns a string representation of the object. JavaScript calls the `toString` method automatically when a number is to be represented as a text value or when a number is referred to in a string concatenation. For `Number` objects and values, the built-in `toString` method returns the string representing the value of the number. You can use `toString` on numeric values, but not on numeric literals:

    // The next two lines are valid
    var howMany=10
    alert("howMany.toString() is " + howMany.toString())

    // The next line causes an error
    alert("45.toString() is " + 45.toString())

## valueOf

Returns the primitive value of a Number object.

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

#### Syntax

    valueOf()

#### Parameters

None

#### Description

The `valueOf` method of `Number` returns the primitive value of a Number object as a number data type. This method is usually called internally by JavaScript and not explicitly in code.

#### Examples

    x = new Number();
    alert(x.valueOf())      //displays 0

#### See also

`Object.valueOf`

Table of Contents | Previous | Next | Index

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

Copyright (c) 1999 Netscape Communications Corporation