Sharpen README pitch and motivation#205
Merged
Merged
Conversation
Now that Amount has reached stage 2, we can more confidently align (and distinguish) the two proposals.
The parts of the data exchange story that are still valid can be discussed as part of the main use case.
gameroman
reviewed
Jun 30, 2026
| <!-- prettier-ignore-end --> | ||
|
|
||
| `Decimal` values are canonicalized, meaning that different representations of the same mathematical value are normalized. For example, "1.20" and "1.2" both result in the same `Decimal` value. | ||
| `Decimal` never exposes trailing zeroes: different representations of the same mathematical value are indistinguishable. For example, "1.20" and "1.2" compare as equal and render identically with `toString`. (An implementation may store values unnormalized internally and normalize only on the way out, when rendering or comparing.) |
Contributor
There was a problem hiding this comment.
Suggested change
| `Decimal` never exposes trailing zeroes: different representations of the same mathematical value are indistinguishable. For example, "1.20" and "1.2" compare as equal and render identically with `toString`. (An implementation may store values unnormalized internally and normalize only on the way out, when rendering or comparing.) | |
| `Decimal` never exposes trailing zeroes: different representations of the same mathematical value are indistinguishable. For example, "1.20" and "1.2" compare as equal and render identically with `toString`. An implementation may store values unnormalized internally and normalize only on the way out, when rendering or comparing. |
| Decimal is based on IEEE 754-2019 Decimal128, which is a standard for base-10 decimal numbers using 128 bits. We will offer a subset of the official Decimal128. There will be, in particular: | ||
| As noted [above](#specification-and-standards), Decimal uses the IEEE 754-2019 Decimal128 data model. We will offer a subset of the official Decimal128. There will be, in particular: | ||
|
|
||
| - a single NaN value--distinct from the built-in `NaN` of JS. The difference between quiet and singaling NaNs will be collapsed into a single (quiet) Decimal NaN. |
Contributor
There was a problem hiding this comment.
Suggested change
| - a single NaN value--distinct from the built-in `NaN` of JS. The difference between quiet and singaling NaNs will be collapsed into a single (quiet) Decimal NaN. | |
| - a single NaN value--distinct from the built-in `NaN` of JS. The difference between quiet and signaling NaNs will be collapsed into a single (quiet) Decimal NaN. |
Contributor
|
oops I'm late. sorry |
Collaborator
Author
These are nice changes, thank you! I'm happy to incorporate them. Anything that helps improve clarity is welcome. |
jessealama
added a commit
that referenced
this pull request
Jun 30, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Rework the opening paragraphs in the README to motivate Decimal from two angles: (1) the practical case (real, end-user-visible rounding bugs from using binary floating-point Numbers for decimal calculations), and (2) the foundational one (a numeric type that matches the arithmetic we were taught, where 0.1 + 0.2 is 0.3).
Focus on exact arithmetic, clarify the relationship between the Decimal and Amount proposals, explain "normalization on the way out".
Merge the standalone RELATED.md into the README so related proposals live in one place.