From e38ce0627e12ade103c17ffe1cc019fe25602c91 Mon Sep 17 00:00:00 2001 From: Michael Dyck Date: Sun, 26 Apr 2020 22:05:34 -0400 Subject: [PATCH] Editorial: Complete standard preambles for numeric methods (#1974) - Move talk of operators out of Number methods, down to where we actually have operators - Move commutative/associative sentences to Notes for Number::multiply and Number::add, just because a Note seems like a better place - Convert Number::subtract's prose into an emu-alg - Convert the preambles of 6 Number methods - to the 'standard' form introduced in PR #1914. - Add standard preambles for numeric methods that don't have one (For the non-prescribed part of the standard preamble, I mostly tried to re-use the wording in the existing preamble. This could probably be made more consistent between the different operations, but that wasn't my goal) --- spec.html | 59 ++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 47 insertions(+), 12 deletions(-) diff --git a/spec.html b/spec.html index 2533aeea11..0b0394a1bb 100644 --- a/spec.html +++ b/spec.html @@ -1491,6 +1491,7 @@

The Number Type

Number::unaryMinus ( _x_ )

+

The abstract operation Number::unaryMinus takes argument _x_ (a Number). It performs the following steps when called:

1. If _x_ is *NaN*, return *NaN*. 1. Return the result of negating _x_; that is, compute a Number with the same magnitude but opposite sign. @@ -1499,6 +1500,7 @@

Number::unaryMinus ( _x_ )

Number::bitwiseNOT ( _x_ )

+

The abstract operation Number::bitwiseNOT takes argument _x_ (a Number). It performs the following steps when called:

1. Let _oldValue_ be ! ToInt32(_x_). 1. Return the result of applying bitwise complement to _oldValue_. The result is a signed 32-bit integer. @@ -1507,9 +1509,7 @@

Number::bitwiseNOT ( _x_ )

Number::exponentiate ( _base_, _exponent_ )

-

- Returns an implementation-dependent approximation of the result of raising _base_ to the power _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:

  • If _exponent_ is *NaN*, the result is *NaN*.
  • If _exponent_ is *+0*, the result is 1, even if _base_ is *NaN*.
    • @@ -1542,8 +1542,7 @@

    Number::exponentiate ( _base_, _exponent_ )

    Number::multiply ( _x_, _y_ )

    -

    The `*` |MultiplicativeOperator| performs multiplication, producing the product of _x_ and _y_. Multiplication is commutative. Multiplication is not always associative in ECMAScript, because of finite precision.

    -

    The result of a floating-point multiplication is governed by the rules of IEEE 754-2019 binary double-precision arithmetic:

    +

    The abstract operation Number::multiply takes arguments _x_ (a Number) and _y_ (a Number). It performs multiplication, producing the product of _x_ and _y_, as determined by the rules of IEEE 754-2019 binary double-precision arithmetic:

    • If either operand is *NaN*, the result is *NaN*. @@ -1564,11 +1563,14 @@

      Number::multiply ( _x_, _y_ )

      In the remaining cases, where neither an infinity nor *NaN* is involved, the product is computed and rounded to the nearest representable value using IEEE 754-2019 roundTiesToEven mode. If the magnitude is too large to represent, the result is then an infinity of appropriate sign. If the magnitude is too small to represent, the result is then a zero of appropriate sign. The ECMAScript language requires support of gradual underflow as defined by IEEE 754-2019.
    + +

    Finite-precision multiplication is commutative, but not always associative.

    +

    Number::divide ( _x_, _y_ )

    -

    The `/` |MultiplicativeOperator| performs division, producing the quotient of _x_ and _y_. _x_ is the dividend and _y_ is the divisor. ECMAScript does not perform integer division. The operands and result of all division operations are double-precision floating-point numbers. The result of division is determined by the specification of IEEE 754-2019 arithmetic:

    +

    The abstract operation Number::divide takes arguments _x_ (a Number) and _y_ (a Number). It performs division, producing the quotient of _x_ and _y_; _x_ is the dividend and _y_ is the divisor. The result is determined by the specification of IEEE 754-2019 arithmetic:

    • If either operand is *NaN*, the result is *NaN*. @@ -1602,7 +1604,7 @@

      Number::divide ( _x_, _y_ )

      Number::remainder ( _n_, _d_ )

      -

      The `%` |MultiplicativeOperator| yields the remainder of its operands from an implied division; _n_ is the dividend and _d_ is the divisor.

      +

      The abstract operation Number::remainder takes arguments _n_ (a Number) and _d_ (a Number). It yields the remainder of its operands from an implied division; _n_ is the dividend and _d_ is the divisor.

      In C and C++, the remainder operator accepts only integral operands; in ECMAScript, it also accepts floating-point operands.

       @@ -1632,9 +1634,7 @@

      Number::remainder ( _n_, _d_ )

      Number::add ( _x_, _y_ )

      -

      The `+` operator performs addition when applied to _x_ and _y_, producing the sum of the operands.

      -

      Addition is a commutative operation, but not always associative.

      -

      The result of an addition is determined using the rules of IEEE 754-2019 binary double-precision arithmetic:

      +

      The abstract operation Number::add takes arguments _x_ (a Number) and _y_ (a Number). It performs addition, producing the sum of _x_ and _y_ as determined using the rules of IEEE 754-2019 binary double-precision arithmetic:

      • If either operand is *NaN*, the result is *NaN*. @@ -1661,16 +1661,25 @@

        Number::add ( _x_, _y_ )

        In the remaining cases, where neither an infinity, nor a zero, nor *NaN* is involved, and the operands have the same sign or have different magnitudes, the sum is computed and rounded to the nearest representable value using IEEE 754-2019 roundTiesToEven mode. If the magnitude is too large to represent, the operation overflows and the result is then an infinity of appropriate sign. The ECMAScript language requires support of gradual underflow as defined by IEEE 754-2019.
      + +

      Finite-precision addition is commutative, but not always associative.

      +

      Number::subtract ( _x_, _y_ )

      -

      The `-` operator performs subtraction when applied to two operands of numeric type, producing the difference of its operands; _x_ is the minuend and _y_ is the subtrahend. It is always the case that `x - y` produces the same result as `x + (-y)`.

      -

      The result of `-` operator is then _x_ + (-_y_).

      +

      The abstract operation Number::subtract takes arguments _x_ (a Number) and _y_ (a Number). It performs subtraction, producing the difference of its operands; _x_ is the minuend and _y_ is the subtrahend. It performs the following steps when called:

      + + 1. Return Number::add(_x_, Number::unaryMinus(_y_)). + + +

      It is always the case that `x - y` produces the same result as `x + (-y)`.

      +

      Number::leftShift ( _x_, _y_ )

      +

      The abstract operation Number::leftShift takes arguments _x_ (a Number) and _y_ (a Number). It performs the following steps when called:

      1. Let _lnum_ be ! ToInt32(_x_). 1. Let _rnum_ be ! ToUint32(_y_). @@ -1681,6 +1690,7 @@

      Number::leftShift ( _x_, _y_ )

      Number::signedRightShift ( _x_, _y_ )

      +

      The abstract operation Number::signedRightShift takes arguments _x_ (a Number) and _y_ (a Number). It performs the following steps when called:

      1. Let _lnum_ be ! ToInt32(_x_). 1. Let _rnum_ be ! ToUint32(_y_). @@ -1691,6 +1701,7 @@

      Number::signedRightShift ( _x_, _y_ )

      Number::unsignedRightShift ( _x_, _y_ )

      +

      The abstract operation Number::unsignedRightShift takes arguments _x_ (a Number) and _y_ (a Number). It performs the following steps when called:

      1. Let _lnum_ be ! ToUint32(_x_). 1. Let _rnum_ be ! ToUint32(_y_). @@ -1701,6 +1712,7 @@

      Number::unsignedRightShift ( _x_, _y_ )

      Number::lessThan ( _x_, _y_ )

      +

      The abstract operation Number::lessThan takes arguments _x_ (a Number) and _y_ (a Number). It performs the following steps when called:

      1. If _x_ is *NaN*, return *undefined*. 1. If _y_ is *NaN*, return *undefined*. @@ -1717,6 +1729,7 @@

      Number::lessThan ( _x_, _y_ )

      Number::equal ( _x_, _y_ )

      +

      The abstract operation Number::equal takes arguments _x_ (a Number) and _y_ (a Number). It performs the following steps when called:

      1. If _x_ is *NaN*, return *false*. 1. If _y_ is *NaN*, return *false*. @@ -1729,6 +1742,7 @@

      Number::equal ( _x_, _y_ )

      Number::sameValue ( _x_, _y_ )

      +

      The abstract operation Number::sameValue takes arguments _x_ (a Number) and _y_ (a Number). It performs the following steps when called:

      1. If _x_ is *NaN* and _y_ is *NaN*, return *true*. 1. If _x_ is *+0* and _y_ is *-0*, return *false*. @@ -1740,6 +1754,7 @@

      Number::sameValue ( _x_, _y_ )

      Number::sameValueZero ( _x_, _y_ )

      +

      The abstract operation Number::sameValueZero takes arguments _x_ (a Number) and _y_ (a Number). It performs the following steps when called:

      1. If _x_ is *NaN* and _y_ is *NaN*, return *true*. 1. If _x_ is *+0* and _y_ is *-0*, return *true*. @@ -1761,6 +1776,7 @@

      NumberBitwiseOp ( _op_, _x_, _y_ )

      Number::bitwiseAND ( _x_, _y_ )

      +

      The abstract operation Number::bitwiseAND takes arguments _x_ (a Number) and _y_ (a Number). It performs the following steps when called:

      1. Return NumberBitwiseOp(`&`, _x_, _y_). @@ -1768,6 +1784,7 @@

      Number::bitwiseAND ( _x_, _y_ )

      Number::bitwiseXOR ( _x_, _y_ )

      +

      The abstract operation Number::bitwiseXOR takes arguments _x_ (a Number) and _y_ (a Number). It performs the following steps when called:

      1. Return NumberBitwiseOp(`^`, _x_, _y_). @@ -1775,6 +1792,7 @@

      Number::bitwiseXOR ( _x_, _y_ )

      Number::bitwiseOR ( _x_, _y_ )

      +

      The abstract operation Number::bitwiseOR takes arguments _x_ (a Number) and _y_ (a Number). It performs the following steps when called:

      1. Return NumberBitwiseOp(`|`, _x_, _y_). @@ -1852,6 +1870,7 @@

      The BigInt Type

      BigInt::unaryMinus ( _x_ )

      +

      The abstract operation BigInt::unaryMinus takes argument _x_ (a BigInt). It performs the following steps when called:

      1. If _x_ is *0n*, return *0n*. 1. Return the BigInt value that represents the mathematical value of negating _x_. @@ -1865,6 +1884,7 @@

      BigInt::bitwiseNOT ( _x_ )

      BigInt::exponentiate ( _base_, _exponent_ )

      +

      The abstract operation BigInt::exponentiate takes arguments _base_ (a BigInt) and _exponent_ (a BigInt). It performs the following steps when called:

      1. If _exponent_ < *0n*, throw a *RangeError* exception. 1. If _base_ is *0n* and _exponent_ is *0n*, return *1n*. @@ -1880,6 +1900,7 @@

      BigInt::multiply ( _x_, _y_ )

      BigInt::divide ( _x_, _y_ )

      +

      The abstract operation BigInt::divide takes arguments _x_ (a BigInt) and _y_ (a BigInt). It performs the following steps when called:

      1. If _y_ is *0n*, throw a *RangeError* exception. 1. Let _quotient_ be the mathematical value of _x_ divided by _y_. @@ -1889,6 +1910,7 @@

      BigInt::divide ( _x_, _y_ )

      BigInt::remainder ( _n_, _d_ )

      +

      The abstract operation BigInt::remainder takes arguments _n_ (a BigInt) and _d_ (a BigInt). It performs the following steps when called:

      1. If _d_ is *0n*, throw a *RangeError* exception. 1. If _n_ is *0n*, return *0n*. @@ -2027,6 +2049,7 @@

      BigIntBitwiseOp ( _op_, _x_, _y_ )

      BigInt::bitwiseAND ( _x_, _y_ )

      +

      The abstract operation BigInt::bitwiseAND takes arguments _x_ (a BigInt) and _y_ (a BigInt). It performs the following steps when called:

      1. Return BigIntBitwiseOp(*"&"*, _x_, _y_). @@ -2034,6 +2057,7 @@

      BigInt::bitwiseAND ( _x_, _y_ )

      BigInt::bitwiseXOR ( _x_, _y_ )

      +

      The abstract operation BigInt::bitwiseXOR takes arguments _x_ (a BigInt) and _y_ (a BigInt). It performs the following steps when called:

      1. Return BigIntBitwiseOp(*"^"*, _x_, _y_). @@ -2041,6 +2065,7 @@

      BigInt::bitwiseXOR ( _x_, _y_ )

      BigInt::bitwiseOR ( _x_, _y_ )

      +

      The abstract operation BigInt::bitwiseOR takes arguments _x_ (a BigInt) and _y_ (a BigInt). It performs the following steps when called:

      1. Return BigIntBitwiseOp(*"|"*, _x_, _y_). @@ -14566,6 +14591,13 @@

      Syntax

      MultiplicativeOperator : one of `*` `/` `%` + +
        +
      • The `*` operator performs multiplication, producing the product of its operands.
        • +
      • The `/` operator performs division, producing the quotient of its operands.
        • +
      • The `%` operator yields the remainder of its operands from an implied division.
        • +
      +

      Static Semantics: IsFunctionDefinition

      @@ -14648,6 +14680,9 @@

      Runtime Semantics: Evaluation

      The Subtraction Operator ( `-` )

      + +

      The `-` operator performs subtraction, producing the difference of its operands.

      +

      Runtime Semantics: Evaluation