Skip to content

docs: add aytechnet/decimal to the alternative libraries - #481

Open
aytechnet wants to merge 1 commit into
shopspring:masterfrom
aytechnet:docs/aytechnet-decimal
Open

aytechnet wants to merge 1 commit into
shopspring:masterfrom
aytechnet:docs/aytechnet-decimal

Conversation

@aytechnet

Copy link
Copy Markdown

Adds aytechnet/decimal to the alternative libraries in the README.

It targets the same trade-off as govalues/decimal and udecimal: fixed, low precision for speed. Its specifics:

  • The value is a single int64, 8 bytes and immutable, and every arithmetic operation is allocation-free. Each value has a unique representation, so == and map keys work: 1.50 == 1.5.
  • The precision is about 17 significant digits, with at most 16 fractional digits. The type also has NaN, ±Inf and a loss flag set when rounding happened.
  • The API mirrors this library, math/big methods aside. Rounding (Round, StringFixed, DivRound, RoundCash, RoundBank, Truncate…) and float conversion (NewFromFloat, NewFromFloatWithExponent) are checked value by value against shopspring v1.4.0 and v1.6.0 in its test suite (bench/compare_round_test.go).
  • Known differences are documented: Ln, Sqrt and Root return no error, and JSON is unquoted by default.

Benchmarks against v1.6.0 are in its README: 4× to 19× on fractional arithmetic and 11× to 26× on integers. The README also notes that this release narrowed the gap a lot compared with v1.4.0.

Thanks for maintaining the reference library and for keeping this list.

@mwoss

mwoss commented Nov 1, 2026

Copy link
Copy Markdown
Member

Hi @aytechnet! Could you let me know what the difference is between this library and the other listed alternatives? I don't want this list become just an advertisement list, but options of other libraries ppl may use and contribute to.

@aytechnet

aytechnet commented Nov 2, 2026 •

Copy link
Copy Markdown
Author

Hi @mwoss,

What it adds is mainly the shape of the type :

  • it is a plain int64 so only 8 bytes instead of at least 16 bytes, with no pointer (no other decimal library support this). That matters if you take care of memory.
  • it is compatible with a large range of integer constant as well (values between -144115188075855871 and 144115188075855871 can safely be used as Decimal)
  • each value has a unique representation accross its whole range : so == and map keys work (it is false with govalues and udecimal)
  • special values instead of errors as NaN and ±Infinite are supported, so calls chain in one expression, these specials values propagates as well correctly (only apd support it)
  • a loss bit is used so it is possible to track rounding errors (only apd support loss information but only this library has the information inside the value)
  • support both quoted and unquoted values in JSON
  • support omitempty json tag nicely as 0 int64 value is unitialized (but 0 value) decimal
  • finally this library mirrors shopspring (except Sqrt (added before) and Ln to allow chaining computation)

But using this library (and its int64 internal representation) have real trade-offs :

  • only about 17 significant digits, beyond that values are rounded with loss bit set instead of an error.
  • operators + and * compile on int64 type and give garbage for non-integerer values (is is mandatory to use Add and Mul).
  • No math/big methods.
  • JSON is unquoted by default.

It's a young public project with one maintainer and few users so far, even if I started it 3 years ago to avoid memory allocation for decimal value but keeping compatibility with shopspring/decimal as well. I use it with invoicing and e-commerce software I run in production. Issues and PRs are welcome.

So the use case is: you want to stay close to this library's API, and your values fit in 17 digits and memory usage is important.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants