decimal

package
v1.64.0 Latest Latest
Warning

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

Go to latest
Published: Nov 10, 2026 License: Apache-2.0 Imports: 5 Imported by: 0

README

Decimal and Money

Import github.com/flanksource/commons/decimal for 19-digit half-even decimals backed by github.com/govalues/decimal. Import github.com/flanksource/commons/bigdecimal for higher precision backed by github.com/woodsbury/decimal128. Values are separate types; conversion is explicit. Neither package provides arbitrary precision.

Use Parse(string) for runtime input and MustParse(string) for constants. Arithmetic delegates to the upstream library and returns Commons values. Decimal arithmetic returns errors such as overflow and division by zero; bigdecimal preserves upstream special-value arithmetic. The bigdecimal Decimal.Compare method panics when either operand is NaN; check IsNaN() first, or use the package-level bigdecimal.Compare, which applies the upstream total order. The embedded .Decimal field provides explicit access to upstream functionality.

String(), %s, %v, JSON, and text use canonical fixed-point notation without insignificant fractional zeros. %f accepts an explicit precision for rounding and padding. JSON always emits quoted numeric strings and accepts strings or numeric tokens without a float conversion. JSON rejects null, malformed input, and nonfinite values. Use pointers for nullable fields. Text decoding is atomic; bigdecimal text serialization rejects nonfinite values.

Both packages expose NewMoney(MoneyOptions). Amount is a finite plain-decimal string parsed with the selected backend's rounding semantics. Currency must contain three uppercase letters; no currency registry or exchange-rate lookup is performed. DecimalPlaces is the minimum display scale from 0 to 31, not an amount rounding instruction. Money strings and JSON include the currency, such as USD 125.00.

Money exposes Amount(), Currency(), DecimalPlaces(), and Cmp(other). Comparisons require initialized values and the same currency. Money arithmetic and implicit precision/currency conversion are not provided. Construct Money with NewMoney; uninitialized values fail validation and serialization, and String panics.

Run the examples and regression suite from the Commons root:

go test ./decimal ./bigdecimal

Regenerate numeric delegates with the pinned upstream modules downloaded by go mod download. Pass the corresponding module-cache directory to the generator:

go run ./internal/gendecimal decimal /path/to/github.com/govalues/decimal@v0.1.36 github.com/govalues/decimal
go run ./internal/gendecimal bigdecimal /path/to/github.com/woodsbury/decimal128@v1.4.1 github.com/woodsbury/decimal128

Documentation

Overview

Package decimal extends govalues decimals with canonical presentation and Money. Values use 19-digit half-even rounding; arithmetic retains Commons result types.

Code generated by internal/gendecimal; DO NOT EDIT.

Index

Examples

Constants

View Source
const MaxPrec = upstream.MaxPrec
View Source
const MaxScale = upstream.MaxScale
View Source
const MinScale = upstream.MinScale

Variables

Functions

This section is empty.

Types

type Decimal

type Decimal struct{ upstream.Decimal }

func Mean

func Mean(d ...Decimal) (Decimal, error)

func MustNew

func MustNew(value int64, scale int) Decimal

func MustParse

func MustParse(s string) Decimal

func New

func New(value int64, scale int) (Decimal, error)

func NewFromFloat64

func NewFromFloat64(f float64) (Decimal, error)

func NewFromInt64

func NewFromInt64(whole int64, frac int64, scale int) (Decimal, error)

func Parse

func Parse(s string) (Decimal, error)

func ParseExact

func ParseExact(s string, scale int) (Decimal, error)

func Prod

func Prod(d ...Decimal) (Decimal, error)

func Sum

func Sum(d ...Decimal) (Decimal, error)

func (Decimal) Abs

func (d Decimal) Abs() Decimal

func (Decimal) Add

func (d Decimal) Add(e Decimal) (Decimal, error)
Example
package main

import (
	"fmt"
	"github.com/flanksource/commons/bigdecimal"
	"github.com/flanksource/commons/decimal"
)

func main() {
	total, err := decimal.MustParse("1.20").Add(decimal.MustParse("0.03"))
	if err != nil {
		panic(err)
	}
	fmt.Printf("%s %.3f\n", total, total)
	fmt.Println(bigdecimal.MustParse("9007199254740993.0000000001"))
}
Output:
1.23 1.230
9007199254740993.0000000001

func (Decimal) AddExact

func (d Decimal) AddExact(e Decimal, scale int) (Decimal, error)

func (Decimal) AddMul

func (d Decimal) AddMul(e Decimal, f Decimal) (Decimal, error)

func (Decimal) AddMulExact

func (d Decimal) AddMulExact(e Decimal, f Decimal, scale int) (Decimal, error)

func (Decimal) AddQuo

func (d Decimal) AddQuo(e Decimal, f Decimal) (Decimal, error)

func (Decimal) AddQuoExact

func (d Decimal) AddQuoExact(e Decimal, f Decimal, scale int) (Decimal, error)

func (Decimal) AppendText

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

func (Decimal) Ceil

func (d Decimal) Ceil(scale int) Decimal

func (Decimal) Clamp

func (d Decimal) Clamp(min Decimal, max Decimal) (Decimal, error)

func (Decimal) Cmp

func (d Decimal) Cmp(e Decimal) int

func (Decimal) CmpAbs

func (d Decimal) CmpAbs(e Decimal) int

func (Decimal) CmpTotal

func (d Decimal) CmpTotal(e Decimal) int

func (Decimal) Coef

func (d Decimal) Coef() uint64

func (Decimal) Compare

func (d Decimal) Compare(other Decimal) int

func (Decimal) CopySign

func (d Decimal) CopySign(e Decimal) Decimal

func (Decimal) Equal

func (d Decimal) Equal(e Decimal) bool

func (Decimal) Exp

func (d Decimal) Exp() (Decimal, error)

func (Decimal) Expm1

func (d Decimal) Expm1() (Decimal, error)

func (Decimal) Float64

func (d Decimal) Float64() (float64, bool)

func (Decimal) Floor

func (d Decimal) Floor(scale int) Decimal

func (Decimal) Format

func (d Decimal) Format(state fmt.State, verb rune)

func (Decimal) Int64

func (d Decimal) Int64(scale int) (int64, int64, bool)

func (Decimal) Inv

func (d Decimal) Inv() (Decimal, error)

func (Decimal) IsInt

func (d Decimal) IsInt() bool

func (Decimal) IsNeg

func (d Decimal) IsNeg() bool

func (Decimal) IsOne

func (d Decimal) IsOne() bool

func (Decimal) IsPos

func (d Decimal) IsPos() bool

func (Decimal) IsZero

func (d Decimal) IsZero() bool

func (Decimal) Less

func (d Decimal) Less(e Decimal) bool

func (Decimal) Log

func (d Decimal) Log() (Decimal, error)

func (Decimal) Log1p

func (d Decimal) Log1p() (Decimal, error)

func (Decimal) Log2

func (d Decimal) Log2() (Decimal, error)

func (Decimal) Log10

func (d Decimal) Log10() (Decimal, error)

func (Decimal) MarshalJSON

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

func (Decimal) MarshalText

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

func (Decimal) Max

func (d Decimal) Max(e Decimal) Decimal

func (Decimal) Min

func (d Decimal) Min(e Decimal) Decimal

func (Decimal) MinScale

func (d Decimal) MinScale() int

func (Decimal) Mul

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

func (Decimal) MulExact

func (d Decimal) MulExact(e Decimal, scale int) (Decimal, error)

func (Decimal) Neg

func (d Decimal) Neg() Decimal

func (Decimal) One

func (d Decimal) One() Decimal

func (Decimal) Pad

func (d Decimal) Pad(scale int) Decimal

func (Decimal) Pow

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

func (Decimal) PowInt

func (d Decimal) PowInt(power int) (Decimal, error)

func (Decimal) Prec

func (d Decimal) Prec() int

func (Decimal) Quantize

func (d Decimal) Quantize(e Decimal) Decimal

func (Decimal) Quo

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

func (Decimal) QuoExact

func (d Decimal) QuoExact(e Decimal, scale int) (Decimal, error)

func (Decimal) QuoRem

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

func (Decimal) Rescale

func (d Decimal) Rescale(scale int) Decimal

func (Decimal) Round

func (d Decimal) Round(scale int) Decimal

func (Decimal) SameScale

func (d Decimal) SameScale(e Decimal) bool

func (Decimal) Scale

func (d Decimal) Scale() int

func (Decimal) Sign

func (d Decimal) Sign() int

func (Decimal) Sqrt

func (d Decimal) Sqrt() (Decimal, error)

func (Decimal) String

func (d Decimal) String() string

func (Decimal) Sub

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

func (Decimal) SubAbs

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

func (Decimal) SubExact

func (d Decimal) SubExact(e Decimal, scale int) (Decimal, error)

func (Decimal) SubMul

func (d Decimal) SubMul(e Decimal, f Decimal) (Decimal, error)

func (Decimal) SubMulExact

func (d Decimal) SubMulExact(e Decimal, f Decimal, scale int) (Decimal, error)

func (Decimal) SubQuo

func (d Decimal) SubQuo(e Decimal, f Decimal) (Decimal, error)

func (Decimal) SubQuoExact

func (d Decimal) SubQuoExact(e Decimal, f Decimal, scale int) (Decimal, error)

func (Decimal) Trim

func (d Decimal) Trim(scale int) Decimal

func (Decimal) Trunc

func (d Decimal) Trunc(scale int) Decimal

func (Decimal) ULP

func (d Decimal) ULP() Decimal

func (*Decimal) UnmarshalJSON

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

func (*Decimal) UnmarshalText

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

func (Decimal) WithinOne

func (d Decimal) WithinOne() bool

func (Decimal) Zero

func (d Decimal) Zero() Decimal

type Money

type Money struct{ money.Value[Decimal] }

func NewMoney

func NewMoney(opts MoneyOptions) (Money, error)
Example
package main

import (
	"fmt"
	"github.com/flanksource/commons/decimal"
)

func main() {
	premium, err := decimal.NewMoney(decimal.MoneyOptions{Amount: "125", Currency: "USD", DecimalPlaces: 2})
	if err != nil {
		panic(err)
	}
	fmt.Println(premium)
	fmt.Println(premium.Amount())
}
Output:
USD 125.00
125

func (Money) Cmp

func (m Money) Cmp(other Money) (int, error)

Cmp compares amounts in the same currency and rejects uninitialized values.

type MoneyOptions

type MoneyOptions = money.Options

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL