Previous     Contents     Index     Next     
Core JavaScript Reference 1.5



Chapter 2   Chapter 2 Top-Level Properties and Functions


This chapter contains all JavaScript properties and functions not associated with any object. In the ECMA specification, these properties and functions are referred to as properties and methods of the global object.

The following table summarizes the top-level properties.


Table 2.1    Top-level properties

Property

Description

Infinity

 

A numeric value representing infinity.  

NaN

 

A value representing Not-A-Number.  

undefined

 

The value undefined.  

The following table summarizes the top-level functions.


Table 2.2    Top-level functions

Function

Description

decodeURI

 

Decodes a URI which has been encoded with encodeURI.  

decodeURIComponent

 

Decodes a URI which has been encoded with encodeURIComponent  

encodeURI

 

Computes a new version of a complete URI replacing each instance of certain characters with escape sequences representing the UTF-8 encoding of the characters.  

encodeURIComponent

 

Computes a new version of components of a URI replacing each instance of certain characters with escape sequences representing the UTF-8 encoding of the characters.  

eval

 

Evaluates a string of JavaScript code without reference to a particular object.  

isFinite

 

Evaluates an argument to determine whether it is a finite number.  

isNaN

 

Evaluates an argument to determine if it is not a number.  

Number

 

Converts an object to a number.  

parseFloat

 

Parses a string argument and returns a floating-point number.  

parseInt

 

Parses a string argument and returns an integer.  

String

 

Converts an object to a string.  



decodeURI



Decodes a Uniform Resource Identifier (URI) previously created by encodeURI or by a similar routine.

Core function  

 

Implemented in  

JavaScript 1.5, NES 6.0  

ECMA version  

ECMA-262 Edition 3.  


Syntax
decodeURI(encodedURI)


Parameters


encodedUri

 

A complete, encoded Uniform Resource Identifier.  


Description
Replaces each escape sequence in the encoded URI with the character that it represents.

Does not decode escape sequences that could not have been introduced by encodeURI.


See also
decodeURIComponent, encodeURI, encodeURIComponent



decodeURIComponent



Decodes a Uniform Resource Identifier (URI) component previously created by encodeURIComponent or by a similar routine.

Core function  

 

Implemented in  

JavaScript 1.5, NES 6.0  

ECMA version  

ECMA-262 Edition 3.  


Syntax
decodeURIComponent(encodedURI)


Parameters


encodedUri

 

An encoded component of a Uniform Resource Identifier.  


Description
Replaces each escape sequence in the encoded URI component with the character that it represents.


See also
decodeURI, encodeURI, encodeURIComponent



encodeURI



Encodes a Uniform Resource Identifier (URI) by replacing each instance of certain characters by one, two, or three escape sequences representing the UTF-8 encoding of the character.



Core function  

 

Implemented in  

JavaScript 1.5, NES 6.0  

ECMA version  

ECMA-262 Edition 3.  


Syntax
encodeURI(uri)


Parameters



uri

 

A complete Uniform Resource Identifier.  


Description
Assumes that the URI is a complete URI, so does not encode reserved characters that have special meaning in the URI.

encodeURI replaces all characters except the following with the appropriate UTF-8 escape sequences:

.



reserved characters  

, / ? : @ & = + $ ,  

unescaped characters  

alphabetic, decimal digits, - _ . ! ~ * ' ( )  

score  

#  


See also
decodeURI, eval, encodeURIComponent



encodeURIComponent



Encodes a Uniform Resource Identifier (URI) component by replacing each instance of certain characters by one, two, or three escape sequences representing the UTF-8 encoding of the character.



Core function  

 

Implemented in  

JavaScript 1.5, NES 6.0  

ECMA version  

ECMA-262 Edition 3.  


Syntax
encodeURIComponent(uri)


Parameters



uri

 

A component of a Uniform Resource Identifier.  


Description
Assumes that the URI is a URI component rather than a complete URI, so does not treat reserved characters as if they have special meaning and encodes them. See encodeURI for the list of reserved characters.

encodeURIComponent replaces all characters except the following with the appropriate UTF-8 escape sequences:

.



unescaped characters  

alphabetic, decimal digits, - _ . ! ~ * ' ( )  

score  

#  


See also
decodeURI, eval, encodeURI



eval



Evaluates a string of JavaScript code without reference to a particular object.



Core function  

 

Implemented in  

JavaScript 1.0

JavaScript 1.4: eval cannot be called indirectly  

ECMA version  

ECMA-262  


Syntax
eval(string)


Parameters



string

 

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


Description
eval is a top-level function and is not associated with any object.

The argument of the eval function is a string. If the string represents an expression, eval evaluates the expression. If the argument represents one or more JavaScript statements, eval performs the statements. Do not call eval to evaluate an arithmetic expression; JavaScript evaluates arithmetic expressions automatically.

If you construct an arithmetic expression as a string, you can use eval to evaluate it at a later time. For example, suppose you have a variable x. You can postpone evaluation of an expression involving x by assigning the string value of the expression, say "3 * x + 2", to a variable, and then calling eval at a later point in your script.

If the argument of eval is not a string, eval returns the argument unchanged. In the following example, the String constructor is specified, and eval returns a String object rather than evaluating the string.

eval(new String("2+2")) // returns a String object containing "2+2"
eval("2+2")             // returns 4

You cannot indirectly use the eval function by invoking it via a name other than eval; if you do, a runtime error might occur. For example, you should not use the following code:

var x = 2
var y = 4
var myEval = eval
myEval("x + y")


Backward Compatibility

JavaScript 1.3 and earlier versions. You can use eval indirectly, although it is discouraged.

JavaScript 1.1. eval is also a method of all objects. This method is described for the Object class.


Examples
The following examples display output using document.write. In server-side JavaScript, you can display the same output by calling the write function instead of using document.write.

Example 1. In the following code, both of the statements containing eval return 42. The first evaluates the string "x + y + 1"; the second evaluates the string "42".

var x = 2
var y = 39
var z = "42"
eval("x + y + 1") // returns 42
eval(z)           // returns 42

Example 2. In the following example, the getFieldName(n) function returns the name of the specified form element as a string. The first statement assigns the string value of the third form element to the variable field. The second statement uses eval to display the value of the form element.

var field = getFieldName(3)
document.write("The field named ", field, " has value of ",
   eval(field + ".value"))

Example 3. The following example uses eval to evaluate the string str. This string consists of JavaScript statements that open an Alert dialog box and assign z a value of 42 if x is five, and assigns 0 to z otherwise. When the second statement is executed, eval will cause these statements to be performed, and it will also evaluate the set of statements and return the value that is assigned to z.

var str = "if (x == 5) {alert('z is 42'); z = 42;} else z = 0; "
document.write("<P>z is ", eval(str))

Example 4. In the following example, the setValue function uses eval to assign the value of the variable newValue to the text field textObject:

function setValue (textObject, newValue) {
   eval ("document.forms[0]." + textObject + ".value") = newValue
}


See also
Object.eval method



Infinity



A numeric value representing infinity.



Core property  

 

Implemented in  

JavaScript 1.3 (In previous versions, Infinity was defined only as a property of the Number object.)  

ECMA version  

ECMA-262  


Syntax
Infinity


Description
Infinity is a top-level property and is not associated with any object.

The initial value of Infinity is Number.POSITIVE_INFINITY. The value Infinity (positive infinity) is greater than any other number including itself. This value behaves mathematically like infinity; for example, anything multiplied by Infinity is Infinity, and anything divided by Infinity is 0.


See also
Number.NEGATIVE_INFINITY , Number.POSITIVE_INFINITY



isFinite



Evaluates an argument to determine whether it is a finite number.



Core function  

 

Implemented in  

JavaScript 1.3  

ECMA version  

ECMA-262  


Syntax
isFinite(number)


Parameters



number

 

The number to evaluate.  


Description
isFinite is a top-level function and is not associated with any object.

You can use this method to determine whether a number is a finite number. The isFinite method examines the number in its argument. If the argument is NaN, positive infinity or negative infinity, this method returns false, otherwise it returns true.


Examples
You can check a client input to determine whether it is a finite number.

if(isFinite(ClientInput) == true)
{
   /* take specific steps */
}


See also
Number.NEGATIVE_INFINITY , Number.POSITIVE_INFINITY



isNaN



Evaluates an argument to determine if it is not a number.



Core function  

 

Implemented in  

JavaScript 1.0: Unix only

JavaScript 1.1, NES 2.0: all platforms  

ECMA version  

ECMA-262  


Syntax
isNaN(testValue)


Parameters



testValue

 

The value you want to evaluate.  


Description
isNaN is a top-level function and is not associated with any object.

The parseFloat and parseInt functions return NaN when they evaluate a value that is not a number. isNaN returns true if passed NaN, and false otherwise.


Examples
The following example evaluates floatValue to determine if it is a number and then calls a procedure accordingly:

floatValue=parseFloat(toFloat)

if (isNaN(floatValue)) {
   notFloat()
} else {
   isFloat()
}


See also
Number.NaN, parseFloat, parseInt



NaN



A value representing Not-A-Number.



Core property  

 

Implemented in  

JavaScript 1.3 (In previous versions, NaN was defined only as a property of the Number object)  

ECMA version  

ECMA-262  


Syntax
NaN


Description
NaN is a top-level property and is not associated with any object.

The initial value of NaN is NaN.

NaN is always unequal to any other number, including NaN itself; you cannot check for the not-a-number value by comparing to Number.NaN. Use the isNaN function instead.

Several JavaScript methods (such as the Number constructor, parseFloat, and parseInt) return NaN if the value specified in the parameter is not a number.

You might use the NaN property to indicate an error condition for a function that should return a valid number.


See also
isNaN, Number.NaN



Number



Converts the specified object to a number.



Core function  

 

Implemented in  

JavaScript 1.2, NES 3.0  

ECMA version  

ECMA-262  


Syntax
Number(obj)


Parameter



obj

 

An object.  


Description
Number is a top-level function and is not associated with any object.

When the object is a Date object, Number returns a value in milliseconds measured from 01 January, 1970 UTC (GMT), positive after this date, negative before.

If obj is a string that does not contain a well-formed numeric literal, Number returns NaN.


Example
The following example converts the Date object to a numerical value:

d = new Date ("December 17, 1995 03:24:00")
alert (Number(d))

This displays a dialog box containing "819199440000."


See also
Number



parseFloat



Parses a string argument and returns a floating point number.



Core function  

 

Implemented in  

JavaScript 1.0: If the first character of the string specified in parseFloat(string) cannot be converted to a number, returns NaN on Solaris and Irix and 0 on all other platforms.

JavaScript 1.1, NES 2.0: Returns NaN on all platforms if the first character of the string specified in parseFloat(string) cannot be converted to a number.  

ECMA version  

ECMA-262  


Syntax
parseFloat(string)


Parameters



string

 

A string that represents the value you want to parse.  


Description
parseFloat is a top-level function and is not associated with any object.

parseFloat parses its argument, a string, and returns a floating point number. If it encounters a character other than a sign (+ or -), numeral (0-9), a decimal point, or an exponent, it returns the value up to that point and ignores that character and all succeeding characters. Leading and trailing spaces are allowed.

If the first character cannot be converted to a number, parseFloat returns NaN.

For arithmetic purposes, the NaN value is not a number in any radix. You can call the isNaN function to determine if the result of parseFloat is NaN. If NaN is passed on to arithmetic operations, the operation results will also be NaN.


Examples
The following examples all return 3.14:

parseFloat("3.14")
parseFloat("314e-2")
parseFloat("0.0314E+2")
var x = "3.14"
parseFloat(x)

The following example returns NaN:

parseFloat("FF2")


See also
isNaN, parseInt



parseInt



Parses a string argument and returns an integer of the specified radix or base.



Core function  

 

Implemented in  

JavaScript 1.0: If the first character of the string specified in parseInt(string) cannot be converted to a number, returns NaN on Solaris and Irix and 0 on all other platforms.

JavaScript 1.1, LiveWire 2.0: Returns NaN on all platforms if the first character of the string specified in parseInt(string) cannot be converted to a number.  

ECMA version  

ECMA-262  


Syntax
parseInt(string[, radix])


Parameters



string

 

A string that represents the value you want to parse.  

radix

 

An integer that represents the radix of the return value.  


Description
parseInt is a top-level function and is not associated with any object.

The parseInt function parses its first argument, a string, and attempts to return an integer of the specified radix (base). For example, a radix of 10 indicates to convert to a decimal number, 8 octal, 16 hexadecimal, and so on. For radixes above 10, the letters of the alphabet indicate numerals greater than 9. For example, for hexadecimal numbers (base 16), A through F are used.

If parseInt encounters a character that is not a numeral in the specified radix, it ignores it and all succeeding characters and returns the integer value parsed up to that point. parseInt truncates numbers to integer values. Leading and trailing spaces are allowed.

If the radix is not specified or is specified as 0, JavaScript assumes the following:

  • If the input string begins with "0x", the radix is 16 (hexadecimal).

  • If the input string begins with "0", the radix is eight (octal). This feature is deprecated.

  • If the input string begins with any other value, the radix is 10 (decimal).
If the first character cannot be converted to a number, parseInt returns NaN.

For arithmetic purposes, the NaN value is not a number in any radix. You can call the isNaN function to determine if the result of parseInt is NaN. If NaN is passed on to arithmetic operations, the operation results will also be NaN.


Examples
The following examples all return 15:

parseInt("F", 16)
parseInt("17", 8)
parseInt("15", 10)
parseInt(15.99, 10)
parseInt("FXX123", 16)
parseInt("1111", 2)
parseInt("15*3", 10)

The following examples all return NaN:

parseInt("Hello", 8)
parseInt("0x7", 10)
parseInt("FFF", 10)

Even though the radix is specified differently, the following examples all return 17 because the input string begins with "0x".

parseInt("0x11", 16)
parseInt("0x11", 0)
parseInt("0x11")


See also
isNaN, parseFloat, Object.valueOf



String



Converts the specified object to a string.



Core function  

 

Implemented in  

JavaScript 1.2, NES 3.0  

ECMA version  

ECMA-262  


Syntax
String(obj)


Parameter



obj

 

An object.  


Description
String is a top-level function and is not associated with any object.

The String method converts the value of any object into a string; it returns the same value as the toString method of an individual object.

When the object is a Date object, String returns a more readable string representation of the date. Its format is: Thu Aug 18 04:37:43 Pacific Daylight Time 1983.


Example
The following example converts the Date object to a readable string.

D = new Date (430054663215)
alert (String(D))

This displays a dialog box containing "Thu Aug 18 04:37:43 GMT-0700 (Pacific Daylight Time) 1983."


See also
String



undefined



The value undefined.



Core property  

 

Implemented in  

JavaScript 1.3  

ECMA version  

ECMA-262  


Syntax
undefined


Description
undefined is a top-level property and is not associated with any object.

A variable that has not been assigned a value is of type undefined. A method or statement also returns undefined if the variable that is being evaluated does not have an assigned value.

You can use undefined to determine whether a variable has a value. In the following code, the variable x is not defined, and the if statement evaluates to true.

var x
if(x == undefined) {
   // these statements execute
}

undefined is also a primitive value.


Previous     Contents     Index     Next     
Copyright © 2000 Netscape Communications Corp. All rights reserved.

Last Updated September 28, 2000