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/stage/1/proposal-bigint-from-exponential.md.
TC39 Atlas
  • English

      • Bigint from exponential S1

      Proposal details
      Proposal overview

      This proposal addresses the inconvenience of creating bigints from exponential notation strings, which currently requires manual parsing. It suggests syntactic support like 1e6n for static cases, and expanding BigInt() or adding APIs like BigInt.parse() for dynamic cases. It includes comparisons with other languages and prior art in npm packages.

      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

      Champion(s): Richard Gibson (@gibson042)

      Stage: 1

      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. 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 elsewhere (e.g., parsing JSON like { "scale": 1e6 } with source text access, or when working with currencies, dates, or times).

      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

      Support for static use cases might be provided syntactically, e.g. 1e6n. If so, this might be unprecedented in widespread programming languages (cf. https://github.com/tc39/ecma262/pull/3857#issuecomment-4960986324).

      Support for dynamic use cases could be provided by expanding the behavior of BigInt("1e6") as suggested by https://github.com/tc39/ecma262/pull/3857, or alternatively by something like BigInt.parse("1e6") or BigInt.fromString("1e6"). Note that the former likely implies corresponding changes to 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").

      Dynamic use cases 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: Also to be determined.