proposal-bigint-math/spec.html at main · tc39/proposal-bigint-math · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
<pre class=metadata>
title: ES BigInt Math (2025)
status: proposal
stage: 1
location: https://github.com/tc39/proposal-bigint-math
copyright: false
contributors: J. S. Choi
</pre>

<emu-intro id=introduction>
  <h1>Introduction</h1>
  <p>This is the formal specification for a proposed extension
  of the `BigInt` JavaScript global object with further operations.
  It modifies the original <a
  href=https://tc39.es/ecma262/multipage/>ECMAScript specification</a> with
  several new or revised clauses. See <a
  href=https://github.com/tc39/proposal-bigint-math/blob/main/README.md>the proposal's
  explainer</a> for the proposal's background, motivation, and usage examples.</p>
</emu-intro>

<emu-clause id="sec-properties-of-the-bigint-constructor">
  <h1>Properties of the BigInt Constructor</h1>
  <p>The BigInt constructor:</p>
  <ul>
    <li>has a [[Prototype]] internal slot whose value is %Function.prototype%.</li>
    <li>has the following properties:</li>
  </ul>

  <emu-clause id="sec-bigint.abs">
    <h1><ins>BigInt.abs ( _x_ )</ins></h1>
    <p>This function returns the absolute value of _x_ as a BigInt; the result has the same magnitude as _x_ but has positive sign.</p>
    <p>It performs the following steps when called:</p>
    <emu-alg>
      1. If _x_ is not a BigInt, throw a *TypeError* exception.
      1. Return the BigInt value that represents abs(ℝ(_x_)).
    </emu-alg>
  </emu-clause>

  <emu-clause id="sec-bigint.cbrt">
    <h1><ins>BigInt.cbrt ( _x_ )</ins></h1>
    <p>This function returns the cube root of _x_ as a BigInt.</p>
    <p>It performs the following steps when called:</p>
    <emu-alg>
      1. If _x_ is not a BigInt, throw a *TypeError* exception.
      1. Let _root_ be the cube root of ℝ(_x_).
      1. Return ℤ(truncate(_root_)).
    </emu-alg>
  </emu-clause>

  <emu-clause id="sec-bigint.max">
    <h1><ins>BigInt.max ( _firstArg_, ..._restArgs_ )</ins></h1>
    <p>Given one or more BigInt arguments, this function returns the largest of the resulting values.</p>
    <p>It performs the following steps when called:</p>
    <emu-alg>
      1. If _x_ is not a BigInt, throw a *TypeError* exception.
      1. Let _highest_ be _firstCoerced_.
      1. For each element _number_ of _restCoerced_, do
        1. If _number_ is not a BigInt, throw a *TypeError* exception.
        1. If _number_ > _highest_, set _highest_ to _number_.
      1. Return _highest_.
    </emu-alg>
    <p>The *"length"* property of this function is *2*<sub>𝔽</sub>.</p>
  </emu-clause>

  <emu-clause id="sec-bigint.min">
    <h1><ins>BigInt.min ( _firstArg_, ..._restArgs_ )</ins></h1>
    <p>Given one or more arguments, this function calls ToBigInt on each of the arguments and returns the smallest of the resulting values.</p>
    <p>It performs the following steps when called:</p>
    <emu-alg>
      1. If _x_ is not a BigInt, throw a *TypeError* exception.
      1. Let _lowest_ be _firstCoerced_.
      1. For each element _number_ of _restCoerced_, do
        1. If _number_ is not a BigInt, throw a *TypeError* exception.
        1. If _number_ &lt; _lowest_, set _lowest_ to _number_.
      1. Return _lowest_.
    </emu-alg>
    <p>The *"length"* property of this function is *2*<sub>𝔽</sub>.</p>
  </emu-clause>

  <emu-clause id="sec-bigint.pow">
    <h1><ins>BigInt.pow ( _base_, _exponent_ )</ins></h1>
    <p>This function performs the following steps when called:</p>
    <emu-alg>
      1. If _base_ is not a BigInt, throw a *TypeError* exception.
      1. If _exponent_ is not a BigInt, throw a *TypeError* exception.
      1. Return BigInt::exponentiate(_base_, _exponent_).
    </emu-alg>
  </emu-clause>

  <emu-clause id="sec-bigint.prototype">
    <h1>BigInt.prototype</h1>
    <p>The initial value of `BigInt.prototype` is the BigInt prototype object.</p>
    <p>This property has the attributes { [[Writable]]: *false*, [[Enumerable]]: *false*, [[Configurable]]: *false* }.</p>
  </emu-clause>

  <emu-clause id="sec-bigint.sign">
    <h1><ins>BigInt.sign ( _x_ )</ins></h1>
    <p>This function returns the sign of _x_ as a BigInt, indicating whether _x_ is positive, negative, or zero.</p>
    <p>It performs the following steps when called:</p>
    <emu-alg>
      1. If _x_ is not a BigInt, throw a *TypeError* exception.
      1. If _x_ is *0*<sub>ℤ</sub>, return _x_.
      1. If _x_ &lt; *0*<sub>ℤ</sub>, return *-1*<sub>ℤ</sub>.
      1. Return *1*<sub>ℤ</sub>.</emu-alg>
  </emu-clause>

  <emu-clause id="sec-bigint.sqrt">
    <h1><ins>BigInt.sqrt ( _x_ )</ins></h1>
    <p>This function returns the square root of _x_ as a BigInt.</p>
    <p>It performs the following steps when called:</p>
    <emu-alg>
      1. If _x_ is not a BigInt, throw a *TypeError* exception.
      1. If _x_ < *0*<sub>ℤ</sub>, throw a *RangeError* exception.
      1. Let _root_ be the square root of ℝ(_x_).
      1. Return ℤ(truncate(_root_)).
    </emu-alg>
  </emu-clause>
</emu-clause>