Skip to content

Add bigint type #525

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 10 commits into from
Nov 5, 2020
Merged

Add bigint type #525

Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
7b0f628
Add bigint type
littledan Feb 22, 2018
51103b7
fixup! Add bigint type
Ms2ger Nov 11, 2019
25f045f
Support unions.
Ms2ger Nov 13, 2019
7b3601b
fixup! Support unions.
Ms2ger Nov 14, 2019
c387fed
fixup! Add bigint type
Ms2ger Nov 14, 2019
6b3c2db
fixup! Add bigint type
Ms2ger Dec 2, 2019
e7383a9
Remove bigint token in favor of integer.
Ms2ger Dec 2, 2019
8738379
fixup! Add bigint type
Ms2ger Dec 2, 2019
3ea5bca
fixup! Add bigint type
Ms2ger Dec 2, 2019
4f8357a
Small fixes
TimothyGu Nov 5, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
132 changes: 129 additions & 3 deletions index.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -161,9 +161,11 @@ urlPrefix: https://tc39.github.io/ecma262/; spec: ECMA-262
text: SetFunctionName; url: sec-setfunctionname
text: SetImmutablePrototype; url: sec-set-immutable-prototype
text: SetIntegrityLevel; url: sec-setintegritylevel
text: ToBigInt; url: #sec-tobigint
text: ToBoolean; url: sec-toboolean
text: ToInt32; url: sec-toint32
text: ToNumber; url: sec-tonumber
text: ToNumeric; url: sec-tonumeric
text: ToObject; url: sec-toobject
text: ToString; url: sec-tostring
text: ToUint16; url: sec-touint16
Expand All @@ -187,6 +189,7 @@ urlPrefix: https://tc39.github.io/ecma262/; spec: ECMA-262
text: array index; url: array-index
text: array iterator object; url: sec-array-iterator-objects
text: built-in function object; url: sec-built-in-function-objects
text: BigInt; url: #sec-ecmascript-language-types-bigint-type
text: callable; for: ECMAScript; url: sec-iscallable
text: Completion Record; url: sec-completion-record-specification-type
text: constructor; url: constructor
Expand Down Expand Up @@ -3594,6 +3597,9 @@ the following algorithm returns <i>true</i>.
</div></th>
<th><div>
<span>numeric types</span>
</div></th>
<th><div>
<span>bigint</span>
</div></th>
<th><div>
<span>string types</span>
Expand Down Expand Up @@ -3628,11 +3634,26 @@ the following algorithm returns <i>true</i>.
<td>●</td>
<td>●</td>
<td>●</td>
<td>●</td>
</tr>
<tr>
<th>numeric types</th>
<td class="belowdiagonal"></td>
<td></td>
<td></td>
<td>●</td>
<td>●</td>
<td>●</td>
<td>●</td>
<td>●</td>
<td>●</td>
<td>●</td>
</tr>
<tr>
<th>bigint</th>
<td class="belowdiagonal"></td>
<td class="belowdiagonal"></td>
<td>(b)</td>
<td>●</td>
<td>●</td>
<td>●</td>
Expand All @@ -3645,6 +3666,7 @@ the following algorithm returns <i>true</i>.
<th>string types</th>
<td class="belowdiagonal"></td>
<td class="belowdiagonal"></td>
<td class="belowdiagonal"></td>
<td></td>
<td>●</td>
<td>●</td>
Expand All @@ -3658,6 +3680,7 @@ the following algorithm returns <i>true</i>.
<td class="belowdiagonal"></td>
<td class="belowdiagonal"></td>
<td class="belowdiagonal"></td>
<td class="belowdiagonal"></td>
<td></td>
<td>●</td>
<td></td>
Expand All @@ -3671,6 +3694,7 @@ the following algorithm returns <i>true</i>.
<td class="belowdiagonal"></td>
<td class="belowdiagonal"></td>
<td class="belowdiagonal"></td>
<td class="belowdiagonal"></td>
<td></td>
<td>●</td>
<td>●</td>
Expand All @@ -3684,6 +3708,7 @@ the following algorithm returns <i>true</i>.
<td class="belowdiagonal"></td>
<td class="belowdiagonal"></td>
<td class="belowdiagonal"></td>
<td class="belowdiagonal"></td>
<td>(a)</td>
<td>●</td>
<td>●</td>
Expand All @@ -3697,6 +3722,7 @@ the following algorithm returns <i>true</i>.
<td class="belowdiagonal"></td>
<td class="belowdiagonal"></td>
<td class="belowdiagonal"></td>
<td class="belowdiagonal"></td>
<td></td>
<td></td>
<td>●</td>
Expand All @@ -3710,6 +3736,7 @@ the following algorithm returns <i>true</i>.
<td class="belowdiagonal"></td>
<td class="belowdiagonal"></td>
<td class="belowdiagonal"></td>
<td class="belowdiagonal"></td>
<td></td>
<td>●</td>
</tr>
Expand All @@ -3723,6 +3750,7 @@ the following algorithm returns <i>true</i>.
<td class="belowdiagonal"></td>
<td class="belowdiagonal"></td>
<td class="belowdiagonal"></td>
<td class="belowdiagonal"></td>
<td></td>
</tr>
</table>
Expand All @@ -3731,6 +3759,10 @@ the following algorithm returns <i>true</i>.
1. The two identified interface-like types are
not the same, and no single [=platform object=] implements both
interface-like types.
1. The types are distinguishable, but there is
<a href="#limit-bigint-numeric-overloading">a separate restriction on their use in
overloading</a> below. Please also note <a href="#limit-bigint-numeric-unions">the
advice about using unions of these types</a>.
</ol>

<div class="example" id="example-distinguishability-diff-types">
Expand Down Expand Up @@ -3781,6 +3813,11 @@ for each pair of items the types at index |i| are [=distinguishable=].
The lowest such index is termed the <dfn id="dfn-distinguishing-argument-index" export>distinguishing argument index</dfn>
for the items of the [=effective overload set=] with the given type list size.

<p id="limit-bigint-numeric-overloading">An [=effective overload set=] must not contain more than
one [=list/item=] with the same [=type list=] [=list/size=], where one [=list/item=] has a
{{bigint}} argument at the [=distinguishing argument index=] and another has a [=numeric type=]
argument at the [=distinguishing argument index=].

<div class="example">

Consider the [=effective overload set=] shown in the previous example.
Expand Down Expand Up @@ -5664,7 +5701,7 @@ the [=integer types=],
{{unrestricted double}}.

The <dfn id="dfn-primitive-type" export>primitive types</dfn> are
{{boolean}} and the [=numeric types=].
{{bigint}}, {{boolean}} and the [=numeric types=].

The <dfn id="dfn-string-type" export>string types</dfn> are
{{DOMString}}, all [=enumeration types=],
Expand Down Expand Up @@ -5768,6 +5805,7 @@ type.
"boolean"
"byte"
"octet"
"bigint"
</pre>

<pre class="grammar" id="prod-UnrestrictedFloatType">
Expand Down Expand Up @@ -6034,6 +6072,16 @@ The [=type name=] of the
{{unrestricted double}} type is "<code>UnrestrictedDouble</code>".


<h4 id="idl-bigint" interface>bigint</h4>

The {{bigint}} type is an arbitrary integer type, unrestricted in range.

{{bigint}} constant values in IDL are represented with
<emu-t class="regex"><a href="#prod-integer">integer</a></emu-t> tokens.

The [=type name=] of the {{bigint}} type is “<code>BigInt</code>”.


<h4 oldids="dom-DOMString" id="idl-DOMString" interface>DOMString</h4>

The {{DOMString}} type corresponds to
Expand Down Expand Up @@ -6529,6 +6577,19 @@ Each pair of [=flattened member types=]
in a [=union type=], <var ignore>T</var> and <var ignore>U</var>,
must be [=distinguishable=].

<p class="advisement" id="limit-bigint-numeric-unions">
It is possible to create a union of {{bigint}} and a [=numeric type=].
However, this is generally only supposed to be used for interfaces such as
[[ECMA-402#numberformat-objects|NumberFormat]], which formats the values rather than using them in
calculations.
It would not be appropriate to accept such a union, only to then convert values of the
[=numeric type=] to a {{bigint}} for further processing, as this runs the risk of introducing
precision errors.
Please
<a href="https://github.com/heycam/webidl/issues/new?title=Intent%20to%20use%20bigint/numeric union">file an issue</a>
before using this feature.
</p>

[=Union type=] constant values
in IDL are represented in the same way that constant values of their
[=member types=] would be
Expand Down Expand Up @@ -6933,6 +6994,7 @@ five forms are allowed.
"Promise"
"USVString"
"any"
"bigint"
"boolean"
"byte"
"double"
Expand Down Expand Up @@ -7186,6 +7248,9 @@ ECMAScript value type.
1. If <a abstract-op>Type</a>(|V|) is Number, then
return the result of <a href="#es-to-unrestricted-double">converting</a> |V|
to an {{unrestricted double}}.
1. If <a abstract-op>Type</a>(|V|) is BigInt, then
return the result of <a href="#es-to-bigint">converting</a> |V|
to a {{bigint}}.
1. If <a abstract-op>Type</a>(|V|) is String, then
return the result of <a href="#es-DOMString">converting</a> |V|
to a {{DOMString}}.
Expand Down Expand Up @@ -7615,6 +7680,38 @@ value when its bit pattern is interpreted as an unsigned 64 bit integer.
{{unrestricted double}} value.
</div>

<h4 id="es-bigint">bigint</h4>

<div id="es-to-bigint" algorithm="convert an ECMAScript value to a bigint">

An ECMAScript value |V| is [=converted to an IDL value|converted=]
to an IDL {{bigint}} value by running the following algorithm:

1. Let |x| be [=?=] [$ToBigInt$](|V|).
1. Return the IDL {{bigint}} value that represents the same numeric value as |x|.
</div>

<div id="bigint-to-es" algorithm="convert a bigint to an ECMAScript value">

The result of [=converted to an ECMAScript value|converting=]
an IDL {{bigint}} value to an ECMAScript value is a BigInt:

1. Return the [=BigInt=] value that represents the same numeric value as the IDL {{bigint}}
value.
</div>

<div id="es-to-bigint-or-numeric" algorithm="convert an ECMAScript value to a numeric type or a bigint">

An ECMAScript value |V| is <dfn lt="converted to a numeric type or bigint">converted</dfn>
to an IDL [=numeric type=] |T| or {{bigint}} value by running the following algorithm:

1. Let |x| be [=?=] [$ToNumeric$](|V|).
1. If [$Type$](|x|) is BigInt, then
1. Return the IDL {{bigint}} value that represents the same numeric value as |x|.
1. Assert: [$Type$](|x|) is Number.
1. Return the result of [=converted to an ECMAScript value|converting=] |x| to |T|.
</div>


<h4 id="es-DOMString">DOMString</h4>

Expand Down Expand Up @@ -8644,23 +8741,33 @@ that correspond to the union’s [=member types=].
1. If |types| includes {{object}}, then return the IDL value
that is a reference to the object |V|.
1. If <a abstract-op>Type</a>(|V|) is Boolean, then:
1. If |types| includes a {{boolean}},
1. If |types| includes {{boolean}},
then return the result of [=converted to an IDL value|converting=]
|V| to {{boolean}}.
1. If <a abstract-op>Type</a>(|V|) is Number, then:
1. If |types| includes a [=numeric type=],
then return the result of [=converted to an IDL value|converting=]
|V| to that [=numeric type=].
1. If <a abstract-op>Type</a>(|V|) is BigInt, then:
1. If |types| includes {{bigint}},
then return the result of [=converted to an IDL value|converting=]
|V| to {{bigint}}
1. If |types| includes a [=string type=],
then return the result of
[=converted to an IDL value|converting=]
|V| to that type.
1. If |types| includes a [=numeric type=] and {{bigint}},
then return the result of [=converted to a numeric type or bigint|converting=]
|V| to either that [=numeric type=] or {{bigint}}.
1. If |types| includes a [=numeric type=],
then return the result of [=converted to an IDL value|converting=]
|V| to that [=numeric type=].
1. If |types| includes a {{boolean}},
1. If |types| includes {{boolean}},
then return the result of [=converted to an IDL value|converting=]
|V| to {{boolean}}.
1. If |types| includes {{bigint}},
then return the result of [=converted to an IDL value|converting=]
|V| to {{bigint}}.
1. [=ECMAScript/Throw=] a {{ECMAScript/TypeError}}.
</div>

Expand Down Expand Up @@ -10990,6 +11097,16 @@ Note: The HTML Standard defines how a security check is performed. [[!HTML]]

then remove from |S| all other entries.

1. Otherwise: if <a abstract-op>Type</a>(|V|) is BigInt
and there is an entry in |S| that has one of the following types at position |i| of its type list,
* {{bigint}}
* a [=nullable type|nullable=] {{bigint}}
* an [=annotated type=] whose [=annotated types/inner type=] is one of the above types
* a [=union type=], [=nullable type|nullable=] union type, or [=annotated type|annotated=] union type
that has one of the above types in its [=flattened member types=]

then remove from |S| all other entries.

1. Otherwise: if there is an entry in |S| that has one of the following types at position |i| of its type list,
* a [=string type=]
* a [=nullable type|nullable=] version of any of the above types
Expand Down Expand Up @@ -11017,6 +11134,15 @@ Note: The HTML Standard defines how a security check is performed. [[!HTML]]

then remove from |S| all other entries.

1. Otherwise: if there is an entry in |S| that has one of the following types at position |i| of its type list,
* {{bigint}}
* a [=nullable type|nullable=] {{bigint}}
* an [=annotated type=] whose [=annotated types/inner type=] is one of the above types
* a [=union type=], [=nullable type|nullable=] union type, or [=annotated type|annotated=] union type
that has one of the above types in its [=flattened member types=]

then remove from |S| all other entries.

1. Otherwise: if there is an entry in |S| that has {{any}} at position |i|
of its type list, then remove from |S| all other entries.
1. Otherwise: [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
Expand Down