Annotated ECMAScript 5.1

‟Ex igne vita”

9 Type Conversion and Testing #

The ECMAScript runtime system performs automatic type conversion as needed. To clarify the semantics of certain constructs it is useful to define a set of conversion abstract operations. These abstract operations are not a part of the language; they are defined here to aid the specification of the semantics of the language. The conversion abstract operations are polymorphic; that is, they can accept a value of any ECMAScript language type, but not of specification types.

9.1 ToPrimitive #

The abstract operation ToPrimitive takes an input argument and an optional argument PreferredType. The abstract operation ToPrimitive converts its input argument to a non-Object type. If an object is capable of converting to more than one primitive type, it may use the optional hint PreferredType to favour that type. Conversion occurs according to Table 10:

Table 10 — ToPrimitive Conversions

Input Type

Result

Undefined

The result equals the input argument (no conversion).

Null

The result equals the input argument (no conversion).

Boolean

The result equals the input argument (no conversion).

Number

The result equals the input argument (no conversion).

String

The result equals the input argument (no conversion).

Object

Return a default value for the Object. The default value of an object is retrieved by calling the [[DefaultValue]] internal method of the object, passing the optional hint PreferredType. The behaviour of the [[DefaultValue]] internal method is defined by this specification for all native ECMAScript objects in 8.12.8.

9.2 ToBoolean #

The abstract operation ToBoolean converts its argument to a value of type Boolean according to Table 11:

Table 11 — ToBoolean Conversions

Argument Type

Result

Undefined

false

Null

false

Boolean

The result equals the input argument (no conversion).

Number

The result is false if the argument is +0, 0, or NaN; otherwise the result is true.

String

The result is false if the argument is the empty String (its length is zero); otherwise the result is true.

Object

true

9.3 ToNumber #

The abstract operation ToNumber converts its argument to a value of type Number according to Table 12:

Table 12 — To Number Conversions

Argument Type

Result

Undefined

NaN

Null

+0

Boolean

The result is 1 if the argument is true. The result is +0 if the argument is false.

Number

The result equals the input argument (no conversion).

String

See grammar and note below.

Object

Apply the following steps:

  1. Let primValue be ToPrimitive(input argument, hint Number).

  2. Return ToNumber(primValue).

9.3.1 ToNumber Applied to the String Type #

ToNumber applied to Strings applies the following grammar to the input String. If the grammar cannot interpret the String as an expansion of StringNumericLiteral, then the result of ToNumber is NaN.

StringNumericLiteral :::

StrWhiteSpaceopt
StrWhiteSpace
optStrNumericLiteral StrWhiteSpaceopt

StrWhiteSpace :::

StrWhiteSpaceChar StrWhiteSpaceopt

StrWhiteSpaceChar :::

WhiteSpace
LineTerminator

StrNumericLiteral :::

StrDecimalLiteral
HexIntegerLiteral

StrDecimalLiteral :::

StrUnsignedDecimalLiteral
+ StrUnsignedDecimalLiteral
- StrUnsignedDecimalLiteral

StrUnsignedDecimalLiteral :::

Infinity
DecimalDigits
. DecimalDigitsoptExponentPartopt
. DecimalDigits ExponentPartopt
DecimalDigits ExponentPart
opt

DecimalDigits :::

DecimalDigit
DecimalDigits DecimalDigit

DecimalDigit ::: one of

0 1 2 3 4 5 6 7 8 9

ExponentPart :::

ExponentIndicator SignedInteger

ExponentIndicator ::: one of

e E

SignedInteger :::

DecimalDigits
+ DecimalDigits
- DecimalDigits

HexIntegerLiteral :::

0x HexDigit
0X HexDigit
HexIntegerLiteral HexDigit

HexDigit ::: one of

0 1 2 3 4 5 6 7 8 9 a b c d e f A B C D E F

Some differences should be noted between the syntax of a StringNumericLiteral and a NumericLiteral (see 7.8.3):

The conversion of a String to a Number value is similar overall to the determination of the Number value for a numeric literal (see 7.8.3), but some of the details are different, so the process for converting a String numeric literal to a value of Number type is given here in full. This value is determined in two steps: first, a mathematical value (MV) is derived from the String numeric literal; second, this mathematical value is rounded as described below.

Once the exact MV for a String numeric literal has been determined, it is then rounded to a value of the Number type. If the MV is 0, then the rounded value is +0 unless the first non white space character in the String numeric literal is ‘-’, in which case the rounded value is 0. Otherwise, the rounded value must be the Number value for the MV (in the sense defined in 8.5), unless the literal includes a StrUnsignedDecimalLiteral and the literal has more than 20 significant digits, in which case the Number value may be either the Number value for the MV of a literal produced by replacing each significant digit after the 20th with a 0 digit or the Number value for the MV of a literal produced by replacing each significant digit after the 20th with a 0 digit and then incrementing the literal at the 20th digit position. A digit is significant if it is not part of an ExponentPart and

9.4 ToInteger #

The abstract operation ToInteger converts its argument to an integral numeric value. This abstract operation functions as follows:

  1. Let number be the result of calling ToNumber on the input argument.

  2. If number is NaN, return +0.

  3. If number is +0, 0, +, or −∞, return number.

  4. Return the result of computing sign(number) * floor(abs(number)).

9.5 ToInt32: (Signed 32 Bit Integer) #

The abstract operation ToInt32 converts its argument to one of 232 integer values in the range 231 through 2311, inclusive. This abstract operation functions as follows:

  1. Let number be the result of calling ToNumber on the input argument.

  2. If number is NaN, +0, 0, +, or −∞, return +0.

  3. Let posInt be sign(number) * floor(abs(number)).

  4. Let int32bit be posInt modulo 232; that is, a finite integer value k of Number type with positive sign and less than 232 in magnitude such that the mathematical difference of posInt and k is mathematically an integer multiple of 232.

  5. If int32bit is greater than or equal to 231, return int32bit 232, otherwise return int32bit.

NOTE Given the above definition of ToInt32:

9.6 ToUint32: (Unsigned 32 Bit Integer) #

The abstract operation ToUint32 converts its argument to one of 232 integer values in the range 0 through 2321, inclusive. This abstraction operation functions as follows:

  1. Let number be the result of calling ToNumber on the input argument.

  2. If number is NaN, +0, 0, +, or , return +0.

  3. Let posInt be sign(number) * floor(abs(number)).

  4. Let int32bit be posInt modulo 232; that is, a finite integer value k of Number type with positive sign and less than 232 in magnitude such that the mathematical difference of posInt and k is mathematically an integer multiple of 232.

  5. Return int32bit.

NOTE Given the above definition of ToUInt32:

9.7 ToUint16: (Unsigned 16 Bit Integer) #

The abstract operation ToUint16 converts its argument to one of 216 integer values in the range 0 through 2161, inclusive. This abstract operation functions as follows:

  1. Let number be the result of calling ToNumber on the input argument.

  2. If number is NaN, +0, 0, +, or , return +0.

  3. Let posInt be sign(number) * floor(abs(number)).

  4. Let int16bit be posInt modulo 216; that is, a finite integer value k of Number type with positive sign and less than 216 in magnitude such that the mathematical difference of posInt and k is mathematically an integer multiple of 216.

  5. Return int16bit.

NOTE Given the above definition of ToUint16:

9.8 ToString #

The abstract operation ToString converts its argument to a value of type String according to Table 13:

Table 13 — ToString Conversions

Argument Type

Result

Undefined

"undefined"

Null

"null"

Boolean

If the argument is true, then the result is "true".

If the argument is false, then the result is "false".

Number

See 9.8.1.

String

Return the input argument (no conversion)

Object

Apply the following steps:

1. Let primValue be ToPrimitive(input argument, hint String).

2. Return ToString(primValue).

9.8.1 ToString Applied to the Number Type #

The abstract operation ToString converts a Number m to String format as follows:

  1. If m is NaN, return the String "NaN".

  2. If m is +0 or 0, return the String "0".

  3. If m is less than zero, return the String concatenation of the String "-" and ToString(m).

  4. If m is infinity, return the String "Infinity".

  5. Otherwise, let n, k, and s be integers such that k 1, 10k1 s < 10k, the Number value for s × 10nk is m, and k is as small as possible. Note that k is the number of digits in the decimal representation of s, that s is not divisible by 10, and that the least significant digit of s is not necessarily uniquely determined by these criteria.

  6. If k n 21, return the String consisting of the k digits of the decimal representation of s (in order, with no leading zeroes), followed by nk occurrences of the character ‘0’.

  7. If 0 < n 21, return the String consisting of the most significant n digits of the decimal representation of s, followed by a decimal point ‘.’, followed by the remaining kn digits of the decimal representation of s.

  8. If 6 < n 0, return the String consisting of the character ‘0’, followed by a decimal point ‘.’, followed by n occurrences of the character ‘0’, followed by the k digits of the decimal representation of s.

  9. Otherwise, if k = 1, return the String consisting of the single digit of s, followed by lowercase character ‘e’, followed by a plus sign ‘+’ or minus sign ‘’ according to whether n1 is positive or negative, followed by the decimal representation of the integer abs(n1) (with no leading zeros).

  10. Return the String consisting of the most significant digit of the decimal representation of s, followed by a decimal point ‘.’, followed by the remaining k1 digits of the decimal representation of s, followed by the lowercase character ‘e’, followed by a plus sign ‘+’ or minus sign ‘’ according to whether n1 is positive or negative, followed by the decimal representation of the integer abs(n1) (with no leading zeros).

NOTE 1 The following observations may be useful as guidelines for implementations, but are not part of the normative requirements of this Standard:

NOTE 2 For implementations that provide more accurate conversions than required by the rules above, it is recommended that the following alternative version of step 5 be used as a guideline:

Otherwise, let n, k, and s be integers such that k 1, 10k1 s < 10k, the Number value for s × 10nk is m, and k is as small as possible. If there are multiple possibilities for s, choose the value of s for which s × 10nk is closest in value to m. If there are two such possible values of s, choose the one that is even. Note that k is the number of digits in the decimal representation of s and that s is not divisible by 10.

NOTE 3 Implementers of ECMAScript may find useful the paper and code written by David M. Gay for binary-to-decimal conversion of floating-point numbers:

Gay, David M. Correctly Rounded Binary-Decimal and Decimal-Binary Conversions. Numerical Analysis, Manuscript 90-10. AT&T Bell Laboratories (Murray Hill, New Jersey). November 30, 1990. Available as
http://cm.bell-labs.com/cm/cs/doc/90/4-10.ps.gz. Associated code available as
http://cm.bell-labs.com/netlib/fp/dtoa.c.gz and as
http://cm.bell-labs.com/netlib/fp/g_fmt.c.gz and may also be found at the various netlib mirror sites.

9.9 ToObject #

The abstract operation ToObject converts its argument to a value of type Object according to Table 14:

Table 14 — ToObject

Argument Type

Result

Undefined

Throw a TypeError exception.

Null

Throw a TypeError exception.

Boolean

Create a new Boolean object whose [[PrimitiveValue]] internal property is set to the value of the argument. See 15.6 for a description of Boolean objects.

Number

Create a new Number object whose [[PrimitiveValue]] internal property is set to the value of the argument. See 15.7 for a description of Number objects.

String

Create a new String object whose [[PrimitiveValue]] internal property is set to the value of the argument. See 15.5 for a description of String objects.

Object

The result is the input argument (no conversion).

9.10 CheckObjectCoercible #

The abstract operation CheckObjectCoercible throws an error if its argument is a value that cannot be converted to an Object using ToObject. It is defined by Table 15:

Table 15 — CheckObjectCoercible Results

Argument Type

Result

Undefined

Throw a TypeError exception.

Null

Throw a TypeError exception.

Boolean

Return

Number

Return

String

Return

Object

Return

9.11 IsCallable #

The abstract operation IsCallable determines if its argument, which must be an ECMAScript language value, is a callable function Object according to Table 16:

Table 16 — IsCallable Results

Argument Type

Result

Undefined

Return false.

Null

Return false.

Boolean

Return false.

Number

Return false.

String

Return false.

Object

If the argument object has an [[Call]] internal method, then return true, otherwise return false.

9.12 The SameValue Algorithm #

The internal comparison abstract operation SameValue(x, y), where x and y are ECMAScript language values, produces true or false. Such a comparison is performed as follows:

  1. If Type(x) is different from Type(y), return false.

  2. If Type(x) is Undefined, return true.

  3. If Type(x) is Null, return true.

  4. If Type(x) is Number, then.

    1. If x is NaN and y is NaN, return true.

    2. If x is +0 and y is -0, return false.

    3. If x is -0 and y is +0, return false.

    4. If x is the same Number value as y, return true.

    5. Return false.

  5. If Type(x) is String, then return true if x and y are exactly the same sequence of characters (same length and same characters in corresponding positions); otherwise, return false.

  6. If Type(x) is Boolean, return true if x and y are both true or both false; otherwise, return false.

  7. Return true if x and y refer to the same object. Otherwise, return false.