ECMAScript API Guide

CHAPTER 4

ECMAScript Core Language

Array Object

Array(item0, item1, . . .)

Array()

Constructor

join(separator)

Array join(separator)

The elements of the array are converted to strings, and these strings are then concatenated, separated by occurrences of the separator. If no separator is provided, a single comma is used as the separator.

length

Array length The length property of this Array object

pop()

Object pop()

Removes tail item from array and returns it. The array is permanently modified: It is shortened in length by one item.

push()

push(Object object)

Adds an item to the end of the array. The array grows in length by one.

reverse()

The elements of the array are rearranged so as to reverse their order. The operation is done in-place, meaning that the original array is modified.

shift()

Object shift()

Returns the first (actually, the zeroth) element of the array and removes it from the array. The array is shortened by one item. All remaining items are "shifted" such that each item's index is one less than before. Example:

  var ar = [ `a','b','c' ];
  var firstItem = ar.shift(); // `a'
  var item = ar[0]; // `b'

sort(comparefn)

Array sort()

The elements of this array are sorted. The sort is not necessarily stable. If comparefn is supplied, it should be a function that accepts two arguments x and y and returns a negative value if x < y, zero if x = y, or a positive value if x > y.

toString()

Array toString()

The elements of this object are converted to strings, and these strings are then concatenated, separated by comma characters. The result is the same as if the built-in join method were invoked for this object with no argument.

unshift()

unshift(value, [...] )

Adds one or more values to the start of the array. If a single argument is passed, it becomes item zero of the array and the array grows in length by one.

Boolean Object

There is seldom a need to use the object version of Boolean in place of true/false literal values. This object is provided for completeness. It is specified in ECMA-262.

Boolean()

Boolean( [true/false] )

Constructor. Optionally takes one of true or false as an argument.

toString()

Boolean toString()

If this boolean value is true, then the string "true" is returned. Otherwise, this boolean value must be false, and the string "false" is returned.

valueOf()

Boolean valueOf()

Returns this boolean value.

Date Object

Date()

constructor of the Date may have various signatures. The date constructor format can accept up to 7 parameters. Here is the format: new Date(year,month,date,hrs,mins,secs,ms)

getDate()

Method returns DateFromTime(LocalTime(t)).

getDay()

Method returns WeekDay(LocalTime(t)). The days of week are numbered from 0 -6. The number 0 represents Sunday and 6 represents Saturday.

getFullYear()

Method returns YearFromTime(LocalTime(t)).

getHours()

Method returns HourFromTime(LocalTime(t)).

getMilliseconds()

Method returns msFromTime(LocalTime(t)).

getMinutes()

Method returns MinFromTime(LocalTime(t)).

getMonth()

Method returns MonthFromTime(LocalTime(t)). The months are returned as an integer value from 0-11. The number 0 represents January and 11 represents December.

getSeconds()

Method returns SecFromTime(LocalTime(t)).

getTime()

Method returns a number, which is this time value. The number value is a millisecond representation of the specified Date object.

getTimezoneOffset()

Method returns (t * LocalTime(t)) / msPerMinute. The difference is in minutes between (GMT) and local time.

getUTCDate()

Method returns DateFromTime(t).

getUTCDay()

Method returns WeekDay(t). The days of week are numbered from 0 -6. The number 0 represents Sunday and 6 represents Saturday.

getUTCFullYear()

Method returns YearFromTime(t). There does not exist a getYearUTC method, therefore this method must be used to obtain a year from an UTC Date object.

getUTCHours()

Method returns HourFromTime(t).

getUTCMilliseconds()

Method returns msFromTime(t).

getUTCMinutes()

Method returns MinFromTime(t).

getUTCSeconds()

Method returns SecFromTime(t).

getYear()

Method returns YearFromTime(LocalTime(t))—1900. \The function getFullYear() is much to be preferred for nearly all purposes, because it avoids the year 2000 problem.

parse(string)

Method applies the ToString operator to its argument and interprets the resulting string as a date; it returns a number, the UTC time value corresponding to the date. The string may be interpreted as a local time, a UTC time, or a time in some other time zone, depending on the contents of the string.

setDate(date)

Method sets the [Value] property of this value to UTC ECMAScript.Date. Returns the value of the [Value] property of the this value. If the [Value] property of this exceeds 30 or 31, the [Value] of this will then be added to the existing date value, not set.

setFullYear(year[,mon[,date]])

Method sets the [Value] property of this value to UTC ECMAScript.Date. Returns the value of the [Value] property of the this value.

setHours(hour[,min[,sec[,ms]]])

Method sets the [Value] property of this value to UTC time. Returns the value of the [Value] property of the this value. When entering a value for hours, an hour value greater than 23 will be added on to the exisitng hour value, not set.

setMilliseconds(ms)

Method computes UTC from argument and sets the [Value] property of this value to TimeClip(calculatedUTCtime). Returns the value of the [Value] property of the this value.

setMinutes(min[,sec[,ms]])

Method sets the [Value] property of this value to UTC time. Returns the value of the [Value] property of the this value.

setMonth(mon[,date])

Method sets the [Value] property of this value to UTC ECMAScript.Date. Returns the value of the [Value] property of the this value. If the [Value] property of this exceeds 11, the [Value] property for this will be added to the existing month, not set

setSeconds(sec [, ms ] )

Method sets the [Value] property of this value to UTC time. Returns the value of the [Value] property of the this value.

setTime(time)

Method sets the [Value] property of the this to TimeClip(time). Returns the value of the [Value] property of the this value. The [Value] property of this is a millisecond value that is converted by the TimeClip(time) method.

setUTCDate(date)

Method sets the [Value] property of this value to ECMAScript.Date. Returns the value of the [Value] property of the this value. If the [Value] property of this exceeds 30 or 31, the [Value] of this will then be added to the existing date value, not set.

setUTCFullYear(year[,mon[,date]])

Method sets the [Value] property of this value to ECMAScript.Date. Returns the value of the [Value] property of the this value.

setUTCFullYear(year[,mon[,date]])

toGMTString()

Returns a string value. The contents of the string are implementation-dependent, but are intended to represent the Date in a convenient, human-readable form in UTC. NOTE: This function is for backwards compatibility only. Its use is not recomended. Use toUTCString() instead.

setUTCHours(min[,sec[,ms]])

Method sets the [Value] property of this value to time. Returns the value of the [Value] property of the this value. When entering a value for hours, an hour value greater than 23 will be added on to the exisitng hour value, not set.

setUTCMilliseconds(ms)

Method sets the [Value] property of this value to time and returns the value of the [Value] property of the this value.

setUTCMinutes(min[,sec[,ms]])

Method sets the [Value] property of this value to time. Returns the value of the [Value] property of the this value.

setUTCMonth(mon[,date])

Method sets the [Value] property of this value to ECMAScript.Date. Returns the value of the [Value] property of the this value. If the [Value] property of this exceeds 11, the [Value] property for this will be added to the existing month, not set

setUTCSeconds(sec [, ms ] )

Method sets the [Value] property of this value to time. Returns the value of the [Value] property of the this value.

setYear(year)

Method sets the [Value] property of this value to UTC ECMAScript.Date. Returns the value of the [Value] property of the this value.

toLocaleString()

Method returns a string value. The contents of the string are implementation-dependent, but are intended to represent the Date in a convenient, human-readable form appropriate to the geographic or cultural locale.

toString()

Method returns this string value. The contents of the string are implementation-dependent, but are intended to represent the Date in a convenient, human-readable form in the current time zone.

toUTCString()

Method returns a string value. The contents of the string are implementation-dependent, but are intended to represent the Date in a convenient, human-readable form in UTC.

UTC()

Method, which may accept different number of arguments. UTC function differs from the Date constructor in two ways: it returns a time value as a number, rather than creating a Date object, and it interprets the arguments in UTC rather than as local time.

valueOf()

Method returns a number, which is this time value. The valueOf() function is not generic. Therefore it will generate a runtime error if the object is not a Date object.

Function Object

Function(p1, p2, . . . , pn, body)

Function Constructor. The last argument specifies the body (executable code)

of a function; any preceding arguments specify formal parameters.

length

The value of the length property is usually an integer that indicates the "typical" number of arguments expected by the function. However, the language permits the function to be invoked with some other number of arguments. The behaviour of a function when invoked on a number of arguments other than the number specified by its length property depends on the function.

toString()

String toString()

An implementation-dependent representation of the function is returned. This representation has the syntax of a FunctionDeclaration. Note in particular that the use and placement of whitespace, line terminators, and semicolons within the representation string is implementation-dependent.

Math Object

All of the Math object's properties and methods are static, which means you should prepend "Math" to the property or method name in your code. For example, use "Math.PI," not simply "PI."

E

The number value for e, the base of the natural logarithms, which is approximately 2.7182818284590452354.

LN10

The number value for the natural logarithm of 10, which is approximately 2.302585092994046.

LN2

The number value for the natural logarithm of 2, which is approximately 0.6931471805599453.

LOG2E

The number value for the base-2 logarithm of e, the base of the natural logarithms; this value is approximately 1.4426950408889634. (Note that the value of Math.LOG2E is approximately the reciprocal of the value of Math.LN2.)

LOG10E

The number value for the base-10 logarithm of e, the base of the natural logarithms; this value is approximately 0.4342944819032518. (Note that the value of Math.LOG10E is approximately the reciprocal of the value of Math.LN10.)

PI

The number value for *, the ratio of the circumference of a circle to its diameter, which is approximately 3.14159265358979323846.

SQRT1_2

The number value for the square root of 1/2, which is approximately 0.7071067811865476. (Note that the value of Math.SQRT1_2 is approximately the reciprocal of the value of Math.SQRT2.)

SQRT2

The number value for the square root of 2, which is approximately 1.4142135623730951.

abs(x)

Number abs(x)

This function returns the absolute value of the argument x; in general, the result has the same magnitude as the argument but has positive sign. The input value x can be any number value. Example: Math.abs(-123.23940) = 123.23940

acos(x)

Number acos(x)

This function returns an implementation-dependent approximation to the arc cosine of the argument. The result is expressed in radians and ranges from +0 to +PI(3.14159...)radians. The input value x must be a number between -1.0 and 1.0. Example: PI/4 = 0.785 Math.acos(0.785) = 0.6681001997570769.

asin(x)

Number asin(x)

This function returns an implementation-dependent approximation to the arc sine of the argument. The result is expressed in radians and ranges from -PI/2 to +PI/2. The input value x must be a number between -1.0 and 1.0. Example: PI/4 = 0.785 Math.asin(0.785) = 0.9026961270378197.

atan(x)

Number atan(x)

This function returns an implementation-dependent approximation to the arc tangent of the argument. The result is expressed in radians and ranges from -PI/2 to +PI/2. The input value x can be any number. Example: 3PI/4 = 2.355 Math.atan(2.355) = 1.1692404275454853.

atan2(x,y)

Number atan2(x,y)

This function returns an implementation-dependent approximation to the arc tangent of the quotient y/x of the arguments y and x, where the signs of the arguments are used to determine the quadrant of the result. Note that it is intentional and traditional for the two-argument arc tangent function that the argument named y be first and the argument named x be second. The result is expressed in radians and ranges from -PI to +PI. The input value x is the x-coordinate of the point. The input value y is the y-coordinate of the point. Example: PI/2 = 1.57 Math.atan2(1.57,-1.57) = 2.356194490192345.

ceil(x)

Number ceil(x)

This function returns the smallest (closest to -infinity) number value that is not less than the argument and is equal to a mathematical integer. If the argument is already an integer, the result is the argument itself. The input value x can be any numeric value or expression. The Math.ceil(x) function property is the same as -Math.floor(-x). Example:

  Math.ceil(123.78457) = 123.

cos(x)

Number cos(x)

This function returns an implementation-dependent approximation to the cosine of the argument. The argument must be expressed in radians.

exp(x)

Number exp(x)

This function returns an implementation-dependent approximation to the exponential function of the argument (e raised to the power of the argument, where e is the base of the natural logarithms). The input value x can be any numeric value or expression greater than 0. Example:

  Math.exp(10) = 22026.465794806718.

floor(x)

Number floor(x)

This function returns the greatest (closest to +infinity)number value that is not greater than the argument and is equal to a mathematical integer. If the argument is already an integer, the result is the argument itself. The input value x can be any numeric value or expression.

Example:

  Math.floor(654.895869)=654.

log(x)

Number log(x)

This function returns an implementation-dependent approximation to natural logarithm of the argument. The input value x can be any numeric value or expression greater than 0. Example:

  Math.log(2) = 0.6931471805599453.

max(x,y)

Number max(x,y)

This function returns the larger of the two arguments. The input values x and y can be any numeric values or expressions. Example:

  Math.max(12.345,12.3456)= 12.3456.

min(x,y)

Number min(x,y)

This function returns the smaller of the two arguments. The input values x and y can be any numeric values or expressions. Example:

  Math.min(-12.457,-12.567)= -12.567.

pow(x,y)

Number pow(x,y)

This function returns an implementation-dependent approximation to the result of raising x to the power of y. The input value x must be the number raised to a power. The input value y must be the power that x is to be raised to. Example:

  Math.pow(2,4) = 16.

random()

Number random()

This function returns a positive floating-point number in the unit interval (0..1). The number value is chosen randomly or pseudo randomly with approximately uniform distribution over that range, using an implementation-dependent algorithm or strategy. This function takes no arguments. Example:

  Math.random()=0.9545176397178535.

round(x)

Number round(x)

This function returns the number value that is closest to the argument and is equal to a mathematical integer. If two integer number values are equally close to the argument, then the result is the number value that is closer to +infinity. If the argument is already an integer, the result is the argument itself. The input value x can be any number. Example:

  Math.round(13.53) = 14.

sin(x)

Number sin(x)

This function returns an implementation-dependent approximation to the sine of the argument. The argument is expressed in radians. The input value x must be an angle measured in radians.

sqrt(x)

Number sqrt(x)

This function returns an implementation-dependent approximation to the square root of the argument. The input value x must be any numeric value or expression greater than or equal to 0. If the input value x is less than zero, the string "NaN" is returned. The string "NaN" stands for "Not a Number". Example:

  Math.sqrt(25) = 5.

tan(x)

Number tan(x)

This function returns an implementation-dependent approximation to the tangent of the argument. The argument is expressed in radians. The input value x must be an angle measured in radians.

Number Object

MAX_VALUE

Number.MAX_VALUE The largest positive finite value of the number type, which is approximately 1.7976931348623157e308

MIN_VALUE

Number.MIN_VALUE The smallest positive nonzero value of the number type, which is approximately 5e-324

NaN

Number.NaN The primitive value NaN represents the set of IEEE Standard "Not-a-Number" values.

NEGATIVE_INFINITY

Number.NEGATIVE_INFINITY The value of negative infinity.

Number()

Constructor of Number has two forms: Number(value) and Number().

POSITIVE_INFINITY

Number.POSITIVE_INFINITY The value of positive infinity.

toString(radix)

toString()

If the radix is the number 10 or not supplied, then this number value is given as an argument to the ToString operator; the resulting string value is returned. If the radix is supplied and is an integer from 2 to 36, but not 10, the result is a string, the choice of which is implementation-dependent. The toString function is not generic; it generates a runtime error if its this value is not a Number object. Therefore, it cannot be transferred to other kinds of objects for use as a method.

valueOf()

Returns this number value. The valueOf function is not generic; it generates a runtime error if its this value is not a Number object. Therefore, it cannot be transferred to other kinds of objects for use as a method.

Object

Object( )

Constructor for Object.

toString()

Object toString()

When the toString method is called on an arbitrary object, the following steps are taken: 1. Get the [[Class]] property of this object. 2. Compute a string value by concatenating the three strings "[object ", Result(1), and "]". 3. Return Result(2).

valueOf()

Object valueOf()

As a rule, the valueOf method for an object simply returns the object; but if the object is a "wrapper" for a host object, as may perhaps be created by the Object constructor, then the contained host object should be returned.

String Object

String(x)

constructor of the string.

charAt(pos)

Method returns a string containing the character at position pos in the string resulting from converting this object to a string. If there is no character at that position, the result is the empty string. The result is a string value, not a string object.

charCodeAt(pos)

Method returns a number (a nonnegative integer less than 2^16) representing the Unicode code point encoding of the character at position pos in the string resulting from converting this object to a string. If there is no character at that position, the result is NaN.

fromCharCode(char0, char1, . . .)

returns a string value containing as many characters as the number of arguments. Each argument specifies one character of the resulting string, with the first argument specifying the first character, and so on, from left to right. An argument is converted to a character by applying the operation ToUint16 and regarding the resulting 16-bit integer as the Unicode code point encoding of a character. If no arguments are supplied, the result is the empty string.

indexOf(searchString, pos)

If the given searchString appears as a substring of the result of converting this object to a string, at one or more positions that are at or to the right of the specified position, then the index of the leftmost such position is returned; otherwise, -1 is returned. If position is undefined or not supplied, 0 is assumed, so as to search all of the string.

lastIndexOf(searchString, pos)

If the given searchString appears as a substring of the result of converting this object to a string, at one or more positions that are at or to the left of the specified position, then the index of the rightmost such position is returned; otherwise, -1 is returned. If position is undefined or not supplied, the length of the string value is assumed, so as to search all of the string.

length

length property equals to the number of characters in the String value represented by this string object.

match(RegExp)

String match(RegExp)

Takes a regular expression object as argument. It returns an Array of matches, else null.

replace(RegExp, String)

String replace(RegExp, String)

Takes a regular expression and a replacement string. Returns original string with replacements accomplished.

search(RegExp)

String search(RegExp)

Takes a regular expression as the sole arg and returns the offset of the first substring that matches, or -1 on no match.

split(separator)

Method returns an Array object, into which substrings of the result of converting this object to a string have been stored. The substrings are determined by searching from left to right for occurrences of the given separator; these occurrences are not part of any substring in the returned array, but serve to divide up the string value. The separator may be a string of any length.

substring(start, end)

Method returns a substring of the result of converting this object to a string, starting from character position start and running to the position end of the string. If second parameter is not present end position is considered end of the string. The result is a string value, not a string object.

toLowerCase()

Method returns a string equal in length to the length of the result of converting this object to a string. The result is a string value, not a string object. Every character of the result is equal to the corresponding character of the string, unless that character has a Unicode 2.0 lowercase equivalent, in which case the lowercase equivalent is used instead. (The canonical Unicode 2.0 case mapping shall be used, which does not depend on implementation or locale.

toString()

Method returns this string value. When concerned with the placement and use of whitespace line terminators, and semicolons within the representation string is implementation-dependent.

toUpperCase()

Method returns a string equal in length to the length of the result of converting this object to a string. The result is a string value, not a string object. Every character of the result is equal to the corresponding character of the string, unless that character has a Unicode 2.0 uppercase equivalent, in which case the uppercase equivalent is used instead. The canonical Unicode 2.0 case mapping shall be used, which does not depend on implementation or locale.

valueOf()

Method returns this string value. The valueOf() function is not generic. Therefore it will generate a runtime error if the object is not a String object.

Top-Level

ECMAScript provides certain "top-level" methods and properties, so-called because they are available from any context: They are not parented off any particular object.

escape(string)

String escape()

The escape function computes a new, URL-legal version of a string in which certain URL-illegal characters have been replaced by hexadecimal escape sequences.

eval(x)

eval()

When the eval function is called with one argument x, the following steps are taken: 1. If x is not a string value, return x. 2. Parse x as an ECMAScript Program. If the parse fails, generate a runtime error. 3. Evaluate the program from step 2. 4. If Result(3) is "normal" completion after value "V", return the value V. 5. Return undefined.

Infinity

A special primitive value representing positive infinity.

isFinite(number)

isFinite()

Applies Number( ) to its argument, then returns false if the result is NaN, +*, or **, and otherwise returns true.

isNaN( value )

isNan()

Returns true if the argument evaluates to NaN ("not a number"), otherwise returns false.

NOTE: Any form of logical comparison of NaN against anything else, including itself, returns false. Use isNaN( ) to determine whether a variable (or a return value, etc.) is equal to NaN.

NaN

The primitive value NaN represents the set of IEEE standard "Not-a-Number" values.

parseFloat(string)

number parseFloat()

Produces a floating-point number by interpretation of the contents of the string argument. If the string cannot be converted to a number, the special value NaN (see above) is returned.

parseInt(string, radix)

number parseInt()

Produces an integer value dictated by interpretation of the contents of the string argument, according to the specified radix.

unescape(string)

String unescape()

The unescape function computes a new version of a string value in which each escape sequences of the sort that might be introduced by the escape function is replaced with the character that it represents.