Table of Contents | Previous | Next | Index


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
escape

Returns the hexadecimal encoding of an argument in the ISO Latin-1 character set; used to create strings to add to a URL.

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.

taint

Adds tainting to a data element or script.

unescape

Returns the ASCII string for the specified hexadecimal encoding value.

untaint

Removes tainting from a data element or script.


escape

Returns the hexadecimal encoding of an argument in the ISO-Latin-1 character set.

Core function

Implemented in

JavaScript 1.0, NES 2.0

ECMA version

ECMA-262 compatible, except for Unicode characters.

Syntax

escape("string")

Parameters

string

A string in the ISO-Latin-1 character set.

Description

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

Use the escape and unescape functions to encode and decode (add property values manually) a Uniform Resource Locator (URL), a Uniform Resource Identifier (URI), or a URI-type string.

The escape function encodes special characters in the specified string and returns the new string. It encodes spaces, punctuation, and any other character that is not an ASCII alphanumeric character, with the exception of these characters:

* @ - _ + . /
Unicode. The escape and unescape functions do not use Unicode as specified by the ECMA specification. Instead, they use the Internet Engineering Task Force (IETF) guidelines for escaping characters. Within a URI, characters use US-ASCII characters (ISO-Latin-1 character set). A URI is a sequence of characters from the basic Latin alphabet, digits, and a few special characters (for example, / and @). The escape sequences do not support \uXXXX as in Unicode or %uXXXX as specified by ECMA, but %XX, where XX is a 2-digit hexadecimal number (for example, %7E). In URI, characters are represented in octets, as 8-bit bytes.

To allow the escape and unescape functions to work with Web server-supported URLs and URIs, JavaScript does not use Unicode for these functions.

Unicode-specific escape sequences, %uXXXX, are not supported.

Examples

Example 1. The following example returns "%26":

escape("&") // returns "%26"
Example 2. The following statement returns a string with encoded characters for spaces, commas, and apostrophes.

// returns "The_rain.%20In%20Spain%2C%20Ma%92am"
escape("The_rain. In Spain, Ma'am")

See also

unescape


eval

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

Core function

Implemented in

JavaScript 1.0

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 should not indirectly use the eval function by invoking it via a name other than eval. 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.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
}
Example 5. The following example creates breed as a property of the object myDog, and also as a variable. The first write statement uses eval('breed') without specifying an object; the string "breed" is evaluated without regard to any object, and the write method displays "Shepherd", which is the value of the breed variable. The second write statement uses myDog.eval('breed') which specifies the object myDog; the string "breed" is evaluated with regard to the myDog object, and the write method displays "Lab", which is the value of the breed property of the myDog object.

function Dog(name,breed,color) {
   this.name=name
   this.breed=breed
   this.color=color
}
myDog = new Dog("Gabby")
myDog.breed="Lab"
var breed='Shepherd'
document.write("<P>" + eval('breed'))
document.write("<BR>" + myDog.eval('breed'))

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.

On platforms that support NaN, 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 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


taint

Adds tainting to a data element or script.

Client-side function

Implemented in

JavaScript 1.1

JavaScript 1.2: removed

Syntax

taint([dataElementName])

Parameters

dataElementName

The property, variable, function, or object to taint. If omitted, taint is added to the script itself.

Description

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

Tainting prevents other scripts from passing information that should be secure and private, such as directory structures or user session history. JavaScript cannot pass tainted values on to any server without the end user's permission.

Use taint to mark data that otherwise is not tainted.

In some cases, control flow rather than data flow carries tainted information. In these cases, taint is added to the script's window. You can add taint to the script's window by calling taint with no arguments.

taint does not modify its argument; instead, it returns a marked copy of the value, or, for objects, an unmarked reference to the value.

Examples

The following statement adds taint to a property so that a script cannot send it to another server without the end user's permission:

taintedStatus=taint(window.defaultStatus)
// taintedStatus now cannot be sent in a URL or form post without
// the end user's permission

See also

navigator.taintEnabled, untaint


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.


unescape

Returns the ASCII string for the specified hexadecimal encoding value.

Core function

Implemented in

JavaScript 1.0, NES 1.0

ECMA version

ECMA-262 compatible, except for Unicode characters.

Syntax

unescape(string)

Parameters

string

A string containing characters in the form "%xx", where xx is a 2-digit hexadecimal number.

Description

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

The string returned by the unescape function is a series of characters in the ISO-Latin-1 character set.

The escape and unescape methods do not use Unicode as specified by the ECMA specification. For information, see the description of "Unicode" on page 557.

Examples

The following example returns "&":

unescape("%26")
The following example returns "!#":

unescape("%21%23")

See also

escape


untaint

Removes tainting from a data element or script.

Client-side function

Implemented in

JavaScript 1.1

JavaScript 1.2: removed

Syntax

untaint([dataElementName])

Parameters

dataElementName

The property, variable, function, or object to remove tainting from. If omitted, taint is removed from the script itself.

Description

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

Tainting prevents other scripts from passing information that should be secure and private, such as directory structures or user session history. JavaScript cannot pass tainted values on to any server without the end user's permission.

Use untaint to clear tainting that marks data that should not to be sent by other scripts to different servers.

A script can untaint only data that originated in that script (that is, only data that has the script's taint code or has the identity (null) taint code). If you use untaint with a data element from another server's script (or any data that you cannot untaint), untaint returns the data without change or error.

In some cases, control flow rather than data flow carries tainted information. In these cases, taint is added to the script's window. You can remove taint from the script's window by calling untaint with no arguments, if the window contains taint only from the current window.

untaint does not modify its argument; instead, it returns an unmarked copy of the value, or, for objects, an unmarked reference to the value.

Examples

The following statement removes taint from a property so that a script can send it to another server:

untaintedStatus=untaint(window.defaultStatus)
// untaintedStatus can now be sent in a URL or form post by other
// scripts

See also

navigator.taintEnabled, taint


Table of Contents | Previous | Next | Index

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

Copyright (c) 1999 Netscape Communications Corporation