Core JavaScript Reference: Chapter 24 - JavaScript: The Definitive Guide

Title and Short Description

Every reference entry begins with a four-part title block like that above. The entries are alphabetized by title. The short description, shown below the title, gives you a quick summary of the item documented in the entry; it can help you quickly decide if you're interested in reading the rest of the page.

Constructor

If the reference page documents a class, and the class has a constructor, this section shows you how to use the constructor method to create instances of the class. Since constructors are a type of method, the Constructor section looks a lot like the Synopsis section of a method's reference page.

Synopsis

Reference pages for functions, methods, and properties have a Synopsis section that shows how you might use the function, method, or property in your code. The reference entries in this book use two different styles of synopses. The entries in the core JavaScript reference and the client-side entries that document methods (such as Window methods) that are not related to the DOM use untyped synopses. For example, the synopsis for the Array.concat( ) method is:

array.concat(value,...)

The italic font indicates text that is to be replaced with something else. array should be replaced with a variable or JavaScript expression that holds or evaluates to an array. And value is simply a name for an argument to be passed to the method. This named argument is decribed later in the synopsis, and that description contains information about the type and purpose of the argument. The ellipsis (...) indicates that this method can take any number of value arguments. Because the terms concat and the open and close parentheses are not in italics, you must include them exactly as shown in your JavaScript code.

Many of the methods documented in the client-side JavaScript section have been standardized by the W3C, and their specifications include definitive type information for method arguments and method return values. These entries include this type information in the synopsis. The synopsis for the Document.getElementById( ) method, for example is:

Element getElementById(StringelementId);

This synopsis uses Java-style syntax to indicate that the getElementById( ) method returns an Element object and expects one string argument named elementId. Because this is a method of Document, it is implicit that it is invoked on a document, and no document prefix is included.

Constants

Some classes define a set of constants that serve as the values for a property or as the arguments to a method. The Node interface, for example, defines important constants to serve as the set of legal values for its nodeType property. When an interface defines constants, they are listed and documented in this section. Note that constants are static properties of the class itself, not of instances of that class

Properties

If the reference page documents a class, the Properties section lists the properties defined by the class and provides short explanations of each. In Part III, “Core JavaScript Reference”, each property also has a complete reference page of its own. In Part IV, “Client-Side JavaScript Reference”, most properties are fully described in this properties list. The most important or complex client-side properties do have a page of their own, and this is noted here. In Part IV, “Client-Side JavaScript Reference”, the properties of DOM-related classes include type information. Properties of other classes and all properties in Part III, “Core JavaScript Reference” are untyped. The property listing looks like this:

Methods

The reference page for a class that defines methods includes a Methods section. It is just like the Properties section, except that it summarizes methods instead of properties. All methods also have reference pages of their own. This summary section lists only method names. Argument type and return type information can be found on the method's reference page.

Description

Most reference pages contain a Description section, which is the basic description of the class, method, function, or property that is being documented. This is the heart of the reference page. If you are learning about a class, method, or property for the first time, you may want to skip directly to this section and then go back and look at previous sections, such as Arguments, Properties, and Methods. If you are already familiar with a class, method, or property, you probably won't need to read this section and instead will just want to quickly look up some specific bit of information (for example, from the Arguments or Properties sections).

In some entries, this section is no more than a short paragraph. In others, it may occupy a page or more. For some simple methods, the Arguments and Returns sections document the method sufficiently by themselves, so the Description section is omitted.

Example

Some pages include an example that shows typical usage. Most pages do not contain examples, however; you'll find those in first half of this book.

Bugs

When an item doesn't work quite right, this section describes the bugs. Note, however, that this book does not attempt to catalog every bug.

See Also

Many reference pages conclude with cross-references to related reference pages that may be of interest. Sometimes reference pages also refer back to one of the main chapters of the book.

Synopsis

arguments

Description

The arguments[] array is defined only within a function body. Within the body of a function, arguments refers to the Arguments object for the function. This object has numbered properties and serves as an array containing all arguments passed to the function. The arguments identifier is essentially a local variable automatically declared and initialized within every function. It refers to an Arguments object only within the body of a function and is undefined in global code.

See Also

Arguments;Chapter 8, Functions

Synopsis

arguments

arguments[n]

Elements

The Arguments object is defined only within a function body. Although it is not technically an array, the Arguments object has numbered properties that function as array elements and a length property that specifies the number of array elements. Its elements are the values that are passed as arguments to the function. Element 0 is the first argument, element 1 is the second argument, and so on. All values passed as arguments become array elements of the Arguments object, whether or not those arguments are given names in the function declaration.

Properties

Description

When a function is invoked, an Arguments object is created for it, and the local variable arguments is automatically initialized to refer to that Arguments object. The main purpose of the Arguments object is to provide a way to determine how many arguments are passed to the function and to refer to unnamed arguments. In addition to the array elements and length property, however, the callee property allows an unnamed function to refer to itself.

For most purposes, the Arguments object can be thought of as an array with the addition of the callee property. However, it is not an instance of Array, and the Arguments.length property does not have any of the special behaviors of the Array.length property and cannot be used to change the size of the array.

The Arguments object has one very unusual feature. When a function has named arguments, the array elements of the Arguments object are synonyms for the local variables that hold the function arguments. The Arguments object and the argument names provide two different ways of referring to the same variable. Changing the value of an argument with an argument name changes the value that is retrieved through the Arguments object, and changing the value of an argument through the Arguments object changes the value that is retrieved by the argument name.

See Also

Function; Chapter 8, Functions

Synopsis

arguments.callee

Description

arguments.callee refers to the function that is currently running. It provides a way for an unnamed function to refer to itself. This property is defined only within a function body.

Example

// An unnamed function literal uses the callee property to refer
// to itself so that it can be recursive
var factorial = function(x) {
    if (x < 2) return 1;
    else return x * arguments.callee(x-1);
}
var y = factorial(5);  // Returns 120

Synopsis

arguments.length

Description

The length property of the Arguments object specifies the number of arguments passed to the current function. This property is defined only within a function body.

Note that this property specifies the number of arguments actually passed, not the number expected. See Function.length for the number of declared arguments. Note also that this property does not have any of the special behavior of the Array.length property.

Example

// Use an Arguments object to check that correct # of args were passed
function check(args) {
    var actual = args.length;           // The actual number of arguments
    var expected = args.callee.length;  // The expected number of arguments
    if (actual != expected) {           // Throw exception if they don't match
        throw new Error("Wrong number of arguments: expected: " +
                         expected + "; actually passed " + actual);
    }
}
// A function that demonstrates how to use the function above
function f(x, y, z) {
    check(arguments);  // Check for correct number of arguments
    return x + y + z;  // Now do the rest of the function normally
}

See Also

Array.length, Function.length

Constructor

new Array( )

new Array(size)

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

Literal Syntax

ECMAScript v3 specifies 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

Methods

Description

Arrays are a basic feature of JavaScript and are documented in detail in Chapter 7, Objects and Arrays.

See Also

Chapter 7, Objects and Arrays

Synopsis

array.concat(value, ...)

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

See Also

Array.join( ), Array.push( ), Array.splice( )

Synopsis

array.join( )

array.join(separator)

Description

join( ) converts each element 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 into array elements—with the split( ) method of the String object. See String.split( ) for details.

Example

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

See Also

String.split( )

Synopsis

array.length

Description

The length property of an array is always one larger than the index of 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.

Synopsis

array.pop( )

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

See Also

Array.push( )

Synopsis

array.push(value, ...)

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.

See Also

Array.pop( )

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;

Synopsis

array.shift( )

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]

See Also

Array.pop( ), Array.unshift( )

Synopsis

array.slice(start, 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 can't be a negative number in Internet Explorer 4. This is fixed in later versions of IE.

See Also

Array.splice( )

Synopsis

array.sort( ) array.sort(orderfunc)

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:

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

Synopsis

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

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(1,2);      // Returns [2,3]; a is [1,4]
a.splice(1,1);      // Returns [4]; a is [1]
a.splice(1,0,2,3);  // Returns []; a is [1 2 3]

See Also

Array.slice( )

Synopsis

array.toLocaleString( )

Description

The toLocaleString( ) 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.

See Also

Array.toString( ), Object.toLocaleString( )

Synopsis

array.toString( )

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 array element to strings (by calling its toString( ) method). Once each element is converted to a string, toString( ) 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.

See Also

Array.toLocaleString( ), Object.toString( )

Synopsis

array.unshift(value, ...)

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

See Also

Array.shift( )

Constructor

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

Methods

Description

Boolean values are a fundamental datatype 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.

See Also

Object

Synopsis

b.toString( )

Synopsis

b.valueOf( )

Constructor

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

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 Coordinated Universal Time (UTC) (which is similar to Greenwich Mean Time [GMT]). See the static Date.UTC( ) method for an alternative.

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.

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 they throw a TypeError exception if you attempt to invoke them on any other type of object:

Static Methods

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

Description

The Date object is a datatype built into the JavaScript language. Date objects are created with the new Date( ) syntax shown earlier.

Once a Date object is created, a number of methods allow you to operate on it. Most 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.

Examples

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>

See Also

Date.parse( ), Date.UTC( )

Synopsis

date.getDate( )

Synopsis

date.getDay( )

Synopsis

date.getFullYear( )

Synopsis

date.getHours( )

Synopsis

date.getMilliseconds( )

Synopsis

date.getMinutes( )

Synopsis

date.getMonth( )

Synopsis

date.getSeconds( )

Synopsis

date.getTime( )

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 a millisecond representation without going through the overhead of first creating a Date object.

See Also

Date, Date.parse( ), Date.setTime( ), Date.UTC( )

Synopsis

date.getTimezoneOffset( )

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

Synopsis

date.getUTCDate( )

Synopsis

date.getUTCDay( )

Synopsis

date.getUTCFullYear( )

Synopsis

date.getUTCHours( )

Synopsis

date.getUTCMilliseconds( )

Synopsis

date.getUTCMinutes( )

Synopsis

date.getUTCMonth( )

Synopsis

date.getUTCSeconds( )

Synopsis

date.getYear( )

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.

Synopsis

Date.parse(date)

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.

See Also

Date, Date.setTime( ), Date.toGMTString( ), Date.UTC( )

Synopsis

date.setDate(day_of_month)

Synopsis

date.setFullYear(year)

date.setFullYear(year, month)

date.setFullYear(year, month, day)

Synopsis

date.setHours(hours)

date.setHours(hours, minutes)

date.setHours(hours, minutes, seconds)

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

Synopsis

date.setMilliseconds(millis)

Synopsis

date.setMinutes(minutes)

date.setMinutes(minutes, seconds)

date.setMinutes(minutes, seconds, millis)

Synopsis

date.setMonth(month)

date.setMonth(month, day)

Synopsis

date.setSeconds(seconds)

date.setSeconds(seconds, millis)

Synopsis

date.setTime(milliseconds)

Synopsis

date.setUTCDate(day_of_month)

Synopsis

date.setUTCFullYear(year)

date.setUTCFullYear(year, month)

date.setUTCFullYear(year, month, day)

Synopsis

date.setUTCHours(hours)

date.setUTCHours(hours, minutes)

date.setUTCHours(hours, minutes, seconds)

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

Synopsis

date.setUTCMilliseconds(millis)

Synopsis

date.setUTCMinutes(minutes)

date.setUTCMinutes(minutes, seconds)

date.setUTCMinutes(minutes, seconds, millis)

Synopsis

date.setUTCMonth(month)

date.setUTCMonth(month, day)

Synopsis

date.setUTCSeconds(seconds)

date.setUTCSeconds(seconds, millis)

Synopsis

date.setYear(year)

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.

Synopsis

date.toDateString( )

See Also

Synopsis

date.toGMTString( )

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.

See Also

Date.toUTCString( )

Synopsis

date.toLocaleDateString( )

See Also

Date.toDateString( ), Date.toLocaleString( ), Date.toLocaleTimeString( ), Date.toString( ), Date.toTimeString( )

Synopsis

date.toLocaleString( )

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.

See Also

Date.toLocaleDateString( ), Date.toLocaleTimeString( ), Date.toString( ), Date.toUTCString( )

Synopsis

date.toLocaleTimeString( )

See Also

Date.toDateString( ), Date.toLocaleDateString( ), Date.toLocaleString( ), Date.toString( ), Date.toTimeString( )

Synopsis

date.toString( )

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.

See Also

Synopsis

date.toTimeString( )

See Also

Date.toString( ), Date.toDateString( ), Date.toLocaleDateString( ), Date.toLocaleString( ), Date.toLocaleTimeString( )

Synopsis

date.toUTCString( )

Description

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

See Also

Date.toLocaleString( ), Date.toString( )

Synopsis

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

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; 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));

See Also

Date, Date.parse( ), Date.setTime( )

Synopsis

date.valueOf( )

Synopsis

decodeURI(uri)

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's reference page for details.

See Also

decodeURIComponent( ), encodeURI( ), encodeURIComponent( ), escape( ), unescape( )

Synopsis

decodeURI(s)

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.

See Also

decodeURI( ), encodeURI( ), encodeURIComponent( ), escape( ), unescape( )

Synopsis

encodeURI(uri)

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 each 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 have to 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

See Also

decodeURI( ), decodeURIComponent( ), encodeURIComponent( ), escape( ), unescape( )

Synopsis

encodeURIComponent(s)

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 /, :, and # 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

See Also

decodeURI( ), decodeURIComponent( ), encodeURI( ), escape( ), unescape( )

Constructor

new Error( )

new Error(message)

Properties

Methods

Description

Instances of the Error class represent errors or exceptions and are typically used with the throw and try/catch statements. The name property specifies the type of the exception, and the message property can provide human-readable details about the exception.

The JavaScript interpreter never throws Error objects 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 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.

Examples

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);
    }
}

See Also

EvalError, RangeError, ReferenceError, SyntaxError, TypeError, URIError

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.

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

Synopsis

error. toString( )

Synopsis

escape(s)

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 %u xxxx (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 %u xxxx sequence.

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

Although the escape( ) function was standardized in the first version of ECMAScript, it was deprecated and removed from the standard by ECMAScript v3. Implementations of ECMAScript are likely to implement this function, but they are not required to. You should use encodeURI( ) and encodeURIComponent( ) instead of escape( ).

Example

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

See Also

encodeURI( ), encodeURIComponent( )

Synopsis

eval(code)

Description

eval( ) is a global method that evaluates a string of JavaScript code in the current lexical scope. 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

Constructor

new EvalError( )

new EvalError(message)

Properties

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.

See Also

Error, Error.message, Error.name

Synopsis

functionfunctionname(argument_name_list) // Function definition statement
{
    body}
function (argument_name_list) {body}      // Unnamed function literal

functionname(argument_value_list)         // Function invocation

Constructor

new Function(argument_names..., body)

Properties

Methods

Description

A function is a fundamental datatype in JavaScript. Chapter 8, Functions explains how to define and use functions, and Chapter 9, Classes, Constructors, and Prototypes 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 earlier. See the Arguments reference page for details.

See Also

Arguments; Chapter 8, Functions, Chapter 9, Classes, Constructors, and Prototypes

Synopsis

function.apply(thisobj, args)

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);

See Also

Function.call( )

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

See Also

Arguments

Synopsis

function.call(thisobj, args...)

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, or to the global object if thisobj is null.

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);

See Also

Function.apply( )

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 is invoked from the top level of a JavaScript program, caller is null. This property may be used only 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.

Synopsis

function.length

Description

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.

See Also

Arguments.length

Synopsis

function.prototype

Description

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.

See Chapter 9, Classes, Constructors, and Prototypes for a full discussion of constructor functions, the prototype property, and the definition of classes in JavaScript.

See Also

Chapter 9, Classes, Constructors, and Prototypes

Synopsis

function.toString( )

Description

The toString( ) method of the Function object converts a function to a string in an implementation-dependent way. In most implementations, such as the implementations in Firefox and IE, 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. In these implementations, the output of this toString( ) method is valid input for the global eval( ) function. This behavior is not required by the specification, however, and should not be relied upon.

Synopsis

getClass(javaobj)

Description

getClass( ) is a function that takes a JavaObject object (javaobj) as an argument. It returns the JavaClass object of that JavaObject. That is, it returns the JavaClass object that represents the Java class of the Java object represented by the specified JavaObject.

Usage

Don't confuse the JavaScript getClass( ) function with the getClass method of all Java objects. Similarly, don't confuse the JavaScript JavaClass object with the Java java.lang.Class class.

Consider the Java Rectangle object created with the following line:

var r = new java.awt.Rectangle( );

r is a JavaScript variable that holds a JavaObject object. Calling the JavaScript function getClass( ) returns a JavaClass object that represents the java.awt.Rectangle class:

var c = getClass(r);

You can see this by comparing this JavaClass object to java.awt.Rectangle:

if (c == java.awt.Rectangle) ...

The Java getClass( ) method is invoked differently and performs an entirely different function:

c = r.getClass( );

After executing this line of code, c is a JavaObject that represents a java.lang.Class object. This java.lang.Class object is a Java object that is a Java representation of the java.awt.Rectangle class. See your Java documentation for details on what you can do with the java.lang.Class class.

To summarize, you can see that the following expression always evaluates to true for any JavaObject o:

(getClass(o.getClass( )) == java.lang.Class)

See Also

JavaArray, JavaClass, JavaObject, JavaPackage; Chapter 12, Scripting Java, Chapter 23, Scripting Java Applets and Flash Movies

Synopsis

this

Global Properties

The global object is not a class, so the following global properties have individual reference entries under their own names. 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:

Global Functions

The global object is an object, not a class. The global functions listed here 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( ):

Global Objects

In addition to the global properties and functions listed earlier, the global object also defines properties that refer to all the other predefined JavaScript objects. All these properties are constructor functions that define classes except for Math, which is a reference to an object that is not a 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. For example, in JavaScript implementations that allow the scripting of Java via LiveConnect or related technologies, the global object is given the java and Packages properties and the getClass( ) method listed here. And in client-side JavaScript, 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";

See Also

Window inPart IV, “Client-Side JavaScript Reference” ; Chapter 4, Variables

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

See Also

isFinite( ), NaN, Number.POSITIVE_INFINITY

Synopsis

isFinite(n)

See Also

Infinity, isNaN( ), NaN, Number.NaN, Number.NEGATIVE_INFINITY, Number.POSITIVE_INFINITY

Synopsis

isNaN(x)

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

See Also

isFinite( ), NaN, Number.NaN, parseFloat( ), parseInt( )

Synopsis

java

Description

In JavaScript implementations that include LiveConnect or other technology for scripting Java, the global java property is a JavaPackage object that represents the java.* package hierarchy. The existence of this property means that a JavaScript expression such as java.util refers to the Java package java.util. For Java packages that do not fall in the java.* hierarchy, see the global Packages property.

See Also

JavaPackage, Packages; Chapter 12, Scripting Java

Synopsis

javaarray.length // The length of the array

javaarray[index] // Read or write an array element

Properties

Description

The JavaArray object is a JavaScript representation of a Java array that allows JavaScript code to read and write the elements of the array using familiar JavaScript array syntax. In addition, the JavaArray object has a length field that specifies the number of elements in the Java array.

When reading and writing values from array elements, data conversion between JavaScript and Java representations is automatically handled by the system. See Chapter 12, Scripting Java for full details.

Usage

Note that Java arrays differ from JavaScript arrays in a couple of important aspects. First, Java arrays have a fixed length that is specified when they are created. For this reason, the JavaArray length field is read-only. The second difference is that Java arrays are typed (i.e., their elements must all be of the same type of data). Attempting to set an array element to a value of the wrong type results in a JavaScript error or exception.

Example

java.awt.Polygon is a JavaClass object. You can create a JavaObject representing an instance of the class like this:

p = new java.awt.Polygon( );

The object p has properties xpoints and ypoints, which are JavaArray objects representing Java arrays of integers. You can initialize the contents of these arrays with JavaScript code like the following:

for(var i = 0; i < p.xpoints.length; i++)
    p.xpoints[i] = Math.round(Math.random( )*100);
for(var i = 0; i < p.ypoints.length; i++)
    p.ypoints[i] = Math.round(Math.random( )*100);

See Also

getClass( ), JavaClass, JavaObject, JavaPackage; Chapter 12, Scripting Java

Synopsis

javaclass.static_member   // Read or write a static Java field or method
new javaclass(...)        // Create a new Java object

Properties

Each JavaClass object contains properties that have the same names as the public static fields and methods of the Java class it represents. These properties allow you to read and write the static fields of the class and invoke the static methods of the class. Each JavaClass object has different properties; you can use a for/in loop to enumerate them for any given JavaClass object.

Description

The JavaClass object is a JavaScript representation of a Java class. The properties of a JavaClass object represent the public static fields and methods (sometimes called class fields and class methods) of the represented class. Note that the JavaClass object does not have properties representing the instance fields of a Java class; individual instances of a Java class are represented by the JavaObject object.

The JavaClass object implements the LiveConnect functionality that allows JavaScript programs to read and write the static variables of Java classes using normal JavaScript syntax. It also provides the functionality that allows JavaScript to invoke the static methods of a Java class.

In addition to allowing JavaScript to read and write Java variable and method values, the JavaClass object allows JavaScript programs to create Java objects (represented by a JavaObject object) by using the new keyword and invoking the constructor method of a JavaClass.

The data conversion required for communication between JavaScript and Java through the JavaClass object is handled automatically by LiveConnect. See Chapter 12, Scripting Java for full details.

Usage

Bear in mind that Java is a typed language. This means that each of the fields of an object has a specific datatype that is set to values of only that type. Attempting to set a field to a value that is not of the correct type results in a JavaScript error or exception. Attempting to invoke a method with arguments of the wrong type also causes an error or exception.

Example

java.lang.System is a JavaClass object that represents the java.lang.System class in Java. You can read a static field of this class with code like the following:

var java_console = java.lang.System.out;

You can invoke a static method of this class with a line like this one:

var version = java.lang.System.getProperty("java.version");

Finally, the JavaClass object also allows you to create new Java objects:

var java_date = new java.lang.Date( );

See Also

getClass( ), JavaArray, JavaObject, JavaPackage; Chapter 12, Scripting Java

Synopsis

javaobject.member // Read or write an instance field or method

Properties

Each JavaObject object contains properties that have the same names as the public instance fields and methods (but not the static or class fields and methods) of the Java object it represents. These properties allow you to read and write the value of public fields and invoke the public methods. The properties of a given JavaObject object obviously depend on the type of Java object it represents. You can use the for/in loop to enumerate the properties of any given JavaObject.

Description

The JavaObject object is a JavaScript representation of a Java object. The properties of a JavaObject object represent the public instance fields and public instance methods defined for the Java object. (The class or static fields and methods of the object are represented by the JavaClass object.)

The JavaObject object implements the LiveConnect functionality that allows JavaScript programs to read and write the public instance fields of a Java object using normal JavaScript syntax. It also provides the functionality that allows JavaScript to invoke the methods of a Java object. Data conversion between JavaScript and Java representations is handled automatically by LiveConnect. See Chapter 12, Scripting Java for full details.

Usage

Bear in mind that Java is a typed language. This means that each field of an object has a specific datatype, and you can set it only to values of that type. For example, the width field of a java.awt.Rectangle object is an integer field, and attempting to set it to a string causes a JavaScript error or exception.

Example

java.awt.Rectangle is a JavaClass that represents the java.awt.Rectangle class. You can create a JavaObject that represents an instance of this class like this:

var r = new java.awt.Rectangle(0,0,4,5);

You can then read the public instance variables of this JavaObject r with code like this:

var perimeter = 2*r.width + 2*r.height;

You can also set the value of public instance variables of r using JavaScript syntax:

r.width = perimeter/4;
r.height = perimeter/4;

See Also

getClass( ), JavaArray, JavaClass, JavaPackage; Chapter 12, Scripting Java

Synopsis

package.package_name  // Refers to another JavaPackage

package.class_name    // Refers to a JavaClass object

Properties

The properties of a JavaPackage object are the names of the JavaPackage objects and JavaClass objects that it contains. These properties are different for each individual JavaPackage. Note that it is not possible to use the JavaScript for/in loop to iterate over the list of property names of a Package object. Consult a Java reference manual to determine the packages and classes contained within any given package.

Description

The JavaPackage object is a JavaScript representation of a Java package. A package in Java is a collection of related classes. In JavaScript, a JavaPackage can contain classes (represented by the JavaClass object) and other JavaPackage objects.

The global object has a JavaPackage property named java that represents the java.* package hierarchy. This JavaPackage object defines properties that refer to other JavaPackage objects. For example, java.lang and java.net refer to the java.lang and http://java.net packages. The java.awt JavaPackage contains properties named Frame and Button, which are references to JavaClass objects and represent the classes java.awt.Frame and java.awt.Button.

The global object also defines a property named Packages, which is the root JavaPackage whose properties refer to the roots of all known package hierarchies. For example, the expression Packages.javax.swing refers to the Java package javax.swing.

It is not possible to use the for/in loop to determine the names of the packages and classes contained within a JavaPackage. You must have this information in advance. You can find it in any Java reference manual or by examining the Java class hierarchy.

See Chapter 12, Scripting Java for further details on working with Java packages, classes, and objects.

See Also

java, JavaArray, JavaClass, JavaObject, Packages; Chapter 12, Scripting Java

Synopsis

Math.constantMath.function( )

Constants

Static Functions

Description

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

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

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

See Also

Number

Synopsis

Math.abs(x)

Synopsis

Math.acos(x)

Synopsis

Math.asin(x)

Synopsis

Math.atan(x)

Synopsis

Math.atan2(y, x)

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.

Synopsis

Math.ceil(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

Synopsis

Math.cos(x)

Synopsis

Math.E

Description

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

Synopsis

Math.exp(x)

Synopsis

Math.floor(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

Synopsis

Math.LN10

Description

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

Synopsis

Math.LN2

Description

Math.LN2 is log _e 10, the natural logarithm of 2. This constant has a value of approximately 0.69314718055994528623.

Synopsis

Math.log(x)

Description

Math.log( ) computes log _e 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:

log10x  = log10e · logex

log2x  = log2e · logex

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); }

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.

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.

Synopsis

Math.max(args...)

Synopsis

Math.min(args...)

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.

Synopsis

Math.pow(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.

Synopsis

Math.random( )

Synopsis

Math.round(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.

Synopsis

Math.sin(x)

Synopsis

Math.sqrt(x)

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

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.

Synopsis

Math.SQRT2

Description

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

Synopsis

Math.tan(x)

Synopsis

NaN

Description

NaN is a 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( ), because NaN always compares as nonequal to any other value, including itself!

See Also

Infinity, isNaN( ), Number.NaN

Constructor

new Number(value)
Number(value)

Constants

Methods

Description

Numbers are a basic, primitive datatype in JavaScript. 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. 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 NaN 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 you can use the Number methods with primitive numeric values as well as with Number objects.

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

See Also

Infinity, Math, NaN

Synopsis

Number.MAX_VALUE

Description

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

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.

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 as 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 property NaN instead of Number.NaN.

See Also

isNaN( ), NaN

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.

See Also

Infinity, isFinite( )

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 property Infinity instead of Number.POSITIVE_INFINITY.

See Also

Infinity, isFinite( )

Synopsis

number.toExponential(digits)

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

See Also

Number.toFixed( ), Number.toLocaleString( ), Number.toPrecision( ), Number.toString( )

Synopsis

number.toFixed(digits)

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

See Also

Number.toExponential( ), Number.toLocaleString( ), Number.toPrecision( ), Number.toString( )

Synopsis

number.toLocaleString( )

See Also

Number.toExponential( ), Number.toFixed( ), Number.toPrecision( ), Number.toString( )

Synopsis

number.toPrecision(precision)

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

See Also

Number.toExponential( ), Number.toFixed( ), Number.toLocaleString( ), Number.toString( )

Synopsis

number.toString(radix)

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. Although the ECMAScript specification does not require implementations to honor any other values for radix, all implementations in common use accept values between 2 and 36.

See Also

Number.toExponential( ), Number.toFixed( ), Number.toLocaleString( ), Number.toPrecision( )

Synopsis

number.valueOf( )

See Also

Object.valueOf( )

Constructor

new Object( )
new Object(value)

Properties

Methods

Description

The Object class is a built-in datatype 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 7, Objects and Arrays.

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

See Also

Array, Boolean, Function, Function.prototype, Number, String; Chapter 7, Objects and Arrays

Synopsis

object.constructor

Description

The constructor property of any object is a reference to the function that was used as the constructor for that object. For example, if you create an array a with the Array( ) constructor, a.constructor is an Array:

a = new Array(1,2,3);   // Create an object
a.constructor == Array  // Evaluates to true

One common use of the constructor property is to determine the type of unknown objects. Given an unknown value, you can use the typeof operator to determine whether it is a primitive value or an object. If it is an object, you can use the constructor property to determine what type of object it is. For example, the following function determines whether a given value is an array:

function isArray(x) {
    return ((typeof x == "object") && (x.constructor == Array));
}

Note, however, that while this technique works for the objects built into core JavaScript, it is not guaranteed to work with host objects such as the Window object of client-side JavaScript. The default implementation of the Object.toString( ) method provides another way to determine the type of an unknown object.

See Also

Object.toString( )

Synopsis

object.hasOwnProperty(propname)

Description

As explained in Chapter 9, Classes, Constructors, and Prototypes, JavaScript objects may have properties of their own, and they may also inherit properties from their prototype object. The hasOwnProperty( ) method provides a way to distinguish between inherited properties and noninherited local properties.

Example

var o = new Object( );            // Create an object
o.x = 3.14;                      // Define a noninherited local property
o.hasOwnProperty("x");           // Returns true: x is a local property of o
o.hasOwnProperty("y");           // Returns false: o doesn't have a property y
o.hasOwnProperty("toString");    // Returns false: toString property is inherited

See Also

Function.prototype, Object.propertyIsEnumerable( ); Chapter 9, Classes, Constructors, and Prototypes

Synopsis

object.isPrototypeOf(o)

Description

As explained in Chapter 9, Classes, Constructors, and Prototypes, JavaScript objects inherit properties from their prototype object. The prototype of an object is referred to by the prototype property of the constructor function that creates and initializes the object. The isPrototypeOf( ) method provides a way to determine if one object is the prototype of another. This technique can be used to determine the class of an object.

Example

var o = new Object( );                               // Create an object
Object.prototype.isPrototypeOf(o)                // true: o is an object
Function.prototype.isPrototypeOf(o.toString);    // true: toString is a function
Array.prototype.isPrototypeOf([1,2,3]);          // true: [1,2,3] is an array
// Here is a way to perform a similar test
(o.constructor == Object);  // true: o was created with Object( ) constructor
(o.toString.constructor == Function);            // true: o.toString is a function
// Prototype objects themselves have prototypes. The following call
// returns true, showing that function objects inherit properties
// from Function.prototype and also from Object.prototype.
Object.prototype.isPrototypeOf(Function.prototype);

See Also

Function.prototype, Object.constructor; Chapter 9, Classes, Constructors, and Prototypes

Synopsis

object.propertyIsEnumerable(propname)

Description

The for/in statement loops through the enumerable properties of an object. Not all properties of an object are enumerable, however: properties added to an object by JavaScript code are enumerable, but the predefined properties (such as methods) of built-in objects are not usually enumerable. The propertyIsEnumerable( ) method provides a way to distinguish between enumerable and nonenumerable properties. Note, however, that the ECMAScript specification states that propertyIsEnumerable( ) does not examine the prototype chain, which means it works only for local properties of an object and does not provide any way to test the enumerability of inherited properties.

Example

var o = new Object( );               // Create an object
o.x = 3.14;                         // Define a property
o.propertyIsEnumerable("x");        // true: property x is local and enumerable
o.propertyIsEnumerable("y");        // false: o doesn't have a property y
o.propertyIsEnumerable("toString"); // false: toString property is inherited
Object.prototype.propertyIsEnumerable("toString");  // false: nonenumerable

See Also

Function.prototype, Object.hasOwnProperty( ); Chapter 7, Objects and Arrays

Synopsis

object.toString( )

Description

This method is intended to return a string representation of the object, localized as appropriate for the current locale. The default toLocaleString( ) method provided by the Object class simply calls the toString( ) method and returns the nonlocalized string that it returns. Note, however, that other classes, including Array, Date, and Number, define their own versions of this method to perform localized string conversions. When defining your own classes, you may want to override this method as well.

See Also

Array.toLocaleString( ), Date.toLocaleString( ), Number.toLocaleString( ), Object.toString( )

Synopsis

object.toString( )

Description

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

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

alert(my_object);

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

var msg = 'My object is: ' + my_object;

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

When you define a custom class in JavaScript, it is good practice to define a toString( ) method for the class. If you do not, the object inherits the default toString( ) method from the Object class. This default method returns a string of the form:

[objectclass]

where class is the class of the object: a value such as "Object", "String", "Number", "Function", "Window", "Document", and so on. This behavior of the default toString( ) method is occasionally useful to determine the type or class of an unknown object. Because most objects have a custom version of toString( ), however, you must explicitly invoke the Object.toString( ) method on an object o with code like this:

Object.prototype.toString.apply(o);

Note that this technique for identifying unknown objects works only for built-in objects. If you define your own object class, it will have a class of "Object". In this case, you can use the Object.constructor property to obtain more information about the object.

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

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

y = Math.sqrt(x);       // Compute a number
ystr = y.toString( );       // Convert it to a string

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

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

alert(my_obj.toString( ));

See Also

Object.constructor, Object.toLocaleString( ), Object.valueOf( )

Synopsis

object.valueOf( )

Description

The valueOf( ) method of an object returns the primitive value associated with that object, if there is one. For objects of type Object, there is no primitive value, and this method simply returns the object itself.

For objects of type Number, however, valueOf( ) returns the primitive numeric value represented by the object. Similarly, it returns the primitive boolean value associated with a Boolean object and the string associated with a String object.

It is rarely necessary to invoke the valueOf( ) method yourself. JavaScript does this automatically whenever an object is used where a primitive value is expected. In fact, because of this automatic invocation of the valueOf( ) method, it is difficult to even distinguish between primitive values and their corresponding objects. The typeof operator shows you the difference between strings and String objects for example, but in practical terms, you can use them equivalently in your JavaScript code.

The valueOf( ) methods of the Number, Boolean, and String objects convert these wrapper objects to the primitive values they represent. The Object( ) constructor performs the opposite operation when invoked with a number, boolean, or string argument: it wraps the primitive value in an appropriate object wrapper. JavaScript performs this primitive-to-object conversion for you in almost all circumstances, so it is rarely necessary to invoke the Object( ) constructor in this way.

In some circumstances, you may want to define a custom valueOf( ) method for your own objects. For example, you might define a JavaScript object type to represent complex numbers (a real number plus an imaginary number). As part of this object type, you would probably define methods for performing complex addition, multiplication, and so on (see Example 9-2, “A complex number class”). But you might also want to treat your complex numbers like ordinary real numbers by discarding the imaginary part. To achieve this, you might do something like the following:

Complex.prototype.valueOf = new Function("return this.real");

With this valueOf( ) method defined for your Complex object type, you can, for example, pass one of your complex number objects to Math.sqrt( ), which computes the square root of the real portion of the complex number.

See Also

Object.toString( )

Synopsis

Packages

Description

In JavaScript implementations that include LiveConnect or other technology for scripting Java, the global Packages property is a JavaPackage object whose properties are all the package roots known to the Java interpreter. For example, Packages.javax.swing refers to the Java package javax.swing. The global property java is a shortcut for Packages.java.

See Also

java, JavaPackage; Chapter 12, Scripting Java

Synopsis

parseFloat(s)

Description

parseFloat( ) parses and returns the first number that occurs in s. Parsing stops, and the value is returned, when parseFloat( ) encounters a character in s that is not a valid part of the number. If s does not begin with a number that parseFloat( ) can parse, the function returns the not-a-number value NaN. Test for this return value with the isNaN( ) function. If you want to parse only the integer portion of a number, use parseInt( ) instead of parseFloat( ).

See Also

isNaN( ), parseInt( )

Synopsis

parseInt(s)

parseInt(s, radix)

Description

parseInt( ) parses and returns the first number (with an optional leading minus sign) that occurs in s. Parsing stops, and the value is returned, when parseInt( ) encounters a character in s that is not a valid digit for the specified radix. If s does not begin with a number that parseInt( ) can parse, the function returns the not-a-number value NaN. Use the isNaN( ) function to test for this return value.

The radix argument specifies the base of the number to be parsed. Specifying 10 makes parseInt( ) parse a decimal number. The value 8 specifies that an octal number (using digits 0 through 7) is to be parsed. The value 16 specifies a hexadecimal value, using digits 0 through 9 and letters A through F. radix can be any value between 2 and 36.

If radix is 0 or is not specified, parseInt( ) tries to determine the radix of the number from s. If s begins (after an optional minus sign) with 0x, parseInt( ) parses the remainder of s as a hexadecimal number. If s begins with a 0, the ECMAScript v3 standard allows an implementation of parseInt( ) to interpret the following characters as an octal number or as a decimal number. Otherwise, if s begins with a digit from 1 through 9, parseInt( ) parses it as a decimal number.

Example

parseInt("19", 10);  // Returns 19  (10 + 9)
parseInt("11", 2);   // Returns 3   (2 + 1)
parseInt("17", 8);   // Returns 15  (8 + 7)
parseInt("1f", 16);  // Returns 31  (16 + 15)
parseInt("10");      // Returns 10
parseInt("0x10");    // Returns 16
parseInt("010");     // Ambiguous: returns 10 or 8

Bugs

When no radix is specified, ECMAScript v3 allows an implementation to parse a string that begins with 0 (but not 0x or 0X) as an octal or as a decimal number. To avoid this ambiguity, you should explicitly specify a radix or leave the radix unspecified only when you are sure that all numbers to be parsed will be decimal numbers, or hexadecimal numbers with the 0x or 0X prefix.

See Also

isNaN( ), parseFloat( )

Constructor

new RangeError( )
new RangeError(message)

Properties

Description

An instance of the RangeError class is thrown when a numeric value is not in its legal range. For example, setting the length of an array to a negative number causes a RangeError to be thrown. See Error for details about throwing and catching exceptions.

See Also

Error, Error.message, Error.name

Constructor

new ReferenceError( )
new ReferenceError(message)

Properties

Description