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:
Assert : Theexecution context stack has at least two elements.- Let callerContext be the second to top element of the
execution context stack . - Let callerRealm be callerContext's
Realm . - 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:
Assert : If direct isfalse , then strictCaller is alsofalse .- If
Type (x) is not String, return x. - Let evalRealm be
the current Realm Record . - Perform ?
HostEnsureCanCompileStrings (callerRealm, evalRealm). - Let inFunction be
false . - Let inMethod be
false . - Let inDerivedConstructor be
false . - If direct is
true , then- Let thisEnvRec be !
GetThisEnvironment (). - If thisEnvRec is a
function Environment Record , then- Let F be thisEnvRec.[[FunctionObject]].
- Set inFunction to
true . - Set inMethod to thisEnvRec.HasSuperBinding().
- If F.[[ConstructorKind]] is
derived , set inDerivedConstructor totrue .
- Let thisEnvRec be !
- Perform the following substeps in an
implementation-defined order, possibly interleaving parsing and error detection:- Let script be
ParseText (!StringToCodePoints (x),Script ). - If script is a
List of errors, throw aSyntaxError exception. - If script
Contains ScriptBody isfalse , returnundefined . - Let body be the
ScriptBody of script. - If inFunction is
false , and bodyContains NewTarget , throw aSyntaxError exception. - If inMethod is
false , and bodyContains SuperProperty , throw aSyntaxError exception. - If inDerivedConstructor is
false , and bodyContains SuperCall , throw aSyntaxError exception.
- Let script be
- If strictCaller is
true , let strictEval betrue . - Else, let strictEval be
IsStrict of script. - Let runningContext be the
running execution context . - NOTE: If direct is
true , runningContext will be theexecution context that performed thedirect eval . If direct isfalse , runningContext will be theexecution context for the invocation of theeval
function. - If direct is
true , then- Let lexEnv be
NewDeclarativeEnvironment (runningContext's LexicalEnvironment). - Let varEnv be runningContext's VariableEnvironment.
- Let lexEnv be
- Else,
- Let lexEnv be
NewDeclarativeEnvironment (evalRealm.[[GlobalEnv]]). - Let varEnv be evalRealm.[[GlobalEnv]].
- Let lexEnv be
- If strictEval is
true , set varEnv to lexEnv. - If runningContext is not already suspended, suspend runningContext.
- Let evalContext be a new ECMAScript code
execution context . - Set evalContext's Function to
null . - Set evalContext's
Realm to evalRealm. - Set evalContext's ScriptOrModule to runningContext's ScriptOrModule.
- Set evalContext's VariableEnvironment to varEnv.
- Set evalContext's LexicalEnvironment to lexEnv.
- Push evalContext onto the
execution context stack ; evalContext is now therunning execution context . - Let result be
EvalDeclarationInstantiation (body, varEnv, lexEnv, strictEval). - If result.[[Type]] is
normal , then- Set result to the result of evaluating body.
- If result.[[Type]] is
normal and result.[[Value]] isempty , then- Set result to
NormalCompletion (undefined ).
- Set result to
- Suspend evalContext and remove it from the
execution context stack . - Resume the context that is now on the top of the
execution context stack as therunning execution context . - Return
Completion (result).
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 let
, const
, or class
declarations are always instantiated in a new LexicalEnvironment.
19.2.1.2 HostEnsureCanCompileStrings ( callerRealm, calleeRealm )
The
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:
- Let varNames be the
VarDeclaredNames of body. - Let varDeclarations be the
VarScopedDeclarations of body. - If strict is
false , then- If varEnv is a
global Environment Record , then- For each element name of varNames, do
- If varEnv.HasLexicalDeclaration(name) is
true , throw aSyntaxError exception. - NOTE:
eval
will not create a global var declaration that would be shadowed by a global lexical declaration.
- If varEnv.HasLexicalDeclaration(name) is
- For each element name of varNames, do
- Let thisEnv be lexEnv.
Assert : The following loop will terminate.- Repeat, while thisEnv is not the same as varEnv,
- If thisEnv is not an
object Environment Record , then- NOTE: The environment of with statements cannot contain any lexical declaration so it doesn't need to be checked for var/let hoisting conflicts.
- For each element name of varNames, do
- If thisEnv.HasBinding(name) is
true , then- Throw a
SyntaxError exception. - NOTE: Annex
B.3.5 defines alternate semantics for the above step.
- Throw a
- NOTE: A
direct eval will not hoist var declaration over a like-named lexical declaration.
- If thisEnv.HasBinding(name) is
- Set thisEnv to thisEnv.[[OuterEnv]].
- If thisEnv is not an
- If varEnv is a
- Let functionsToInitialize be a new empty
List . - Let declaredFunctionNames be a new empty
List . - For each element d of varDeclarations, in reverse
List order, do- If d is neither a
VariableDeclaration nor aForBinding nor aBindingIdentifier , thenAssert : d is either aFunctionDeclaration , aGeneratorDeclaration , anAsyncFunctionDeclaration , or anAsyncGeneratorDeclaration .- NOTE: If there are multiple function declarations for the same name, the last declaration is used.
- Let fn be the sole element of the
BoundNames of d. - If fn is not an element of declaredFunctionNames, then
- If varEnv is a
global Environment Record , then- Let fnDefinable be ? varEnv.CanDeclareGlobalFunction(fn).
- If fnDefinable is
false , throw aTypeError exception.
- Append fn to declaredFunctionNames.
- Insert d as the first element of functionsToInitialize.
- If varEnv is a
- If d is neither a
- NOTE: Annex
B.3.3.3 adds additional steps at this point. - Let declaredVarNames be a new empty
List . - For each element d of varDeclarations, do
- If d is a
VariableDeclaration , aForBinding , or aBindingIdentifier , then- For each String vn of the
BoundNames of d, do- If vn is not an element of declaredFunctionNames, then
- If varEnv is a
global Environment Record , then- Let vnDefinable be ? varEnv.CanDeclareGlobalVar(vn).
- If vnDefinable is
false , throw aTypeError exception.
- If vn is not an element of declaredVarNames, then
- Append vn to declaredVarNames.
- If varEnv is a
- If vn is not an element of declaredFunctionNames, then
- For each String vn of the
- If d is a
- NOTE: No abnormal terminations occur after this algorithm step unless varEnv is a
global Environment Record and theglobal object is aProxy exotic object . - Let lexDeclarations be the
LexicallyScopedDeclarations of body. - For each element d of lexDeclarations, do
- NOTE: Lexically declared names are only instantiated here but not initialized.
- For each element dn of the
BoundNames of d, do- If
IsConstantDeclaration of d istrue , then- Perform ? lexEnv.CreateImmutableBinding(dn,
true ).
- Perform ? lexEnv.CreateImmutableBinding(dn,
- Else,
- Perform ? lexEnv.CreateMutableBinding(dn,
false ).
- Perform ? lexEnv.CreateMutableBinding(dn,
- If
- For each
Parse Node f of functionsToInitialize, do- Let fn be the sole element of the
BoundNames of f. - Let fo be
InstantiateFunctionObject of f with argument lexEnv. - If varEnv is a
global Environment Record , then- Perform ? varEnv.CreateGlobalFunctionBinding(fn, fo,
true ).
- Perform ? varEnv.CreateGlobalFunctionBinding(fn, fo,
- Else,
- Let bindingExists be varEnv.HasBinding(fn).
- If bindingExists is
false , then- Let status be ! varEnv.CreateMutableBinding(fn,
true ). Assert : status is not anabrupt completion because of validation preceding step10 .- Perform ! varEnv.InitializeBinding(fn, fo).
- Let status be ! varEnv.CreateMutableBinding(fn,
- Else,
- Perform ! varEnv.SetMutableBinding(fn, fo,
false ).
- Perform ! varEnv.SetMutableBinding(fn, fo,
- Let fn be the sole element of the
- For each String vn of declaredVarNames, do
- If varEnv is a
global Environment Record , then- Perform ? varEnv.CreateGlobalVarBinding(vn,
true ).
- Perform ? varEnv.CreateGlobalVarBinding(vn,
- Else,
- Let bindingExists be varEnv.HasBinding(vn).
- If bindingExists is
false , then- Let status be ! varEnv.CreateMutableBinding(vn,
true ). Assert : status is not anabrupt completion because of validation preceding step10 .- Perform ! varEnv.InitializeBinding(vn,
undefined ).
- Let status be ! varEnv.CreateMutableBinding(vn,
- If varEnv is a
- Return
NormalCompletion (empty ).
An alternative version of this algorithm is described in
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:
- Let num be ?
ToNumber (number). - If num is
NaN ,+∞ 𝔽, or-∞ 𝔽, returnfalse . - 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:
- Let num be ?
ToNumber (number). - If num is
NaN , returntrue . - Otherwise, return
false .
A reliable way for ECMAScript code to test if a value X
is a X !== X
. The result will be X
is a
19.2.4 parseFloat ( string )
The parseFloat
function produces a
The parseFloat
function is the %parseFloat% intrinsic object. When the parseFloat
function is called with one argument string, the following steps are taken:
- Let inputString be ?
ToString (string). - Let trimmedString be !
TrimString (inputString,start ). - If neither trimmedString nor any prefix of trimmedString satisfies the syntax of a
StrDecimalLiteral (see7.1.4.1 ), returnNaN . - Let numberString be the longest prefix of trimmedString, which might be trimmedString itself, that satisfies the syntax of a
StrDecimalLiteral . - Let mathFloat be MV of numberString.
- If mathFloat = 0, then
- If the first code unit of trimmedString is the code unit 0x002D (HYPHEN-MINUS), return
-0 𝔽. - Return
+0 𝔽.
- If the first code unit of trimmedString is the code unit 0x002D (HYPHEN-MINUS), return
- Return
𝔽 (mathFloat).
parseFloat
may interpret only a leading portion of string as a
19.2.5 parseInt ( string, radix )
The parseInt
function produces an 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:
- Let inputString be ?
ToString (string). - Let S be !
TrimString (inputString,start ). - Let sign be 1.
- If S is not empty and the first code unit of S is the code unit 0x002D (HYPHEN-MINUS), set sign to -1.
- 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.
- Let R be
ℝ (?ToInt32 (radix)). - Let stripPrefix be
true . - If R ≠ 0, then
- If R < 2 or R > 36, return
NaN . - If R ≠ 16, set stripPrefix to
false .
- If R < 2 or R > 36, return
- Else,
- Set R to 10.
- If stripPrefix is
true , then- If the length of S is at least 2 and the first two code units of S are either
"0x" or"0X" , then- Remove the first two code units from S.
- Set R to 16.
- If the length of S is at least 2 and the first two code units of S are either
- 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.
- Let Z be the
substring of S from 0 to end. - If Z is empty, return
NaN . - 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 animplementation-approximated value representing theinteger value that is represented by Z in radix-R notation.) - If mathInt = 0, then
- If sign = -1, return
-0 𝔽. - Return
+0 𝔽.
- If sign = -1, return
- Return
𝔽 (sign × mathInt).
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
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:
:
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
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
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:
- Let strLen be the number of code units in string.
- Let R be the empty String.
- Let k be 0.
- Repeat,
- If k = strLen, return R.
- Let C be the code unit at index k within string.
- If C is in unescapedSet, then
- Set k to k + 1.
- Set R to the
string-concatenation of R and C.
- Else,
- Let cp be !
CodePointAt (string, k). - If cp.[[IsUnpairedSurrogate]] is
true , throw aURIError exception. - Set k to k + cp.[[CodeUnitCount]].
- Let Octets be the
List of octets resulting by applying the UTF-8 transformation to cp.[[CodePoint]]. - For each element octet of Octets, do
- 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
- Set R to the
- Let cp be !
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:
- Let strLen be the length of string.
- Let R be the empty String.
- Let k be 0.
- Repeat,
- If k = strLen, return R.
- Let C be the code unit at index k within string.
- If C is not the code unit 0x0025 (PERCENT SIGN), then
- Let S be the String value containing only the code unit C.
- Else,
- Let start be k.
- If k + 2 ≥ strLen, throw a
URIError exception. - If the code units at index (k + 1) and (k + 2) within string do not represent hexadecimal digits, throw a
URIError exception. - Let B be the 8-bit value represented by the two hexadecimal digits at index (k + 1) and (k + 2).
- Set k to k + 2.
- Let n be the number of leading 1 bits in B.
- If n = 0, then
- Let C be the code unit whose value is B.
- If C is not in reservedSet, then
- Let S be the String value containing only the code unit C.
- Else,
- Let S be the
substring of string from start to k + 1.
- Let S be the
- Else,
- If n = 1 or n > 4, throw a
URIError exception. - If k + (3 × (n - 1)) ≥ strLen, throw a
URIError exception. - Let Octets be a
List whose sole element is B. - Let j be 1.
- Repeat, while j < n,
- Set k to k + 1.
- If the code unit at index k within string is not the code unit 0x0025 (PERCENT SIGN), throw a
URIError exception. - If the code units at index (k + 1) and (k + 2) within string do not represent hexadecimal digits, throw a
URIError exception. - Let B be the 8-bit value represented by the two hexadecimal digits at index (k + 1) and (k + 2).
- Set k to k + 2.
- Append B to Octets.
- Set j to j + 1.
Assert : The length of Octets is n.- If Octets does not contain a valid UTF-8 encoding of a Unicode code point, throw a
URIError exception. - 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. - Let S be
UTF16EncodeCodePoint (V).
- If n = 1 or n > 4, throw a
- Set R to the
string-concatenation of R and S. - Set k to k + 1.
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
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
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
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:
- Let uriString be ?
ToString (encodedURI). - Let reservedURISet be a String containing one instance of each code unit valid in
uriReserved plus"#" . - Return ?
Decode (uriString, reservedURISet).
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:
19.2.6.4 encodeURI ( uri )
The encodeURI
function computes a new version of a UTF-16 encoded (
The encodeURI
function is the %encodeURI% intrinsic object. When the encodeURI
function is called with one argument uri, the following steps are taken:
- Let uriString be ?
ToString (uri). - Let unescapedURISet be a String containing one instance of each code unit valid in
uriReserved anduriUnescaped plus"#" . - Return ?
Encode (uriString, unescapedURISet).
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 (
The encodeURIComponent
function is the %encodeURIComponent% intrinsic object. When the encodeURIComponent
function is called with one argument uriComponent, the following steps are taken:
- Let componentString be ?
ToString (uriComponent). - Let unescapedURIComponentSet be a String containing one instance of each code unit valid in
uriUnescaped . - Return ?
Encode (componentString, unescapedURIComponentSet).