Chapter 23. Core JavaScript Reference

Arrays are a basic feature of JavaScript and are documented in detail in Chapter 9.

Inherits from/Overrides

Inherits from Object

Constructor

new Array( )
new Array(size)
new Array(element0, element1, ..., elementn)

Arguments

size: The desired number of elements in the array. The returned array has its length field set to size.
element0, ... elementn: An argument list of two or more arbitrary values. When the Array( ) constructor is invoked with these arguments, the newly created array is initialized with the specified argument values as its elements and its length field set to the number of arguments.

Returns

The newly created and initialized array. When Array( ) is invoked with no arguments, the returned array is empty and has a length field of 0. When invoked with a single numeric argument, the constructor returns an array with the specified number of undefined elements. When invoked with any other arguments, the constructor initializes the array with the values specified by the arguments. When the Array( ) constructor is called as a function, without the new operator, it behaves exactly as it does when called with the new operator.

Throws

RangeError: When a single integer size argument is passed to the Array( ) constructor, a RangeError exception is thrown if size is negative or is larger than 2³²-1.

Literal Syntax

ECMAScript v3 specifies and JavaScript 1.2 and JScript 3.0 implement an array literal syntax. You may also create and initialize an array by placing a comma-separated list of expressions within square brackets. The values of these expressions become the elements of the array. For example:

var a = [1, true, 'abc'];
var b = [a[0], a[0]*2, f(x)];

Properties

length: A read/write integer specifying the number of elements in the array or, when the array does not have contiguous elements, a number one larger than the index of the last element in the array. Changing the value of this property truncates or extends the array.

Methods

concat( ): Concatenates elements to an array.
join( ): Converts all array elements to strings and concatenate them.
pop( ): Removes an item from the end of an array.
push( ): Pushes an item onto the end of an array.
reverse( ): Reverses, in place, the order of the elements of an array.
shift( ): Shifts an element off the beginning of an array.
slice( ): Returns a subarray slice of an array.
sort( ): Sorts, in place, the elements of an array.
splice( ): Inserts, deletes, or replaces array elements.
toLocaleString( ): Converts an array to a localized string.
toString( ): Converts an array to a string.
unshift( ): Inserts elements at the beginning of an array.

Description

Availability

JavaScript 1.2; JScript 3.0; ECMAScript v3

Synopsis

array.concat(value, ...)

Arguments

value, ...: Any number of values to be concatenated with array.

Returns

A new array, which is formed by concatenating each of the specified arguments to array.

Description

concat( ) creates and returns a new array that is the result of concatenating each of its arguments to array. It does not modify array. If any of the arguments to concat( ) is itself an array, the elements of that array are concatenated, rather than the array itself.

Example

var a = [1,2,3];
a.concat(4, 5)          // Returns [1,2,3,4,5]
a.concat([4,5]);        // Returns [1,2,3,4,5]
a.concat([4,5],[6,7])   // Returns [1,2,3,4,5,6,7]
a.concat(4, [5,[6,7]])  // Returns [1,2,3,4,5,[6,7]]

Availability

JavaScript 1.1, JScript 2.0; ECMAScript v1

Synopsis

array.join( ) 
array.join(separator)

Arguments

separator: An optional character or string used to separate one element of the array from the next in the returned string. If this argument is omitted, a comma is used.

Returns

The string that results from converting each element of array to a string and then concatenating them together, with the separator string between elements.

Description

join( ) converts each of the elements of an array to a string and then concatenates those strings, inserting the specified separator string between the elements. It returns the resulting string.

You can perform a conversion in the opposite direction -- splitting a string up into array elements -- with the split( ) method of the String object. See the String.split( ) reference page for details.

Example

a = new Array(1, 2, 3, "testing");
s = a.join("+");  // s is the string "1+2+3+testing"

Availability

Synopsis

array.length

Description

The length property of an array is always one larger than the highest element defined in the array. For traditional "dense" arrays that have contiguous elements and begin with element 0, the length property specifies the number of elements in the array.

The length property of an array is initialized when the array is created with the Array( ) constructor method. Adding new elements to an array updates the length, if necessary:

a = new Array( );                       // a.length initialized to 0
b = new Array(10);                       // b.length initialized to 10
c = new Array("one", "two", "three");    // c.length initialized to 3
c[3] = "four";                           // c.length updated to 4
c[10] = "blastoff";                      // c.length becomes 11

You can set the value of the length property to change the size of an array. If you set length to be smaller than its previous value, the array is truncated and elements at the end are lost. If you set length to be larger than its previous value, the array becomes bigger and the new elements added at the end of the array have the undefined value.

Array.pop( )

remove and return the last element of an array

Availability

JavaScript 1.2; JScript 5.5; ECMAScript v3

Synopsis

array.pop( )

Returns

The last element of array.

Description

pop( ) deletes the last element of array, decrements the array length, and returns the value of the element that it deleted. If the array is already empty, pop( ) does not change the array and returns the undefined value.

Example

pop( ), and its companion method push( ), provide the functionality of a first-in, last-out stack. For example:

var stack = [];       // stack: []
stack.push(1, 2);     // stack: [1,2]     Returns 2
stack.pop( );        // stack: [1]       Returns 2
stack.push([4,5]);    // stack: [1,[4,5]] Returns 2
stack.pop( )         // stack: [1]       Returns [4,5]
stack.pop( );        // stack: []        Returns 1

Availability

JavaScript 1.2; JScript 5.5; ECMAScript v3

Synopsis

array.push(value, ...)

Arguments

value, ...: One or more values to be appended to the end of array.

Returns

The new length of the array, after the specified values are appended to it.

Description

push( ) appends its arguments, in order, to the end of array. It modifies array directly, rather than creating a new array. push( ), and its companion method pop( ), use arrays to provide the functionality of a first in, last out stack. See Array.pop( ) for an example.

Bugs

In Netscape's implementations of JavaScript, when the language version is explicitly set to 1.2 this function returns the last value appended, rather than returning the new array length.

Availability

JavaScript 1.1; JScript 2.0; ECMAScript v1

Synopsis

array.reverse( )

Description

The reverse( ) method of an Array object reverses the order of the elements of an array. It does this "in place" -- it rearranges the elements of the specified array, without creating a new array. If there are multiple references to array, the new order of the array elements is visible through all references.

Example

a = new Array(1, 2, 3);    // a[0] == 1, a[2] == 3;
a.reverse( );             // Now a[0] == 3, a[2] == 1;

Array.shift( )

shift array elements down

Availability

JavaScript 1.2; JScript 5.5; ECMAScript v3

Synopsis

array.shift( )

Returns

The former first element of the array.

Description

shift( ) removes and returns the first element of array, shifting all subsequent elements down one place to occupy the newly vacant space at the start of the array. If the array is empty, shift( ) does nothing and returns the undefined value. Note that shift( ) does not create a new array; instead, it modifies array directly.

shift( ) is similar to Array.pop( ), except it operates on the beginning of an array rather than the end. shift( ) is often used in conjunction with unshift( ).

Example

var a = [1, [2,3], 4]
a.shift( );  // Returns 1; a = [[2,3], 4]
a.shift( );  // Returns [2,3]; a = [4]

Availability

JavaScript 1.2; JScript 3.0; ECMAScript v3

Synopsis

array.slice(start, end)

Arguments

start: The array index at which the slice is to begin. If negative, this argument specifies a position measured from the end of the array. That is, -1 indicates the last element, -2 indicates the second from last element, and so on.
end: The array index immediately after the end of the slice. If not specified, the slice includes all array elements from the start to the end of the array. If this argument is negative, it specifies an array element measured from the end of the array.

Returns

A new array that contains the elements of array from the element specified by start, up to, but not including, the element specified by end.

Description

slice( ) returns a slice, or subarray, of array. The returned array contains the element specified by start and all subsequent elements up to, but not including, the element specified by end. If end is not specified, the returned array contains all elements from the start to the end of array.

Note that slice( ) does not modify the array. If you want to actually remove a slice of an array, use Array.splice( ).

Example

var a = [1,2,3,4,5];
a.slice(0,3);    // Returns [1,2,3]
a.slice(3);      // Returns [4,5]
a.slice(1,-1);   // Returns [2,3,4]
a.slice(-3,-2);  // Returns [3]; buggy in IE 4: returns [1,2,3]

Bugs

start cannot be a negative number in Internet Explorer 4.

Availability

JavaScript 1.1; JScript 2.0; ECMAScript v1

Synopsis

array.sort( ) array.sort(orderfunc)

Arguments

orderfunc: An optional function used to specify the sorting order.

Returns

A reference to the array. Note that the array is sorted in place and no copy is made.

Description

The sort( ) method sorts the elements of array in place -- no copy of the array is made. If sort( ) is called with no arguments, the elements of the array are arranged in alphabetical order (more precisely, the order determined by the character encoding). To do this, elements are first converted to strings, if necessary, so that they can be compared.

If you want to sort the array elements in some other order, you must supply a comparison function that compares two values and returns a number indicating their relative order. The comparison function should take two arguments, a and b, and should return one of the following:

A value less than zero, if, according to your sort criteria, a is "less than" b and should appear before b in the sorted array.
Zero, if a and b are equivalent for the purposes of this sort.
A value greater than zero, if a is "greater than" b for the purposes of the sort.

Note that undefined elements of an array are always sorted to the end of the array. This is true even if you provide a custom ordering function: undefined values are never passed to the orderfunc you supply.

Example

The following code shows how you might write a comparison function to sort an array of numbers in numerical, rather than alphabetical order:

// An ordering function for a numerical sort
function numberorder(a, b) { return a - b; }

a = new Array(33, 4, 1111, 222);
a.sort( );             // Alphabetical sort: 1111, 222, 33, 4
a.sort(numberorder);    // Numerical sort: 4, 33, 222, 1111

Array.splice( )

insert, remove, or replace array elements

Availability

JavaScript 1.2; JScript 5.5; ECMAScript v3

Synopsis

array.splice(start, deleteCount, value, ...)

Arguments

start: The array element at which the insertion and/or deletion is to begin.
deleteCount: The number of elements, starting with and including start, to be deleted from array. This argument is optional; if not specified, splice( ) deletes all elements from start to the end of the array.
value, ...: Zero or more values to be inserted into array, beginning at the index specified by start.

Returns

An array containing the elements, if any, deleted from array. Note, however, that due to a bug, the return value is not always an array in the Netscape implementation of JavaScript 1.2.

Description

splice( ) deletes zero or more array elements starting with and including the element start and replaces them with zero or more values specified in the argument list. Array elements that appear after the insertion or deletion are moved as necessary so that they remain contiguous with the rest of the array. Note that, unlike the similarly named slice( ), splice( ) modifies array directly.

Example

The operation of splice( ) is most easily understood through an example:

var a = [1,2,3,4,5,6,7,8]
a.splice(4);        // Returns [5,6,7,8]; a is [1,2,3,4]
a.splice(1,2);      // Returns [2,3]; a is [1,4]
a.splice(1,1);      // Netscape/JavaScript 1.2 returns 4 instead of [4]
a.splice(1,0,2,3);  // Netscape/JavaScript 1.2 returns undefined instead of []

Bugs

splice( ) is supposed to return an array of deleted elements in all cases. However, in Netscape's JavaScript 1.2 interpreter, when a single element is deleted it returns that element rather than an array containing the element. Also, if no elements are deleted, it returns nothing instead of returning an empty array. Netscape implementions of JavaScript emulate this buggy behavior whenever Version 1.2 of the language is explicitly specified.

Availability

JavaScript 1.5; JScript 5.5; ECMAScript v1

Inherits from/Overrides

Overrides Object.toLocaleString( )

Synopsis

array.toLocaleString( )

Returns

A localized string representation of array.

Throws

TypeError: If this method is invoked on an object that is not an Array.

Description

The toString( ) method of an array returns a localized string representation of an array. It does this by calling the toLocaleString( ) method of all of the array elements, then concatenating the resulting strings using a locale-specific separator character.

Availability

JavaScript 1.1; JScript 2.0; ECMAScript v1

Inherits from/Overrides

Overrides Object.toString( )

Synopsis

array.toString( )

Returns

A string representation of array.

Throws

TypeError: If this method is invoked on an object that is not an Array.

Description

The toString( ) method of an array converts an array to a string and returns the string. When an array is used in a string context, JavaScript automatically converts it to a string by calling this method. On some occasions, however, you may want to call toString( ) explicitly.

toString( ) converts an array to a string by first converting each of the array elements to strings (by calling their toString( ) methods). Once each element is converted to a string, it outputs them in a comma-separated list. This return value is the same string that would be returned by the join( ) method with no arguments.

Bugs

In Netscape implementations, when Version 1.2 of the language is explicitly specified, toString( ) returns its list of comma-and-space-separated array elements within square brackets using array literal notation. This occurs, for example, when the language attribute of a <script> tag is explicitly specified as "JavaScript1.2".

Availability

JavaScript 1.2; JScript 5.5; ECMAScript v3

Synopsis

array.unshift(value, ...)

Arguments

value, ...: One or more values that are to be inserted at the start of array.

Returns

The new length of the array.

Description

unshift( ) inserts its arguments at the beginning of array, shifting the existing elements to higher indexes to make room. The first argument to shift( ) becomes the new element 0 of the array, the second argument, if any, becomes the new element 1, and so on. Note that unshift( ) does not create a new array; it modifies array directly.

Example

unshift( ) is often used in conjunction with shift( ). For example:

var a = [];             // a:[]
a.unshift(1);           // a:[1]          Returns: 1
a.unshift(22);          // a:[22,1]       Returns: 2
a.shift( );            // a:[1]          Returns: 22
a.unshift(33,[4,5]);    // a:[33,[4,5],1] Returns: 3

Availability

Boolean values are a fundamental data type in JavaScript. The Boolean object is an object wrapper around the boolean value. This Boolean object type exists primarily to provide a toString( ) method to convert boolean values to strings. When the toString( ) method is invoked to convert a boolean value to a string (and it is often invoked implicitly by JavaScript) JavaScript internally converts the boolean value to a transient Boolean object, on which the method can be invoked.

Inherits from/Overrides

Inherits from Object

Constructor

new Boolean(value) //Constructor function
Boolean(value) // Conversion function

Arguments

value: The value to be held by the Boolean object or to be converted to a boolean value.

Returns

When invoked as a constructor with the new operator, Boolean( ) converts its argument to a boolean value and returns a Boolean object that contains that value. When invoked as a function, without the new operator, Boolean( ) simply converts its argument to a primitive boolean value and returns that value.

The values 0, NaN, null, the empty string "", and the undefined value are all converted to false. All other primitive values, except false (but including the string "false"), and all objects and arrays are converted to true.

Methods

toString( ): Returns true or false, depending on the boolean value represented by the Boolean object.
valueOf( ): Returns the primitive boolean value contained in the Boolean object.

Description

Availability

JavaScript 1.1; JScript 2.0; ECMAScript v1

Inherits from/Overrides

Overrides Object.toString( )

Synopsis

b.toString( )

Returns

The string "true" or "false", depending on the value of the primitive boolean value or Boolean object b.

Throws

TypeError: If this method is invoked on an object that is not a Boolean.

Boolean.valueOf( )

the boolean value of a Boolean object

Availability

JavaScript 1.1; JScript 2.0; ECMAScript v1

Inherits from/Overrides

Overrides Object.valueOf( )

Synopsis

b.valueOf( )

Returns

The primitive boolean value held by the Boolean object b.

Throws

TypeError: If this method is invoked on an object that is not a Boolean.

Date

manipulate dates and times

Availability

With no arguments, the Date( ) constructor creates a Date object set to the current date and time. When one numeric argument is passed, it is taken as the internal numeric representation of the date in milliseconds, as returned by the getTime( ) method. When one string argument is passed, it is a string representation of a date, in the format accepted by the Date.parse( ) method. Otherwise, the constructor is passed between two and seven numeric arguments that specify the individual fields of the date and time. All but the first two arguments -- the year and month fields -- are optional. Note that these date and time fields are specified using local time, not UTC (similar to GMT) time. See the static Date.UTC( ) method for an alternative.

Inherits from/Overrides

Inherits from Object

Constructor

new Date( )
new Date(milliseconds)
new Date(datestring)
new Date(year, month, day, hours, minutes, seconds, ms)

Date( ) may also be called as a function, without the new operator. When invoked in this way, Date( ) ignores any arguments passed to it and returns a string representation of the current date and time.

Arguments

milliseconds

Methods

The Date object has no properties that can be read and written directly; instead, all access to date and time values is done through methods. Most methods of the Date object come in two forms: one that operates using local time, and one that operates using universal (UTC or GMT) time. If a method has "UTC" in its name, it operates using universal time. These pairs of methods are listed together below. For example, the listing for get[UTC]Day( ) refers to both the methods getDay( ) and getUTCDay( ).

Date methods may be invoked only on Date objects and throw a TypeError exception if you attempt to invoke them on any other type of object.

get[UTC]Date( ): Returns the day of the month of a Date object, in local or universal time.
get[UTC]Day( ): Returns the day of the week of a Date object, in local or universal time.
get[UTC]FullYear( ): Returns the year of the date in full four-digit form, in local or universal time.
get[UTC]Hours( ): Returns the hours field of a Date object, in local or universal time.
get[UTC]Milliseconds( ): Returns the milliseconds field of a Date object, in local or universal time.
get[UTC]Minutes( ): Returns the minutes field of a Date object, in local or universal time.
get[UTC]Month( ): Returns the month field of a Date object, in local or universal time.
get[UTC]Seconds( ): Returns the seconds field of a Date object, in local or universal time.
getTime( ): Returns the internal, millisecond representation of a Date object. Note that this value is independent of time zone, and therefore, there is not a separate getUTCTime( ) method.
getTimezoneOffset( ): Returns the difference, in minutes, between the local and UTC representations of this date. Note that the value returned depends on whether daylight savings time is or would be in effect at the specified date.
getYear( ): Returns the year field of a Date object. Deprecated in favor of getFullYear( ).
set[UTC]Date( ): Sets the day of the month field of the date, using local or universal time.
set[UTC]FullYear( ): Sets the year (and optionally month and day) of the date, using local or universal time.
set[UTC]Hours( ): Sets the hour (and optionally the minutes, seconds, and milliseconds fields) of the date, using local or universal time.
set[UTC]Milliseconds( ): Sets the milliseconds field of a date, using local or universal time.
set[UTC]Minutes( ): Sets the minutes field (and optionally the seconds and milliseconds fields) of a date, using local or universal time.
set[UTC]Month( ): Sets the month field (and optionally the day of the month) of a date, using local or universal time.
set[UTC]Seconds( ): Sets the seconds field (and optionally the milliseconds field) of a date, using local or universal time.
setTime( ): Sets the fields of a Date object using the millisecond format.
setYear( ): Sets the year field of a Date object. Deprecated in favor of setFullYear( ).
toDateString( ): Returns a string that represents the date portion of the date, expressed in the local time zone.
toGMTString( ): Converts a Date to a string, using the GMT time zone. Deprecated in favor of toUTCString( ).
toLocaleDateString( ): Returns a string that represents the date portion of the date, expressed in the local time zone, using the local date formatting conventions.
toLocaleString( ): Converts a Date to a string, using the local time zone and the local date formatting conventions.
toLocaleTimeString( ): Returns a string that represents the time portion of the date, expressed in the local time zone, using the local time formatting conventions.
toString( ): Converts a Date to a string using the local time zone.
toTimeString( ): Returns a string that represents the time portion of the date, expressed in the local time zone.
toUTCString( ): Converts a Date to a string, using universal time.
valueOf( ): Converts a Date to its internal millisecond format.

Static Methods

In addition to the many instance methods listed above, the Date object also defines two static methods. These methods are invoked through the Date( ) constructor itself, not through individual Date objects:

Date.parse( ): Parses a string representation of a date and time and returns the internal millisecond representation of that date.
Date.UTC( )

Description

The Date object is a data type built into the JavaScript language. Date objects are created with the new Date( ) syntax shown in the preceding Constructor section.

Once a Date object is created, there are a number of methods that allow you to operate on it. Most of the methods simply allow you to get and set the year, month, day, hour, minute, second, and millisecond fields of the object, using either local time or UTC (universal, or GMT) time. The toString( ) method and its variants convert dates to human-readable strings. getTime( ) and setTime( ) convert to and from the internal representation of the Date object -- the number of milliseconds since midnight (GMT) on January 1, 1970. In this standard millisecond format, a date and time are represented by a single integer, which makes date arithmetic particularly easy. The ECMAScript standard requires the Date object to be able to represent any date and time, to millisecond precision, within 100 million days before or after 1/1/1970. This is a range of plus or minus 273,785 years, so the JavaScript clock will not "roll over" until the year 275755.

Example

Once you create a Date object, there are a variety of methods you can use to operate on it:

d = new Date( );  // Get the current date and time
document.write('Today is: " + d.toLocaleDateString( ) + '. ');  // Display date
document.write('The time is: ' + d.toLocaleTimeString( ));      // Display time
var dayOfWeek = d.getDay( );                          // What weekday is it?
var weekend = (dayOfWeek == 0) || (dayOfWeek == 6);  // Is it a weekend?

Another common use of the Date object is to subtract the millisecond representations of the current time from some other time to determine the difference between the two times. The following client-side example shows two such uses:

<script language="JavaScript">
today = new Date( );      // Make a note of today's date
christmas = new Date( );  // Get a date with the current year
christmas.setMonth(11);    // Set the month to December...
christmas.setDate(25);     // and the day to the 25th

// If Christmas hasn't already passed, compute the number of
// milliseconds between now and Christmas, convert this
// to a number of days and print a message
if (today.getTime( ) < christmas.getTime( )) {
    difference = christmas.getTime( ) - today.getTime( );
    difference = Math.floor(difference / (1000 * 60 * 60 * 24));
    document.write('Only ' + difference + ' days until Christmas!<p>');
}
</script>

// ... rest of HTML document here ...

<script language="JavaScript">
// Here we use Date objects for timing
// We divide by 1000 to convert milliseconds to seconds
now = new Date( );
document.write('<p>It took ' +
    (now.getTime( )-today.getTime( ))/1000 +
    'seconds to load this page.');
</script>

Availability

return the day of the week

Synopsis

date.getDate( )

Returns

The day of the month of the specified Date object date, using local time. Return values are between 1 and 31.

Date.getDay( )

Availability

JavaScript 1.0; JScript 1.0; ECMAScript v1

Synopsis

date.getDay( )

Returns

The day of the week of the specified Date object date, using local time. Return values are between 0 (Sunday) and 6 (Saturday).

Date.getFullYear( )

return the year

Availability

return the hours field of a Date

Synopsis

date.getFullYear( )

Returns

The year that results when date is expressed in local time. The return value is a full four-digit year, including the century, not a two-digit abbreviation.

Date.getHours( )

Availability

JavaScript 1.0; JScript 1.0; ECMAScript v1

Synopsis

date.getHours( )

Returns

The hours field, expressed in local time, of the specified Date object date. Return values are between 0 (midnight) and 23 (11 p.m.).

Date.getMilliseconds( )

return the milliseconds field of a Date

Availability

return the minutes field of a Date

Synopsis

date.getMilliseconds( )

Returns

The milliseconds field, expressed in local time, of date.

Date.getMinutes( )

Availability

JavaScript 1.0; JScript 1.0; ECMAScript v1

Synopsis

date.getMinutes( )

Returns

The minutes field, expressed in local time, of the specified Date object date. Return values are between 0 and 59.

Date.getMonth( )

return the month of a Date

Availability

JavaScript 1.0; JScript 1.0; ECMAScript v1

Synopsis

date.getMonth( )

Returns

The month field, expressed in local time, of the specified Date object date. Return values are between 0 ( January) and 11 (December).

Date.getSeconds( )

return the seconds field of a Date

Availability

JavaScript 1.0; JScript 1.0; ECMAScript v1

Synopsis

date.getSeconds( )

Returns

The seconds field, expressed in local time, of the specified Date object date. Return values are between 0 and 59.

Date.getTime( )

return a Date in milliseconds

Availability

JavaScript 1.0; JScript 1.0; ECMAScript v1

Synopsis

date.getTime( )

Returns

The millisecond representation of the specified Date object date; that is, the number of milliseconds between midnight (GMT) on 1/1/1970 and the date and time specified by date.

Description

getTime( ) converts a date and time to a single integer. This is useful when you want to compare two Date objects or to determine the time elapsed between two dates. Note that the millisecond representation of a date is independent of the time zone, so there is no getUTCTime( ) method in addition to this one. Don't confuse this getTime( ) method with the getDay( ) and getDate( ) methods, which return the day of the week and the day of the month, respectively.

Date.parse( ) and Date.UTC( ) allow you to convert a date and time specification to millisecond representation without going through the overhead of first creating a Date object.

Availability

JavaScript 1.0; JScript 1.0; ECMAScript v1

Synopsis

date.getTimezoneOffset( )

Returns

The difference, in minutes, between Greenwich Mean Time (GMT) and local time.

Description

getTimezoneOffset( ) returns the number of minutes difference between the GMT or UTC time and the local time. In effect, this function tells you what time zone the JavaScript code is running in and whether or not daylight savings time is (or would be) in effect at the specified date.

The return value is measured in minutes, rather than hours, because some countries have time zones that are not at even one-hour intervals.

Date.getUTCDate( )

return the day of the month (universal time)

Availability

The day of the month (a value between 1 and 31) that results when date is expressed in universal time.

Synopsis

date.getUTCDate( )

Returns

Date.getUTCDay( )

return the day of the week (universal time)

Availability

return the year (universal time)

Synopsis

date.getUTCDay( )

Returns

The day of the week that results when date is expressed in universal time. Return values are between 0 (Sunday) and 6 (Saturday).

Date.getUTCFullYear( )

Availability

JavaScript 1.2; JScript 3.0; ECMAScript v1

Synopsis

date.getUTCFullYear( )

Returns

The year that results when date is expressed in universal time. The return value is a full four-digit year, not a two-digit abbreviation.

Date.getUTCHours( )

return the hours field of a Date (universal time)

Availability

JavaScript 1.2; JScript 3.0; ECMAScript v1

Synopsis

date.getUTCHours( )

Returns

The hours field, expressed in universal time, of date. The return value is an integer between 0 (midnight) and 23 (11 p.m.).

Date.getUTCMilliseconds( )

return the milliseconds field of a Date (universal time)

Availability

JavaScript 1.2; JScript 3.0; ECMAScript v1

Synopsis

date.getUTCMilliseconds( )

Returns

The milliseconds field, expressed in universal time, of date.

Date.getUTCMinutes( )

return the minutes field of a Date (universal time)

Availability

return the month of the year (universal time)

Synopsis

date.getUTCMinutes( )

Returns

The minutes field, expressed in universal time, of date. The return value is an integer between 0 and 59.

Date.getUTCMonth( )

Availability

return the seconds field of a Date (universal time)

Synopsis

date.getUTCMonth( )

Returns

The month of the year that results when date is expressed in universal time. The return value is an integer between 0 ( January) and 11 (December). Note that the Date object represents the first day of the month as 1 but represents the first month of the year as 0.

Date.getUTCSeconds( )

Availability

JavaScript 1.2; JScript 3.0; ECMAScript v1

Synopsis

date.getUTCSeconds( )

Returns

The seconds field, expressed in universal time, of date. The return value is an integer between 0 and 59.

Date.getYear( )

return the year field of a Date

Availability

JavaScript 1.0; JScript 1.0; ECMAScript v1; deprecated by ECMAScript v3

Synopsis

date.getYear( )

Returns

The year field of the specified Date object date minus 1900.

Description

getYear( ) returns the year field of a specified Date object minus 1900. As of ECMAScript v3, it is not required in conforming JavaScript implementations; use getFullYear( ) instead.

Bugs

Netscape implementations of JavaScript 1.0 through 1.2 subtract 1900 only for years between 1900 and 1999.

Date.parse( )

parse a date/time string

Availability

Synopsis

Date.parse(date)

Arguments

date: A string containing the date and time to be parsed.

Returns

The number of milliseconds between the specified date and time and midnight GMT on January 1, 1970.

Description

Date.parse( ) is a static method of Date. It is always invoked through the Date constructor as Date.parse( ), not through a Date object as date.parse( ). Date.parse( ) takes a single string argument. It parses the date contained in this string and returns it in millisecond format, which can be used directly, used to create a new Date object, or used to set the date in an existing Date object with Date.setTime( ).

The ECMAScript standard does not specify the format of the strings that can be parsed by Date.parse( ) except to say that this method can parse the strings returned by the Date.toString( ) and Date.toUTCString( ) methods. Unfortunately, these functions format dates in an implementation-dependent way, so it is not in general possible to write dates in a way that is guaranteed to be understood by all JavaScript implementations.

Availability

set the year and, optionally, the month and date

Synopsis

date.setDate(day_of_month)

Arguments

day_of_month: An integer between 1 and 31 that is used as the new value (in local time) of the day-of-month field of date.

Returns

The millisecond representation of the adjusted date. Prior to ECMAScript standardization, this method returns nothing.

Date.setFullYear( )

Availability

set the hours, minutes, seconds, and milliseconds fields of a Date

Synopsis

date.setFullYear(year)
date.setFullYear(year, month) 
date.setFullYear(year, month, day)

Arguments

year: The year, expressed in local time, to be set in date. This argument should be an integer that includes the century, such as 1999; it should not be an abbreviation, such as 99.
month: An optional integer, between 0 and 11 that is used as the new value (in local time) of the month field of date.
day: An optional integer, between 1 and 31 that is used as the new value (in local time) of the day-of-month field of date.

Returns

The internal millisecond representation of the adjusted date.

Date.setHours( )

Availability

set the milliseconds field of a Date

Synopsis

date.setHours(hours)
date.setHours(hours, minutes) 
date.setHours(hours, minutes,
seconds) 
date.setHours(hours, minutes, seconds, millis)

Arguments

hours: An integer between 0 (midnight) and 23 (11 p.m.) local time that is set as the new hours value of date.
minutes: An optional integer, between 0 and 59, that is used as the new value (in local time) of the minutes field of date. This argument is not supported prior to ECMAScript standardization.
seconds: An optional integer, between 0 and 59, that is used as the new value (in local time) of the seconds field of date. This argument is not supported prior to ECMAScript standardization.
millis: An optional integer, between 0 and 999, that is used as the new value (in local time) of the milliseconds field of date. This argument is not supported prior to ECMAScript standardization.

Returns

The millisecond representation of the adjusted date. Prior to ECMAScript standardization, this method returns nothing.

Date.setMilliseconds( )

Availability

set the minutes and seconds fields of a Date

Synopsis

date.setMilliseconds(millis)

Arguments

millis: The milliseconds field, expressed in local time, to be set in date. This argument should be an integer between 0 and 999.

Returns

The millisecond representation of the adjusted date.

Date.setMinutes( )

Availability

set the month and day fields of a Date

Synopsis

date.setMinutes(minutes) 
date.setMinutes(minutes, seconds) 
date.setMinutes(minutes, seconds, millis)

Arguments

minutes: An integer between 0 and 59 that is set as the minutes value (in local time) of the Date object date.
seconds: An optional integer, between 0 and 59, that is used as the new value (in local time) of the seconds field of date. This argument is not supported prior to ECMAScript standardization.
millis: An optional integer, between 0 and 999, that is used as the new value (in local time) of the milliseconds field of date. This argument is not supported prior to ECMAScript standardization.

Returns

The millisecond representation of the adjusted date. Prior to ECMAScript standardization, this method returns nothing.

Date.setMonth( )

Availability

set the seconds and milliseconds fields of a Date

Synopsis

date.setMonth(month)
date.setMonth(month, day)

Arguments

month: An integer between 0 ( January) and 11 (December) that is set as the month value (in local time) for the Date object date. Note that months are numbered beginning with 0, while days within the month are numbered beginning with 1.
day: An optional integer, between 1 and 31 that is used as the new value (in local time) of the day-of-month field of date. This argument is not supported prior to ECMAScript standardization.

Returns

The millisecond representation of the adjusted date. Prior to ECMAScript standardization, this method returns nothing.

Date.setSeconds( )

Availability

set a Date in milliseconds

Synopsis

date.setSeconds(seconds) 
date.setSeconds(seconds, millis)

Arguments

seconds: An integer between 0 and 59 that is set as the seconds value for the Date object date.
millis: An optional integer, between 0 and 999, that is used as the new value (in local time) of the milliseconds field of date. This argument is not supported prior to ECMAScript standardization.

Returns

The millisecond representation of the adjusted date. Prior to ECMAScript standardization, this method returns nothing.

Date.setTime( )

Availability

set the day of the month (universal time)

Synopsis

date.setTime(milliseconds)

Arguments

milliseconds: The number of milliseconds between the desired date and time and midnight GMT on January 1, 1970. A millisecond value of this type may also be passed to the Date( ) constructor and may be obtained by calling the Date.UTC( ) and Date.parse( ) methods. Representing a date in this millisecond format makes it independent of time zone.

Returns

The milliseconds argument. Prior to ECMAScript standardization, this method returns nothing.

Date.setUTCDate( )

Availability

set the year, month, and day (universal time)

Synopsis

date.setUTCDate(day_of_month)

Arguments

day_of_month: The day of the month, expressed in universal time, to be set in date. This argument should be an integer between 1 and 31.

Returns

The internal millisecond representation of the adjusted date.

Date.setUTCFullYear( )

Availability

set the hours, minutes, seconds, and milliseconds fields of a Date (universal time)

Synopsis

date.setUTCFullYear(year)
date.setUTCFullYear(year, month)
date.setUTCFullYear(year, month, day)

Arguments

year: The year, expressed in universal time, to be set in date. This argument should be an integer that includes the century, such as 1999, not be an abbreviation, such as 99.
month: An optional integer, between 0 and 11 that is used as the new value (in universal time) of the month field of date.
day: An optional integer, between 1 and 31 that is used as the new value (in universal time) of the day-of-month field of date.

Returns

The internal millisecond representation of the adjusted date.

Date.setUTCHours( )

Availability

set the milliseconds field of a Date (universal time)

Synopsis

date.setUTCHours(hours) 
date.setUTCHours(hours, minutes) 
date.setUTCHours(hours, minutes, seconds) 
date.setUTCHours(hours,minutes, seconds, millis)

Arguments

hours: The hours field, expressed in universal time, to be set in date. This argument should be an integer between 0 (midnight) and 23 (11 p.m.).
minutes: An optional integer, between 0 and 59, that is used as the new value (in universal time) of the minutes field of date.
seconds: An optional integer, between 0 and 59, that is used as the new value (in universal time) of the seconds field of date.
millis: An optional integer, between 0 and 999, that is used as the new value (in universal time) of the milliseconds field of date.

Returns

The millisecond representation of the adjusted date.

Date.setUTCMilliseconds( )

Availability

set the minutes and seconds fields of a Date (universal time)

Synopsis

date.setUTCMilliseconds(millis)

Arguments

millis: The milliseconds field, expressed in universal time, to be set in date. This argument should be an integer between 0 and 999.

Returns

The millisecond representation of the adjusted date.

Date.setUTCMinutes( )

Availability

set the month and day fields of a Date (universal time)

Synopsis

date.setUTCMinutes(minutes) 
date.setUTCMinutes(minutes, seconds) 
date.setUTCMinutes(minutes, seconds, millis)

Arguments

minutes: The minutes field, expressed in universal time, to be set in date. This argument should be an integer between 0 and 59.
seconds: An optional integer, between 0 and 59, that is used as the new value (in universal time) of the seconds field of date.
millis: An optional integer, between 0 and 999, that is used as the new value (in universal time) of the milliseconds field of date.

Returns

The millisecond representation of the adjusted date.

Date.setUTCMonth( )

Availability

set the seconds and milliseconds fields of a Date (universal time)

Synopsis

date.setUTCMonth(month) 
date.setUTCMonth(month, day)

Arguments

month: The month, expressed in universal time, to be set in date. This argument should be an integer between 0 ( January) and 11 (December). Note that months are numbered beginning with 0, while days within the month are numbered beginning with 1.
day: An optional integer, between 1 and 31 that is used as the new value (in universal time) of the day-of-month field of date.

Returns

The millisecond representation of the adjusted date.

Date.setUTCSeconds( )

Availability

set the year field of a Date

Synopsis

date.setUTCSeconds(seconds) 
date.setUTCSeconds(seconds, millis)

Arguments

seconds: The seconds field, expressed in universal time, to be set in date. This argument should be an integer between 0 and 59.
millis: An optional integer, between 0 and 999, that is used as the new value (in universal time) of the milliseconds field of date.

Returns

The millisecond representation of the adjusted date.

Date.setYear( )

Availability

JavaScript 1.0; JScript 1.0; ECMAScript v1; deprecated by ECMAScript v3

Synopsis

date.setYear(year)

Arguments

year: An integer that is set as the year value (in local time) for the Date object date. If this value is between 0 and 99, inclusive, 1900 is added to it and it is treated as a year between 1900 and 1999.

Returns

The millisecond representation of the adjusted date. Prior to ECMAScript standardization, this method returns nothing.

Description

setYear( ) sets the year field of a specified Date object, with special behavior for years between 1900 and 1999.

As of ECMAScript v3, this function is no longer required in conforming JavaScript implementations; use setFullYear( ) instead.

Date.toDateString( )

return the date portion of a Date as a string

Availability

JavaScript 1.0; JScript 1.0; ECMAScript v1; deprecated by ECMAScript v3

Synopsis

date.toDateString( )

Returns

An implementation-dependent human-readable string representation of the date portion of date, expressed in the local time zone.

Availability

Synopsis

date.toGMTString( )

Returns

A string representation of the date and time specified by the Date object date. The date is converted from the local time zone to the GMT time zone before being converted to a string.

Description

toGMTString( ) is deprecated in favor of the identical method Date.toUTCString( ).

As of ECMAScript v3, conforming implementations of JavaScript are no longer required to provide this method; use toUTCString( ) instead.

Availability

JavaScript 1.5; JScript 5.5; ECMAScript v3

Synopsis

date.toLocaleDateString( )

Returns

An implementation-dependent human-readable string representation of the date portion of date, expressed in the local time zone and formatted according to local conventions.

Availability

JavaScript 1.0; JScript 1.0; ECMAScript v1

Synopsis

date.toLocaleString( )

Returns

A string representation of the date and time specified by date. The date and time are represented in the local time zone and formatted using locally appropriate conventions.

Usage

toLocaleString( ) converts a date to a string, using the local time zone. This method also uses local conventions for date and time formatting, so the format may vary from platform to platform and from country to country. toLocaleString( ) returns a string formatted in what is likely the user's preferred date and time format.

Availability

JavaScript 1.0; JScript 1.0; ECMAScript v1 Overrides Object.toString( )

Synopsis

date.toLocaleTimeString( )

Returns

An implementation-dependent human-readable string representation of the time portion of date, expressed in the local time zone and formatted according to local conventions.

Availability

Synopsis

date.toString( )

Returns

A human-readable string representation of date, expressed in the local time zone.

Description

toString( ) returns a human-readable, implementation-dependent string representation of date. Unlike toUTCString( ), toString( ) expresses the date in the local time zone. Unlike toLocaleString( ), toString( ) may not represent the date and time using locale-specific formatting.

Availability

Synopsis

date.toTimeString( )

Returns

A implementation-dependent human-readable string representation of the time portion of date, expressed in the local time zone.

Availability

Synopsis

date.toUTCString( )

Returns

A human-readable string representation, expressed in universal time, of date.

Description

toUTCString( ) returns an implementation-dependent string that represents date in universal time.

Availability

JavaScript 1.1; ECMAScript v1

Synopsis

Date.UTC(year, month, day, hours, minutes, seconds, ms)

Arguments

year: The year in four-digit format. If this argument is between 0 and 99, inclusive, 1900 will be added to it and it will be treated as a year between 1900 and 1999.
month: The month, specified as an integer from 0 ( January) to 11 (December).
day: The day of the month, specified as an integer from 1 to 31. Note that this argument uses 1 as its lowest value, while other arguments use 0 as their lowest value. This argument is optional.
hours: The hour, specified as an integer from 0 (midnight) to 23 (11 p.m.). This argument is optional.
minutes: The minutes in the hour, specified as an integer from 0 to 59. This argument is optional.
seconds: The seconds in the minute, specified as an integer from 0 to 59. This argument is optional.
ms: The number of milliseconds. This argument is optional and is ignored prior to ECMAScript standardization.

Returns

The millisecond representation of the specified universal time. That is, this method returns the number of milliseconds between midnight GMT on January 1, 1970 and the specified time.

Description

Date.UTC( ) is a static method; it is invoked through the Date( ) constructor, not through an individual Date object.

The arguments to Date.UTC( ) specify a date and time and are understood to be in UTC (Universal Coordinated Time) -- they are in the GMT time zone. The specified UTC time is converted to the millisecond format, which can be used by the Date( ) constructor method and by the Date.setTime( ) method.

The Date( ) constructor method can accept date and time arguments identical to those that Date.UTC( ) accepts. The difference is that the Date( ) constructor assumes local time, while Date.UTC( ) assumes universal time (GMT). To create a Date object using a UTC time specification, you can use code like this:

d = new Date(Date.UTC(1996, 4, 8, 16, 30));

Availability

Inherits from/Overrides

Overrides Object.valueOf( )

Synopsis

date.valueOf( )

Returns

The millisecond representation of date. The value returned is the same as that returned by Date.getTime( ).

decodeURI( )

unescape characters in a URI

Availability

Synopsis

decodeURI( uri)

Arguments

uri: A string that contains an encoded URI or other text to be decoded.

Returns

A copy of uri, with any hexadecimal escape sequences replaced with the characters they represent.

Throws

URIError: Indicates that one or more of the escape sequences in uri is malformed and cannot be correctly decoded.

Description

decodeURI( ) is a global function that returns a decoded copy of its uri argument. It reverses the encoding performed by encodeURI( ); see that function for details.

Availability

Synopsis

decodeURI(s)

Arguments

s: A string that contains an encoded URI component or other text to be decoded.

Returns

A copy of s, with any hexadecimal escape sequences replaced with the characters they represent.

Throws

URIError: Indicates that one or more of the escape sequences in s is malformed and cannot be correctly decoded.

Description

decodeURIComponent( ) is a global function that returns a decoded copy of its s argument. It reverses the encoding performed by encodeURIComponent( ). See that function's reference page for details.

Availability

Synopsis

encodeURI(uri)

Arguments

uri: A string that contains the URI or other text to be encoded.

Returns

A copy of uri, with certain characters replaced by hexadecimal escape sequences.

Throws

URIError: Indicates that uri contains malformed Unicode surrogate pairs and cannot be encoded.

Description

encodeURI( ) is a global function that returns an encoded copy of its uri argument. ASCII letters and digits are not encoded, nor are the following ASCII punctuation characters:

- _ . ! ~ * ' ( )

Because encodeURI( ) is intended to encode complete URIs, the following ASCII punctuation characters, which have special meaning in URIs, are not escaped either:

; / ? : @ & = + $ , #

Any other characters in uri are replaced by converting the character to its UTF-8 encoding and then encoding each of the resulting one, two, or three bytes with a hexadecimal escape sequence of the form %xx. In this encoding scheme, ASCII characters are replaced with a single %xx escape, characters with encodings between \u0080 and \u07ff are replaced with two escape sequences, and all other 16-bit Unicode characters are replaced with three escape sequences.

If you use this method to encode a URI, you should be certain that none of the components of the URI (such as the query string) contain URI separator characters such as ? and #. If the components may contain these characters, you should encode each component separately with encodeURIComponent( ).

Use decodeURI( ) to reverse the encoding applied by this method. Prior to ECMAScript v3, you can use escape( ) and unescape( ) methods (which are now deprecated) to perform a similar kind of encoding and decoding.

Example

// Returns http://www.isp.com/app.cgi?arg1=1&arg2=hello%20world
encodeURI("http://www.isp.com/app.cgi?arg1=1&arg2=hello world");
encodeURI("\u00a9");  // The copyright character encodes to %C2%A9

Availability

Synopsis

encodeURIComponent(s)

Arguments

s: A string that contains a portion of a URI or other text to be encoded.

Returns

A copy of s, with certain characters replaced by hexadecimal escape sequences.

Throws

URIError: Indicates that s contains malformed Unicode surrogate pairs and cannot be encoded.

Description

encodeURIComponent( ) is a global function that returns an encoded copy of its s argument. ASCII letters and digits are not encoded, nor are the following ASCII punctuation characters:

- _ . ! ~ * ' ( )

All other characters, including punctuation characters such as /, :, # that serve to separate the various components of a URI, are replaced with one or more hexadecimal escape sequences. See encodeURI( ) for a description of the encoding scheme used.

Note the difference between encodeURIComponent( ) and encodeURI( ): encodeURIComponent( ) assumes that its argument is a portion (such as the protocol, hostname, path, or query string) of a URI. Therefore it escapes the punctuation characters that are used to separate the portions of a URI.

Example

encodeURIComponent("hello world?");  // Returns hello%20world%3F

Availability

Inherits from/Overrides

Inherits from Object

Constructor

new Error( )
new Error(message)

Arguments

message: An optional error message that provides details about the exception.

Returns

A newly constructed Error object. If the message argument is specified, the Error object will use it as the value of its message property; otherwise, it will use an implementation-defined default string as the value of that property. When the Error( ) constructor is called as a function, without the new operator, it behaves just as it does when called with the new operator.

The JavaScript interpreter never throws Error object directly; instead, it throws instances of one of the Error subclasses such as SyntaxError or RangeError. In your own code you may find it convenient to throw Error objects to signal exceptions, or you may prefer to simply throw an error message or error code as a primitive string or number value.

Note that the ECMAScript specification defines a toString( ) method for the Error class (it is inherited by each of the subclasses of Error) but that it does not require this toString( ) method to return a string that contains the contents of the message property. Therefore, you should not expect the toString( ) method to convert an Error object to convert to a meaningful human-readable string. To display an error message to a user, you should explicitly use the name and message properties of the Error object.

Example

You might signal an exception with code like the following:

function factorial(x) {
    if (x < 0) throw new Error("factorial: x must be >= 0");
    if (x <= 1) return 1; else return x * factorial(x-1);
}

And if you catch an exception, you might display its to the user with code like the following (which uses the client-side Window.alert( ) method):

try { &*(&/* an error is thrown here */ }
catch(e) {
    if (e instanceof Error) {  // Is it an instance of Error or a subclass?
        alert(e.name + ": " + e.message);
    }
}

Availability

convert an Error object to a string

Synopsis

error.message

Description

The message property of an Error object (or of an instance of any subclass of Error) is intended to contain a human-readable string that provides details about the error or exception that occurred. If a message argument is passed to the Error( ) constructor, this message becomes the value of the message property. If no message argument is passed, an Error object inherits an implementation-defined default value (which may be the empty string) for this property.

Error.name

the type of an error

Availability

JavaScript 1.5; JScript 5.5; ECMAScript v3

Synopsis

error.name

Description

The name property of an Error object (or of an instance of any subclass of Error) specifies the type of error or exception that occurred. All Error objects inherit this property from their constructor. The value of the property is the same as the name of the constructor. Thus SyntaxError objects have a name property of "SyntaxError" and EvalError objects have a name of "EvalError".

Error.toString( )

Availability

JavaScript 1.5; JScript 5.5; ECMAScript v3

Inherits from/Overrides

Overrides Object.toString( )

Synopsis

error.toString( )

Returns

An implementation-defined string. The ECMAScript standard does not specify anything about the return value of this method, except that it is a string. Notably, it does not require the returned string to contain the error name or the error message.

escape( )

encode a string

Availability

JavaScript 1.0; JScript 1.0; ECMAScript v1; deprecated in ECMAScript v3

Synopsis

escape(s)

Arguments

s: The string that is to be "escaped" or encoded.

Returns

An encoded copy of s in which certain characters have been replaced by hexadecimal escape sequences.

Description

escape( ) is a global function. It returns a new string that contains an encoded version of s. The string s itself is not modified.

escape( ) returns a string in which all characters of s other than ASCII letters, digits, and the punctuation characters @, *, _, +, -, ., and / have been replaced by escape sequences of the form %xx or %uxxxx (where x represents a hexadecimal digit). Unicode characters \u0000 to \u00ff are replaced with the %xx escape sequence, and all other Unicode characters are replaced with the %uxxxx sequence.

Use the unescape( ) function to decode a string encoded with escape( ).

In client-side JavaScript, a common use of escape( ) is to encode cookie values, which have restrictions on the punctuation characters they may contain. See the Document.cookie reference page in the client-side reference section.

Although the escape( ) function was standardized in the first version of ECMAScript, it has been deprecated and removed from the standard by ECMAScript v3. Implementations of ECMAScript are likely to implement this function, but they are not required to. In JavaScript 1.5 and JScript 5.5 and later, you should use encodeURI( ) and encodeURIComponent( ) instead of escape( ).

Example

escape("Hello World!");  // Returns "Hello%20World%21"

Availability

JavaScript 1.0; JScript 1.0; ECMAScript v1

Synopsis

eval(code)

Arguments

code: A string that contains the JavaScript expression to be evaluated or the statements to be executed.

Returns

The value of the evaluated code, if any.

Throws

SyntaxError: Indicates that code does not contain legal JavaScript.
EvalError: Indicates that eval( ) was called illegally, through an identifier other than "eval", for example. See the restrictions on this function described below.
Other exception: If the JavaScript code passed to eval( ) generates an exception, eval( ) will pass that exception on to the caller.

Description

eval( ) is a global method that evaluates a string containing JavaScript code. If code contains an expression, eval evaluates the expression and returns its value. If code contains a JavaScript statement or statements, eval( ) executes those statements and returns the value, if any, returned by the last statement. If code does not return any value, eval( ) returns undefined. Finally, if code throws an exception, eval( ) passes that exception on to the caller.

eval( ) provides a very powerful capability to the JavaScript language, but its use is infrequent in real-world programs. Obvious uses are to write programs that act as recursive JavaScript interpreters and to write programs that dynamically generate and evaluate JavaScript code.

Most JavaScript functions and methods that expect string arguments accept arguments of other types as well and simply convert those argument values to strings before proceeding. eval( ) does not behave like this. If the code argument is not a primitive string, it is simply returned unchanged. Be careful, therefore, that you do not inadvertently pass a String object to eval( ) when you intended to pass a primitive string value.

For purposes of implementation efficiency, the ECMAScript v3 standard places an unusual restriction on the use of eval( ). An ECMAScript implementation is allowed to throw an EvalError exception if you attempt to overwrite the eval property or if you assign the eval( ) method to another property and attempt to invoke it through that property.

Example

eval("1+2");  // Returns 3

// This code uses client-side JavaScript methods to prompt the user to
// enter an expression and to display the results of evaluating it.
// See the client-side methods Window.alert( ) and Window.prompt( ) for details.
try {
    alert("Result: " +  eval(prompt("Enter an expression:","")));
}
catch(exception) {
    alert(exception);
}

var myeval = eval;  // May throw an EvalError
myeval("1+2");      // May throw an EvalError

EvalError

thrown when eval( ) is used improperly

Availability

Inherits from/Overrides

Inherits from Error

Constructor

new EvalError( )
new EvalError(message)

Arguments

message: An optional error message that provides details about the exception. If specified, this argument is used as the value for the message property of the EvalError object.

Returns

A newly constructed EvalError object. If the message argument is specified, the Error object will use it as the value of its message property; otherwise, it will use an implementation-defined default string as the value of that property. When the EvalError( ) constructor is called as a function, without the new operator, it behaves just as it does when called with the new operator.

Properties

message: An error message that provides details about the exception. This property holds the string passed to the constructor or an implementation-defined default string. See Error.message for details.
name: A string that specifies the type of the exception. All EvalError objects inherit the value "EvalError" for this property.

Description

An instance of the EvalError class may be thrown when the global function eval( ) is invoked under any other name. See eval( ) for an explanation of the restrictions on how this function may be invoked. See Error for details about throwing and catching exceptions.

Availability

JavaScript 1.2; JScript 5.5; ECMAScript v3

Inherits from/Overrides

Inherits from Object

Synopsis

function functionname(argument_name_list) // Function definition statement 
{
    body 
} 
function (argument_name_list) { body } // Unnamed function literal; JavaScript 1.2 
functionname(argument_value_list)      // Function invocation

Constructor

new Function(argument_names..., body) // JavaScript 1.1 and later

Arguments

argument_names...: Any number of string arguments, each naming one or more arguments of the Function object being created.
body: A string that specifies the body of the function. It may contain any number of JavaScript statements, separated with semicolons, and may refer to any of the argument names specified by previous arguments to the constructor.

Returns

A newly created Function object. Invoking the function executes the JavaScript code specified by body.

Throws

SyntaxError: Indicates that there was a JavaScript syntax error in the body argument or in one of the argument_names arguments.

Properties

arguments[]: An array of arguments that were passed to the function. Deprecated.
caller: A reference to the Function object that invoked this one, or null if the function was invoked from top-level code. Deprecated.
length: The number of named arguments specified when the function was declared.
prototype: An object which, for a constructor function, defines properties and methods shared by all objects created with that constructor function.

Methods

apply( ): Invokes a function as a method of a specified object, passing a specified array of arguments.
call( ): Invokes a function as a method of a specified object, passing the specified arguments.
toString( ): Returns a string representation of the function.

Description

A function is a fundamental data type in JavaScript. Chapter 7 explains how to define and use functions, and Chapter 8 covers the related topics of methods, constructors, and the prototype property of functions. See those chapters for complete details. Note that although function objects may be created with the Function( ) constructor described here, this is not efficient, and the preferred way to define functions, in most cases, is with a function definition statement or a function literal.

In JavaScript 1.1 and later, the body of a function is automatically given a local variable, named arguments, that refers to an Arguments object. This object is an array of the values passed as arguments to the function. Don't confuse this with the deprecated arguments[] property listed above. See the Arguments reference page for details.

Availability

Synopsis

function.apply(thisobj, args)

Arguments

thisobj: The object to which function is to be applied. In the body of the function, thisobj becomes the value of the this keyword.
args: An array of values to be passed as arguments to function.

Returns

Whatever value is returned by the invocation of function.

Throws

TypeError: If this method is invoked on an object that is not a function or if this method is invoked with an args argument that is not an array or an Arguments object.

Description

apply( ) invokes the specified function as if it were a method of thisobj, passing it the arguments contained in the args array. It returns the value returned by the function invocation. Within the body of the function, the this keyword refers to the thisobj object.

The args argument must be an array or an Arguments object. Use Function.call( ) instead if you want to specify the arguments to pass to the function individually instead of as array elements.

Example

// Apply the default Object.toString( ) method to an object that
// overrides it with its own version of the method. Note no arguments.
Object.prototype.toString.apply(o);

// Invoke the Math.max( ) method with apply to find the largest
// element in an array. Note that first argument doesn't matter
// in this case.
var data = [1,2,3,4,5,6,7,8];
Math.max.apply(null, data);

Availability

JavaScript 1.0; JScript 1.0; ECMAScript v1; deprecated by ECMAScript v3

Synopsis

function.arguments[i] 
function.arguments.length

Description

The arguments property of a Function object is an array of the arguments that are passed to a function. It is only defined while the function is executing. arguments.length specifies the number of elements in the array.

This property is deprecated in favor of the Arguments object. Although ECMAScript v1 supports the Function.arguments property, it has been removed from ECMAScript v3 and conforming implementations may no longer support this property. Therefore, it should never be used in new JavaScript code.

Availability

JavaScript 1.0, JScript 2.0; deprecated by ECMAScript

Synopsis

function.call(thisobj, args...)

Arguments

thisobj: The object on which function is to be invoked. In the body of the function, thisobj becomes the value of the this keyword.
args...: Any number of arguments, which will be passed as arguments to function.

Returns

Whatever value is returned by the invocation of function.

Throws

TypeError: If this method is invoked on an object that is not a function.

Description

call( ) invokes the specified function as if it were a method of thisobj, passing it any arguments that follow thisobj in the argument list. The return value of call( ) is the value returned by the function invocation. Within the body of the function, the this keyword refers to the thisobj object.

Use Function.apply( ) instead if you want to specify the arguments to pass to the function in an array.

Example

// Call the default Object.toString( ) method on an object that
// overrides it with its own version of the method. Note no arguments.
Object.prototype.toString.call(o);

Availability

Synopsis

function.caller

Description

In early versions of JavaScript, the caller property of a Function object is a reference to the function that invoked the current one. If the function was invoked from the top level of a JavaScript program, caller is null. This property may only be used from within the function (i.e., the caller property is only defined for a function while that function is executing).

Function.caller is not part of the ECMAScript standard and is not required in conforming implementations. It should not be used.

Function.length

the number of declared arguments

Availability

The length property of a function specifies the number of named arguments declared when the function was defined. The function may actually be invoked with more than or fewer than this number of arguments. Don't confuse this property of a Function object with the length property of the Arguments object which specifies the number of arguments actually passed to the function. See Arguments.length for an example.

Synopsis

function.length

Description

Availability

The prototype property is used when a function is used as a constructor. It refers to an object that serves as the prototype for an entire class of objects. Any object created by the constructor inherits all properties of the object referred to by the prototype property.

Synopsis

function.prototype

Description

See Chapter 8 for a full discussion of constructor functions, the prototype property, and the definition of classes in JavaScript.

Bugs

JavaScript 1.1 requires a constructor to be used once before anything can be assigned to its prototype object.

Availability

JavaScript 1.0; JScript 2.0; ECMAScript v1

Synopsis

function.toString( )

Returns

A string that represents the function.

Throws

TypeError: If this method is invoked on an object that is not a Function.

Description

The toString( ) method of the Function object converts a function to a string in an implementation-dependent way. In Netscape implementations, this method returns a string of valid JavaScript code -- code that includes the function keyword, argument list, the complete body of the function, and so on.

Global

the global object

Availability

The global object is not a class, so the following global properties have individual reference entries under their own name. That is, you can find details on the undefined property listed under the name "undefined," not under "Global.undefined." Note that all top-level variables are also properties of the global object.

Synopsis

this

Global Properties

Infinity: A numeric value that represents positive infinity.
NaN: The not-a-number value.
undefined: The undefined value.

Global Functions

The global object is an object, not a class. The global functions listed below are not methods of any object, and their reference entries appear under the function name. For example, you'll find details on the parseInt( ) function under "parseInt( )," not "Global.parseInt( )."

decodeURI( ): Decodes a string escaped with encodeURI( ).
decodeURIComponent( ): Decodes a string escaped with encodeURIComponent( ).
encodeURI: Encodes a URI by escaping certain characters.
encodeURIComponent: Encodes a URI component by escaping certain characters.
escape( ): Encodes a string by replacing certain characters with escape sequences.
eval( ): Evaluates a string of JavaScript code and return the result.
isFinite( ): Tests whether a value is a finite number.
isNaN: Tests whether a value is the not-a-number value.
parseFloat( ): Parses a number from a string.
parseInt( ): Parses an integer from a string.
unescape( ): Decodes a string encoded with escape( ).

Global Objects

In addition to the global properties and functions listed above, the global object also defines properties that refer to all the other predefined JavaScript objects. All of these properties are constructor functions that define classes except for Math, which is a reference to an object that is not a constructor.

Array: The Array( ) constructor.
Boolean: The Boolean( ) constructor.
Date: The Date( ) constructor.
Error: The Error( ) constructor.
EvalError: The EvalError( ) constructor.
Function: The Function( ) constructor.
Math: A reference to an object that defines mathematical functions.
Number: The Number( ) constructor.
Object: The Object( ) constructor.
RangeError: The RangeError( ) constructor.
ReferenceError: The ReferenceError( ) constructor.
RegExp: The RegExp( ) constructor.
String: The String( ) constructor.
SyntaxError: The SyntaxError( ) constructor.
TypeError: The TypeError( ) constructor.
URIError: The URIError( ) constructor.

Description

The global object is a predefined object that serves as a placeholder for the global properties and functions of JavaScript. All other predefined objects, functions, and properties are accessible through the global object. The global object is not a property of any other object, so it does not have a name. (The title of this reference page was chosen simply for organizational convenience and does not indicate that the global object is named "Global"). In top-level JavaScript code, you can refer to the global object with the keyword this. It is rarely necessary to refer to the global object in this way, however, because the global object serves as the top of the scope chain, which means that unqualified variable and function names are looked up as properties of the object. When JavaScript code refers to the parseInt( ) function, for example, it is referring to the parseInt property of the global object. The fact that the global object is the top of the scope chain also means that all variables declared in top-level JavaScript code become properties of the global object.

The global object is simply an object, not a class. There is no Global( ) constructor, and there is no way to instantiate a new global object.

When JavaScript is embedded in a particular environment, the global object is usually given additional properties that are specific to that environment. In fact, the type of the global object is not specified by the ECMAScript standard, and an implementation or embedding of JavaScript may use an object of any type as the global object, as long as the object defines the basic properties and functions listed here. In client-side JavaScript, for example, the global object is a Window object and represents the web browser window within which the JavaScript code is running.

Example

In core JavaScript, none of the predefined properties of the global object are enumerable, so you can list all implicitly and explicitly declared global variables with a for/in loop like this:

var variables = ""
for(var name in this)
    variables += name + "\n";

Availability

JavaScript 1.3; JScript 3.0; ECMAScript v1

Synopsis

Infinity

Description

Infinity is a global property that contains the special numeric value representing positive infinity. The Infinity property is not enumerated by for/in loops and cannot be deleted with the delete operator. Note that Infinity is not a constant and can be set to any other value, something that you should take care not to do. (Number.POSITIVE_INFINITY is a constant, however.)

Availability

true if x is (or can be converted to) the special not-a-number value; false if x is any other value.

Synopsis

isFinite(n)

Arguments

n: The number to be tested.

Returns

true if n is (or can be converted to) a finite number or false if n is NaN (not a number) or positive or negative infinity.

Availability

JavaScript 1.1; JScript 1.0; ECMAScript v1

Synopsis

isNaN(x)

Arguments

x: The value to be tested.

Returns

Description

isNaN( ) tests its argument to determine whether it is the value NaN, which represents an illegal number (such as the result of division by zero). This function is required, because comparing a NaN with any value, including itself, always returns false, so it is not possible to test for NaN with the == or === operators.

A common use of isNaN( ) is to test the results of parseFloat( ) and parseInt( ) to determine if they represent legal numbers. You can also use isNaN( ) to check for arithmetic errors, such as division by zero.

Example

isNaN(0);                  // Returns false
isNaN(0/0);                // Returns true
isNaN(parseInt("3"));      // Returns false
isNaN(parseInt("hello"));  // Returns true
isNaN("3");                // Returns false
isNaN("hello");            // Returns true
isNaN(true);               // Returns false
isNaN(undefined);          // Returns true

Availability

Synopsis

Math.constant 
Math.function( )

Constants

Math.E

Static Functions

Math.abs( )

Description

Math is an object that defines properties that refer to useful mathematical functions and constants. These functions and constants are conveniently grouped by this Math object and are invoked with syntax like this:

y = Math.sin(x);
area = radius * radius * Math.PI;

Math is not a class of objects like Date and String are. There is no Math( ) constructor, and functions like Math.sin( ) are simply functions, not methods that operate on an object.

Availability

Synopsis

Math.abs(x)

Arguments

x: Any number.

Returns

The absolute value of x.

Math.acos( )

compute an arc cosine

Availability

compute the angle from the X-axis to a point

Synopsis

Math.acos(x)

Arguments

x: A number between -1.0 and 1.0.

Returns

The arc cosine, or inverse cosine, of the specified value x. This return value is between 0 and radians.

Math.asin( )

compute an arc sine

Availability

JavaScript 1.0; JScript 1.0; ECMAScript v1

Synopsis

Math.asin(x)

Arguments

x: A number between -1.0 and 1.0.

Returns

The arc sine of the specified value x. This return value is between -/2 and /2 radians.

Math.atan( )

compute an arc tangent

Availability

JavaScript 1.0; JScript 1.0; ECMAScript v1

Synopsis

Math.atan(x)

Arguments

x: Any number.

Returns

The arc tangent of the specified value x. This return value is between -/2 and /2 radians.

Math.atan2( )

Availability

JavaScript 1.0; JScript 1.0; ECMAScript v1

Synopsis

Math.atan2(y, x)

Arguments

y: The Y-coordinate of the point.
x: The X-coordinate of the point.

Returns

A value between - and radians that specifies the counterclockwise angle between the positive X-axis and the point (x, y).

Description

The Math.atan2( ) function computes the arc tangent of the ratio y/x. The y argument can be considered the Y-coordinate (or "rise") of a point, and the x argument can be considered the X-coordinate (or "run") of the point. Note the unusual order of the arguments to this function: the Y-coordinate is passed before the X-coordinate.

Math.ceil( )

round a number up

Availability

JavaScript 1.0; JScript 1.0; ECMAScript v1

Synopsis

Math.ceil(x)

Arguments

x: Any numeric value or expression.

Returns

The closest integer greater than or equal to x.

Description

Math.ceil( ) computes the ceiling function -- i.e., it returns the closest integer value that is greater than or equal to the function argument. Math.ceil( ) differs from Math.round( ) in that it always rounds up, rather than rounding up or down to the closest integer. Also note that Math.ceil( ) does not round negative numbers to larger negative numbers; it rounds them up toward zero.

Example

a = Math.ceil(1.99);   // Result is 2.0
b = Math.ceil(1.01);   // Result is 2.0
c = Math.ceil(1.0);    // Result is 1.0
d = Math.ceil(-1.99);  // Result is -1.0

Math.cos( )

compute a cosine

Availability

JavaScript 1.0; JScript 1.0; ECMAScript v1

Synopsis

Math.cos(x)

Arguments

x: An angle, measured in radians. To convert degrees to radians, multiply the degree value by 0.017453293 (2/360).

Returns

The cosine of the specified value x. This return value is between -1.0 and 1.0.

Math.E

the mathematical constant e

Availability

JavaScript 1.0; JScript 1.0; ECMAScript v1

Synopsis

Math.E

Description

Math.E is the mathematical constant e the base of the natural logarithms, with a value of approximately 2.71828.

Math.exp( )

compute ex

Availability

JavaScript 1.0; JScript 1.0; ECMAScript v1

Synopsis

Math.exp(x)

Arguments

x: A numeric value or expression to be used as the exponent.

Returns

e^x, e raised to the power of the specified exponent x, where e is the base of the natural logarithms, with a value of approximately 2.71828.

Math.floor( )

round a number down

Availability

JavaScript 1.0; JScript 1.0; ECMAScript v1

Synopsis

Math.floor(x)

Arguments

x: Any numeric value or expression.

Returns

The closest integer less than or equal to x.

Description

Math.floor( ) computes the floor function -- in other words, it returns the nearest integer value that is less than or equal to the function argument.

Math.floor( ) rounds a floating-point value down to the closest integer. This behavior differs from that of Math.round( ), which rounds up or down to the nearest integer. Also note that Math.floor( ) rounds negative numbers down (i.e., to be more negative), not up (i.e., closer to zero).

Example

a = Math.floor(1.99);    // Result is 1.0
b = Math.floor(1.01);    // Result is 1.0
c = Math.floor(1.0);     // Result is 1.0
d = Math.floor(-1.01);   // Result is -2.0

Math.LN10

the mathematical constant loge10

Availability

JavaScript 1.0; JScript 1.0; ECMAScript v1

Synopsis

Math.LN10

Description

Math.LN10 is log_e2, the natural logarithm of 10. This constant has a value of approximately 2.3025850929940459011.

Math.LN2

the mathematical constant loge2

Availability

JavaScript 1.0; JScript 1.0; ECMAScript v1

Synopsis

Math.LN2

Description

Math.LN2 is loge2 the natural logarithm of 2. This constant has a value of approximately 0.69314718055994528623.

Math.log( )

compute a natural logarithm

Availability

JavaScript 1.0; JScript 1.0; ECMAScript v1

Synopsis

Math.log(x)

Arguments

x: Any numeric value or expression greater than zero.

Returns

The natural logarithm of x.

Description

Math.log( ) computes log₃x the natural logarithm of its argument. The argument must be greater than zero.

You can compute the base-10 and base-2 logarithms of a number with these formulas:

log₁₀x = log₁₀e·log_ex

log₂x = log₂e·log_ex

These formulas translate into the following JavaScript functions:

function log10(x) { return Math.LOG10E * Math.log(x); }
function log2(x) { return  Math.LOG2E * Math.log(x); }

Math.LOG10E

the mathematical constant log10e

Availability

JavaScript 1.0; JScript 1.0; ECMAScript v1

Synopsis

Math.LOG10E

Description

Math.LOG10E is log₁₀e, the base-10 logarithm of the constant e. It has a value of approximately 0.43429448190325181667.

Math.LOG2E

the mathematical constant log2e

Availability

JavaScript 1.0; JScript 1.0; ECMAScript v1

Synopsis

Math.LOG2E

Description

Math.LOG2E is log₂e, the base-2 logarithm of the constant e. It has a value of approximately 1.442695040888963387.

Math.max( )

return the largest argument

Availability

JavaScript 1.0; JScript 1.0; ECMAScript v1; enhanced in ECMAScript v3

Synopsis

Math.max(args...)

Arguments

args...: Zero or more values. Prior to ECMAScript v3, this method expects exactly two arguments.

Returns

The largest of the arguments. Returns -Infinity if there are no arguments. Returns NaN if any of the arguments is NaN or is a non-numeric value that cannot be converted to a number.

Math.min( )

return the smallest argument

Availability

JavaScript 1.0; JScript 1.0; ECMAScript v1; enhanced in ECMAScript v3

Synopsis

Math.min(args...)

Arguments

args...

Returns

The smallest of the specified arguments. Returns Infinity if there are no arguments. Returns NaN if any argument is NaN or is a non-numeric value that cannot be converted to a number.

Math.PI

the mathematical constant

Availability

JavaScript 1.0; JScript 1.0; ECMAScript v1

Synopsis

Math.PI

Description

Math.PI is the constant or pi, the ratio of the circumference of a circle to its diameter. It has a value of approximately 3.14159265358979.

Math.pow( )

compute xy

Availability

JavaScript 1.0; JScript 1.0; ECMAScript v1

Synopsis

Math.pow(x, y)

Arguments

x

Returns

x to the power of y, x^y.

Description

Math.pow( ) computes x to the power of y. Any values of x and y may be passed to Math.pow( ). However, if the result is an imaginary or complex number, Math.pow( ) returns NaN. In practice, this means that if x is negative, y should be a positive or negative integer. Also, bear in mind that large exponents can easily cause floating-point overflow and return a value of Infinity.

Math.random( )

return a pseudorandom number

Availability

JavaScript 1.1; JScript 1.0; ECMAScript v1

Synopsis

Math.random( )

Returns

A pseudorandom number between 0.0 and 1.0.

Math.round( )

round to the nearest integer

Availability

JavaScript 1.0; JScript 1.0; ECMAScript v1

Synopsis

Math.round(x)

Arguments

x: Any number.

Returns

The integer closest to x.

Description

Math.round( ) rounds its argument up or down to the nearest integer. It rounds .5 up. For example, it rounds 2.5 to 3 and rounds -2.5 to -2.

Math.sin( )

compute a sine

Availability

JavaScript 1.0; JScript 1.0; ECMAScript v1

Synopsis

Math.sin(x)

Arguments

x: An angle, in radians. To convert degrees to radians, multiply by 0.017453293 (2/360).

Returns

The sine of x.

Math.sqrt( )

compute a square root

Availability

JavaScript 1.0; JScript 1.0; ECMAScript v1

Synopsis

Math.sqrt(x)

Arguments

x: A numeric value greater than or equal to zero.

Returns

The square root of x. Returns NaN if x is less than zero.

Description

Math.sqrt( ) computes the square root of a number. Note, however, that you can compute arbitrary roots of a number with Math.pow( ). For example:

Math.cuberoot = function(x){ return Math.pow(x,1/3); }
Math.cuberoot(8);  // Returns 2

Math.SQRT1_2

the mathematical constant 1/

Availability

JavaScript 1.0; JScript 1.0; ECMAScript v1

Synopsis

Math.SQRT1_2

Description

Math.SQRT1_2 is 1/ the reciprocal of the square root of 2. This constant has a value of approximately 0.7071067811865476.

Math.SQRT2

the mathematical constant

Availability

JavaScript 1.0; JScript 1.0; ECMAScript v1

Synopsis

Math.SQRT2

Description

Math.SQRT2 is the constant , the square root of 2. This constant has a value of approximately 1.414213562373095.

Math.tan( )

compute a tangent

Availability

JavaScript 1.0; JScript 1.0; ECMAScript v1

Synopsis

Math.tan(x)

Arguments

x: An angle, measured in radians. To convert degrees to radians, multiply the degree value by 0.017453293 (2/360).

Returns

The tangent of the specified angle x.

NaN

the not-a-number property

Availability

JavaScript 1.3; JScript 3.0; ECMAScript v1

Synopsis

NaN

Description

NaN is global property that refers to the special numeric not-a-number value. The NaN property is not enumerated by for/in loops and cannot be deleted with the delete operator. Note that NaN is not a constant and can be set to any other value, something that you should take care not to do.

To determine if a value is not a number, use isNaN( ), since NaN always compares non-equal to any other value, including itself!

Availability

JavaScript 1.1; JScript 2.0; ECMAScript v1

Inherits from/Overrides

Inherits from Object

Constructor

new Number(value)
Number(value)

Arguments

value: The numeric value of the Number object being created, or a value to be converted to a number.

Returns

When Number( ) is used with the new operator as a constructor, it returns a newly constructed Number object. When Number( ) is invoked as a function without the new operator, it converts its argument to a primitive numeric value and returns that value (or NaN if the conversion failed).

Constants

Number.MAX_VALUE: The largest representable number.
Number.MIN_VALUE: The smallest representable number.
Number.NaN: Not-a-number value.
Number.NEGATIVE_INFINITY: Negative infinite value; returned on overflow.
Number.POSITIVE_INFINITY: Infinite value; returned on overflow.

Methods

toString( ): Converts a number to a string, using a specified radix (base).
toLocaleString( ): Converts a number to a string, using local number formatting conventions.
toFixed( ): Converts a number to a string that contains a specified number of digits after the decimal place.
toExponential( ): Converts a number to a string using exponential notation with the specified number of digits after the decimal place.
toPrecision( ): Converts a number to a string using the specified number of significant digits. Uses exponential or fixed-point notation depending on the size of the number and the number of significant digits specified.

Description

Numbers are a basic, primitive data type in JavaScript. In JavaScript 1.1, however, JavaScript also supports the Number object, which is a wrapper object around a primitive numeric value. JavaScript automatically converts between the primitive and object forms as necessary. In JavaScript 1.1, you can explicitly create a Number object with the Number( ) constructor, although there is rarely any need to do so.

The Number( ) constructor can also be used without the new operator, as a conversion function. When invoked in this way, it attempts to convert its argument to a number and returns the primitive numeric value (or NaN) that results from the conversion.

The Number( ) constructor is also used as a placeholder for five useful numeric constants: the largest and smallest representable numbers; positive and negative infinity; and the special not-a-number value. Note that these values are properties of the Number( ) constructor function itself, not of individual number objects. For example, you can use the MAX_VALUE property as follows:

var biggest = Number.MAX_VALUE

but not like this:

var n = new Number(2);
var biggest = n.MAX_VALUE

By contrast, the toString( ) and other methods of the Number object are methods of each Number object, not of the Number( ) constructor function. As noted earlier, JavaScript automatically converts from primitive numeric values to Number objects whenever necessary. This means that we can use the Number methods with primitive numeric values as well as with Number objects.

var value = 1234;
var binary_value = n.toString(2);

Availability

JavaScript 1.1; JScript 2.0, ECMAScript v1

Synopsis

Number.MAX_VALUE

Description

Number.MAX_VALUE is the largest number representable in JavaScript. Its value is approximately 1.79E+308.

Number.MIN_VALUE

the minimum numeric value

Availability

JavaScript 1.1; JScript 2.0, ECMAScript v1

Synopsis

Number.MIN_VALUE

Description

Number.MIN_VALUE is the smallest (closest to zero, not most negative) number representable in JavaScript. Its value is approximately 5E-324.

Number.NaN

the special not-a-number value

Availability

JavaScript 1.1; JScript 2.0, ECMAScript v1

Synopsis

Number.NaN

Description

Number.NaN is a special value that indicates that the result of some mathematical operation (such as taking the square root of a negative number) is not a number. parseInt( ) and parseFloat( ) return this value when they cannot parse the specified string, and you might use Number.NaN in a similar way to indicate an error condition for some function that normally returns a valid number.

JavaScript prints the Number.NaN value as NaN. Note that the NaN value always compares unequal to any other number, including NaN itself. Thus, you cannot check for the not-a-number value by comparing to Number.NaN. Use the isNaN( ) function instead. In ECMAScript v1 and later, you can also use the predefined global constant NaN instead of using Number.NaN.

Availability

JavaScript 1.1; JScript 2.0, ECMAScript v1

Synopsis

Number.NEGATIVE_INFINITY

Description

Number.NEGATIVE_INFINITY is a special numeric value that is returned when an arithmetic operation or mathematical function generates a negative value greater than the largest representable number in JavaScript (i.e., more negative than -Number.MAX_VALUE).

JavaScript displays the NEGATIVE_INFINITY value as -Infinity. This value behaves mathematically like infinity; for example, anything multiplied by infinity is infinity and anything divided by infinity is zero. In ECMAScript v1 and later, you can also use -Infinity instead of Number.NEGATIVE_INFINITY.

Availability

JavaScript 1.1; JScript 2.0, ECMAScript v1

Synopsis

Number.POSITIVE_INFINITY

Description

Number.POSITIVE_INFINITY is a special numeric value returned when an arithmetic operation or mathematical function overflows or generates a value greater than the largest representable number in JavaScript (i.e., greater than Number.MAX_VALUE). Note that when numbers "underflow," or become less than Number.MIN_VALUE, JavaScript converts them to zero.

JavaScript displays the POSITIVE_INFINITY value as Infinity. This value behaves mathematically like infinity; for example, anything multiplied by infinity is infinity and anything divided by infinity is zero. In ECMAScript v1 and later, you can also use the predefined global constant Infinity instead of Number.POSITIVE_INFINITY.

Availability

JavaScript 1.5; JScript 5.5, ECMAScript v3

Synopsis

number.toExponential(digits)

Arguments

digits: The number of digits that will appear after the decimal point. This may be a value between 0 and 20, inclusive, and implementations may optionally support a larger range of values. If this argument is omitted, as many digits as necessary will be used.

Returns

A string representation of number, in exponential notation, with one digit before the decimal place and digits digits after the decimal place. The fractional part of the number is rounded, or padded with zeros, as necessary, so that it has the specified length.

Throws

RangeError: If digits is too small or too large. Values between 0 and 20, inclusive, will not cause a RangeError. Implementations are allowed to support larger and smaller values as well.
TypeError: If this method is invoked on an object that is not a Number.

Example

var n = 12345.6789;
n.toExponential(1);     // Returns 1.2e+4
n.toExponential(5);     // Returns 1.23457e+4
n.toExponential(10);    // Returns 1.2345678900e+4
n.toExponential( );    // Returns 1.23456789e+4

Availability

JavaScript 1.5; JScript 5.5, ECMAScript v3

Synopsis

number.toFixed(digits)

Arguments

digits: The number of digits to appear after the decimal point; this may be a value between 0 and 20, inclusive, and implementations may optionally support a larger range of values. If this argument is omitted, it is treated as 0.

Returns

A string representation of number that does not use exponential notation and has exactly digits digits after the decimal place. The number is rounded if necessary, and the fractional part is padded with zeros if necessary so that it has the specified length. If number is greater than 1e+21, this method simply calls Number.toString( ) and returns a string in exponential notation.

Throws

RangeError: If digits is too small or too large. Values between 0 and 20, inclusive, will not cause a RangeError. Implementations are allowed to support larger and smaller values as well.
TypeError: If this method is invoked on an object that is not a Number.

Example

var n = 12345.6789;
n.toFixed( );            // Returns 12346: note rounding, no fractional part
n.toFixed(1);             // Returns 12345.7: note rounding
n.toFixed(6);             // Returns 12345.678900: note added zeros
(1.23e+20).toFixed(2);    // Returns 123000000000000000000.00
(1.23e-10).toFixed(2)     // Returns 0.00

Availability

JavaScript 1.5; JScript 5.5, ECMAScript v3

Synopsis

number.toLocaleString( )

Returns

An implementation-dependent string representation of the number, formatted according to local conventions, which may affect such things as the punctuation characters used for the decimal point and the thousands separator.

Throws

TypeError: If this method is invoked on an object that is not a Number.

Availability

JavaScript 1.5; JScript 5.5, ECMAScript v3

Synopsis

number.toPrecision(precision)

Arguments

precision: The number of significant digits to appear in the returned string. This may be a value between 1 and 21, inclusive. Implementations are allowed to optionally support larger and smaller values of precision. If this argument is omitted, the toString( ) method is used instead to convert the number to a base-10 value.

Returns

A string representation of number that contains precision significant digits. If precision is large enough to include all the digits of the integer part of number, the returned string uses fixed-point notation. Otherwise, exponential notation is used with one digit before the decimal place and precision -1 digits after the decimal place. The number is rounded or padded with zeros as necessary.

Throws

RangeError: If digits is too small or too large. Values between 1 and 21, inclusive, will not cause a RangeError. Implementations are allowed to support larger and smaller values as well.
TypeError: If this method is invoked on an object that is not a Number.

Example

var n = 12345.6789;
n.toPrecision(1);   // Returns 1e+4
n.toPrecision(3);   // Returns 1.23e+4
n.toPrecision(5);   // Returns 12346: note rounding
n.toPrecision(10);  // Returns 12345.67890: note added zero

Availability

JavaScript 1.1; JScript 2.0, ECMAScript v1

Inherits from/Overrides

Overrides Object.toString( )

Synopsis

number.toString(radix)

Arguments

radix: An optional argument that specifies the radix, or base, between 2 and 36, in which the number should be represented. If omitted, base 10 is used. Note, however, that the ECMAScript specification allows an implementation to return any value if this argument is specified as any value other than 10.

Returns

A string representation of the number.

Throws

TypeError: If this method is invoked on an object that is not a Number.

Description

The toString( ) method of the Number object converts a number to a string. When the radix argument is omitted or is specified as 10, the number is converted to a base-10 string. If radix is any other value, this method returns an implementation-defined string. Netscape implementations and Microsoft implementations after JScript 3.0 honor the radix argument and return a string representation of the number in the specified base.

Availability

JavaScript 1.1; JScript 2.0, ECMAScript v1

Inherits from/Overrides

Overrides Object.valueOf( )

Synopsis

number.valueOf( )

Returns

The primitive number value of this Number object. It is rarely necessary to call this method explicitly.

Throws

TypeError: If this method is invoked on an object that is not a Number.

Availability

JavaScript objects JavaScript 1.0; JScript 1.0; ECMAScript v1

Constructor

new Object( )new 
Object(value)

Arguments

value: This optional argument specifies a primitive JavaScript value -- a number, boolean, or string -- that is to be converted to a Number, Boolean, or String object. This object is not supported prior to JavaScript 1.1 and ECMAScript v1.

Returns

If no value argument is passed, this constructor returns a newly created Object instance. If a primitive value argument is specified, the constructor creates and returns a Number, Boolean, or String object wrapper for the primitive value. When the Object( ) constructor is called as a function, without the new operator, it behaves just as it does when used with the new operator.

Properties

constructor: A reference to the JavaScript function that was the constructor for the object.

Methods

hasOwnProperty( ): Checks whether an object has a locally defined (noninherited) property with a specified name.
isPrototypeOf( ): Checks whether this object is the prototype object of a specified object.
propertyIsEnumerable( ): Checks whether a named property exists and would be enumerated by a for/in loop.
toLocaleString( ): Returns a localized string representation of the object. The default implementation of this method simply calls toString( ), but subclasses may override it to provide localization.
toString( ): Returns a string representation of the object. The implementation of this method provided by the Object class is quite generic and does not provide much useful information. Subclasses of Object typically override this method by defining their own toString( ) method which produces more useful output.
valueOf( ): Returns the primitive value of the object, if any. For objects of type Object, this method simply returns the object itself. Subclasses of Object, such as Number and Boolean, override this method to return the primitive value associated with the object.

Description

The Object class is a built-in data type of the JavaScript language. It serves as the superclass for all other JavaScript objects; therefore, methods and behavior of the Object class are inherited by all other objects. The basic behavior of objects in JavaScript is explained in Chapter 8.

In addition to the Object( ) constructor shown above, objects can also be created and initialized using the Object literal syntax described in Chapter 8.

Availability