ECMAScript® 2024 Language Specification

Draft ECMA-262 / December 6, 2023

7.1 Type Conversion

The ECMAScript language implicitly performs automatic type conversion as needed. To clarify the semantics of certain constructs it is useful to define a set of conversion abstract operations. The conversion abstract operations are polymorphic; they can accept a value of any ECMAScript language type. But no other specification types are used with these operations.

The BigInt type has no implicit conversions in the ECMAScript language; programmers must call BigInt explicitly to convert values from other types.

7.1.1 ToPrimitive ( input [ , preferredType ] )

The abstract operation ToPrimitive takes argument input (an ECMAScript language value) and optional argument preferredType (string or number) and returns either a normal completion containing an ECMAScript language value or a throw completion. It 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. It performs the following steps when called:

  1. If input is an Object, then
    1. Let exoticToPrim be ? GetMethod(input, @@toPrimitive).
    2. If exoticToPrim is not undefined, then
      1. If preferredType is not present, then
        1. Let hint be "default".
      2. Else if preferredType is string, then
        1. Let hint be "string".
      3. Else,
        1. Assert: preferredType is number.
        2. Let hint be "number".
      4. Let result be ? Call(exoticToPrim, input, « hint »).
      5. If result is not an Object, return result.
      6. Throw a TypeError exception.
    3. If preferredType is not present, let preferredType be number.
    4. Return ? OrdinaryToPrimitive(input, preferredType).
  2. Return input.
 Note

When ToPrimitive is called without a hint, then it generally behaves as if the hint were number. However, objects may over-ride this behaviour by defining a @@toPrimitive method. Of the objects defined in this specification only Dates (see 21.4.4.45) and Symbol objects (see 20.4.3.5) over-ride the default ToPrimitive behaviour. Dates treat the absence of a hint as if the hint were string.

7.1.1.1 OrdinaryToPrimitive ( O, hint )

The abstract operation OrdinaryToPrimitive takes arguments O (an Object) and hint (string or number) and returns either a normal completion containing an ECMAScript language value or a throw completion. It performs the following steps when called:

  1. If hint is string, then
    1. Let methodNames be « "toString", "valueOf" ».
  2. Else,
    1. Let methodNames be « "valueOf", "toString" ».
  3. For each element name of methodNames, do
    1. Let method be ? Get(O, name).
    2. If IsCallable(method) is true, then
      1. Let result be ? Call(method, O).
      2. If result is not an Object, return result.
  4. Throw a TypeError exception.

7.1.2 ToBoolean ( argument )

The abstract operation ToBoolean takes argument argument (an ECMAScript language value) and returns a Boolean. It converts argument to a value of type Boolean. It performs the following steps when called:

  1. If argument is a Boolean, return argument.
  2. If argument is one of undefined, null, +0𝔽, -0𝔽, NaN, 0ℤ, or the empty String, return false.
  3. NOTE: This step is replaced in section B.3.6.1.
  4. Return true.

7.1.3 ToNumeric ( value )

The abstract operation ToNumeric takes argument value (an ECMAScript language value) and returns either a normal completion containing either a Number or a BigInt, or a throw completion. It returns value converted to a Number or a BigInt. It performs the following steps when called:

  1. Let primValue be ? ToPrimitive(value, number).
  2. If primValue is a BigInt, return primValue.
  3. Return ? ToNumber(primValue).

7.1.4 ToNumber ( argument )

The abstract operation ToNumber takes argument argument (an ECMAScript language value) and returns either a normal completion containing a Number or a throw completion. It converts argument to a value of type Number. It performs the following steps when called:

  1. If argument is a Number, return argument.
  2. If argument is either a Symbol or a BigInt, throw a TypeError exception.
  3. If argument is undefined, return NaN.
  4. If argument is either null or false, return +0𝔽.
  5. If argument is true, return 1𝔽.
  6. If argument is a String, return StringToNumber(argument).
  7. Assert: argument is an Object.
  8. Let primValue be ? ToPrimitive(argument, number).
  9. Assert: primValue is not an Object.
  10. Return ? ToNumber(primValue).

7.1.4.1 ToNumber Applied to the String Type

The abstract operation StringToNumber specifies how to convert a String value to a Number value, using the following grammar.

Syntax

StringNumericLiteral ::: StrWhiteSpaceopt StrWhiteSpaceopt StrNumericLiteral StrWhiteSpaceopt StrWhiteSpace ::: StrWhiteSpaceChar StrWhiteSpaceopt StrWhiteSpaceChar ::: WhiteSpace LineTerminator StrNumericLiteral ::: StrDecimalLiteral NonDecimalIntegerLiteral[~Sep] StrDecimalLiteral ::: StrUnsignedDecimalLiteral + StrUnsignedDecimalLiteral - StrUnsignedDecimalLiteral StrUnsignedDecimalLiteral ::: Infinity DecimalDigits[~Sep] . DecimalDigits[~Sep]opt ExponentPart[~Sep]opt . DecimalDigits[~Sep] ExponentPart[~Sep]opt DecimalDigits[~Sep] ExponentPart[~Sep]opt

All grammar symbols not explicitly defined above have the definitions used in the Lexical Grammar for numeric literals (12.9.3)

Note

Some differences should be noted between the syntax of a StringNumericLiteral and a NumericLiteral:

7.1.4.1.1 StringToNumber ( str )

The abstract operation StringToNumber takes argument str (a String) and returns a Number. It performs the following steps when called:

  1. Let text be StringToCodePoints(str).
  2. Let literal be ParseText(text, StringNumericLiteral).
  3. If literal is a List of errors, return NaN.
  4. Return StringNumericValue of literal.

7.1.4.1.2 Runtime Semantics: StringNumericValue

The syntax-directed operation StringNumericValue takes no arguments and returns a Number.

Note

The conversion of a StringNumericLiteral to a Number value is similar overall to the determination of the NumericValue of a NumericLiteral (see 12.9.3), but some of the details are different.

It is defined piecewise over the following productions:

StringNumericLiteral ::: StrWhiteSpaceopt
  1. Return +0𝔽.
 StringNumericLiteral ::: StrWhiteSpaceopt StrNumericLiteral StrWhiteSpaceopt
  1. Return StringNumericValue of StrNumericLiteral.
 StrNumericLiteral ::: NonDecimalIntegerLiteral
  1. Return 𝔽(MV of NonDecimalIntegerLiteral).
 StrDecimalLiteral ::: - StrUnsignedDecimalLiteral
  1. Let a be StringNumericValue of StrUnsignedDecimalLiteral.
  2. If a is +0𝔽, return -0𝔽.
  3. Return -a.
 StrUnsignedDecimalLiteral ::: Infinity
  1. Return +∞𝔽.
 StrUnsignedDecimalLiteral ::: DecimalDigits . DecimalDigitsopt ExponentPartopt
  1. Let a be MV of the first DecimalDigits.
  2. If the second DecimalDigits is present, then
    1. Let b be MV of the second DecimalDigits.
    2. Let n be the number of code points in the second DecimalDigits.
  3. Else,
    1. Let b be 0.
    2. Let n be 0.
  4. If ExponentPart is present, let e be MV of ExponentPart. Otherwise, let e be 0.
  5. Return RoundMVResult((a + (b × 10-n)) × 10e).
 StrUnsignedDecimalLiteral ::: . DecimalDigits ExponentPartopt
  1. Let b be MV of DecimalDigits.
  2. If ExponentPart is present, let e be MV of ExponentPart. Otherwise, let e be 0.
  3. Let n be the number of code points in DecimalDigits.
  4. Return RoundMVResult(b × 10e - n).
 StrUnsignedDecimalLiteral ::: DecimalDigits ExponentPartopt
  1. Let a be MV of DecimalDigits.
  2. If ExponentPart is present, let e be MV of ExponentPart. Otherwise, let e be 0.
  3. Return RoundMVResult(a × 10e).

7.1.4.1.3 RoundMVResult ( n )

The abstract operation RoundMVResult takes argument n (a mathematical value) and returns a Number. It converts n to a Number in an implementation-defined manner. For the purposes of this abstract operation, a digit is significant if it is not zero or there is a non-zero digit to its left and there is a non-zero digit to its right. For the purposes of this abstract operation, "the mathematical value denoted by" a representation of a mathematical value is the inverse of "the decimal representation of" a mathematical value. It performs the following steps when called:

  1. If the decimal representation of n has 20 or fewer significant digits, return 𝔽(n).
  2. Let option1 be the mathematical value denoted by the result of replacing each significant digit in the decimal representation of n after the 20th with a 0 digit.
  3. Let option2 be the mathematical value denoted by the result of replacing each significant digit in the decimal representation of n after the 20th with a 0 digit and then incrementing it at the 20th position (with carrying as necessary).
  4. Let chosen be an implementation-defined choice of either option1 or option2.
  5. Return 𝔽(chosen).

7.1.5 ToIntegerOrInfinity ( argument )

The abstract operation ToIntegerOrInfinity takes argument argument (an ECMAScript language value) and returns either a normal completion containing either an integer, +∞, or -∞, or a throw completion. It converts argument to an integer representing its Number value with fractional part truncated, or to +∞ or -∞ when that Number value is infinite. It performs the following steps when called:

  1. Let number be ? ToNumber(argument).
  2. If number is one of NaN, +0𝔽, or -0𝔽, return 0.
  3. If number is +∞𝔽, return +∞.
  4. If number is -∞𝔽, return -∞.
  5. Return truncate(ℝ(number)).
 Note
𝔽(ToIntegerOrInfinity(x)) never returns -0𝔽 for any value of x. The truncation of the fractional part is performed after converting x to a mathematical value.

7.1.6 ToInt32 ( argument )

The abstract operation ToInt32 takes argument argument (an ECMAScript language value) and returns either a normal completion containing an integral Number or a throw completion. It converts argument to one of 232 integral Number values in the inclusive interval from 𝔽(-231) to 𝔽(231 - 1). It performs the following steps when called:

  1. Let number be ? ToNumber(argument).
  2. If number is not finite or number is either +0𝔽 or -0𝔽, return +0𝔽.
  3. Let int be truncate(ℝ(number)).
  4. Let int32bit be int modulo 232.
  5. If int32bit ≥ 231, return 𝔽(int32bit - 232); otherwise return 𝔽(int32bit).
 Note

Given the above definition of ToInt32:

  • The ToInt32 abstract operation is idempotent: if applied to a result that it produced, the second application leaves that value unchanged.
  • ToInt32(ToUint32(x)) is the same value as ToInt32(x) for all values of x. (It is to preserve this latter property that +∞𝔽 and -∞𝔽 are mapped to +0𝔽.)
  • ToInt32 maps -0𝔽 to +0𝔽.

7.1.7 ToUint32 ( argument )

The abstract operation ToUint32 takes argument argument (an ECMAScript language value) and returns either a normal completion containing an integral Number or a throw completion. It converts argument to one of 232 integral Number values in the inclusive interval from +0𝔽 to 𝔽(232 - 1). It performs the following steps when called:

  1. Let number be ? ToNumber(argument).
  2. If number is not finite or number is either +0𝔽 or -0𝔽, return +0𝔽.
  3. Let int be truncate(ℝ(number)).
  4. Let int32bit be int modulo 232.
  5. Return 𝔽(int32bit).
 Note

Given the above definition of ToUint32:

  • Step 5 is the only difference between ToUint32 and ToInt32.
  • The ToUint32 abstract operation is idempotent: if applied to a result that it produced, the second application leaves that value unchanged.
  • ToUint32(ToInt32(x)) is the same value as ToUint32(x) for all values of x. (It is to preserve this latter property that +∞𝔽 and -∞𝔽 are mapped to +0𝔽.)
  • ToUint32 maps -0𝔽 to +0𝔽.

7.1.8 ToInt16 ( argument )

The abstract operation ToInt16 takes argument argument (an ECMAScript language value) and returns either a normal completion containing an integral Number or a throw completion. It converts argument to one of 216 integral Number values in the inclusive interval from 𝔽(-215) to 𝔽(215 - 1). It performs the following steps when called:

  1. Let number be ? ToNumber(argument).
  2. If number is not finite or number is either +0𝔽 or -0𝔽, return +0𝔽.
  3. Let int be truncate(ℝ(number)).
  4. Let int16bit be int modulo 216.
  5. If int16bit ≥ 215, return 𝔽(int16bit - 216); otherwise return 𝔽(int16bit).

7.1.9 ToUint16 ( argument )

The abstract operation ToUint16 takes argument argument (an ECMAScript language value) and returns either a normal completion containing an integral Number or a throw completion. It converts argument to one of 216 integral Number values in the inclusive interval from +0𝔽 to 𝔽(216 - 1). It performs the following steps when called:

  1. Let number be ? ToNumber(argument).
  2. If number is not finite or number is either +0𝔽 or -0𝔽, return +0𝔽.
  3. Let int be truncate(ℝ(number)).
  4. Let int16bit be int modulo 216.
  5. Return 𝔽(int16bit).
 Note

Given the above definition of ToUint16:

  • The substitution of 216 for 232 in step 4 is the only difference between ToUint32 and ToUint16.
  • ToUint16 maps -0𝔽 to +0𝔽.

7.1.10 ToInt8 ( argument )

The abstract operation ToInt8 takes argument argument (an ECMAScript language value) and returns either a normal completion containing an integral Number or a throw completion. It converts argument to one of 28 integral Number values in the inclusive interval from -128𝔽 to 127𝔽. It performs the following steps when called:

  1. Let number be ? ToNumber(argument).
  2. If number is not finite or number is either +0𝔽 or -0𝔽, return +0𝔽.
  3. Let int be truncate(ℝ(number)).
  4. Let int8bit be int modulo 28.
  5. If int8bit ≥ 27, return 𝔽(int8bit - 28); otherwise return 𝔽(int8bit).

7.1.11 ToUint8 ( argument )

The abstract operation ToUint8 takes argument argument (an ECMAScript language value) and returns either a normal completion containing an integral Number or a throw completion. It converts argument to one of 28 integral Number values in the inclusive interval from +0𝔽 to 255𝔽. It performs the following steps when called:

  1. Let number be ? ToNumber(argument).
  2. If number is not finite or number is either +0𝔽 or -0𝔽, return +0𝔽.
  3. Let int be truncate(ℝ(number)).
  4. Let int8bit be int modulo 28.
  5. Return 𝔽(int8bit).

7.1.12 ToUint8Clamp ( argument )

The abstract operation ToUint8Clamp takes argument argument (an ECMAScript language value) and returns either a normal completion containing an integral Number or a throw completion. It clamps and rounds argument to one of 28 integral Number values in the inclusive interval from +0𝔽 to 255𝔽. It performs the following steps when called:

  1. Let number be ? ToNumber(argument).
  2. If number is NaN, return +0𝔽.
  3. Let mv be the extended mathematical value of number.
  4. Let clamped be the result of clamping mv between 0 and 255.
  5. Let f be floor(clamped).
  6. If clamped < f + 0.5, return 𝔽(f).
  7. If clamped > f + 0.5, return 𝔽(f + 1).
  8. If f is even, return 𝔽(f). Otherwise, return 𝔽(f + 1).
 Note

Unlike most other ECMAScript integer conversion operations, ToUint8Clamp rounds rather than truncates non-integral values. It also uses “round half to even” tie-breaking, which differs from the “round half up” tie-breaking of Math.round.

7.1.13 ToBigInt ( argument )

The abstract operation ToBigInt takes argument argument (an ECMAScript language value) and returns either a normal completion containing a BigInt or a throw completion. It converts argument to a BigInt value, or throws if an implicit conversion from Number would be required. It performs the following steps when called:

  1. Let prim be ? ToPrimitive(argument, number).
  2. Return the value that prim corresponds to in Table 12.
Table 12: BigInt Conversions
Argument Type Result
Undefined Throw a TypeError exception.
Null Throw a TypeError exception.
Boolean Return 1n if prim is true and 0n if prim is false.
BigInt Return prim.
Number Throw a TypeError exception.
String
  1. Let n be StringToBigInt(prim).
  2. If n is undefined, throw a SyntaxError exception.
  3. Return n.
Symbol Throw a TypeError exception.

7.1.14 StringToBigInt ( str )

The abstract operation StringToBigInt takes argument str (a String) and returns a BigInt or undefined. It performs the following steps when called:

  1. Let text be StringToCodePoints(str).
  2. Let literal be ParseText(text, StringIntegerLiteral).
  3. If literal is a List of errors, return undefined.
  4. Let mv be the MV of literal.
  5. Assert: mv is an integer.
  6. Return ℤ(mv).

7.1.14.1 StringIntegerLiteral Grammar

StringToBigInt uses the following grammar.

Syntax

StringIntegerLiteral ::: StrWhiteSpaceopt StrWhiteSpaceopt StrIntegerLiteral StrWhiteSpaceopt StrIntegerLiteral ::: SignedInteger[~Sep] NonDecimalIntegerLiteral[~Sep]

7.1.14.2 Runtime Semantics: MV

7.1.15 ToBigInt64 ( argument )

The abstract operation ToBigInt64 takes argument argument (an ECMAScript language value) and returns either a normal completion containing a BigInt or a throw completion. It converts argument to one of 264 BigInt values in the inclusive interval from ℤ(-263) to ℤ(263 - 1). It performs the following steps when called:

  1. Let n be ? ToBigInt(argument).
  2. Let int64bit be ℝ(n) modulo 264.
  3. If int64bit ≥ 263, return ℤ(int64bit - 264); otherwise return ℤ(int64bit).

7.1.16 ToBigUint64 ( argument )

The abstract operation ToBigUint64 takes argument argument (an ECMAScript language value) and returns either a normal completion containing a BigInt or a throw completion. It converts argument to one of 264 BigInt values in the inclusive interval from 0ℤ to ℤ(264 - 1). It performs the following steps when called:

  1. Let n be ? ToBigInt(argument).
  2. Let int64bit be ℝ(n) modulo 264.
  3. Return ℤ(int64bit).

7.1.17 ToString ( argument )

The abstract operation ToString takes argument argument (an ECMAScript language value) and returns either a normal completion containing a String or a throw completion. It converts argument to a value of type String. It performs the following steps when called:

  1. If argument is a String, return argument.
  2. If argument is a Symbol, throw a TypeError exception.
  3. If argument is undefined, return "undefined".
  4. If argument is null, return "null".
  5. If argument is true, return "true".
  6. If argument is false, return "false".
  7. If argument is a Number, return Number::toString(argument, 10).
  8. If argument is a BigInt, return BigInt::toString(argument, 10).
  9. Assert: argument is an Object.
  10. Let primValue be ? ToPrimitive(argument, string).
  11. Assert: primValue is not an Object.
  12. Return ? ToString(primValue).

7.1.18 ToObject ( argument )

The abstract operation ToObject takes argument argument (an ECMAScript language value) and returns either a normal completion containing an Object or a throw completion. It converts argument to a value of type Object according to Table 13:

Table 13: ToObject Conversions
Argument Type Result
Undefined Throw a TypeError exception.
Null Throw a TypeError exception.
Boolean Return a new Boolean object whose [[BooleanData]] internal slot is set to argument. See 20.3 for a description of Boolean objects.
Number Return a new Number object whose [[NumberData]] internal slot is set to argument. See 21.1 for a description of Number objects.
String Return a new String object whose [[StringData]] internal slot is set to argument. See 22.1 for a description of String objects.
Symbol Return a new Symbol object whose [[SymbolData]] internal slot is set to argument. See 20.4 for a description of Symbol objects.
BigInt Return a new BigInt object whose [[BigIntData]] internal slot is set to argument. See 21.2 for a description of BigInt objects.
Object Return argument.

7.1.19 ToPropertyKey ( argument )

The abstract operation ToPropertyKey takes argument argument (an ECMAScript language value) and returns either a normal completion containing a property key or a throw completion. It converts argument to a value that can be used as a property key. It performs the following steps when called:

  1. Let key be ? ToPrimitive(argument, string).
  2. If key is a Symbol, then
    1. Return key.
  3. Return ! ToString(key).

7.1.20 ToLength ( argument )

The abstract operation ToLength takes argument argument (an ECMAScript language value) and returns either a normal completion containing an integral Number or a throw completion. It clamps and truncates argument to an integral Number suitable for use as the length of an array-like object. It performs the following steps when called:

  1. Let len be ? ToIntegerOrInfinity(argument).
  2. If len ≤ 0, return +0𝔽.
  3. Return 𝔽(min(len, 253 - 1)).

7.1.21 CanonicalNumericIndexString ( argument )

The abstract operation CanonicalNumericIndexString takes argument argument (a String) and returns a Number or undefined. If argument is either "-0" or exactly matches the result of ToString(n) for some Number value n, it returns the respective Number value. Otherwise, it returns undefined. It performs the following steps when called:

  1. If argument is "-0", return -0𝔽.
  2. Let n be ! ToNumber(argument).
  3. If ! ToString(n) is argument, return n.
  4. Return undefined.

A canonical numeric string is any String value for which the CanonicalNumericIndexString abstract operation does not return undefined.

7.1.22 ToIndex ( value )

The abstract operation ToIndex takes argument value (an ECMAScript language value) and returns either a normal completion containing a non-negative integer or a throw completion. It converts value to an integer and returns that integer if it is non-negative and corresponds with an integer index. Otherwise, it throws an exception. It performs the following steps when called:

  1. Let integer be ? ToIntegerOrInfinity(value).
  2. If integer is not in the inclusive interval from 0 to 253 - 1, throw a RangeError exception.
  3. Return integer.