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.

- `escape` returns the hexadecimal encoding of the specified string in the ISO-Latin-1 character set.

- `unescape` returns the ASCII string, an ISO-Latin-1 character set sequence.

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 input `string` begins with `"0x"`, the radix is 16 (hexadecimal).

- If the input `string` begins with `"0"`, the radix is eight (octal).

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

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