ECMAScript® 2021 Language Specification

Draft ECMA-262 / March 6, 2021

19.2 Function Properties of the Global Object

19.2.1 eval ( x )

The eval function is the %eval% intrinsic object. When the eval function is called with one argument x, the following steps are taken:

  1. Assert: The execution context stack has at least two elements.
  2. Let callerContext be the second to top element of the execution context stack.
  3. Let callerRealm be callerContext's Realm.
  4. Return ? PerformEval(x, callerRealm, false, false).

19.2.1.1 PerformEval ( x, callerRealm, strictCaller, direct )

The abstract operation PerformEval takes arguments x, callerRealm, strictCaller, and direct. It performs the following steps when called:

  1. Assert: If direct is false, then strictCaller is also false.
  2. If Type(x) is not String, return x.
  3. Let evalRealm be the current Realm Record.
  4. Perform ? HostEnsureCanCompileStrings(callerRealm, evalRealm).
  5. Let inFunction be false.
  6. Let inMethod be false.
  7. Let inDerivedConstructor be false.
  8. If direct is true, then
    1. Let thisEnvRec be ! GetThisEnvironment().
    2. If thisEnvRec is a function Environment Record, then
      1. Let F be thisEnvRec.[[FunctionObject]].
      2. Set inFunction to true.
      3. Set inMethod to thisEnvRec.HasSuperBinding().
      4. If F.[[ConstructorKind]] is derived, set inDerivedConstructor to true.
  9. Perform the following substeps in an implementation-defined order, possibly interleaving parsing and error detection:
    1. Let script be ParseText(! StringToCodePoints(x), Script).
    2. If script is a List of errors, throw a SyntaxError exception.
    3. If script Contains ScriptBody is false, return undefined.
    4. Let body be the ScriptBody of script.
    5. If inFunction is false, and body Contains NewTarget, throw a SyntaxError exception.
    6. If inMethod is false, and body Contains SuperProperty, throw a SyntaxError exception.
    7. If inDerivedConstructor is false, and body Contains SuperCall, throw a SyntaxError exception.
  10. If strictCaller is true, let strictEval be true.
  11. Else, let strictEval be IsStrict of script.
  12. Let runningContext be the running execution context.
  13. NOTE: If direct is true, runningContext will be the execution context that performed the direct eval. If direct is false, runningContext will be the execution context for the invocation of the eval function.
  14. If direct is true, then
    1. Let lexEnv be NewDeclarativeEnvironment(runningContext's LexicalEnvironment).
    2. Let varEnv be runningContext's VariableEnvironment.
  15. Else,
    1. Let lexEnv be NewDeclarativeEnvironment(evalRealm.[[GlobalEnv]]).
    2. Let varEnv be evalRealm.[[GlobalEnv]].
  16. If strictEval is true, set varEnv to lexEnv.
  17. If runningContext is not already suspended, suspend runningContext.
  18. Let evalContext be a new ECMAScript code execution context.
  19. Set evalContext's Function to null.
  20. Set evalContext's Realm to evalRealm.
  21. Set evalContext's ScriptOrModule to runningContext's ScriptOrModule.
  22. Set evalContext's VariableEnvironment to varEnv.
  23. Set evalContext's LexicalEnvironment to lexEnv.
  24. Push evalContext onto the execution context stack; evalContext is now the running execution context.
  25. Let result be EvalDeclarationInstantiation(body, varEnv, lexEnv, strictEval).
  26. If result.[[Type]] is normal, then
    1. Set result to the result of evaluating body.
  27. If result.[[Type]] is normal and result.[[Value]] is empty, then
    1. Set result to NormalCompletion(undefined).
  28. Suspend evalContext and remove it from the execution context stack.
  29. Resume the context that is now on the top of the execution context stack as the running execution context.
  30. Return Completion(result).
 Note

The eval code cannot instantiate variable or function bindings in the variable environment of the calling context that invoked the eval if the calling context is evaluating formal parameter initializers or if either the code of the calling context or the eval code is strict mode code. Instead such bindings are instantiated in a new VariableEnvironment that is only accessible to the eval code. Bindings introduced by let, const, or class declarations are always instantiated in a new LexicalEnvironment.

19.2.1.2 HostEnsureCanCompileStrings ( callerRealm, calleeRealm )

The host-defined abstract operation HostEnsureCanCompileStrings takes arguments callerRealm (a Realm Record) and calleeRealm (a Realm Record). It allows host environments to block certain ECMAScript functions which allow developers to compile strings into ECMAScript code.

An implementation of HostEnsureCanCompileStrings may complete normally or abruptly. Any abrupt completions will be propagated to its callers. The default implementation of HostEnsureCanCompileStrings is to unconditionally return an empty normal completion.

19.2.1.3 EvalDeclarationInstantiation ( body, varEnv, lexEnv, strict )

The abstract operation EvalDeclarationInstantiation takes arguments body, varEnv, lexEnv, and strict. It performs the following steps when called:

  1. Let varNames be the VarDeclaredNames of body.
  2. Let varDeclarations be the VarScopedDeclarations of body.
  3. If strict is false, then
    1. If varEnv is a global Environment Record, then
      1. For each element name of varNames, do
        1. If varEnv.HasLexicalDeclaration(name) is true, throw a SyntaxError exception.
        2. NOTE: eval will not create a global var declaration that would be shadowed by a global lexical declaration.
    2. Let thisEnv be lexEnv.
    3. Assert: The following loop will terminate.
    4. Repeat, while thisEnv is not the same as varEnv,
      1. If thisEnv is not an object Environment Record, then
        1. NOTE: The environment of with statements cannot contain any lexical declaration so it doesn't need to be checked for var/let hoisting conflicts.
        2. For each element name of varNames, do
          1. If thisEnv.HasBinding(name) is true, then
            1. Throw a SyntaxError exception.
            2. NOTE: Annex B.3.5 defines alternate semantics for the above step.
          2. NOTE: A direct eval will not hoist var declaration over a like-named lexical declaration.
      2. Set thisEnv to thisEnv.[[OuterEnv]].
  4. Let functionsToInitialize be a new empty List.
  5. Let declaredFunctionNames be a new empty List.
  6. For each element d of varDeclarations, in reverse List order, do
    1. If d is neither a VariableDeclaration nor a ForBinding nor a BindingIdentifier, then
      1. Assert: d is either a FunctionDeclaration, a GeneratorDeclaration, an AsyncFunctionDeclaration, or an AsyncGeneratorDeclaration.
      2. NOTE: If there are multiple function declarations for the same name, the last declaration is used.
      3. Let fn be the sole element of the BoundNames of d.
      4. If fn is not an element of declaredFunctionNames, then
        1. If varEnv is a global Environment Record, then
          1. Let fnDefinable be ? varEnv.CanDeclareGlobalFunction(fn).
          2. If fnDefinable is false, throw a TypeError exception.
        2. Append fn to declaredFunctionNames.
        3. Insert d as the first element of functionsToInitialize.
  7. NOTE: Annex B.3.3.3 adds additional steps at this point.
  8. Let declaredVarNames be a new empty List.
  9. For each element d of varDeclarations, do
    1. If d is a VariableDeclaration, a ForBinding, or a BindingIdentifier, then
      1. For each String vn of the BoundNames of d, do
        1. If vn is not an element of declaredFunctionNames, then
          1. If varEnv is a global Environment Record, then
            1. Let vnDefinable be ? varEnv.CanDeclareGlobalVar(vn).
            2. If vnDefinable is false, throw a TypeError exception.
          2. If vn is not an element of declaredVarNames, then
            1. Append vn to declaredVarNames.
  10. NOTE: No abnormal terminations occur after this algorithm step unless varEnv is a global Environment Record and the global object is a Proxy exotic object.
  11. Let lexDeclarations be the LexicallyScopedDeclarations of body.
  12. For each element d of lexDeclarations, do
    1. NOTE: Lexically declared names are only instantiated here but not initialized.
    2. For each element dn of the BoundNames of d, do
      1. If IsConstantDeclaration of d is true, then
        1. Perform ? lexEnv.CreateImmutableBinding(dn, true).
      2. Else,
        1. Perform ? lexEnv.CreateMutableBinding(dn, false).
  13. For each Parse Node f of functionsToInitialize, do
    1. Let fn be the sole element of the BoundNames of f.
    2. Let fo be InstantiateFunctionObject of f with argument lexEnv.
    3. If varEnv is a global Environment Record, then
      1. Perform ? varEnv.CreateGlobalFunctionBinding(fn, fo, true).
    4. Else,
      1. Let bindingExists be varEnv.HasBinding(fn).
      2. If bindingExists is false, then
        1. Let status be ! varEnv.CreateMutableBinding(fn, true).
        2. Assert: status is not an abrupt completion because of validation preceding step 10.
        3. Perform ! varEnv.InitializeBinding(fn, fo).
      3. Else,
        1. Perform ! varEnv.SetMutableBinding(fn, fo, false).
  14. For each String vn of declaredVarNames, do
    1. If varEnv is a global Environment Record, then
      1. Perform ? varEnv.CreateGlobalVarBinding(vn, true).
    2. Else,
      1. Let bindingExists be varEnv.HasBinding(vn).
      2. If bindingExists is false, then
        1. Let status be ! varEnv.CreateMutableBinding(vn, true).
        2. Assert: status is not an abrupt completion because of validation preceding step 10.
        3. Perform ! varEnv.InitializeBinding(vn, undefined).
  15. Return NormalCompletion(empty).
 Note

An alternative version of this algorithm is described in B.3.5.

19.2.2 isFinite ( number )

The isFinite function is the %isFinite% intrinsic object. When the isFinite function is called with one argument number, the following steps are taken:

  1. Let num be ? ToNumber(number).
  2. If num is NaN, +∞𝔽, or -∞𝔽, return false.
  3. Otherwise, return true.

19.2.3 isNaN ( number )

The isNaN function is the %isNaN% intrinsic object. When the isNaN function is called with one argument number, the following steps are taken:

  1. Let num be ? ToNumber(number).
  2. If num is NaN, return true.
  3. Otherwise, return false.
 Note

A reliable way for ECMAScript code to test if a value X is a NaN is an expression of the form X !== X. The result will be true if and only if X is a NaN.

19.2.4 parseFloat ( string )

The parseFloat function produces a Number value dictated by interpretation of the contents of the string argument as a decimal literal.

The parseFloat function is the %parseFloat% intrinsic object. When the parseFloat function is called with one argument string, the following steps are taken:

  1. Let inputString be ? ToString(string).
  2. Let trimmedString be ! TrimString(inputString, start).
  3. If neither trimmedString nor any prefix of trimmedString satisfies the syntax of a StrDecimalLiteral (see 7.1.4.1), return NaN.
  4. Let numberString be the longest prefix of trimmedString, which might be trimmedString itself, that satisfies the syntax of a StrDecimalLiteral.
  5. Let mathFloat be MV of numberString.
  6. If mathFloat = 0, then
    1. If the first code unit of trimmedString is the code unit 0x002D (HYPHEN-MINUS), return -0𝔽.
    2. Return +0𝔽.
  7. Return 𝔽(mathFloat).
 Note

parseFloat may interpret only a leading portion of string as a Number value; it ignores any code units that cannot be interpreted as part of the notation of a decimal literal, and no indication is given that any such code units were ignored.

19.2.5 parseInt ( string, radix )

The parseInt function produces an integral Number dictated by interpretation of the contents of the string argument according to the specified radix. Leading white space in string is ignored. If radix is undefined or 0, it is assumed to be 10 except when the number begins with the code unit pairs 0x or 0X, in which case a radix of 16 is assumed. If radix is 16, the number may also optionally begin with the code unit pairs 0x or 0X.

The parseInt function is the %parseInt% intrinsic object. When the parseInt function is called, the following steps are taken:

  1. Let inputString be ? ToString(string).
  2. Let S be ! TrimString(inputString, start).
  3. Let sign be 1.
  4. If S is not empty and the first code unit of S is the code unit 0x002D (HYPHEN-MINUS), set sign to -1.
  5. If S is not empty and the first code unit of S is the code unit 0x002B (PLUS SIGN) or the code unit 0x002D (HYPHEN-MINUS), remove the first code unit from S.
  6. Let R be ℝ(? ToInt32(radix)).
  7. Let stripPrefix be true.
  8. If R ≠ 0, then
    1. If R < 2 or R > 36, return NaN.
    2. If R ≠ 16, set stripPrefix to false.
  9. Else,
    1. Set R to 10.
  10. If stripPrefix is true, then
    1. If the length of S is at least 2 and the first two code units of S are either "0x" or "0X", then
      1. Remove the first two code units from S.
      2. Set R to 16.
  11. If S contains a code unit that is not a radix-R digit, let end be the index within S of the first such code unit; otherwise, let end be the length of S.
  12. Let Z be the substring of S from 0 to end.
  13. If Z is empty, return NaN.
  14. Let mathInt be the integer value that is represented by Z in radix-R notation, using the letters A-Z and a-z for digits with values 10 through 35. (However, if R is 10 and Z contains more than 20 significant digits, every significant digit after the 20th may be replaced by a 0 digit, at the option of the implementation; and if R is not 2, 4, 8, 10, 16, or 32, then mathInt may be an implementation-approximated value representing the integer value that is represented by Z in radix-R notation.)
  15. If mathInt = 0, then
    1. If sign = -1, return -0𝔽.
    2. Return +0𝔽.
  16. Return 𝔽(sign × mathInt).
 Note

parseInt may interpret only a leading portion of string as an integer value; it ignores any code units that cannot be interpreted as part of the notation of an integer, and no indication is given that any such code units were ignored.

19.2.6 URI Handling Functions

Uniform Resource Identifiers, or URIs, are Strings that identify resources (e.g. web pages or files) and transport protocols by which to access them (e.g. HTTP or FTP) on the Internet. The ECMAScript language itself does not provide any support for using URIs except for functions that encode and decode URIs as described in 19.2.6.2, 19.2.6.3, 19.2.6.4 and 19.2.6.5

Note

Many implementations of ECMAScript provide additional functions and methods that manipulate web pages; these functions are beyond the scope of this standard.

19.2.6.1 URI Syntax and Semantics

A URI is composed of a sequence of components separated by component separators. The general form is:

Scheme : First / Second ; Third ? Fourth

where the italicized names represent components and “:”, “/”, “;” and “?” are reserved for use as separators. The encodeURI and decodeURI functions are intended to work with complete URIs; they assume that any reserved code units in the URI are intended to have special meaning and so are not encoded. The encodeURIComponent and decodeURIComponent functions are intended to work with the individual component parts of a URI; they assume that any reserved code units represent text and so must be encoded so that they are not interpreted as reserved code units when the component is part of a complete URI.

The following lexical grammar specifies the form of encoded URIs.

Syntax

uri ::: uriCharactersopt uriCharacters ::: uriCharacter uriCharactersopt uriCharacter ::: uriReserved uriUnescaped uriEscaped uriReserved ::: one of ; / ? : @ & = + $ , uriUnescaped ::: uriAlpha DecimalDigit uriMark uriEscaped ::: % HexDigit HexDigit uriAlpha ::: one of a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z uriMark ::: one of - _ . ! ~ * ' ( ) Note

The above syntax is based upon RFC 2396 and does not reflect changes introduced by the more recent RFC 3986.

Runtime Semantics

When a code unit to be included in a URI is not listed above or is not intended to have the special meaning sometimes given to the reserved code units, that code unit must be encoded. The code unit is transformed into its UTF-8 encoding, with surrogate pairs first converted from UTF-16 to the corresponding code point value. (Note that for code units in the range [0, 127] this results in a single octet with the same value.) The resulting sequence of octets is then transformed into a String with each octet represented by an escape sequence of the form "%xx".

19.2.6.1.1 Encode ( string, unescapedSet )

The abstract operation Encode takes arguments string (a String) and unescapedSet (a String). It performs URI encoding and escaping. It performs the following steps when called:

  1. Let strLen be the number of code units in string.
  2. Let R be the empty String.
  3. Let k be 0.
  4. Repeat,
    1. If k = strLen, return R.
    2. Let C be the code unit at index k within string.
    3. If C is in unescapedSet, then
      1. Set k to k + 1.
      2. Set R to the string-concatenation of R and C.
    4. Else,
      1. Let cp be ! CodePointAt(string, k).
      2. If cp.[[IsUnpairedSurrogate]] is true, throw a URIError exception.
      3. Set k to k + cp.[[CodeUnitCount]].
      4. Let Octets be the List of octets resulting by applying the UTF-8 transformation to cp.[[CodePoint]].
      5. For each element octet of Octets, do
        1. Set R to the string-concatenation of:
          • R
          • "%"
          • the String representation of octet, formatted as a two-digit uppercase hexadecimal number, padded to the left with a zero if necessary

19.2.6.1.2 Decode ( string, reservedSet )

The abstract operation Decode takes arguments string (a String) and reservedSet (a String). It performs URI unescaping and decoding. It performs the following steps when called:

  1. Let strLen be the length of string.
  2. Let R be the empty String.
  3. Let k be 0.
  4. Repeat,
    1. If k = strLen, return R.
    2. Let C be the code unit at index k within string.
    3. If C is not the code unit 0x0025 (PERCENT SIGN), then
      1. Let S be the String value containing only the code unit C.
    4. Else,
      1. Let start be k.
      2. If k + 2 ≥ strLen, throw a URIError exception.
      3. If the code units at index (k + 1) and (k + 2) within string do not represent hexadecimal digits, throw a URIError exception.
      4. Let B be the 8-bit value represented by the two hexadecimal digits at index (k + 1) and (k + 2).
      5. Set k to k + 2.
      6. Let n be the number of leading 1 bits in B.
      7. If n = 0, then
        1. Let C be the code unit whose value is B.
        2. If C is not in reservedSet, then
          1. Let S be the String value containing only the code unit C.
        3. Else,
          1. Let S be the substring of string from start to k + 1.
      8. Else,
        1. If n = 1 or n > 4, throw a URIError exception.
        2. If k + (3 × (n - 1)) ≥ strLen, throw a URIError exception.
        3. Let Octets be a List whose sole element is B.
        4. Let j be 1.
        5. Repeat, while j < n,
          1. Set k to k + 1.
          2. If the code unit at index k within string is not the code unit 0x0025 (PERCENT SIGN), throw a URIError exception.
          3. If the code units at index (k + 1) and (k + 2) within string do not represent hexadecimal digits, throw a URIError exception.
          4. Let B be the 8-bit value represented by the two hexadecimal digits at index (k + 1) and (k + 2).
          5. Set k to k + 2.
          6. Append B to Octets.
          7. Set j to j + 1.
        6. Assert: The length of Octets is n.
        7. If Octets does not contain a valid UTF-8 encoding of a Unicode code point, throw a URIError exception.
        8. Let V be the code point obtained by applying the UTF-8 transformation to Octets, that is, from a List of octets into a 21-bit value.
        9. Let S be UTF16EncodeCodePoint(V).
    5. Set R to the string-concatenation of R and S.
    6. Set k to k + 1.
 Note

This syntax of Uniform Resource Identifiers is based upon RFC 2396 and does not reflect the more recent RFC 3986 which replaces RFC 2396. A formal description and implementation of UTF-8 is given in RFC 3629.

In UTF-8, characters are encoded using sequences of 1 to 6 octets. The only octet of a sequence of one has the higher-order bit set to 0, the remaining 7 bits being used to encode the character value. In a sequence of n octets, n > 1, the initial octet has the n higher-order bits set to 1, followed by a bit set to 0. The remaining bits of that octet contain bits from the value of the character to be encoded. The following octets all have the higher-order bit set to 1 and the following bit set to 0, leaving 6 bits in each to contain bits from the character to be encoded. The possible UTF-8 encodings of ECMAScript characters are specified in Table 49.

Table 49 (Informative): UTF-8 Encodings
Code Unit Value Representation 1st Octet 2nd Octet 3rd Octet 4th Octet
0x0000 - 0x007F 00000000 0zzzzzzz 0zzzzzzz
0x0080 - 0x07FF 00000yyy yyzzzzzz 110yyyyy 10zzzzzz
0x0800 - 0xD7FF xxxxyyyy yyzzzzzz 1110xxxx 10yyyyyy 10zzzzzz
0xD800 - 0xDBFF
followed by
0xDC00 - 0xDFFF 		110110vv vvwwwwxx
followed by
110111yy yyzzzzzz 		11110uuu 10uuwwww 10xxyyyy 10zzzzzz
0xD800 - 0xDBFF
not followed by
0xDC00 - 0xDFFF 		causes URIError
0xDC00 - 0xDFFF causes URIError
0xE000 - 0xFFFF xxxxyyyy yyzzzzzz 1110xxxx 10yyyyyy 10zzzzzz

Where
uuuuu = vvvv + 1
to account for the addition of 0x10000 as in section 3.8 of the Unicode Standard (Surrogates).

The above transformation combines each surrogate pair (for which code unit values in the inclusive range 0xD800 to 0xDFFF are reserved) into a UTF-32 representation and encodes the resulting 21-bit value into UTF-8. Decoding reconstructs the surrogate pair.

RFC 3629 prohibits the decoding of invalid UTF-8 octet sequences. For example, the invalid sequence C0 80 must not decode into the code unit 0x0000. Implementations of the Decode algorithm are required to throw a URIError when encountering such invalid sequences.

19.2.6.2 decodeURI ( encodedURI )

The decodeURI function computes a new version of a URI in which each escape sequence and UTF-8 encoding of the sort that might be introduced by the encodeURI function is replaced with the UTF-16 encoding of the code points that it represents. Escape sequences that could not have been introduced by encodeURI are not replaced.

The decodeURI function is the %decodeURI% intrinsic object. When the decodeURI function is called with one argument encodedURI, the following steps are taken:

  1. Let uriString be ? ToString(encodedURI).
  2. Let reservedURISet be a String containing one instance of each code unit valid in uriReserved plus "#".
  3. Return ? Decode(uriString, reservedURISet).
 Note

The code point # is not decoded from escape sequences even though it is not a reserved URI code point.

19.2.6.3 decodeURIComponent ( encodedURIComponent )

The decodeURIComponent function computes a new version of a URI in which each escape sequence and UTF-8 encoding of the sort that might be introduced by the encodeURIComponent function is replaced with the UTF-16 encoding of the code points that it represents.

The decodeURIComponent function is the %decodeURIComponent% intrinsic object. When the decodeURIComponent function is called with one argument encodedURIComponent, the following steps are taken:

  1. Let componentString be ? ToString(encodedURIComponent).
  2. Let reservedURIComponentSet be the empty String.
  3. Return ? Decode(componentString, reservedURIComponentSet).

19.2.6.4 encodeURI ( uri )

The encodeURI function computes a new version of a UTF-16 encoded (6.1.4) URI in which each instance of certain code points is replaced by one, two, three, or four escape sequences representing the UTF-8 encoding of the code points.

The encodeURI function is the %encodeURI% intrinsic object. When the encodeURI function is called with one argument uri, the following steps are taken:

  1. Let uriString be ? ToString(uri).
  2. Let unescapedURISet be a String containing one instance of each code unit valid in uriReserved and uriUnescaped plus "#".
  3. Return ? Encode(uriString, unescapedURISet).
 Note

The code point # is not encoded to an escape sequence even though it is not a reserved or unescaped URI code point.

19.2.6.5 encodeURIComponent ( uriComponent )

The encodeURIComponent function computes a new version of a UTF-16 encoded (6.1.4) URI in which each instance of certain code points is replaced by one, two, three, or four escape sequences representing the UTF-8 encoding of the code point.

The encodeURIComponent function is the %encodeURIComponent% intrinsic object. When the encodeURIComponent function is called with one argument uriComponent, the following steps are taken:

  1. Let componentString be ? ToString(uriComponent).
  2. Let unescapedURIComponentSet be a String containing one instance of each code unit valid in uriUnescaped.
  3. Return ? Encode(componentString, unescapedURIComponentSet).