Previous Contents Index Next
Core JavaScript Reference 1.5

> 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. JavaScript 1.5, NES 6.0: added toExponential, toFixed, and toPrecision methods.
> 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
> --- | ---
> toExponential | Returns a string representing the number in exponential notation.
> toFixed | Returns a string representing the number in fixed-point notation.
> toPrecision | Returns a string representing the number to a specified precision in fixed-point notation.
> 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

> toExponential

> Returns a string representing the Number object in exponential notation.

> Method of | Number
> Implemented in | JavaScript 1.5
> ECMA version | ECMA-262, Edition 3

> Syntax
> toExponential([fractionDigits])

> Parameters

> fractionDigits | An integer specifying the number of digits after the decimal point. Defaults to as many digits as necessary to specify the number.

> Description
> The Number.prototype.toExponential method returns a string representing a Number object in exponential notation with one digit before the decimal point, rounded to fractionDigits digits after the decimal point. If the fractionDigits argument is omitted, the number of digits after the decimal point defaults to the number of digits necessary to represent the value uniquely.

> If you use the toExponential method for a numeric literal and the numeric literal has no exponent and no decimal point, leave a space before the dot that precedes the method call to prevent the dot from being interpreted as a decimal point.

> If a number has more digits that requested by the fractionDigits parameter, the number is rounded to the nearest number represented by fractionDigits digits. See the discussion of rounding in the description of the toFixed method on page 129, which also applies to toExponential.

> Examples
> var num=77.1234
> alert("num.toExponential() is " + num.toExponential()) //displays 7.71234e+1
> alert("num.toExponential(4) is " + num.toExponential(4)) //displays 7.7123e+1
> alert("num.toExponential(2) is " + num.toExponential(2)) //displays 7.71e+1
> alert("77.1234.toExponential() is " + 77.1234.toExponential())
> //displays 7.71234e+1
> alert("77 .toExponential() is " + 77 .toExponential()) //displays 7.7e+1

> See also
> toFixed, toPrecision, toString

> toFixed

> Returns a string representing the Number object in fixed-point notation.

> Method of | Number
> Implemented in | JavaScript 1.5
> ECMA version | ECMA-262, Edition 3

> Syntax
> toFixed([fractionDigits])

> Parameters

> fractionDigits | An integer specifying the number of digits after the decimal point. Defaults to zero.

> Description
> The Number.prototype.toFixed method returns a string representing a Number object in fixed-point notation, rounded to the number of digits after the decimal point specified by fractionDigits.

> The output of toFixed may be more precise than toString for some values, because toString outputs only enough significant digits to distinguish the number from adjacent number values.

> If a number has more digits that requested by the fractionDigits parameter, the number is rounded to the nearest number represented by fractionDigits digits. If the number is exactly halfway between two representable numbers, it is rounded away from zero (up if it is positive, down if it is negative). Thus:

>   0.124.toFixed(2) returns "0.12".
>   0.125.tofixed(2) returns "0.13", because 0.125 is exactly halfway between 0.12 and 0.13.
>   0 .126.tofixed(2) returns "0.13".
> Given this convention, one might expect 0.045.toFixed(2) to return "0.05", but it returns "0.04". This is because of the way computers represent IEEE 754 floating-point numbers. The IEEE 754 standard uses binary fractions (fractions of 0's and 1's after the dot). Just as some numbers, such as 1/3, are not representable precisely as decimal fractions, other numbers, such as 0.045, are not precisely representable as binary fractions. The IEEE 754 standard dictates that 0.045 be approximated to 0.04499999999999999833466546306226518936455249786376953125, which is precisely representable as a binary fraction. This approximation is closer to 0.04 than to 0.05, so 0.045.toFixed(2) returns "0.04".

> Examples
> var num=10.1234
> alert("num.toFixed() is " + num.toFixed()) //displays 10
> alert("num.toFixed(4) is " + num.toFixed(4)) //displays 10.1234 alert("num.toFixed(2) is " + num.toFixed(2)) //displays 10.12

> See also
> toExponential, toPrecision, toString

> toPrecision

> Returns a string representing the Number object to the specified precision.

> Method of | Number
> Implemented in | JavaScript 1.5
> ECMA version | ECMA-262, Edition 3

> Syntax
> toPrecision([precision])

> Parameters

> precision | An integer specifying the number of digits after the decimal point.

> Description
> The Number.prototype.toPrecision method returns a string representing a Number object in fixed-point or exponential notation rounded to precision significant digits.

> If you use the toPrecision method for a numeric literal and the numeric literal has no exponent and no decimal point, leave a space before the dot that precedes the method call to prevent the dot from being interpreted as a decimal point.

> If the precision argument is omitted, behaves as Number.prototype.toString.

> If a number has more digits that requested by the precision parameter, the number is rounded to the nearest number represented by precision digits. See the discussion of rounding in the description of the toFixed method on page 129, which also applies to toPrecision.

> Examples
> var num=5.123456
> alert("num.toPrecision() is " + num.toPrecision()) //displays 5.123456
> alert("num.toPrecision(4) is " + num.toPrecision(4)) //displays 5.123
> alert("num.toPrecision(2) is " + num.toPrecision(2)) //displays 5.1
> alert("num.toPrecision(2) is " + num.toPrecision(1)) //displays 5
> alert("num.toPrecision(2) is " + num.toPrecision(1)) //displays 5
> alert("1250 .toPrecision() is " + 1250 .toPrecision(2))
> //displays 1.3e+3
> alert("1250 .toPrecision(5) is " + 1250 .toPrecision(5))
> //displays 1250.0

> See also
> toExponential, toFixed, toString

> 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.

> If you use the toString method for a numeric literal and the numeric literal has no exponent and no decimal point, leave a space before the dot that precedes the method call to prevent the dot from being interpreted as a decimal point.

> For Number objects and values, the built-in toString method returns the string representing the value of the number.

> var howMany=10;
> alert("howMany.toString() is " + howMany.toString())
> alert("45 .toString() is " + 45 .toString())

> See also
> toExponential, toFixed, toPrecision

> 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

> Previous Contents Index Next

> Copyright © 2000 Netscape Communications Corp. All rights reserved.

Last Updated September 28, 2000