tc39 / tc39/proposal-amount

fractionDigits and significantDigits

Open
#54 16 comments 0 reactions 1 assignee View on GitHub

@jessealama is already working on this.

Since Sep 22, 2025.

  • #63 by @jessealama — merged
Dominant language
HTML
Stars
58
Forks
12
Avg merge
2h 35m
Merged PRs (30d)
2

Description

Current Behavior

The current design is incoherent in its interpretation and usage of fractionDigits and significantDigits, especially in the places where it computes those from provided values. Some examples:

Input value computed fractionDigits computed significantDigits Output value
120 0 3 "120"
"1.20e2" 2 3 "120.00"
"1.410e15" 3 4 "1410000000000000.000"
"0.05" 2 3 "0.05"
".05" 2 2 "0.05"
"5e-2" 0 1 "0"
0 0 1 "0"
"000.00" 2 5 "0.00"
"0.00" 2 3 "0.00"
".00" 2 2 "0.00"
"00e-2" 0 2 "0"

The computed significantDigits is never used in the spec and has no effect on the output. The computed fractionDigits specifies the number of digits to output after the decimal point, which sometimes results in incorrect output, as seen in the table above.

Corrected Behavior

I propose that we adopt the mathematical definition of fractionDigits to be the power of 10 of the least significant precise digit of the value. This works for both zero and nonzero values:

Input value mathematical fractionDigits
0 0
"0.0000" 4
".0000" 4
"0e-3" 3
"1245.000" 3
120 0
"120.0" 1
"00120" 0
"0.05" 2
".05" 2
"5e-2" 2
"5.0e-2" 3
"1.23e3" -1
"1.410e15" -12

Negative fractionDigits are required if we want to faithfully store the precision of numbers in exponential notation. Thus, if we include exponential notation as part of the resolution of issue #52, then we must allow and process negative fractionDigits.

significantDigits

Since it's never used, I propose that significantDigits not be computed.

On the other hand, the explainer provides a method to read significantDigits of Amounts. That method is not in the spec, and I assume the spec is correct here. If we wish to introduce such a method, we should define significantDigits in terms of fractionDigits as follows:

If $value$ is finite and nonzero, let $e$ be the unique integer for which $10^{e}\le\lvert value\rvert\lt 10^{e+1}$. Then let $significantDigits = e + fractionDigits + 1$. This results in the following for the above examples:

Input value computed fractionDigits computed significantDigits
0 0 degenerate
"0.0000" 4 degenerate
".0000" 4 degenerate
"0e-3" 3 degenerate
"1245.000" 3 7
120 0 3
"120.0" 1 4
"00120" 0 3
"0.05" 2 1
".05" 2 1
"5e-2" 2 1
"5.0e-2" 3 2
"1.23e3" -1 3
"1.410e15" -12 4

Unfortunately significantDigits becomes degenerate if $value$ is zero. For this reason my preference is to not compute it and not provide an accessor to read it. If provided as an option, we should ignore it if the input is zero.

Infinities and NaN

fractionDigits and significantDigits have no effect on infinities and NaN, so we should ignore them if provided as options on input.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.