For AI agents: the complete documentation index is available at /tc39-atlas/en/llms.txt, the full documentation bundle is available at /tc39-atlas/en/llms-full.txt, and this page is available as Markdown at /tc39-atlas/en/proposals/year/pending/proposal-bigint-from-exponential.md.
TC39 Atlas
  • English

      • Bigint from exponential S2

      Proposal details
      Proposal overview

      Exponential notation is useful for dealing with big integers but cannot be used directly when defining a BigInt, and BigInt(…) loses precision above 2^53. The proposal adds syntactic support such as 1e6n for static cases and expands StringToBigInt so dynamic cases such as BigInt("1e6") and BigUint64Array.from(["1e6"]) can parse exponential-notation strings. This expansion can also affect operator behavior unless explicit changes preserve backwards compatibility. Alternatives such as BigInt.parse("1e6") or BigInt.fromString("1e6") are also considered.

      Note

      The README below comes from the upstream repository and may contain outdated stage or status metadata. Use the proposal details above as the current source of truth.

      Bigint from exponential

      Status

      The TC39 Process

      Stage: 2

      Champions:

      Specification: http://tc39.es/proposal-bigint-from-exponential/

      Motivation

      Exponential notation is useful for dealing with big integers, but unavailable for direct use in defining a bigint.

      Use of _ separators helps, but isn't quite enough for sufficiently large values. BigInt(…) is lossy above 253. Manual conversion is possible (e.g., /^(?:(0|[1-9][0-9]*)(?:[.]([0-9]*))?|[.]([0-9]+))(?:[Ee]([+-]?[0-9]+))?$/ validates and matches the relevant whole-number/fraction/decimal-exponent parts), but cumbersome and tedious.

      Use cases

      This was discovered in Amount, but also comes up in other contexts (GitHub reports 20.3e3 files matching pattern BigInt[(][^)a-z]*[0-9]e[0-9]):

      • parsing JSON like { "scale": 1e6 } with source text access
      • working with currencies and/or financial values, particularly fine-grained cryptocurrencies (e.g., in algorand-js)
      • working with high-resolution dates or times (e.g., in the ECMAScript Temporal polyfill, and WASI libraries)

      Many use cases are static, where the exponential notation is part of the source text, while others are dynamic and therefore require a built-in function.

      Description

      For static use cases, we propose syntactic support like 1e6n1.

      For dynamic use cases, we propose expanding the behavior of StringToBigInt as suggested by https://github.com/tc39/ecma262/pull/3857, supporting BigInt("1e6")/BigUint64Array.from(["1e6"])/etc. Note that this also affects operator behavior (e.g., 1_000_000n == "1e6" and 1_000_000n <= "1e6" and 1_000_000n >= "1e6", just like the Number analogs 1_000_000 == "1e6" and 1_000_000 <= "1e6" and 1_000_000 >= "1e6") absent explicit changes to preserve backwards compatibility.

      Alternatives like BigInt.parse("1e6") or BigInt.fromString("1e6") could also be considered.

      Dynamic use cases technically cover the static ones, albeit with erosion of developer experience and implementer satisfaction.

      Prior art

      Some npm packages already support parsing exponential-notation strings into arbitrary-precision integers (or analogous strings):

      And there is an even larger population of arbitrary-precision decimal libraries that generalize such behavior beyond integers.

      Across other programming languages, .NET BigInteger.Parse(str, options) supports AllowDecimalPoint and AllowExponent options, but that seems to be as far as it goes:

      Language/APILeading +/-Wrapping whitespaceRadix prefixes
      (e.g. 0x)      		Separators
      (e.g. _)      		Decimal/exponent
      Go (new(big.Int)).SetString(str, 0)yesnoyesyesno
      Java new BigInteger(str, radix)yesnon/anono
      JavaScript BigInt(str)yesyesyesnono
      .NET BigInteger.Parse(str, options)optionaloptionalnooptionaloptional
      Python int(str, base=0)yesyesyesyesno
      Rust num_bigint from_str_radix(&str, radix)yesnon/ayesno

      And for context, ECMAScript is unusual in its strictness:

      Language/APIFloating-point → arbitrary-precision integer
      Go (*big.Float).Int(new(big.Int))truncates toward zero
      Java bigDecimal.toBigInteger()truncates toward zero
      JavaScript BigInt(flt)rejects non-integer
      .NET new BigInteger(flt)truncates toward zero
      Python int(flt)truncates toward zero
      Rust num_bigint from_f64(flt)truncates toward zero

      Presentation history

      Implementations

      Polyfill/transpiler implementations

      None yet.

      Native implementations

      Check here after Stage 2.7.

      Frequently asked questions

      Q: Should dynamic parsing also support _ separators?

      A: Not through BigInt(string), but maybe through a different API.

      Q: Should dynamic parsing be configurable?

      A: Not without doing the same for numbers, which seems like a separate proposal.

      Q: Are decimals allowed as in e.g. BigInt("86.4e12") === 86_400_000_000_000n?

      A: Yes, and this is important for precision-preserving canonical forms (e.g., differentiating 1.000e3n from 1e3n).

      Q: #8 Are negative exponents allowed as in e.g. 1230e-1n === 123n?

      A: To be determined. Restricting support to non-negative exponents would not be difficult.

      Q: #9 Is it web-compatible to change the behavior of 1_000_000n == "1e6" and 1_000_000n <= "1e6" and 1_000_000n >= "1e6"?

      A: To be determined, but if not then it is still possible to carve out exceptions while still supporting the primary use cases.

      Footnotes

      1. This might be unprecedented in widespread programming languages (cf. https://github.com/tc39/ecma262/pull/3857#issuecomment-4960986324). ↩