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
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 and optional argument preferredType. 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:
Assert : input is anECMAScript language value .- If
Type (input) is Object, then- Let exoticToPrim be ?
GetMethod (input,@@toPrimitive ). - If exoticToPrim is not
undefined , then - If preferredType is not present, let preferredType be
number . - Return ?
OrdinaryToPrimitive (input, preferredType).
- Let exoticToPrim be ?
- Return input.
When ToPrimitive is called with no hint, then it generally behaves as if the hint were
7.1.1.1 OrdinaryToPrimitive ( O, hint )
The abstract operation OrdinaryToPrimitive takes arguments O and hint. It performs the following steps when called:
Assert :Type (O) is Object.Assert : hint is eitherstring ornumber .- If hint is
string , then- Let methodNames be «
"toString" ,"valueOf" ».
- Let methodNames be «
- Else,
- Let methodNames be «
"valueOf" ,"toString" ».
- Let methodNames be «
- For each element name of methodNames, do
- Let method be ?
Get (O, name). - If
IsCallable (method) istrue , then
- Let method be ?
- Throw a
TypeError exception.
7.1.2 ToBoolean ( argument )
The abstract operation ToBoolean takes argument argument. It converts argument to a value of type Boolean according to
Argument Type | Result |
---|---|
Undefined |
Return |
Null |
Return |
Boolean | Return argument. |
Number |
If argument is |
String |
If argument is the empty String (its length is 0), return |
Symbol |
Return |
BigInt |
If argument is |
Object |
Return An alternate algorithm related to the [[IsHTMLDDA]] internal slot is mandated in section |
7.1.3 ToNumeric ( value )
The abstract operation ToNumeric takes argument value. It returns value converted to a Number or a BigInt. It performs the following steps when called:
- Let primValue be ?
ToPrimitive (value,number ). - If
Type (primValue) is BigInt, return primValue. - Return ?
ToNumber (primValue).
7.1.4 ToNumber ( argument )
The abstract operation ToNumber takes argument argument. It converts argument to a value of type Number according to
Argument Type | Result |
---|---|
Undefined |
Return |
Null |
Return |
Boolean |
If argument is |
Number | Return argument (no conversion). |
String | See grammar and conversion algorithm below. |
Symbol |
Throw a |
BigInt |
Throw a |
Object |
Apply the following steps:
|
7.1.4.1 ToNumber Applied to the String Type
The terminal symbols of this grammar are all composed of characters in the Unicode Basic Multilingual Plane (BMP). Therefore, the result of
Syntax
All grammar symbols not explicitly defined above have the definitions used in the Lexical Grammar for numeric literals (
Some differences should be noted between the syntax of a
-
A
StringNumericLiteral may include leading and/or trailing white space and/or line terminators. -
A
StringNumericLiteral that is decimal may have any number of leading0
digits. -
A
StringNumericLiteral that is decimal may include a+
or-
to indicate its sign. -
A
StringNumericLiteral that is empty or contains only white space is converted to+0 𝔽. -
Infinity
and-Infinity
are recognized as aStringNumericLiteral but not as aNumericLiteral . -
A
StringNumericLiteral cannot include aBigIntLiteralSuffix .
7.1.4.1.1 Runtime Semantics: MV
The conversion of a String to a
-
The MV of
is 0.StringNumericLiteral ::: [empty] -
The MV of
is 0.StringNumericLiteral ::: StrWhiteSpace -
The MV of
is the MV ofStringNumericLiteral ::: StrWhiteSpace opt StrNumericLiteral StrWhiteSpace opt StrNumericLiteral , no matter whether white space is present or not. -
The MV of
is the negative of the MV ofStrDecimalLiteral ::: - StrUnsignedDecimalLiteral StrUnsignedDecimalLiteral . (Note that if the MV ofStrUnsignedDecimalLiteral is 0, the negative of this MV is also 0. The rounding rule described below handles the conversion of this signless mathematical zero to a floating-point+0 𝔽 or-0 𝔽 as appropriate.) -
The MV of
is 1010000 (a value so large that it will round toStrUnsignedDecimalLiteral ::: Infinity +∞ 𝔽). -
The MV of
is the MV of the firstStrUnsignedDecimalLiteral ::: DecimalDigits . DecimalDigits DecimalDigits plus (the MV of the secondDecimalDigits times 10-n), where n is the number of code points in the secondDecimalDigits . -
The MV of
is the MV ofStrUnsignedDecimalLiteral ::: DecimalDigits . ExponentPart DecimalDigits times 10e, where e is the MV ofExponentPart . -
The MV of
is (the MV of the firstStrUnsignedDecimalLiteral ::: DecimalDigits . DecimalDigits ExponentPart DecimalDigits plus (the MV of the secondDecimalDigits times 10-n)) times 10e, where n is the number of code points in the secondDecimalDigits and e is the MV ofExponentPart . -
The MV of
is the MV ofStrUnsignedDecimalLiteral ::: . DecimalDigits DecimalDigits times 10-n, where n is the number of code points inDecimalDigits . -
The MV of
is the MV ofStrUnsignedDecimalLiteral ::: . DecimalDigits ExponentPart DecimalDigits times 10e - n, where n is the number of code points inDecimalDigits and e is the MV ofExponentPart . -
The MV of
is the MV ofStrUnsignedDecimalLiteral ::: DecimalDigits ExponentPart DecimalDigits times 10e, where e is the MV ofExponentPart .
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 -
, in which case the rounded value is
-
it is not
0
; or -
there is a non-zero digit to its left and there is a non-zero digit, not in the
ExponentPart , to its right.
7.1.5 ToIntegerOrInfinity ( argument )
The abstract operation ToIntegerOrInfinity takes argument argument. It converts argument to an
7.1.6 ToInt32 ( argument )
The abstract operation ToInt32 takes argument argument. It converts argument to one of 232
- Let number be ?
ToNumber (argument). - If number is
NaN ,+0 𝔽,-0 𝔽,+∞ 𝔽, or-∞ 𝔽, return+0 𝔽. - Let int be the
mathematical value that is the same sign as number and whose magnitude isfloor (abs (ℝ (number))). - Let int32bit be int
modulo 232. - If int32bit ≥ 231, return
𝔽 (int32bit - 232); otherwise return𝔽 (int32bit).
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. It converts argument to one of 232
Given the above definition of ToUint32:
-
Step
5 is the only difference between ToUint32 andToInt32 . - 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. It converts argument to one of 216
- Let number be ?
ToNumber (argument). - If number is
NaN ,+0 𝔽,-0 𝔽,+∞ 𝔽, or-∞ 𝔽, return+0 𝔽. - Let int be the
mathematical value that is the same sign as number and whose magnitude isfloor (abs (ℝ (number))). - Let int16bit be int
modulo 216. - If int16bit ≥ 215, return
𝔽 (int16bit - 216); otherwise return𝔽 (int16bit).
7.1.9 ToUint16 ( argument )
The abstract operation ToUint16 takes argument argument. It converts argument to one of 216
7.1.10 ToInt8 ( argument )
The abstract operation ToInt8 takes argument argument. It converts argument to one of 28
7.1.11 ToUint8 ( argument )
The abstract operation ToUint8 takes argument argument. It converts argument to one of 28
7.1.12 ToUint8Clamp ( argument )
The abstract operation ToUint8Clamp takes argument argument. It converts argument to one of 28
Unlike the other ECMAScript Math.round
which does “round half up” tie-breaking.
7.1.13 ToBigInt ( argument )
The abstract operation ToBigInt takes argument argument. 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:
- Let prim be ?
ToPrimitive (argument,number ). - Return the value that prim corresponds to in
Table 13 .
Argument Type | Result |
---|---|
Undefined |
Throw a |
Null |
Throw a |
Boolean |
Return 1n if prim is 0n if prim is |
BigInt | Return prim. |
Number |
Throw a |
String |
|
Symbol |
Throw a |
7.1.14 StringToBigInt ( argument )
Apply the algorithm in
- Replace the
StrUnsignedDecimalLiteral production withDecimalDigits to not allowInfinity , decimal points, or exponents. - If the MV is
NaN , returnNaN , otherwise return the BigInt which exactly corresponds to the MV, rather than rounding to a Number.
7.1.15 ToBigInt64 ( argument )
The abstract operation ToBigInt64 takes argument argument. It converts argument to one of 264 BigInt values in the range
7.1.16 ToBigUint64 ( argument )
The abstract operation ToBigUint64 takes argument argument. It converts argument to one of 264 BigInt values in the range
7.1.17 ToString ( argument )
The abstract operation ToString takes argument argument. It converts argument to a value of type String according to
Argument Type | Result |
---|---|
Undefined |
Return |
Null |
Return |
Boolean |
If argument is If argument is |
Number |
Return ! |
String | Return argument. |
Symbol |
Throw a |
BigInt |
Return ! |
Object |
Apply the following steps:
|
7.1.18 ToObject ( argument )
The abstract operation ToObject takes argument argument. It converts argument to a value of type Object according to
Argument Type | Result |
---|---|
Undefined |
Throw a |
Null |
Throw a |
Boolean |
Return a new Boolean object whose [[BooleanData]] internal slot is set to argument. See |
Number |
Return a new Number object whose [[NumberData]] internal slot is set to argument. See |
String |
Return a new String object whose [[StringData]] internal slot is set to argument. See |
Symbol |
Return a new Symbol object whose [[SymbolData]] internal slot is set to argument. See |
BigInt |
Return a new BigInt object whose [[BigIntData]] internal slot is set to argument. See |
Object | Return argument. |
7.1.19 ToPropertyKey ( argument )
The abstract operation ToPropertyKey takes argument argument. It converts argument to a value that can be used as a property key. It performs the following steps when called:
- Let key be ?
ToPrimitive (argument,string ). - If
Type (key) is Symbol, then- Return key.
- Return !
ToString (key).
7.1.20 ToLength ( argument )
The abstract operation ToLength takes argument argument. It converts argument to an
- Let len be ?
ToIntegerOrInfinity (argument). - If len ≤ 0, return
+0 𝔽. - Return
𝔽 (min (len, 253 - 1)).
7.1.21 CanonicalNumericIndexString ( argument )
The abstract operation CanonicalNumericIndexString takes argument argument. It returns argument converted to a
A canonical numeric string is any String value for which the CanonicalNumericIndexString abstract operation does not return
7.1.22 ToIndex ( value )
The abstract operation ToIndex takes argument value. It returns value argument converted to a non-negative
- If value is
undefined , then- Return 0.
- Else,
- Let integerIndex be
𝔽 (?ToIntegerOrInfinity (value)). - If integerIndex <
+0 𝔽, throw aRangeError exception. - Let index be !
ToLength (integerIndex). - If !
SameValue (integerIndex, index) isfalse , throw aRangeError exception. - Return
ℝ (index).
- Let integerIndex be