FastDecimal

Fast arbitrary-precision decimal arithmetic for Elixir.

A pure-Elixir alternative to decimal — designed for the hot paths fintech, ledger, and pricing code live in: add, sub, mult, div, sum, parse, format. Drop-in via a compat shim, ships with Ecto integration. No native dependencies.

import FastDecimal

~d"1.23"
|> FastDecimal.add(~d"4.567")
|> FastDecimal.mult(~d"2")
|> FastDecimal.to_string()
# => "11.594"

FastDecimal.sum([~d"1.5", ~d"2.5", ~d"3"])
# => ~d"7.0"

FastDecimal.round(~d"1.236", 2)         # ~d"1.24"
FastDecimal.sqrt(~d"2", precision: 10)   # ~d"1.414213562"
FastDecimal.div(~d"10", ~d"3", precision: 5)  # ~d"3.3333"

Benchmarks

mix bench reproduces the headline summary in about a minute.

Methodology

Every number below is the median across 7 independent samples × 200,000 iterations per scenario. Each sample runs in a fresh process (resetting BEAM state), with 1,000 warmup iterations and a forced GC before measurement. Times use :erlang.monotonic_time(:nanosecond).

We report median (p25–p75 IQR) — the interquartile range survives outliers from GC pauses and scheduler steals. A row is marked stable when even the pessimistic ratio (FastDecimal's p75 vs Decimal's p25) clears 2×.

The geometric mean speedup is reproducible across runs (observed: 11.11× – 11.28× across 4 consecutive runs on the same JIT-enabled OTP install). Specific per-op nanosecond values shift 5-10% per run due to macOS scheduler noise (E-core vs P-core dispatch, GC interactions); the speedup ratios are stable. Numbers below are from one representative run — run mix bench to see your own.

Headline summary (mix bench)

Tested on macOS arm64 / 10 cores against two flavors of OTP 26 on the same hardware:

JIT helps FastDecimal proportionally more than decimal (FastDecimal's hot paths have more inlining opportunities per work-unit), so the speedup ratio is larger on JIT — but even on the older interpreter without JIT, FastDecimal is still ~8× faster on average.

Detailed table (BEAMAsm JIT, OTP 26)

Format: median (p25–p75 IQR). Speedup column: median (pessimistic – optimistic ratios).

At-parity ops (called out honestly):

• to_string :normal, to_string :scientific, to_integer: 1.0× – 1.2× faster but not stable at the pessimistic IQR edge ≥2× — marked marginal in the bench output. decimal's formatters are exceptionally tight; we win, just less decisively.

Realistic workloads (mix run bench/realistic.exs)

Production-style code patterns. Speedups vary 10-25% across runs (the workload code allocates more, so GC interactions vary), but every workload comes in 10×+ faster than decimal:

Allocations + reductions (mix run bench/profile.exs)

4 reductions per add is at the BEAM floor — no operation on a struct can do less.

Reproduce

The whole suite is in bench/ and runs from mix. No Docker, no setup beyond mix deps.get. See the Benchmark suite page for methodology and per-file detail.

mix deps.get
mix test                  # 15 doctests + 37 properties + 313 unit tests = 365 total
mix bench                 # → bench/summary.exs (headline table, ~1 minute)
mix bench.all             # → every bench file end-to-end (~20 minutes)

# Or run a specific bench:
mix run bench/division.exs        # div / div_int / div_rem / rem
mix run bench/rounding.exs        # round/3 × 7 modes
mix run bench/sqrt.exs            # sqrt at 6 precisions
mix run bench/conversion.exs      # to_string formats, cast, to_int/float
mix run bench/special_values.exs  # NaN/Inf overhead
mix run bench/realistic.exs       # fintech-style workloads
mix run bench/batch.exs           # sum/product at 4 list sizes
mix run bench/profile.exs         # per-op time + alloc + reductions
mix run bench/parse.exs           # parser strategy shootout
mix run bench/representation.exs  # struct vs raw tuple
mix run bench/targeted.exs        # parse / compare-large-gap / normalize-multi-zero / to_integer
mix run bench/disasm.exs          # BEAM bytecode dump

See bench/README.md for what each script measures and the design decision it backed.

Test coverage

The suite is the regression gate for future optimization work and the correctness floor for trusting outputs:

• 15 doctests in module + function docs
• 37 property-based tests (test/fastdecimal/property_test.exs) covering invariants: round-trip, commutativity, associativity, div_rem identity, sqrt(x)² ≈ x, comparison antisymmetry/transitivity/reflexivity (including a wide-exp generator that exercises the hybrid-compare prefilter), NaN propagation, normalize idempotence
• 313 unit tests across:
  • test/fastdecimal_test.exs — core arithmetic + struct API
  • test/fastdecimal/extended_test.exs — NaN/Inf/round/cast/sqrt/div_int/formats/is_decimal
  • test/fastdecimal/parser_test.exs — parser edge cases
  • test/fastdecimal/edge_cases_test.exs — zero handling, bignum boundary, exponent alignment, rounding corners
  • test/fastdecimal/compat_test.exs — drop-in shim
  • test/fastdecimal/ecto_type_test.exs — Ecto round-trip
  • test/fastdecimal/correctness_test.exs — two kinds of correctness verification:
    1. Mathematical-truth tests — known exact results pinned per operation (1.23 + 4.567 == 5.797, 0.1 + 0.2 == 0.3 exactly, sqrt(4) == 2, banker's rounding tables, etc.). These verify FastDecimal is computing arithmetic correctly without relying on Decimal as the source of truth.
    2. Differential tests vs decimal — for each operation, a matrix of diverse inputs runs through both libraries and the outputs are compared for semantic equality. The 74 tests in this file perform >10,000 individual cross-checks between the two libraries (e.g., add runs 36×36 = 1296 input pairs through both libs). Catches any drift in semantics.

Run with mix test. Full suite finishes in under a second.

Total: 365 tests/properties/doctests — stable across consecutive runs. Includes 23 dedicated security regression tests covering CVE-2026-32686-class exponent-amplification DoS protection.

Security

FastDecimal is not vulnerable to CVE-2026-32686 (exponent-amplification DoS that affected ericmj/decimal < 2.4.0). Three layers of defense:

1. Parser rejects scientific-notation inputs with explicit exponent magnitude > 65,535. FastDecimal.parse("1e1000000000") returns :error rather than producing a value whose materialization would OOM the BEAM.
2. pow10/1 internal cap raises on n > 100,000. Catches operations that would materialize huge values even when the value was constructed directly via new(coef, exp) bypassing the parser.
3. to_string(_, :normal) refuses to produce output larger than 1 MB. The :scientific and :raw formats remain available for legitimate large-exponent values (they don't materialize the zeros).

These bounds are well above any practical use case (IEEE 754 decimal128 itself tops out at exp ±6,144) but kill the runaway path. Regression tests live at test/fastdecimal/security_test.exs.

Where the two libraries legitimately diverge

FastDecimal does exact arithmetic; decimal rounds to its Context.precision (28 by default). For inputs whose true result has >28 significant digits, the two libraries produce different values — that's a documented design difference, not a bug. The differential tests constrain inputs so the result stays within 28 sig figs (where the libs should agree); the property tests document the divergence explicitly.

Installation

def deps do
  [
    {:fastdecimal, "~> 1.0"}
  ]
end

Feature surface

Construction

import FastDecimal

~d"1.23"                          # Compile-time literal (zero parse cost at runtime)
~d"1.23e10"                       # Scientific notation
~d"Infinity"                      # +∞
~d"-Inf"                          # -∞
~d"NaN"                           # NaN

FastDecimal.new("1.23")           # Runtime parse, raises on bad input
FastDecimal.new(42)               # From integer
FastDecimal.new(123, -2)          # From coef + exp
FastDecimal.parse("1.23")         # {:ok, t} | :error  — no raise
FastDecimal.cast(value)           # Soft parse, accepts FastDecimal/Decimal/int/string/float/nil

Arithmetic

FastDecimal.add(a, b)
FastDecimal.sub(a, b)
FastDecimal.mult(a, b)
FastDecimal.div(a, b, precision: 28, rounding: :half_even)
FastDecimal.div_int(a, b)         # Truncated integer division
FastDecimal.div_rem(a, b)         # {quotient, remainder}
FastDecimal.rem(a, b)
FastDecimal.negate(a)
FastDecimal.abs(a)
FastDecimal.sqrt(a, precision: 28)  # Newton-Raphson
FastDecimal.round(a, places, mode)   # All 7 rounding modes

Batch

FastDecimal.sum(list)             # Tight Elixir-side reduce
FastDecimal.product(list)

Comparison & predicates

FastDecimal.compare(a, b)         # :lt | :eq | :gt | :nan
FastDecimal.equal?(a, b)
FastDecimal.lt?(a, b) ; FastDecimal.gt?(a, b)
FastDecimal.min(a, b) ; FastDecimal.max(a, b)

FastDecimal.zero?(d) ; FastDecimal.positive?(d) ; FastDecimal.negative?(d)
FastDecimal.nan?(d)  ; FastDecimal.inf?(d)     ; FastDecimal.finite?(d)

Conversion

FastDecimal.to_string(d)              # "1.23"
FastDecimal.to_string(d, :scientific) # "1.23" — IEEE compact (only emits E for very small/large)
FastDecimal.to_string(d, :raw)        # "123E-2"
FastDecimal.to_string(d, :xsd)        # XSD canonical (= :normal for our repr)

FastDecimal.to_integer(d)             # raises on fractional
FastDecimal.to_float(d)               # lossy for non-terminating binaries
FastDecimal.normalize(d)              # strips trailing zeros

Guard-safe macro

require FastDecimal

def process(d) when FastDecimal.is_decimal(d), do: ...

Migrating from decimal

The 30-second version, for the common case:

defmodule MyLedger do
  alias FastDecimal.Compat, as: Decimal   # add this line, rest stays the same

  def total(items) do
    Enum.reduce(items, Decimal.new(0), fn item, acc ->
      Decimal.add(acc, item.amount)
    end)
  end
end

The Compat shim mirrors decimal's public surface and auto-coerces inputs (real %Decimal{}, %FastDecimal{}, strings, integers, floats). It costs 5-15% vs calling FastDecimal.* directly.

Five things that don't translate cleanly and how to handle each:

• %Decimal{...} struct literals — module-bound, need rewriting
• Decimal.Context.set/with/get — no equivalent (this is the real blocker for some codebases)
• :sNaN / :qNaN distinction — collapsed to :nan
• -0 vs 0 — collapsed
• Signal flags / traps — not supported

See MIGRATION.md for the full guide — decision tree, mechanical steps, real before/after examples, and an FAQ. Most projects migrate in under an hour; some need a wrapper module around precision-policy code; a few should stay on decimal.

Differences from decimal (summary)

Ecto integration

defmodule MyApp.Invoice do
  use Ecto.Schema

  schema "invoices" do
    field :total, FastDecimal.Ecto.Type
  end
end

FastDecimal.Ecto.Type is automatically compiled when Ecto is in your deps. It bridges between Decimal (what the database adapter speaks) and FastDecimal (what your code holds). cast/1, load/1, dump/1, equal?/2 are all implemented.

Design philosophy

Every operation's implementation was chosen by running a benchmark, not by guessing. The full decision record — with the measurements behind each call — lives in bench/README.md. A few highlights:

• The char-by-char walker parser beat :binary.split + :erlang.binary_to_integer by 1.4–3× on every input shorter than ~25 digits (bench/parse.exs).
• The iolist to_string beat the bit-syntax binary builder by 20%, because iodata_to_binary is implemented as an Erlang BIF that pre-computes total size.
• pow10 lookup table extended to 38 entries + binary exponentiation for larger n. Speeds up div at precision 28 by ~40% (medium values) and ~36% (large values) — the prior recursive pow10(28) path was the bottleneck.
• div_rem rewritten to compute quotient + remainder directly from aligned coefficients in one pass, instead of the previous "div_int, then mult, then sub" cascade. From 2.7× → 6.2× speedup.
• to_string :scientific switched to IEEE 754-2008 "to-scientific-string" (compact form, matches decimal's output). Was a correctness gap, not just a perf one — turns out decimal's :scientific doesn't always emit E notation; it uses normal form when adjusted_exp >= -6. Fixed alignment is now parity with decimal.
• sum/1 and product/1 rewritten as allocation-free accumulators. The old version did pairwise add/mult, producing one throwaway %FastDecimal{} struct per element. The new version carries raw {coef, exp} and only builds the final struct at the end — N−1 fewer allocations. sum of 100 went from 29× → 56× faster than decimal. (Special values trip the is_integer guard and fall through to a pairwise slow path.)
• binary_part instead of bit-syntax pattern match in to_string :normal. The <<int_part::binary-size(N), frac_part::binary>> form creates two sub-binary refs; binary_part/3 is a BIF that's about 5% faster. Tipped us from parity to 1.05× on to_string.
• equal? / lt? / gt? short-circuit clauses for identical struct shapes (same coef, same exp). Common when comparing a stored value to a fresh literal — returns the answer in a single pattern match instead of going through compare/2.
• A Rust NIF prototype for arithmetic ops lost to pure Elixir on every hot path: NIF dispatch overhead (~36 ns) exceeded the per-op cost of pure-Elixir add (~12 ns). It only won at div with high precision (~2.5×) and parse of long strings (~1.5×). Not enough to justify a native dependency and the install friction it adds. The prototype was deleted before v1.0 — the lesson lives in this README.
• The %FastDecimal{} struct wrapper is only ~5–9% slower than raw {coef, exp} tuples — cheap enough to pay for ergonomics (bench/representation.exs).
• Explicit when c in -2^60..2^60 guards on hot paths add overhead with zero benefit (BEAM's JIT already specializes for immediate-int operands).
• %{a | coef: ...} (Elixir's strict update form) produced cleaner BEAM bytecode (put_map_exact instead of put_map_assoc) but wall-time was identical or 1% slower — kept the literal-struct form for readability (bench/disasm.exs).

The rule: if you have a hypothesis about a faster way, write the bench, run it, commit the script. Negative results stay in the tree so we don't re-test the same idea.

Why pure Elixir (the bench data)

NIF dispatch overhead is ~36 ns on this machine. A pure-Elixir add total is ~12 ns. The dispatch cost alone is 3× the work-cost for every cheap op. The Rust NIF prototype we built and benchmarked confirmed this — it lost on every per-op arithmetic and only won at high-precision div and long-string parse. Not enough to justify shipping a binary dependency that requires Rust on every consumer's machine. FastDecimal is pure Elixir; no native compilation step.

License

MIT. See LICENSE.