diff --git a/spec.html b/spec.html index dd4c3284d6..8261c1d2d6 100644 --- a/spec.html +++ b/spec.html @@ -141,6 +141,7 @@

Conformance

A conforming implementation of ECMAScript may provide additional types, values, objects, properties, and functions beyond those described in this specification. In particular, a conforming implementation of ECMAScript may provide properties not described in this specification, and values for those properties, for objects that are described in this specification.

A conforming implementation of ECMAScript may support program and regular expression syntax not described in this specification. In particular, a conforming implementation of ECMAScript may support program syntax that makes use of any “future reserved words” noted in subclause of this specification.

A conforming implementation of ECMAScript must not implement any extension that is listed as a Forbidden Extension in subclause .

+

A conforming implementation of ECMAScript must not redefine any facilities that are not implementation-defined, implementation-approximated, or host-defined.

@@ -175,6 +176,21 @@

Web Scripting

Each Web browser and server that supports ECMAScript supplies its own host environment, completing the ECMAScript execution environment.

 + +

Hosts and Implementations

+

To aid integrating ECMAScript into host environments, this specification defers the definition certain facilities (e.g., abstract operations), either in whole or in part, to a source outside of this specification. Editorially, this specification distinguishes the following kinds of deferrals.

+ +

An implementation is an external source that further defines facilities enumerated in Annex or those that are marked as implementation-defined or implementation-approximated. In informal use, an implementation refers to a concrete artefact, such as a particular web browser.

+

An implementation-defined facility is one that defers its definition to an external source without further qualification. This specification does not make any recommendations for particular behaviours, and conforming implementations are free to choose any behaviour within the constraints put forth by this specification.

+

An implementation-approximated facility is one that defers its definition to an external source while recommending an ideal behaviour. While conforming implementations are free to choose any behaviour within the constraints put forth by this specification, they are encouraged to strive to approximate the ideal. Some mathematical operations, such as Math.exp, are implementation-approximated.

+

A host is an external source that further defines facilities listed in Annex but does not further define other implementation-defined or implementation-approximated facilities. In informal use, a host refers to the set of all implementations, such as the set of all web browsers, that interface with this specification in the same way via Annex . A host is often an external specification, such as WHATWG HTML (https://html.spec.whatwg.org/). In other words, facilities that are host-defined are often further defined in external specifications.

+

A host hook is an abstract operation that is defined in whole or in part by an external source. All host hooks must be listed in Annex .

+

A host-defined facility is one that defers its definition to an external source without further qualification and is listed in Annex . Implementations that are not hosts may also provide definitions for host-defined facilities.

+

A host environment is a particular choice of definition for all host-defined facilities. A host environment typically includes objects or functions which allow obtaining input and providing output as host-defined properties of the global object.

+

This specification follows the editorial convention of always using the most specific term. For example, if a facility is host-defined, it should not be referred to as implementation-defined.

+

Both hosts and implementations may interface with this specification via the language types, specification types, abstract operations, grammar productions, intrinsic objects, and intrinsic symbols defined herein.

+ +

ECMAScript Overview

The following is an informal overview of ECMAScript—not all parts of the language are described. This overview is not part of the standard proper.

@@ -210,6 +226,24 @@

The Strict Variant of ECMAScript

Terms and Definitions

For the purposes of this document, the following terms and definitions apply.

+ +

implementation-approximated

+

an implementation-approximated facility is defined in whole or in part by an external source but has a recommended, ideal behaviour in this specification

+ + + +

implementation-defined

+

an implementation-defined facility is defined in whole or in part by an external source to this specification

+ + + +

host-defined

+

same as implementation-defined

+ +

Editorially, see clause .

+ + +

type

set of data values as defined in clause of this specification

@@ -408,7 +442,7 @@

function

built-in function

built-in object that is a function

-

Examples of built-in functions include `parseInt` and `Math.exp`. An implementation may provide implementation-dependent built-in functions that are not described in this specification.

+

Examples of built-in functions include `parseInt` and `Math.exp`. A host or implementation may provide additional built-in functions that are not described in this specification.

 @@ -432,7 +466,7 @@

method

built-in method

method that is a built-in function

-

Standard built-in methods are defined in this specification, and an ECMAScript implementation may specify and provide other additional built-in methods.

+

Standard built-in methods are defined in this specification. A host or implementation may provide additional built-in methods that are not described in this specification.

 @@ -1485,7 +1519,7 @@

Numeric Types

The Number Type

-

The Number type has exactly 18437736874454810627ℝ (that is, 2ℝ64ℝ - 2ℝ53ℝ + 3ℝ) values, representing the double-precision 64-bit format IEEE 754-2019 values as specified in the IEEE Standard for Binary Floating-Point Arithmetic, except that the 9007199254740990ℝ (that is, 2ℝ53ℝ - 2ℝ) distinct “Not-a-Number” values of the IEEE Standard are represented in ECMAScript as a single special *NaN* value. (Note that the *NaN* value is produced by the program expression `NaN`.) In some implementations, external code might be able to detect a difference between various Not-a-Number values, but such behaviour is implementation-dependent; to ECMAScript code, all *NaN* values are indistinguishable from each other.

+

The Number type has exactly 18437736874454810627ℝ (that is, 2ℝ64ℝ - 2ℝ53ℝ + 3ℝ) values, representing the double-precision 64-bit format IEEE 754-2019 values as specified in the IEEE Standard for Binary Floating-Point Arithmetic, except that the 9007199254740990ℝ (that is, 2ℝ53ℝ - 2ℝ) distinct “Not-a-Number” values of the IEEE Standard are represented in ECMAScript as a single special *NaN* value. (Note that the *NaN* value is produced by the program expression `NaN`.) In some implementations, external code might be able to detect a difference between various Not-a-Number values, but such behaviour is implementation-defined; to ECMAScript code, all *NaN* values are indistinguishable from each other.

The bit pattern that might be observed in an ArrayBuffer (see ) or a SharedArrayBuffer (see ) after a Number value has been stored into it is not necessarily the same as the internal representation of that Number value used by the ECMAScript implementation.

 @@ -1530,7 +1564,7 @@

Number::bitwiseNOT ( _x_ )

Number::exponentiate ( _base_, _exponent_ )

-

The abstract operation Number::exponentiate takes arguments _base_ (a Number) and _exponent_ (a Number). It returns an implementation-dependent approximation of the result of raising _base_ to the power _exponent_, subject to the following requirements:

+

The abstract operation Number::exponentiate takes arguments _base_ (a Number) and _exponent_ (a Number). It returns an implementation-approximated value representing the result of raising _base_ to the power _exponent_, subject to the following requirements:

-

The actual process performed is implementation-defined, but typically consists of performing whatever I/O operations are necessary to allow HostResolveImportedModule to synchronously retrieve the appropriate Module Record, and then calling its Evaluate concrete method. This might require performing similar normalization as HostResolveImportedModule does.

+

The actual process performed is host-defined, but typically consists of performing whatever I/O operations are necessary to allow HostResolveImportedModule to synchronously retrieve the appropriate Module Record, and then calling its Evaluate concrete method. This might require performing similar normalization as HostResolveImportedModule does.

 @@ -24775,10 +24809,10 @@

Error Handling and Language Extensions

An implementation shall report all errors as specified, except for the following:

  • - Except as restricted in , an implementation may extend |Script| syntax, |Module| syntax, and regular expression pattern or flag syntax. To permit this, all operations (such as calling `eval`, using a regular expression literal, or using the Function or RegExp constructor) that are allowed to throw *SyntaxError* are permitted to exhibit implementation-defined behaviour instead of throwing *SyntaxError* when they encounter an implementation-defined extension to the script syntax or regular expression pattern or flag syntax. + Except as restricted in , a host or implementation may extend |Script| syntax, |Module| syntax, and regular expression pattern or flag syntax. To permit this, all operations (such as calling `eval`, using a regular expression literal, or using the Function or RegExp constructor) that are allowed to throw *SyntaxError* are permitted to exhibit host-defined behaviour instead of throwing *SyntaxError* when they encounter a host-defined extension to the script syntax or regular expression pattern or flag syntax.
  • - Except as restricted in , an implementation may provide additional types, values, objects, properties, and functions beyond those described in this specification. This may cause constructs (such as looking up a variable in the global scope) to have implementation-defined behaviour instead of throwing an error (such as *ReferenceError*). + Except as restricted in , a host or implementation may provide additional types, values, objects, properties, and functions beyond those described in this specification. This may cause constructs (such as looking up a variable in the global scope) to have host-defined behaviour instead of throwing an error (such as *ReferenceError*).
@@ -24856,7 +24890,7 @@

The Global Object

  • is created before control enters any execution context.
  • does not have a [[Construct]] internal method; it cannot be used as a constructor with the `new` operator.
  • does not have a [[Call]] internal method; it cannot be invoked as a function.
    • -
  • has a [[Prototype]] internal slot whose value is implementation-dependent.
    • +
  • has a [[Prototype]] internal slot whose value is host-defined.
  • may have host defined properties in addition to the properties defined in this specification. This may include a property whose value is the global object itself.
    • @@ -24916,7 +24950,7 @@

    Runtime Semantics: PerformEval ( _x_, _callerRealm_, _strictCaller_, _direct 1. Set _inFunction_ to *true*. 1. Set _inMethod_ to _thisEnvRec_.HasSuperBinding(). 1. If _F_.[[ConstructorKind]] is ~derived~, set _inDerivedConstructor_ to *true*. - 1. Perform the following substeps in an implementation-dependent order, possibly interleaving parsing and error detection: + 1. Perform the following substeps in an implementation-defined order, possibly interleaving parsing and error detection: 1. Let _script_ be the ECMAScript code that is the result of parsing ! UTF16DecodeString(_x_), for the goal symbol |Script|. If the parse fails, throw a *SyntaxError* exception. If any early errors are detected, throw a *SyntaxError* exception (but see also clause ). 1. If _script_ Contains |ScriptBody| is *false*, return *undefined*. 1. Let _body_ be the |ScriptBody| of _script_. @@ -24958,7 +24992,7 @@

    Runtime Semantics: PerformEval ( _x_, _callerRealm_, _strictCaller_, _direct

    HostEnsureCanCompileStrings ( _callerRealm_, _calleeRealm_ )

    -

    HostEnsureCanCompileStrings is an implementation-defined abstract operation that allows host environments to block certain ECMAScript functions which allow developers to compile strings into ECMAScript code.

    +

    HostEnsureCanCompileStrings is a host-defined abstract operation that 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.

     @@ -25120,7 +25154,7 @@

    parseInt ( _string_, _radix_ )

    1. Set _R_ to 16. 1. If _S_ contains a code unit that is not a radix-_R_ digit, let _Z_ be the substring of _S_ consisting of all code units before the first such code unit; otherwise, let _Z_ be _S_. 1. If _Z_ is empty, return *NaN*. - 1. Let _mathInt_ be the mathematical 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-dependent approximation to the mathematical integer value that is represented by _Z_ in radix-_R_ notation.) + 1. Let _mathInt_ be the mathematical 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 mathematical integer value that is represented by _Z_ in radix-_R_ notation.) 1. If _mathInt_ = 0ℝ, then 1. If _sign_ = -1, return *-0*. 1. Return *+0*. @@ -26225,7 +26259,7 @@

    Runtime Semantics: CreateDynamicFunction ( _constructor_, _newTarget_, _kind 1. Let _prefix_ be the prefix associated with _kind_ in . 1. Let _sourceString_ be the string-concatenation of _prefix_, *" anonymous("*, _P_, 0x000A (LINE FEED), *") {"*, _bodyString_, and *"}"*. 1. Let _sourceText_ be ! UTF16DecodeString(_sourceString_). - 1. Perform the following substeps in an implementation-dependent order, possibly interleaving parsing and error detection: + 1. Perform the following substeps in an implementation-defined order, possibly interleaving parsing and error detection: 1. Let _parameters_ be the result of parsing ! UTF16DecodeString(_P_), using _parameterGoal_ as the goal symbol. Throw a *SyntaxError* exception if the parse fails. 1. Let _body_ be the result of parsing ! UTF16DecodeString(_bodyString_), using _goal_ as the goal symbol. Throw a *SyntaxError* exception if the parse fails. 1. Let _strict_ be ContainsUseStrict of _body_. @@ -26394,10 +26428,10 @@

    Function.prototype.toString ( )

    When the `toString` method is called, the following steps are taken:

    1. Let _func_ be the *this* value. - 1. If _func_ is a bound function exotic object or a built-in function object, then return an implementation-dependent String source code representation of _func_. The representation must have the syntax of a |NativeFunction|. Additionally, if _func_ is a Well-known Intrinsic Object and is not identified as an anonymous function, the portion of the returned String that would be matched by |PropertyName| must be the initial value of the *"name"* property of _func_. + 1. If _func_ is a bound function exotic object or a built-in function object, then return an implementation-defined String source code representation of _func_. The representation must have the syntax of a |NativeFunction|. Additionally, if _func_ is a Well-known Intrinsic Object and is not identified as an anonymous function, the portion of the returned String that would be matched by |PropertyName| must be the initial value of the *"name"* property of _func_. 1. If Type(_func_) is Object and _func_ has a [[SourceText]] internal slot and _func_.[[SourceText]] is a sequence of Unicode code points and ! HostHasSourceTextAvailable(_func_) is *true*, then 1. Return ! UTF16Encode(_func_.[[SourceText]]). - 1. If Type(_func_) is Object and IsCallable(_func_) is *true*, then return an implementation-dependent String source code representation of _func_. The representation must have the syntax of a |NativeFunction|. + 1. If Type(_func_) is Object and IsCallable(_func_) is *true*, then return an implementation-defined String source code representation of _func_. The representation must have the syntax of a |NativeFunction|. 1. Throw a *TypeError* exception. @@ -26457,9 +26491,9 @@

    prototype

         - +

    HostHasSourceTextAvailable ( _func_ )

    -

    HostHasSourceTextAvailable is an implementation-defined abstract operation that allows host environments to prevent the source text from being provided for a given function.

    +

    HostHasSourceTextAvailable is a host-defined abstract operation that allows host environments to prevent the source text from being provided for a given function.

    An implementation of HostHasSourceTextAvailable must complete normally in all cases. This operation must be deterministic with respect to its parameters. Each time it is called with a specific _func_ as its argument, it must return the same completion record. The default implementation of HostHasSourceTextAvailable is to unconditionally return a normal completion with a value of *true*.

         @@ -27307,7 +27341,7 @@

    Number.prototype.toFixed ( _fractionDigits_ )

    Number.prototype.toLocaleString ( [ _reserved1_ [ , _reserved2_ ] ] )

    An ECMAScript implementation that includes the ECMA-402 Internationalization API must implement the `Number.prototype.toLocaleString` method as specified in the ECMA-402 specification. If an ECMAScript implementation does not include the ECMA-402 API the following specification of the `toLocaleString` method is used.

    -

    Produces a String value that represents this Number value formatted according to the conventions of the host environment's current locale. This function is implementation-dependent, and it is permissible, but not encouraged, for it to return the same thing as `toString`.

    +

    Produces a String value that represents this Number value formatted according to the conventions of the host environment's current locale. This function is implementation-defined, and it is permissible, but not encouraged, for it to return the same thing as `toString`.

    The meanings of the optional parameters to this method are defined in the ECMA-402 specification; implementations that do not include ECMA-402 support must not use those parameter positions for anything else.

     @@ -27364,7 +27398,7 @@

    Number.prototype.toString ( [ _radix_ ] )

    1. Else, let _radixNumber_ be ? ToInteger(_radix_). 1. If _radixNumber_ < 2 or _radixNumber_ > 36, throw a *RangeError* exception. 1. If _radixNumber_ = 10, return ! ToString(_x_). - 1. Return the String representation of this Number value using the radix specified by _radixNumber_. Letters `a`-`z` are used for digits with values 10 through 35. The precise algorithm is implementation-dependent, however the algorithm should be a generalization of that specified in . + 1. Return the String representation of this Number value using the radix specified by _radixNumber_. Letters `a`-`z` are used for digits with values 10 through 35. The precise algorithm is implementation-defined, however the algorithm should be a generalization of that specified in .

    The `toString` function is not generic; it throws a *TypeError* exception if its *this* value is not a Number or a Number object. Therefore, it cannot be transferred to other kinds of objects for use as a method.

    The *"length"* property of the `toString` method is 1.

    @@ -27478,7 +27512,7 @@

    BigInt.prototype.constructor

    BigInt.prototype.toLocaleString ( [ _reserved1_ [ , _reserved2_ ] ] )

    An ECMAScript implementation that includes the ECMA-402 Internationalization API must implement the `BigInt.prototype.toLocaleString` method as specified in the ECMA-402 specification. If an ECMAScript implementation does not include the ECMA-402 API the following specification of the `toLocaleString` method is used.

    -

    Produces a String value that represents this BigInt value formatted according to the conventions of the host environment's current locale. This function is implementation-dependent, and it is permissible, but not encouraged, for it to return the same thing as `toString`.

    +

    Produces a String value that represents this BigInt value formatted according to the conventions of the host environment's current locale. This function is implementation-defined, and it is permissible, but not encouraged, for it to return the same thing as `toString`.

    The meanings of the optional parameters to this method are defined in the ECMA-402 specification; implementations that do not include ECMA-402 support must not use those parameter positions for anything else.

     @@ -27494,7 +27528,7 @@

    BigInt.prototype.toString ( [ _radix_ ] )

    1. Else, let _radixNumber_ be ? ToInteger(_radix_). 1. If _radixNumber_ < 2 or _radixNumber_ > 36, throw a *RangeError* exception. 1. If _radixNumber_ = 10, return ! ToString(_x_). - 1. Return the String representation of this Number value using the radix specified by _radixNumber_. Letters `a`-`z` are used for digits with values 10 through 35. The precise algorithm is implementation-dependent, however the algorithm should be a generalization of that specified in . + 1. Return the String representation of this Number value using the radix specified by _radixNumber_. Letters `a`-`z` are used for digits with values 10 through 35. The precise algorithm is implementation-defined, however the algorithm should be a generalization of that specified in .

    The `toString` function is not generic; it throws a *TypeError* exception if its *this* value is not a BigInt or a BigInt object. Therefore, it cannot be transferred to other kinds of objects for use as a method.

    @@ -27624,7 +27658,7 @@

    Math.abs ( _x_ )

    Math.acos ( _x_ )

    -

    Returns an implementation-dependent approximation to the arc cosine of _x_. The result is expressed in radians and ranges from *+0* to +π.

    +

    Returns an implementation-approximated value representing the result of the arc cosine of _x_. The result is expressed in radians and ranges from *+0* to +π.