zerodecimal

package module
v0.0.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 13, 2026 License: MIT Imports: 11 Imported by: 0

README

zerodecimal

Zero-allocation, panic-free, fixed-point decimals for latency-critical Go.

Why another decimal library

  • Strictly zero heap allocations. Parsing, arithmetic, comparison, rounding, conversions, and every Unmarshal/Scan path perform exactly zero heap allocations — success and error paths alike — enforced by testing.AllocsPerRun gates in the default test suite (alloc_test.go).
  • Faster than every Go decimal library we could find. The committed benchstat comparisons show a −35% time geomean against quagmt/udecimal (the previous fastest) and −90% against shopspring/decimal (benchmarks/bench-vs-*.txt).
  • Bit-exact. Every operation is differentially checked against shopspring/decimal's unbounded arithmetic — including an iff proof for every returned overflow — deterministically in the default suite (crosscheck_test.go) and by 23 fuzz targets (fuzz_test.go).
  • Panic-free. Fallible operations return zero-allocation sentinel errors (errors.go) and the fuzz suite requires every target to be total — no input, including garbage binary payloads, may panic the library.

Install

go get github.com/AlexandrosKyriakakis/zerodecimal

import "github.com/AlexandrosKyriakakis/zerodecimal" // package zerodecimal

Requires Go 1.26+. The library has zero runtime dependencies.

price, err := zerodecimal.NewFromString("99.99")
if err != nil {
    return err
}
qty := zerodecimal.NewFromInt(3)

total, err := price.Mul(qty)
if err != nil {
    return err
}
fmt.Println(total)                // 299.97
fmt.Println(total.StringFixed(4)) // 299.9700

Runnable examples for parsing, arithmetic, rounding, JSON, and SQL live in example_test.go.

Design

type Decimal struct {
    coef u128  // |value| · 10^prec, 0 ≤ coef < 2^128
    neg  bool
    prec uint8 // fractional digits, 0..19
}

A Decimal is a 24-byte pointer-free value: copy it freely, compare it cheaply, pack it densely. The domain is |value| < 2^128 / 10^prec — up to 39 significant digits with up to 19 fractional. There is no big.Int anywhere in the package: every operation runs on fixed-width 128/256-bit integer math, so nothing can escape to the heap and out-of-domain results return ErrOverflow instead of degrading into arbitrary-precision slowness. The zero value is the canonical decimal zero, ready to use; no operation produces a negative zero.

Reciprocal division is the headline optimization. Decimal rescaling, rounding, formatting, and division all reduce to dividing by powers of ten, and zerodecimal never asks the hardware divider to do it: 64-bit dividends use precomputed Granlund–Montgomery–Warren multiply-high magics, and 128/256-bit dividends chain Möller–Granlund 2-by-1 steps off a precomputed reciprocal table (div10.go, tables generated and re-proven against bits.Div64 and big.Int in tables_test.go). A multiply-high plus a shift replaces an 18-cycle DIV — and for 128-bit dividends, two dependent DIVs — which is where most of the headroom over udecimal comes from.

Div uses adaptive precision: the result is the exact quotient truncated at the largest precision ≤ DefaultPrec (19 by default) whose coefficient still fits 128 bits, so huge quotients degrade precision gracefully and ErrOverflow is reserved for integer quotients that genuinely exceed 2^128.

Because == compares representations, an arithmetic result of 1.50 differs from a parsed 1.5 under ==; use Equal or Cmp for numeric comparison. Parsing trims trailing fractional zeros; arithmetic never does (it would tax the hot path); formatting trims at output.

Error model

All sentinels live in errors.go, are returned bare (never wrapped, except Scan's unsupported-type message), and match with errors.Is. The constructors and arithmetic operations have panicking twins for call sites with proven bounds; rows marked — below have none.

Operation Possible sentinels Panicking twin
New ErrOverflow, ErrPrecOutOfRange MustNew
NewFromString, ParseBytes ErrEmptyString, ErrMaxStrLen, ErrInvalidFormat, ErrOverflow, ErrPrecOutOfRange RequireFromString
NewFromStringTrunc, ParseBytesTrunc ErrEmptyString, ErrMaxStrLen, ErrInvalidFormat, ErrOverflow —
NewFromFloat, NewFromFloat32 ErrInvalidFloat, ErrOverflow, ErrPrecOutOfRange RequireFromFloat
NewFromHiLo ErrPrecOutOfRange —
Add, Sub, Mul ErrOverflow MustAdd, MustSub, MustMul
Div ErrDivideByZero, ErrOverflow MustDiv
QuoRem, Mod ErrDivideByZero, ErrOverflow MustQuoRem, MustMod
Sum, Avg ErrOverflow MustSum, MustAvg
IntPart ErrIntPartOverflow —
UnmarshalText, UnmarshalJSON the parse sentinels —
UnmarshalBinary ErrInvalidBinaryData —
Scan the parse sentinels, ErrInvalidFloat, ErrScanNil, ErrScanType —

Everything else is infallible: NewFromInt/NewFromInt32/NewFromUint64, Neg, Abs, Sign, the Is* predicates, Cmp and the comparison family, Min/Max, the entire rounding family, Prec, ToHiLo, String, StringFixed, AppendFixed, and InexactFloat64. AppendText, AppendBinary, the Marshal* methods, and Value return an error only to satisfy their interfaces — it is always nil.

Allocation guarantees

Exactly what alloc_test.go enforces with testing.AllocsPerRun on every make test run, across six value shapes (small integers, typical prices, full 19-digit precision, extreme precision mismatch, near-2^128 coefficients, negatives), on success and error paths:

Allocations Operations Gate
exactly 0 NewFromString, ParseBytes, Add, Sub, Mul, Div, QuoRem, Mod, Cmp, Equal, Neg, Abs, Sign, Round, RoundBank, RoundUp, RoundDown, RoundCeil, RoundFloor, Truncate, Floor, Ceil, IntPart, InexactFloat64, NewFromFloat, AppendText, AppendFixed, AppendBinary, Min, Max, MustAdd, UnmarshalText, UnmarshalJSON, UnmarshalBinary, Scan (string and []byte) TestAllocsZero
exactly 1 String (outside the cache window), StringFixed — the returned string itself TestAllocsOne
exactly 1 MarshalText, MarshalJSON, MarshalBinary — the returned slice, sized exactly TestAllocsCodecMarshal
exactly 0 String and Value on values inside the small-value cache window (−1000.00..+1000.00, ≤ 2 places) TestAllocsStringCached, TestAllocsSQLValueCached
exactly 2 Value outside the cache window — the canonical string plus boxing it into driver.Value TestAllocsSQLValueUncached

The counts are asserted as exact, not upper bounds, so a regression in either direction fails the suite. Since the steady state allocates nothing, zerodecimal generates no GC pressure regardless of GOGC.

Parsing rules

Grammar: ['+'|'-'] digits ['.' digits] [('e'|'E') ['+'|'-'] digits], ASCII only, at most 200 bytes.

Accepted:

  • plain literals: "123", "-4.20", "+1", redundant zeros ("00012.3400" → 12.34)
  • scientific notation: "1.23e4" → 12300, "1E-7" → 0.0000001 (required for JSON float interop)
  • up to 39 significant digits: "340282366920938463463374607431768211455" (= 2^128−1) parses; one more unit is ErrOverflow

Rejected:

  • "" → ErrEmptyString; input over 200 bytes → ErrMaxStrLen
  • "1." and ".1" → ErrInvalidFormat: both sides of the dot need a digit (deliberately stricter than shopspring), as do ".", "-", "1..2", "1e", "1e+"
  • whitespace, underscores, non-ASCII digits, "NaN", "Inf" → ErrInvalidFormat
  • more than 19 fractional digits → ErrPrecOutOfRange (strict variants)

The Trunc variants (NewFromStringTrunc, ParseBytesTrunc) replace ErrPrecOutOfRange with truncation toward zero at 19 fractional digits (possibly to exactly zero) and accept any mantissa within the 200-byte input cap (ErrMaxStrLen still applies) whenever the truncated value is representable; grammar violations and genuinely unrepresentable values still error. Results are always canonical: trailing fractional zeros are trimmed ("1.500" parses identically to "1.5") and parsing never allocates — not even on failure.

Rounding modes

places counts fractional digits; places ≥ d.Prec() returns d unchanged. The whole family is infallible — the increment can never overflow — and rounding a negative value to zero yields the canonical unsigned zero.

Method Mode 2.5 → 3.5 → -2.5 →
Round(0) half away from zero (shopspring Round) 3 4 -3
RoundBank(0) half to even (banker's) 2 4 -2
RoundUp(0) away from zero 3 4 -3
RoundDown(0) / Truncate(0) toward zero 2 3 -2
RoundCeil(0) toward +∞ 3 4 -2
RoundFloor(0) toward −∞ 2 3 -3

Floor() and Ceil() are RoundFloor(0) and RoundCeil(0). Every mode is pinned tie-by-tie against its shopspring equivalent in crosscheck_test.go and fuzzed in fuzz_test.go.

Benchmarks

The comparative suite lives in benchmarks/ — a separate Go module, so the competitor dependencies never touch the library's go.mod. Full committed results: bench-vs-udecimal.txt, bench-vs-shopspring.txt, bench-vs-alpacadecimal.txt, bench-vs-ericlagergren.txt; methodology and the deliberate semantic asymmetries are documented in benchmarks/README.md.

Against quagmt/udecimal — the fastest existing Go decimal — zerodecimal is faster on 89 of the 90 op × shape rows and statistically tied on the remaining one (MarshalJSON/small_int):

goos: darwin
goarch: arm64
cpu: Apple M1 Pro
                          │   udecimal   │             zerodecimal             │
                          │    sec/op    │   sec/op     vs base                │
Add/typical_price-10         4.673n ± 0%   2.375n ± 0%  -49.18% (p=0.000 n=10)
Mul/typical_price-10         6.234n ± 0%   2.350n ± 0%  -62.29% (p=0.000 n=10)
Div/typical_price-10         12.93n ± 1%   11.70n ± 1%   -9.51% (p=0.000 n=10)
QuoRem/typical_price-10     13.455n ± 2%   3.155n ± 0%  -76.56% (p=0.000 n=10)
Cmp/typical_price-10         5.291n ± 0%   3.108n ± 2%  -41.26% (p=0.000 n=10)
Parse/typical_price-10       14.32n ± 0%   12.75n ± 0%  -10.96% (p=0.000 n=10)
String/typical_price-10      32.46n ± 1%   25.89n ± 1%  -20.24% (p=0.000 n=10)
geomean                      15.50n        10.07n       -35.03%

Against shopspring/decimal, the de-facto standard:

                          │  shopspring   │             zerodecimal             │
                          │    sec/op     │   sec/op     vs base                │
Add/typical_price-10        39.975n ± 2%   2.375n ± 0%  -94.06% (p=0.000 n=10)
Mul/typical_price-10        40.375n ± 1%   2.350n ± 0%  -94.18% (p=0.000 n=10)
Div/typical_price-10        210.35n ± 1%   11.70n ± 1%  -94.44% (p=0.000 n=10)
RoundBank/typical_price-10 353.250n ± 2%   4.677n ± 1%  -98.68% (p=0.000 n=10)
Parse/typical_price-10       75.92n ± 2%   12.75n ± 0%  -83.21% (p=0.000 n=10)
String/typical_price-10     106.50n ± 2%   25.89n ± 1%  -75.69% (p=0.000 n=10)
geomean                      93.42n        10.07n       -89.59%

Allocations are 0 on every row where any competitor manages 0, and 0 on many where they do not (e.g. udecimal's Mul/large allocates 160 B/op across 4 allocations; zerodecimal allocates nothing).

Known trade-offs

Allocation floors accepted by design (from benchmarks/README.md):

  • String: 1 alloc outside the cache window — a string-returning API must allocate its immutable result; the rendering itself is a stack buffer.
  • MarshalText/MarshalJSON/MarshalBinary: 1 alloc — callers own and may mutate marshal results, so sharing cached bytes is off the table; the slice is sized exactly.
  • Value: 2 allocs outside the cache window — the canonical string plus boxing into the driver.Value interface; there is no cheaper portable shape.

PGO

PGO attaches to binaries, not libraries — so zerodecimal cannot ship it, but your build can claim it. The hot paths are written PGO-friendly: no interfaces or indirect calls anywhere (devirtualization is never needed), and the slow arms (addSlow, mulSlow, the multi-limb division bodies) are deliberately outlined into small functions that profile-driven inlining can promote straight into your hot loops past the default inlining budget.

  1. Collect a CPU profile from production or a representative load: pprof.StartCPUProfile / curl .../debug/pprof/profile > default.pgo.
  2. Drop it at your main package root as default.pgo (picked up by go build automatically, i.e. -pgo=auto) or pass -pgo=/path/to.pprof.
  3. Rebuild and ship.

The committed benchmarks/bench-pgo.txt shows what the benchmark binary itself gains when rebuilt against its own profile (make bench-pgo): a −7.5% time geomean, with the arithmetic core improving the most because its outlined slow arms inline into the measured call sites. Three op families honestly regress where PGO's layout choices cost a little: every Cmp shape (+7% to +10%), the short Parse inputs (+2% to +5%), and NewFromFloat/typical_price (+2.5%) — the excerpt shows the worst such row:

                          │   default   │                 pgo                 │
                          │   sec/op    │   sec/op     vs base                │
Add/typical_price-10        2.375n ± 0%   2.022n ± 0%  -14.88% (p=0.000 n=10)
Sub/typical_price-10        3.743n ± 0%   3.119n ± 1%  -16.68% (p=0.000 n=10)
Mul/large-10                4.429n ± 1%   3.520n ± 0%  -20.52% (p=0.000 n=10)
Div/typical_price-10        11.70n ± 1%   10.24n ± 0%  -12.48% (p=0.000 n=10)
QuoRem/typical_price-10     3.155n ± 0%   2.651n ± 1%  -15.95% (p=0.000 n=10)
RoundBank/typical_price-10  4.677n ± 1%   3.730n ± 1%  -20.26% (p=0.000 n=10)
Cmp/typical_price-10        3.108n ± 2%   3.417n ± 0%   +9.96% (p=0.000 n=10)
geomean                     10.07n        9.313n        -7.50%

On amd64 deployments also consider GOAMD64=v3: the BMI2/ADX instructions materially speed the bits.Mul64/bits.Add64 carry chains that dominate the primitives (arm64 needs no flag).

Build tags

Tag Effect
zerodecimal_prec9 lowers the compile-time DefaultPrec to 9 fractional digits (nanos), trading fractional resolution for integer range in division results
zerodecimal_prec12 lowers DefaultPrec to 12, matching alpacadecimal's fixed scale
zerodecimal_nostrcache compiles out the ~8 MB small-value string/driver.Value cache (−1000.00..+1000.00) built at init

DefaultPrec is a compile-time constant by design — never a mutable global — so precision checks fold into immediate compares.

The full test suites assume DefaultPrec = 19. Compile + go vet is the supported verification level for the zerodecimal_prec9 and zerodecimal_prec12 configurations in v1.

How correctness is enforced

  • Deterministic cross-check in the default suite (crosscheck_test.go): every arithmetic, comparison, rounding, parsing, and formatting result is checked against shopspring/decimal's unbounded big.Int arithmetic over an exhaustive boundary-value pair sweep plus 30,000 fixed-seed boundary-biased random pairs. The overflow oracle is iff: every ErrOverflow must be proven exact (the true coefficient really is ≥ 2^128) and every fitting result must be returned — a spurious error fails as loudly as a wrong value.
  • 23 differential fuzz targets (fuzz_test.go, make fuzz-all): parse round trips and raw-string parsing, Add/Sub/Mul/Div/ QuoRem/Mod/Cmp with the same iff overflow proofs, all seven rounding modes pinned to their shopspring equivalents, StringFixed, JSON/binary/SQL round trips, garbage binary input (which must never panic), float conversion, and a structural-invariant target. quagmt/udecimal serves as a second, bit-compatible oracle for Add/Sub/Mul.
  • 6.5+ million fixed-seed primitive cases: the u128/u256 primitives and every reciprocal-division path are verified against bits.Div64 and big.Int at carry, limb, power-of-ten, and exact-overflow boundaries plus millions of shaped random cases per run (u128_test.go, u256_test.go, div10_test.go — the loop counts sum past 6.5 million), and the generated magic-constant tables are recomputed from their definitions in tables_test.go.
  • Codegen gates: the inlining shape of the hot paths (what must inline, what must stay outlined, cost ceilings against compiler drift) is asserted from the compiler's own -m=2 report in the default suite.

Limitations vs shopspring/decimal

  • Bounded domain. |value| < 2^128 / 10^prec — at most 39 significant digits and 19 fractional digits. There is no arbitrary-precision fallback; out-of-domain results return ErrOverflow. shopspring is unbounded.
  • places is uint8. Negative places (rounding at tens/hundreds positions, shopspring's Round(-2)) are unsupported by design — this is what keeps the entire rounding family infallible.
  • Division precision is compile-time. Div truncates at adaptive precision up to DefaultPrec (19, or 9/12 via build tags); there is no runtime DivisionPrecision knob and no DivRound.
  • No Pow, Sqrt, or transcendental functions yet.
  • Stricter parsing. "1." and ".1" are rejected; shopspring accepts both.
  • No exotic float forms. NewFromFloat rejects NaN/±Inf with ErrInvalidFloat rather than panicking, and converts via the shortest decimal representation (like shopspring) — floats outside the domain error instead of rounding silently.

License

MIT

Documentation

Overview

Package zerodecimal provides a fixed-point decimal type for latency-critical financial code: zero heap allocations on every hot path, panic-free sentinel errors, and arithmetic that is bit-exact against arbitrary-precision references.

Representation

A Decimal is a 24-byte value: value = (neg ? -1 : +1) * coef / 10^prec, where coef is an unsigned 128-bit integer and prec is 0..19. There is no big.Int fallback anywhere: every operation runs on fixed-width integer math, so nothing escapes to the heap. The representable domain is |value| < 2^128 / 10^prec (up to 39 significant digits); operations whose exact result leaves the domain return ErrOverflow instead of degrading.

Error model

Operations that can fail return (Decimal, error) with package-level sentinel errors and never panic. The constructors and the arithmetic operations have panicking twins (MustNew, RequireFromString, MustAdd, ...) for constants, tests, and call sites with proven bounds; the Trunc parsers, NewFromHiLo, IntPart, the Unmarshal methods, and Scan have none. Operations that cannot fail (Neg, Abs, rounding, comparisons, formatting) return Decimal directly and chain freely.

Allocations

Parsing, arithmetic, comparison, rounding, conversions, the Append* methods, and every Unmarshal and Scan path allocate nothing — on success and error paths alike. String and StringFixed cost exactly one allocation (the returned string; values within ±1000.00 at up to two decimal places are served from a precomputed cache for zero), the Marshal* methods exactly one (the returned slice), and SQL Value at most two. The default test suite enforces these counts exactly with testing.AllocsPerRun.

Equality

Arithmetic does not trim trailing fractional zeros, so == on Decimal values is representation equality, not numeric equality: a result equal to 1.50 differs from a parsed 1.5 under ==. Use Equal or Cmp for numeric comparison. Parsing and string constructors trim trailing fractional zeros; NewFromHiLo keeps the supplied precision verbatim for raw interop. Zero is always the zero value Decimal{} — no operation produces a negative zero.

Build tags

DefaultPrec — the precision Div targets and strict parsing accepts — is a compile-time constant: 19 by default, lowered to 9 or 12 with the zerodecimal_prec9 or zerodecimal_prec12 build tags. The full test suites assume DefaultPrec = 19; the zerodecimal_prec9 and zerodecimal_prec12 configurations are verified at compile + vet level only in v1. The zerodecimal_nostrcache tag compiles out the small-value string cache that String and Value consult.

Example 
package main

import (
	"fmt"

	zerodecimal "github.com/AlexandrosKyriakakis/zerodecimal"
)

func main() {
	price, err := zerodecimal.NewFromString("99.99")
	if err != nil {
		panic(err)
	}
	qty := zerodecimal.NewFromInt(3)

	total, err := price.Mul(qty)
	if err != nil {
		panic(err)
	}
	fmt.Println(total)
	fmt.Println(total.StringFixed(4))
}

Output:
299.97
299.9700

Index

Examples

Constants

View Source 
const DefaultPrec uint8 = 19

DefaultPrec is the target number of fractional digits for division results and the maximum accepted by strict parsing. It is a compile-time constant (never a runtime knob) so precision checks fold to immediate compares; build with -tags zerodecimal_prec9 or zerodecimal_prec12 to lower it.

View Source 
const MaxPrec uint8 = 19

MaxPrec is the maximum number of fractional digits a Decimal can carry. It is bounded by the 10^19 < 2^64 invariant the scaling tables rely on.

Variables

View Source 
var (
	// ErrOverflow is returned when the exact result of an operation does not
	// fit a 128-bit coefficient at the result precision.
	ErrOverflow = errors.New("zerodecimal: value overflows 128-bit coefficient")

	// ErrDivideByZero is returned by Div, QuoRem, and Mod when the divisor is zero.
	ErrDivideByZero = errors.New("zerodecimal: division by zero")

	// ErrPrecOutOfRange is returned when a requested or parsed precision
	// exceeds MaxPrec fractional digits.
	ErrPrecOutOfRange = errors.New("zerodecimal: precision out of range")

	// ErrInvalidFormat is returned when parsing input that is not a valid decimal.
	ErrInvalidFormat = errors.New("zerodecimal: invalid format")

	// ErrEmptyString is returned when parsing empty input.
	ErrEmptyString = errors.New("zerodecimal: empty input")

	// ErrMaxStrLen is returned when parsing input longer than 200 bytes.
	ErrMaxStrLen = errors.New("zerodecimal: input exceeds 200 bytes")

	// ErrInvalidFloat is returned by float constructors for NaN or infinities.
	ErrInvalidFloat = errors.New("zerodecimal: NaN or Infinity")

	// ErrIntPartOverflow is returned when the integer part does not fit int64.
	ErrIntPartOverflow = errors.New("zerodecimal: integer part overflows int64")

	// ErrInvalidBinaryData is returned by UnmarshalBinary for malformed input.
	ErrInvalidBinaryData = errors.New("zerodecimal: invalid binary data")

	// ErrScanNil is returned when scanning SQL NULL into a Decimal; use
	// NullDecimal for nullable columns.
	ErrScanNil = errors.New("zerodecimal: cannot scan nil into Decimal")

	// ErrScanType is returned when scanning an unsupported source type.
	ErrScanType = errors.New("zerodecimal: unsupported Scan source type")
)

Sentinel errors for every fallible operation in the package. They are returned bare (never wrapped) on hot paths so that error returns stay allocation-free; match with errors.Is.

View Source 
var One = NewFromInt(1)

One is the decimal one with precision 0.

View Source 
var Zero = Decimal{}

Zero is the canonical decimal zero, identical to the zero value Decimal{}.

Functions

This section is empty.

Types

type Decimal 

type Decimal struct {
	// contains filtered or unexported fields
}

Decimal is a fixed-point decimal number: 

value = (neg ? -1 : +1) · coef / 10^prec

with coef an unsigned 128-bit coefficient and prec 0..MaxPrec fractional digits. A Decimal is a 24-byte pointer-free value — copy it freely; the zero value is the canonical decimal zero and ready to use. The field order is load-bearing: coef first keeps the hot-path limb loads at offset zero.

INVARIANT (canonical zero): a Decimal with a zero coefficient is always exactly Decimal{} — neg false, prec 0. Every code path that can produce zero routes through newDecimal, so a negative zero cannot exist and sign predicates need no zero checks.

Arithmetic never trims trailing fractional zeros, so == compares representations, not numbers (1.5 != 1.50 under ==); use Equal or Cmp for numeric comparison.

func Avg 

func Avg(first Decimal, rest ...Decimal) (Decimal, error)

Avg returns the arithmetic mean (first + rest...)/(1 + len(rest)) with Div's adaptive precision and error contract; the intermediate Sum can also overflow.

func Max 

func Max(first Decimal, rest ...Decimal) Decimal

Max returns the numerically largest argument (1.5 and 1.50 compare equal; the first of equal values wins). It is infallible — comparison never overflows.

func Min 

func Min(first Decimal, rest ...Decimal) Decimal

Min returns the numerically smallest argument (1.5 and 1.50 compare equal; the first of equal values wins). It is infallible — comparison never overflows.

func MustAvg 

func MustAvg(first Decimal, rest ...Decimal) Decimal

MustAvg is Avg for operands with proven bounds: it panics on error.

func MustNew 

func MustNew(value int64, exp int32) Decimal

MustNew is New for arguments with proven bounds: it panics instead of returning an error.

func MustSum 

func MustSum(first Decimal, rest ...Decimal) Decimal

MustSum is Sum for operands with proven bounds: it panics on error.

func New 

func New(value int64, exp int32) (Decimal, error)

New returns value · 10^exp. A positive exp scales the coefficient and returns ErrOverflow when the result exceeds 128 bits (always, once exp > 38 with a nonzero value). A negative exp becomes fractional precision; when it exceeds MaxPrec, factors of ten are stripped from value while it stays exact, and ErrPrecOutOfRange is returned if the precision still cannot fit. New(0, exp) is Zero for every exp.

func NewFromFloat 

func NewFromFloat(f float64) (Decimal, error)

NewFromFloat converts f through its shortest decimal representation — the digits strconv prints for the exact bits of f — with no silent rounding: NaN and infinities return ErrInvalidFloat, |f| ≥ 2^128 returns ErrOverflow, and a nonzero |f| below 10^-19 or a shortest form needing more than MaxPrec fractional digits returns ErrPrecOutOfRange. For lossy ingestion of arbitrary floats, make the rounding explicit instead: NewFromStringTrunc(strconv.FormatFloat(f, 'f', -1, 64)).

func NewFromFloat32 

func NewFromFloat32(f float32) (Decimal, error)

NewFromFloat32 is NewFromFloat with the shortest form computed at 32-bit precision: NewFromFloat32(0.1) is exactly 0.1, not the longer expansion of float64(float32(0.1)).

func NewFromHiLo 

func NewFromHiLo(neg bool, hi, lo uint64, prec uint8) (Decimal, error)

NewFromHiLo assembles a Decimal from its raw representation — sign, 128-bit coefficient limbs, and fractional precision — the inverse of ToHiLo, for zero-cost interop with other 128-bit decimal layouts. The coefficient is taken verbatim: trailing fractional zeros are NOT trimmed, though a zero coefficient still collapses to the canonical Decimal{}. Returns ErrPrecOutOfRange when prec > MaxPrec.

func NewFromInt 

func NewFromInt(v int64) Decimal

NewFromInt returns the Decimal with the exact value of v and precision 0.

func NewFromInt32 

func NewFromInt32(v int32) Decimal

NewFromInt32 returns the Decimal with the exact value of v and precision 0.

func NewFromString 

func NewFromString(s string) (Decimal, error)

NewFromString parses a decimal literal — optional sign, digits, optional fraction, optional e/E exponent — into the exact Decimal it denotes. Values needing more than MaxPrec fractional digits return ErrPrecOutOfRange (use NewFromStringTrunc to truncate instead), coefficients past 2^128-1 return ErrOverflow, and grammar violations return ErrInvalidFormat. Stricter than shopspring/decimal: "1." and ".1" are rejected — both sides of the dot need a digit. The result is canonical (trailing fractional zeros trimmed) and parsing never allocates.

Example 
package main

import (
	"errors"
	"fmt"

	zerodecimal "github.com/AlexandrosKyriakakis/zerodecimal"
)

func main() {
	d, err := zerodecimal.NewFromString("1.5000")
	if err != nil {
		panic(err)
	}
	fmt.Println(d) // trailing fractional zeros trim at parse time

	sci, err := zerodecimal.NewFromString("1.23e4")
	if err != nil {
		panic(err)
	}
	fmt.Println(sci)

	_, err = zerodecimal.NewFromString(".5") // both sides of the dot need a digit
	fmt.Println(errors.Is(err, zerodecimal.ErrInvalidFormat))
}

Output:
1.5
12300
true

func NewFromStringTrunc 

func NewFromStringTrunc(s string) (Decimal, error)

NewFromStringTrunc is NewFromString except that a value needing more than MaxPrec fractional digits is truncated toward zero at prec MaxPrec — possibly to exactly zero — instead of returning ErrPrecOutOfRange. The truncation also covers mantissas longer than the 128-bit coefficient can hold: input with forty or more significant digits parses whenever the truncated value itself is representable, and ErrOverflow remains only for values whose truncated coefficient exceeds 2^128-1. All other errors are unchanged.

Example 
package main

import (
	"errors"
	"fmt"

	zerodecimal "github.com/AlexandrosKyriakakis/zerodecimal"
)

func main() {
	// Strict parsing rejects values needing more than MaxPrec fractional digits...
	_, err := zerodecimal.NewFromString("0.123456789012345678901")
	fmt.Println(errors.Is(err, zerodecimal.ErrPrecOutOfRange))

	// ...while the Trunc variant truncates toward zero at MaxPrec instead.
	d, err := zerodecimal.NewFromStringTrunc("0.123456789012345678901")
	if err != nil {
		panic(err)
	}
	fmt.Println(d)
}

Output:
true
0.1234567890123456789

func NewFromUint64 

func NewFromUint64(v uint64) Decimal

NewFromUint64 returns the Decimal with the exact value of v and precision 0.

func ParseBytes 

func ParseBytes(b []byte) (Decimal, error)

ParseBytes is NewFromString over a byte slice, avoiding any string conversion: b is read in place, never retained, and never modified.

func ParseBytesTrunc 

func ParseBytesTrunc(b []byte) (Decimal, error)

ParseBytesTrunc is NewFromStringTrunc over a byte slice (see ParseBytes).

func RequireFromFloat 

func RequireFromFloat(f float64) Decimal

RequireFromFloat is NewFromFloat for values with proven bounds: it panics instead of returning an error.

func RequireFromString 

func RequireFromString(s string) Decimal

RequireFromString is NewFromString for literals with proven validity, such as constants and test fixtures: it panics instead of returning an error.

func Sum 

func Sum(first Decimal, rest ...Decimal) (Decimal, error)

Sum returns first + rest[0] + ... + rest[n-1], folding Add left to right, and stops with ErrOverflow as soon as a partial sum overflows.

func (Decimal) Abs 

func (d Decimal) Abs() Decimal

Abs returns |d|, preserving precision.

func (Decimal) Add 

func (d Decimal) Add(e Decimal) (Decimal, error)

Add returns d + e computed exactly at precision max(d.prec, e.prec). ErrOverflow is returned iff the exact coefficient at that precision does not fit 128 bits — alignment itself can never fail, and opposite-sign operands can never overflow. Both same-precision cases run inline: same signs add as a single 128-bit magnitude add, opposite signs subtract as a single 128-bit magnitude subtract with a conditional two's-complement fix keyed on the borrow. Only differing precisions outline, straight into addUnaligned.

Example 
package main

import (
	"fmt"

	zerodecimal "github.com/AlexandrosKyriakakis/zerodecimal"
)

func main() {
	a := zerodecimal.RequireFromString("0.1")
	b := zerodecimal.RequireFromString("0.2")
	fmt.Println(a.MustAdd(b))

	x, y := 0.1, 0.2 // the float64 arithmetic that decimals exist to avoid
	fmt.Println(x + y)
}

Output:
0.3
0.30000000000000004

func (Decimal) AppendBinary 

func (d Decimal) AppendBinary(b []byte) ([]byte, error)

AppendBinary implements encoding.BinaryAppender, appending the MarshalBinary encoding of d to b and returning the extended slice. The error is always nil. It allocates only if b lacks capacity.

func (Decimal) AppendFixed 

func (d Decimal) AppendFixed(b []byte, places uint8) []byte

AppendFixed appends the StringFixed rendering of d to b and returns the extended slice. It allocates only if b lacks capacity.

func (Decimal) AppendText 

func (d Decimal) AppendText(b []byte) ([]byte, error)

AppendText appends the canonical decimal representation of d to b and returns the extended slice, matching the encoding.TextAppender shape. The error is always nil. Values inside the small-value cache window append the precomputed string (byte-identical to appendCanonical's output, since the cache is built through it — see cache.go); everything else renders inline. It allocates only if b lacks capacity.

func (Decimal) Ceil 

func (d Decimal) Ceil() Decimal

Ceil returns the smallest integer value ≥ d: 2.5 → 3 and -2.5 → -2, with precision 0 unless d already had none.

func (Decimal) Cmp 

func (d Decimal) Cmp(e Decimal) int

Cmp returns -1 when d < e, 0 when d == e numerically, and +1 when d > e. Decimals of different precision compare by value: 1.5 equals 1.50. Comparison is infallible — no precision alignment can overflow.

func (Decimal) Div 

func (d Decimal) Div(e Decimal) (Decimal, error)

Div returns d ÷ e truncated toward zero at adaptive precision: the result is trunc(d/e · 10^p) with precision p, for the LARGEST p ≤ DefaultPrec whose quotient coefficient fits 128 bits. Exact results therefore keep p = DefaultPrec (their trailing zeros are not trimmed), while quotients of huge magnitudes degrade precision gracefully instead of failing. ErrOverflow only when even the integer quotient (p = 0) does not fit; ErrDivideByZero when e is zero. Dividing zero by anything nonzero is Zero.

The common case is fast-pathed: p = DefaultPrec is the maximum precision, so when its quotient already fits 128 bits (the overwhelmingly common shape) it trivially realizes the largest-p contract and Div returns immediately, skipping the bound estimate, descent loop and p+1 probe entirely. Those run only on the degradation path, when even p = DefaultPrec overflows.

Example 
package main

import (
	"errors"
	"fmt"

	zerodecimal "github.com/AlexandrosKyriakakis/zerodecimal"
)

func main() {
	third, err := zerodecimal.NewFromInt(1).Div(zerodecimal.NewFromInt(3))
	if err != nil {
		panic(err)
	}
	fmt.Println(third) // truncated at DefaultPrec fractional digits

	fmt.Println(zerodecimal.NewFromInt(1).MustDiv(zerodecimal.NewFromInt(8)))

	_, err = zerodecimal.NewFromInt(1).Div(zerodecimal.Zero)
	fmt.Println(errors.Is(err, zerodecimal.ErrDivideByZero))
}

Output:
0.3333333333333333333
0.125
true

func (Decimal) Equal 

func (d Decimal) Equal(e Decimal) bool

Equal reports whether d and e are numerically equal, ignoring trailing fractional zeros (1.5 equals 1.50). Use it instead of ==, which is representation equality. Identical representations short-circuit before any comparison work.

Example 
package main

import (
	"fmt"

	zerodecimal "github.com/AlexandrosKyriakakis/zerodecimal"
)

func main() {
	a := zerodecimal.RequireFromString("1.5")
	// An arithmetic result keeps its precision: 0.75 + 0.75 is 1.50, not 1.5.
	b := zerodecimal.RequireFromString("0.75").MustAdd(zerodecimal.RequireFromString("0.75"))

	fmt.Println(a == b)     // == compares representations
	fmt.Println(a.Equal(b)) // Equal compares values
	fmt.Println(a.Cmp(b))
}

Output:
false
true
0

func (Decimal) Floor 

func (d Decimal) Floor() Decimal

Floor returns the largest integer value ≤ d: 2.5 → 2 and -2.5 → -3, with precision 0 unless d already had none.

func (Decimal) GreaterThan 

func (d Decimal) GreaterThan(e Decimal) bool

GreaterThan reports whether d > e.

func (Decimal) GreaterThanOrEqual 

func (d Decimal) GreaterThanOrEqual(e Decimal) bool

GreaterThanOrEqual reports whether d ≥ e.

func (Decimal) InexactFloat64 

func (d Decimal) InexactFloat64() float64

InexactFloat64 returns the float64 nearest to d. The conversion goes through strconv.ParseFloat over the canonical string for correct round-to-nearest-even; every Decimal is finite and |d| < 2^128 stays well inside float64 range, so the parse cannot fail.

func (Decimal) IntPart 

func (d Decimal) IntPart() (int64, error)

IntPart returns the integer part of d truncated toward zero, or ErrIntPartOverflow when it does not fit int64. MinInt64 round-trips: NewFromInt(math.MinInt64).IntPart() returns math.MinInt64.

func (Decimal) IsNegative 

func (d Decimal) IsNegative() bool

IsNegative reports whether d < 0. The bare flag is exact because the canonical-zero invariant keeps zero unsigned.

func (Decimal) IsPositive 

func (d Decimal) IsPositive() bool

IsPositive reports whether d > 0.

func (Decimal) IsZero 

func (d Decimal) IsZero() bool

IsZero reports whether d == 0.

func (Decimal) LessThan 

func (d Decimal) LessThan(e Decimal) bool

LessThan reports whether d < e.

func (Decimal) LessThanOrEqual 

func (d Decimal) LessThanOrEqual(e Decimal) bool

LessThanOrEqual reports whether d ≤ e.

func (Decimal) MarshalBinary 

func (d Decimal) MarshalBinary() ([]byte, error)

MarshalBinary implements encoding.BinaryMarshaler using the compact wire format documented at the binFlag constants: 10 bytes when the coefficient fits one limb, 18 otherwise, NOT udecimal-compatible. It costs exactly one allocation — the result, sized exactly.

func (Decimal) MarshalJSON 

func (d Decimal) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler, rendering d as a double-quoted canonical decimal string ("1.23") — ALWAYS quoted, because a bare JSON number is read as float64 by most consumers and would silently lose digits past 2^53. The rendering happens in a stack buffer, so the one allocation is the exactly-sized result; it deliberately never aliases the small-value string cache, since callers own the returned bytes and may mutate them.

Example 
package main

import (
	"encoding/json"
	"fmt"

	zerodecimal "github.com/AlexandrosKyriakakis/zerodecimal"
)

func main() {
	type Order struct {
		Price zerodecimal.Decimal `json:"price"`
		Qty   zerodecimal.Decimal `json:"qty"`
	}
	data, err := json.Marshal(Order{
		Price: zerodecimal.RequireFromString("19.99"),
		Qty:   zerodecimal.NewFromInt(2),
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(string(data)) // always quoted: bare JSON numbers lose digits past 2^53
}

Output:
{"price":"19.99","qty":"2"}

func (Decimal) MarshalText 

func (d Decimal) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler, returning the canonical decimal representation of d (the exact bytes String produces) in a freshly allocated slice. It costs exactly one allocation — the result, sized exactly (the rendering happens in a stack buffer first).

func (Decimal) Mod 

func (d Decimal) Mod(e Decimal) (Decimal, error)

Mod returns the remainder of QuoRem: d - trunc(d/e)·e, carrying the sign of d and precision max(d.prec, e.prec), with the same error contract.

func (Decimal) Mul 

func (d Decimal) Mul(e Decimal) (Decimal, error)

Mul returns d × e. The exact product carries d.prec + e.prec fractional digits (at most 2·MaxPrec); when that exceeds DefaultPrec the excess digits are truncated toward zero, so the result precision is min(d.prec + e.prec, DefaultPrec). ErrOverflow iff the truncated coefficient does not fit 128 bits. One-limb products that need no rescale take a single hardware multiply; everything else outlines into mulSlow.

func (Decimal) MustAdd 

func (d Decimal) MustAdd(e Decimal) Decimal

MustAdd is Add for operands with proven bounds: it panics on error.

func (Decimal) MustDiv 

func (d Decimal) MustDiv(e Decimal) Decimal

MustDiv is Div for operands with proven bounds: it panics on error.

func (Decimal) MustMod 

func (d Decimal) MustMod(e Decimal) Decimal

MustMod is Mod for operands with proven bounds: it panics on error.

func (Decimal) MustMul 

func (d Decimal) MustMul(e Decimal) Decimal

MustMul is Mul for operands with proven bounds: it panics on error.

func (Decimal) MustQuoRem 

func (d Decimal) MustQuoRem(e Decimal) (Decimal, Decimal)

MustQuoRem is QuoRem for operands with proven bounds: it panics on error.

func (Decimal) MustSub 

func (d Decimal) MustSub(e Decimal) Decimal

MustSub is Sub for operands with proven bounds: it panics on error.

func (Decimal) Neg 

func (d Decimal) Neg() Decimal

Neg returns -d, preserving precision; the negation of zero is zero.

func (Decimal) Prec 

func (d Decimal) Prec() uint8

Prec returns the number of fractional digits of d (0..MaxPrec).

func (Decimal) QuoRem 

func (d Decimal) QuoRem(e Decimal) (Decimal, Decimal, error)

QuoRem returns the truncated quotient q = trunc(d/e) and the remainder r = d - q·e (T-division, matching Go's integer operators and the shopspring/udecimal convention). q has precision 0 and the sign of d.neg != e.neg; r has precision f = max(d.prec, e.prec), the sign of d, and |r| < |e|; the identity d = q·e + r always holds. ErrDivideByZero when e is zero; ErrOverflow when the quotient does not fit a 128-bit coefficient, or when the divisor aligned to precision f does not.

Example 
package main

import (
	"fmt"

	zerodecimal "github.com/AlexandrosKyriakakis/zerodecimal"
)

func main() {
	q, r := zerodecimal.RequireFromString("7.5").MustQuoRem(zerodecimal.NewFromInt(2))
	fmt.Println(q, r)
}

Output:
3 1.5

func (Decimal) Round 

func (d Decimal) Round(places uint8) Decimal

Round rounds d to places fractional digits with ties away from zero (shopspring Round semantics): 2.5 → 3 and -2.5 → -3. places counts fractional digits only; negative places (rounding integer positions) are unsupported by design, which keeps the whole rounding family infallible. places ≥ d.Prec() returns d unchanged.

Example 
package main

import (
	"fmt"

	zerodecimal "github.com/AlexandrosKyriakakis/zerodecimal"
)

func main() {
	fmt.Println(zerodecimal.RequireFromString("2.5").Round(0)) // ties away from zero
	fmt.Println(zerodecimal.RequireFromString("-2.5").Round(0))
	fmt.Println(zerodecimal.RequireFromString("1.2345").Round(2))
}

Output:
3
-3
1.23

func (Decimal) RoundBank 

func (d Decimal) RoundBank(places uint8) Decimal

RoundBank rounds d to places fractional digits with ties to even (banker's rounding): 2.5 → 2, 3.5 → 4, -2.5 → -2. places ≥ d.Prec() returns d unchanged.

Example 
package main

import (
	"fmt"

	zerodecimal "github.com/AlexandrosKyriakakis/zerodecimal"
)

func main() {
	fmt.Println(zerodecimal.RequireFromString("2.5").RoundBank(0)) // ties to even
	fmt.Println(zerodecimal.RequireFromString("3.5").RoundBank(0))
	fmt.Println(zerodecimal.RequireFromString("-2.5").RoundBank(0))
}

Output:
2
4
-2

func (Decimal) RoundCeil 

func (d Decimal) RoundCeil(places uint8) Decimal

RoundCeil rounds d to places fractional digits toward +∞: 1.01 → 1.1 but -1.09 → -1.0 at one place. places ≥ d.Prec() returns d unchanged.

func (Decimal) RoundDown 

func (d Decimal) RoundDown(places uint8) Decimal

RoundDown rounds d to places fractional digits toward zero, simply dropping the excess digits: 1.09 → 1.0 and -1.09 → -1.0 at one place. places ≥ d.Prec() returns d unchanged.

func (Decimal) RoundFloor 

func (d Decimal) RoundFloor(places uint8) Decimal

RoundFloor rounds d to places fractional digits toward -∞: -1.01 → -1.1 but 1.09 → 1.0 at one place. places ≥ d.Prec() returns d unchanged.

func (Decimal) RoundUp 

func (d Decimal) RoundUp(places uint8) Decimal

RoundUp rounds d to places fractional digits away from zero: any dropped nonzero remainder steps the magnitude up, so 1.01 → 1.1 and -1.01 → -1.1 at one place. places ≥ d.Prec() returns d unchanged.

func (*Decimal) Scan 

func (d *Decimal) Scan(src any) error

Scan implements sql.Scanner, populating d from a value produced by a database driver. string and []byte parse as strict decimal literals (NewFromString grammar, scientific notation included); int64, int32, int, and uint64 convert exactly at precision 0; float64 converts through its shortest decimal representation (NewFromFloat semantics — NaN and infinities return ErrInvalidFloat). A nil src (SQL NULL) returns ErrScanNil; use NullDecimal for nullable columns. Any other type returns an error wrapping ErrScanType. d is left unchanged on every error path.

Every supported conversion is allocation-free. The unsupported-type branch is the package's one fmt call: it allocates the wrapped error, which is acceptable on a path that is cold by construction — a column's driver type does not change between rows.

func (Decimal) Sign 

func (d Decimal) Sign() int

Sign returns -1 when d < 0, 0 when d == 0, and +1 when d > 0.

func (Decimal) String 

func (d Decimal) String() string

String returns the canonical decimal representation of d (the exact form appendCanonical produces). Values inside the small-value cache window return the precomputed string with zero allocations; everything else costs exactly one string allocation.

func (Decimal) StringFixed 

func (d Decimal) StringFixed(places uint8) string

StringFixed returns d rounded to places fractional digits (ties away from zero, like Round) and formatted with EXACTLY places fractional digits — zero-padded, never trimmed — so StringFixed(3) of 1.5 is "1.500". With places 0 the result has no decimal point. It costs one string allocation.

func (Decimal) Sub 

func (d Decimal) Sub(e Decimal) (Decimal, error)

Sub returns d - e computed exactly at precision max(d.prec, e.prec), with the same overflow contract as Add. Both same-precision cases run inline: opposite signs subtract as a magnitude add, same signs as a single 128-bit magnitude subtract with a conditional two's-complement fix keyed on the borrow. Only differing precisions outline, straight into addUnaligned (the shared differing-precision arm) with the sign of e flipped — a zero e keeps its canonical unsigned form, so its sign is never flipped.

func (Decimal) ToHiLo 

func (d Decimal) ToHiLo() (neg bool, hi, lo uint64, prec uint8)

ToHiLo exposes the raw representation of d, such that d = (neg ? -1 : +1) · (hi·2^64 + lo) / 10^prec. It is total: every Decimal round-trips exactly through NewFromHiLo.

func (Decimal) Truncate 

func (d Decimal) Truncate(places uint8) Decimal

Truncate drops every fractional digit past places, identical to RoundDown. places ≥ d.Prec() returns d unchanged.

func (*Decimal) UnmarshalBinary 

func (d *Decimal) UnmarshalBinary(data []byte) error

UnmarshalBinary implements encoding.BinaryUnmarshaler for the MarshalBinary wire format. Validation is strict — any violation returns ErrInvalidBinaryData and leaves d unchanged:

  • the length must be exactly 10 or 18 bytes, consistent with the high-limb flag bit (every truncation is caught, never read past)
  • reserved flag bits 2..7 must be zero (the format-version guard)
  • prec must not exceed MaxPrec
  • a present high limb must be nonzero (the canonical encoding emits the short form whenever it can, so a zero high limb marks a foreign or corrupted encoder)

A zero coefficient is normalized through newDecimal regardless of the encoded sign and precision, so a foreign encoder's "-0.000" still decodes to the canonical Decimal{}. It never allocates.

func (*Decimal) UnmarshalJSON 

func (d *Decimal) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler, accepting both the package's own quoted form ("1.23") and bare JSON numbers — the strict parse grammar includes scientific notation, so float-encoded numbers like 1.5e-7 decode exactly. A literal null is a no-op (the stdlib convention, mirroring json.Unmarshal on pointers); use NullDecimal to distinguish null from a value. Exactly one balanced quote pair is stripped, so "null" in quotes and unbalanced quotes are parse errors. Errors are the bare parse sentinels and leave d unchanged. It never allocates.

Example 
package main

import (
	"encoding/json"
	"fmt"

	zerodecimal "github.com/AlexandrosKyriakakis/zerodecimal"
)

func main() {
	var d zerodecimal.Decimal
	// Bare JSON numbers decode exactly too, scientific notation included.
	if err := json.Unmarshal([]byte(`1.5e-7`), &d); err != nil {
		panic(err)
	}
	fmt.Println(d)
}

Output:
0.00000015

func (*Decimal) UnmarshalText 

func (d *Decimal) UnmarshalText(b []byte) error

UnmarshalText implements encoding.TextUnmarshaler, parsing the strict decimal literal grammar of NewFromString (scientific notation included). Errors are the bare parse sentinels — match with errors.Is — and d is left unchanged on every error path. It never allocates.

func (Decimal) Value 

func (d Decimal) Value() (driver.Value, error)

Value implements driver.Valuer, rendering d as its canonical string — the one decimal wire form every SQL driver and database agree on, with no float rounding and no driver-side numeric truncation. Values inside the small-value cache window return a pre-boxed driver.Value with zero allocations; everything else costs exactly two — the canonical string plus boxing its header into the interface (the bytes themselves are shared, not copied).

type NullDecimal 

type NullDecimal struct {
	Decimal Decimal
	Valid   bool
}

NullDecimal is a Decimal that can represent SQL NULL: Valid false means NULL, and then Decimal holds the zero value. It follows the database/sql Null* convention so nullable columns scan without errors.

Example 
package main

import (
	"fmt"

	zerodecimal "github.com/AlexandrosKyriakakis/zerodecimal"
)

func main() {
	var n zerodecimal.NullDecimal

	// SQL NULL scans to Valid == false without an error.
	if err := n.Scan(nil); err != nil {
		panic(err)
	}
	fmt.Println(n.Valid)

	// Driver strings parse with the strict literal grammar.
	if err := n.Scan("123.45"); err != nil {
		panic(err)
	}
	fmt.Println(n.Valid, n.Decimal)

	// Value renders the canonical string every database agrees on.
	v, err := n.Value()
	if err != nil {
		panic(err)
	}
	fmt.Println(v)
}

Output:
false
true 123.45
123.45

func NewNullDecimal 

func NewNullDecimal(d Decimal) NullDecimal

NewNullDecimal returns a valid NullDecimal holding d.

func (NullDecimal) MarshalJSON 

func (n NullDecimal) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler: the JSON null literal when n is invalid, otherwise the double-quoted canonical string of the held Decimal. The null bytes are freshly allocated too — callers own MarshalJSON results and may mutate them.

func (NullDecimal) MarshalText 

func (n NullDecimal) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler: the empty string when n is invalid (the conventional text rendering of NULL), otherwise the canonical bytes of the held Decimal.

func (*NullDecimal) Scan 

func (n *NullDecimal) Scan(src any) error

Scan implements sql.Scanner: a nil src (SQL NULL) clears n to the invalid zero NullDecimal without error; any other src follows Decimal.Scan, with a conversion error also clearing n — a NullDecimal never holds a stale value after a failed scan.

func (*NullDecimal) UnmarshalJSON 

func (n *NullDecimal) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler: a literal null clears n to the invalid zero NullDecimal (unlike Decimal, where null is a no-op — here the type exists to record it); anything else must parse per Decimal.UnmarshalJSON and marks n valid. A parse error leaves n unchanged.

func (*NullDecimal) UnmarshalText 

func (n *NullDecimal) UnmarshalText(b []byte) error

UnmarshalText implements encoding.TextUnmarshaler: empty input clears n to the invalid zero NullDecimal; anything else must parse as a strict decimal literal and marks n valid. A parse error leaves n unchanged.

func (NullDecimal) Value 

func (n NullDecimal) Value() (driver.Value, error)

Value implements driver.Valuer: SQL NULL when n is invalid, otherwise the canonical string of the held Decimal (see Decimal.Value).

Source Files

View all Source files

Directories

Path Synopsis
internal
gen command
Command gen computes the reciprocal-division tables for package zerodecimal and writes them to tables.go in the package root.
 Command gen computes the reciprocal-division tables for package zerodecimal and writes them to tables.go in the package root.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.