README
¶
🧧 Fixed-Point Decimal Money
Be Precise: using floats to represent currency is almost criminal. — Robert.C.Martin, "Clean Code" p.301
- as fast as
int64 - no
floatin parsing nor printing, does not leak precision ISO 4217[^1][^2] currency- block mismatched currency arithmetics
- 100 LOC
- fuzz tests
var BuySP500Price = fpmoney.FromInt(9000, fpmoney.SGD)
input := []byte(`{"sp500": {"amount": 9000.02, "currency": "SGD"}}`)
type Stonks struct {
SP500 fpmoney.Amount `json:"sp500"`
}
var v Stonks
if err := json.Unmarshal(input, &v); err != nil {
log.Fatal(err)
}
amountToBuy := fpmoney.FromInt(0, fpmoney.SGD)
if v.SP500.GreaterThan(BuySP500Price) {
amountToBuy = amountToBuy.Add(v.SP500.Mul(2))
}
fmt.Println(amountToBuy)
// Output: 18000.04 SGD
Ultra Small Fractions
Some denominations have very low fractions.
Storing them int64 you would get.
BTCsatoshi is1 BTC = 100,000,000 satoshi, which is still enough for ~92,233,720,368 BTC.ETHwei is1 ETH = 1,000,000,000,000,000,000 wei, which is ~9 ETH. If you deal with wei, you may considerbigintor multipleint64. In fact, official Ethereum code is in Go and it is using bigint (code).
Benchmarks
$ go test -bench=. -benchmem .
goos: darwin
goarch: arm64
pkg: github.com/nikolaydubina/fpmoney
cpu: Apple M3 Max
BenchmarkCurrency_UnmarshalText-16 711695404 1.610 ns/op 0 B/op 0 allocs/op
BenchmarkCurrency_AppendText-16 446232057 2.698 ns/op 0 B/op 0 allocs/op
BenchmarkCurrency_MarshalText-16 81956246 13.99 ns/op 8 B/op 1 allocs/op
BenchmarkCurrency_String-16 1000000000 1.064 ns/op 0 B/op 0 allocs/op
BenchmarkArithmetic/add-16 924924993 1.305 ns/op 0 B/op 0 allocs/op
BenchmarkJSON/small/encode-16 6004620 198.5 ns/op 160 B/op 3 allocs/op
BenchmarkJSON/small/decode-16 5047149 238.7 ns/op 152 B/op 2 allocs/op
BenchmarkJSON/large/encode-16 4739722 255.7 ns/op 176 B/op 3 allocs/op
BenchmarkJSON/large/decode-16 3737406 315.3 ns/op 152 B/op 2 allocs/op
BenchmarkBinary/small/encode-16 132380481 9.044 ns/op 16 B/op 1 allocs/op
BenchmarkBinary/small/decode-16 100000000 10.80 ns/op 16 B/op 1 allocs/op
BenchmarkBinary/large/encode-16 133549021 8.995 ns/op 16 B/op 1 allocs/op
BenchmarkBinary/large/decode-16 100000000 10.61 ns/op 16 B/op 1 allocs/op
PASS
ok github.com/nikolaydubina/fpmoney 15.804s
References and Related Work
- ferdypruis/iso4217 was a good inspiration and reference material. it was used in early version as well. it is well maintained and fast library for currencies.
github.com/shopspring/decimal: fixed precision; faster printing/parsing/arithmetics; currency handlinggithub.com/Rhymond/go-money: does not usefloatorinterface{}in parsing; currency is enumgithub.com/ferdypruis/iso4217: skipped deprecated currencies to fit intouint8and smaller struct size- https://en.wikipedia.org/wiki/ISO_4217
[^1]: excluding currencies with 4+ minor units CLF, UYW
[^2]: excluding deprecated currencies HRD, HRK, SLL, ZWL
Documentation
¶
Index ¶
- Constants
- Variables
- type Amount
- func (a Amount) Add(b Amount) Amount
- func (s Amount) AppendBinary(b []byte) ([]byte, error)
- func (a Amount) AppendJSON(b []byte) ([]byte, error)
- func (a Amount) Convert(to Currency, rate float64) Amount
- func (a Amount) Currency() Currency
- func (a Amount) DivMod(b int) (part Amount, remainder Amount)
- func (a Amount) Float32() float32
- func (a Amount) Float64() float64
- func (a Amount) GreaterThan(b Amount) bool
- func (a Amount) GreaterThanOrEqual(b Amount) bool
- func (a Amount) LessThan(b Amount) bool
- func (a Amount) LessThanOrEqual(b Amount) bool
- func (s Amount) MarshalBinary() ([]byte, error)
- func (a Amount) MarshalJSON() ([]byte, error)
- func (a Amount) Mul(b int) Amount
- func (a Amount) MulFraction(b float64) Amount
- func (a Amount) Scaled() int64
- func (a Amount) String() string
- func (a Amount) StringPair() (amount, currency string)
- func (a Amount) Sub(b Amount) Amount
- func (s *Amount) UnmarshalBinary(b []byte) error
- func (a *Amount) UnmarshalJSON(b []byte) (err error)
- type Currency
- type ErrCurrencyMismatch
Examples ¶
- Amount
- Amount (Equality)
- Amount (Equality_same_currency)
- Amount (Equality_wrong_currency)
- Amount.Convert
- Amount.Convert (Same)
- Amount.DivMod (Part)
- Amount.DivMod (Whole)
- Amount.MulFraction
- Amount.MulFraction (Identity)
- Amount.MulFraction (Negate)
- Amount.MulFraction (Whole)
- Amount.MulFraction (Zero)
- Amount.Scaled (Fractions)
- Amount.Scaled (From_scaled)
- Amount.Scaled (Large)
- Amount.Scaled (Many_fractions)
- Amount.Scaled (Whole)
- Amount.StringPair
- Currency.MarshalText
- Currency.UnmarshalText
- FromFloat
Constants ¶
View Source
const NumBytes = 8 + 1
Variables ¶
View Source
var Currencies = [...]Currency{}/* 177 elements not displayed */
View Source
var ErrUnknownCurrency = errors.New("unknown Currency")
View Source
var ErrWrongCurrencyString = errors.New("wrong currency string")
Functions ¶
This section is empty.
Types ¶
type Amount ¶
type Amount struct {
// contains filtered or unexported fields
}
Amount stores fixed-precision decimal money. Stores integer number of cents for ISO 4217 currency. Values fit in ~92 quadrillion for 2 decimal currencies. Does not use float in printing nor parsing. Rounds down fractional cents during parsing. Blocking arithmetic operations that result in loss of precision.
Example ¶
package main
import (
"encoding/json"
"fmt"
"log"
_ "embed"
"github.com/nikolaydubina/fpmoney"
)
func main() {
var BuySP500Price = fpmoney.FromInt(9000, fpmoney.SGD)
input := []byte(`{"sp500": {"amount": 9000.02, "currency": "SGD"}}`)
type Stonks struct {
SP500 fpmoney.Amount `json:"sp500"`
}
var v Stonks
if err := json.Unmarshal(input, &v); err != nil {
log.Fatal(err)
}
amountToBuy := fpmoney.FromInt(0, fpmoney.SGD)
if v.SP500.GreaterThan(BuySP500Price) {
amountToBuy = amountToBuy.Add(v.SP500.Mul(2))
}
fmt.Println(amountToBuy)
}
Output: 18000.04 SGD
Example (Equality) ¶
package main
import (
"fmt"
_ "embed"
"github.com/nikolaydubina/fpmoney"
)
func main() {
x := fpmoney.FromInt(3, fpmoney.SGD)
y := fpmoney.FromInt(9, fpmoney.SGD)
fmt.Println(y == x.Mul(3))
}
Output: true
Example (Equality_same_currency) ¶
package main
import (
"fmt"
_ "embed"
"github.com/nikolaydubina/fpmoney"
)
func main() {
x := fpmoney.FromInt(10, fpmoney.SGD)
y := fpmoney.FromInt(10, fpmoney.SGD)
fmt.Println(y == x)
}
Output: true
Example (Equality_wrong_currency) ¶
package main
import (
"fmt"
_ "embed"
"github.com/nikolaydubina/fpmoney"
)
func main() {
x := fpmoney.FromInt(10, fpmoney.USD)
y := fpmoney.FromInt(10, fpmoney.SGD)
fmt.Println(y == x)
}
Output: false
func FromFloat ¶
Example ¶
package main
import (
"fmt"
_ "embed"
"github.com/nikolaydubina/fpmoney"
)
func main() {
x := fpmoney.FromFloat(144.96, fpmoney.SGD)
fmt.Println(x)
}
Output: 144.96 SGD
func FromIntScaled ¶
func (Amount) AppendBinary ¶ added in v1.4.0
func (Amount) Convert ¶ added in v1.4.0
Convert with rate=to/from
Example ¶
package main
import (
"fmt"
_ "embed"
"github.com/nikolaydubina/fpmoney"
)
func main() {
price := fpmoney.FromInt(100, fpmoney.USD)
fmt.Print(price.Convert(fpmoney.EUR, 0.85))
}
Output: 85 EUR
Example (Same) ¶
package main
import (
"fmt"
_ "embed"
"github.com/nikolaydubina/fpmoney"
)
func main() {
price := fpmoney.FromInt(100, fpmoney.USD)
fmt.Print(price.Convert(fpmoney.USD, 1234))
}
Output: 100 USD
func (Amount) DivMod ¶ added in v1.2.1
Example (Part) ¶
package main
import (
"fmt"
_ "embed"
"github.com/nikolaydubina/fpmoney"
)
func main() {
x := fpmoney.FromInt(1, fpmoney.SGD)
a, r := x.DivMod(3)
fmt.Println(a, r)
}
Output: 0.33 SGD 0.01 SGD
Example (Whole) ¶
package main
import (
"fmt"
_ "embed"
"github.com/nikolaydubina/fpmoney"
)
func main() {
x := fpmoney.FromInt(1, fpmoney.SGD)
a, r := x.DivMod(5)
fmt.Println(a, r)
}
Output: 0.2 SGD 0 SGD
func (Amount) GreaterThan ¶
func (Amount) GreaterThanOrEqual ¶
func (Amount) LessThanOrEqual ¶
func (Amount) MarshalBinary ¶ added in v1.4.0
func (Amount) MarshalJSON ¶
func (Amount) MulFraction ¶ added in v1.5.0
MulFraction multiplies by non-integer amount.
Example ¶
package main
import (
"fmt"
_ "embed"
"github.com/nikolaydubina/fpmoney"
)
func main() {
x := fpmoney.FromInt(3, fpmoney.SGD)
fmt.Println(x.MulFraction(1.5))
}
Output: 4.5 SGD
Example (Identity) ¶
package main
import (
"fmt"
_ "embed"
"github.com/nikolaydubina/fpmoney"
)
func main() {
x := fpmoney.FromInt(3, fpmoney.SGD)
fmt.Println(x.MulFraction(1))
}
Output: 3 SGD
Example (Negate) ¶
package main
import (
"fmt"
_ "embed"
"github.com/nikolaydubina/fpmoney"
)
func main() {
x := fpmoney.FromInt(3, fpmoney.SGD)
fmt.Println(x.MulFraction(-1))
}
Output: -3 SGD
Example (Whole) ¶
package main
import (
"fmt"
_ "embed"
"github.com/nikolaydubina/fpmoney"
)
func main() {
x := fpmoney.FromInt(2, fpmoney.SGD)
fmt.Println(x.MulFraction(2))
}
Output: 4 SGD
Example (Zero) ¶
package main
import (
"fmt"
_ "embed"
"github.com/nikolaydubina/fpmoney"
)
func main() {
x := fpmoney.FromInt(3, fpmoney.SGD)
fmt.Println(x.MulFraction(0))
}
Output: 0 SGD
func (Amount) Scaled ¶ added in v1.2.0
Example (Fractions) ¶
package main
import (
"fmt"
_ "embed"
"github.com/nikolaydubina/fpmoney"
)
func main() {
v := fpmoney.FromFloat(42.23, fpmoney.EUR)
fmt.Println(v.Scaled())
}
Output: 4223
Example (From_scaled) ¶
package main
import (
"fmt"
_ "embed"
"github.com/nikolaydubina/fpmoney"
)
func main() {
v := fpmoney.FromIntScaled(17, fpmoney.EUR)
fmt.Println(v.Scaled())
}
Output: 17
Example (Large) ¶
package main
import (
"fmt"
_ "embed"
"github.com/nikolaydubina/fpmoney"
)
func main() {
v := fpmoney.FromFloat(8764534896.42, fpmoney.USD)
fmt.Println(v.Scaled())
}
Output: 876453489642
Example (Many_fractions) ¶
package main
import (
"fmt"
_ "embed"
"github.com/nikolaydubina/fpmoney"
)
func main() {
v := fpmoney.FromFloat(17.0, fpmoney.BHD)
fmt.Println(v.Scaled())
}
Output: 17000
Example (Whole) ¶
package main
import (
"fmt"
_ "embed"
"github.com/nikolaydubina/fpmoney"
)
func main() {
v := fpmoney.FromFloat(23.0, fpmoney.EUR)
fmt.Println(v.Scaled())
}
Output: 2300
func (Amount) StringPair ¶ added in v1.3.1
Example ¶
package main
import (
"fmt"
_ "embed"
"github.com/nikolaydubina/fpmoney"
)
func main() {
amount := fpmoney.FromFloat(11.23, fpmoney.SGD)
amountStr, currencyStr := amount.StringPair()
fmt.Print(currencyStr, ":", amountStr)
}
Output: SGD:11.23
func (*Amount) UnmarshalBinary ¶ added in v1.4.0
func (*Amount) UnmarshalJSON ¶
UnmarshalJSON parses string. This is implemented directly for speed. Avoiding json.Decoder, interface{}, reflect, tags, temporary structs. Avoiding mallocs. Go json package provides: - check that pointer method receiver is not nil; - removes whitespace in b []bytes
type Currency ¶ added in v0.4.0
type Currency uint8
Currency is ISO 4217 without deprecated currencies.
- excluding currencies with 4+ minor units `CLF`, `UYW`
- excluding deprecated currencies `HRD`, `HRK`, `SLL`, `ZWL`
const ( UndefinedCurrency Currency = iota // AED // json:"AED" AFN // json:"AFN" ALL // json:"ALL" AMD // json:"AMD" ANG // json:"ANG" AOA // json:"AOA" ARS // json:"ARS" AUD // json:"AUD" AWG // json:"AWG" AZN // json:"AZN" BAM // json:"BAM" BBD // json:"BBD" BDT // json:"BDT" BGN // json:"BGN" BHD // json:"BHD" BIF // json:"BIF" BMD // json:"BMD" BND // json:"BND" BOB // json:"BOB" BOV // json:"BOV" BRL // json:"BRL" BSD // json:"BSD" BTN // json:"BTN" BWP // json:"BWP" BYN // json:"BYN" BZD // json:"BZD" CAD // json:"CAD" CDF // json:"CDF" CHE // json:"CHE" CHF // json:"CHF" CHW // json:"CHW" CLP // json:"CLP" CNY // json:"CNY" COP // json:"COP" COU // json:"COU" CRC // json:"CRC" CUP // json:"CUP" CVE // json:"CVE" CZK // json:"CZK" DJF // json:"DJF" DKK // json:"DKK" DOP // json:"DOP" DZD // json:"DZD" EGP // json:"EGP" ERN // json:"ERN" ETB // json:"ETB" EUR // json:"EUR" FJD // json:"FJD" FKP // json:"FKP" GBP // json:"GBP" GEL // json:"GEL" GHS // json:"GHS" GIP // json:"GIP" GMD // json:"GMD" GNF // json:"GNF" GTQ // json:"GTQ" GYD // json:"GYD" HKD // json:"HKD" HNL // json:"HNL" HRD // json:"HRD" HTG // json:"HTG" HUF // json:"HUF" IDR // json:"IDR" ILS // json:"ILS" INR // json:"INR" IQD // json:"IQD" IRR // json:"IRR" ISK // json:"ISK" JMD // json:"JMD" JOD // json:"JOD" JPY // json:"JPY" KES // json:"KES" KGS // json:"KGS" KHR // json:"KHR" KMF // json:"KMF" KPW // json:"KPW" KRW // json:"KRW" KWD // json:"KWD" KYD // json:"KYD" KZT // json:"KZT" LAK // json:"LAK" LBP // json:"LBP" LKR // json:"LKR" LRD // json:"LRD" LSL // json:"LSL" LYD // json:"LYD" MAD // json:"MAD" MDL // json:"MDL" MGA // json:"MGA" MKD // json:"MKD" MMK // json:"MMK" MNT // json:"MNT" MOP // json:"MOP" MRU // json:"MRU" MUR // json:"MUR" MVR // json:"MVR" MWK // json:"MWK" MXN // json:"MXN" MXV // json:"MXV" MYR // json:"MYR" MZN // json:"MZN" NAD // json:"NAD" NGN // json:"NGN" NIO // json:"NIO" NOK // json:"NOK" NPR // json:"NPR" NZD // json:"NZD" OMR // json:"OMR" PAB // json:"PAB" PEN // json:"PEN" PGK // json:"PGK" PHP // json:"PHP" PKR // json:"PKR" PLN // json:"PLN" PYG // json:"PYG" QAR // json:"QAR" RON // json:"RON" RSD // json:"RSD" RUB // json:"RUB" RWF // json:"RWF" SAR // json:"SAR" SBD // json:"SBD" SCR // json:"SCR" SDG // json:"SDG" SEK // json:"SEK" SGD // json:"SGD" SHP // json:"SHP" SLE // json:"SLE" SOS // json:"SOS" SRD // json:"SRD" SSP // json:"SSP" STN // json:"STN" SVC // json:"SVC" SYP // json:"SYP" SZL // json:"SZL" THB // json:"THB" TJS // json:"TJS" TMT // json:"TMT" TND // json:"TND" TOP // json:"TOP" TRY // json:"TRY" TTD // json:"TTD" TWD // json:"TWD" TZS // json:"TZS" UAH // json:"UAH" UGX // json:"UGX" USD // json:"USD" USN // json:"USN" UYI // json:"UYI" UYU // json:"UYU" UZS // json:"UZS" VED // json:"VED" VES // json:"VES" VND // json:"VND" VUV // json:"VUV" WST // json:"WST" XAF // json:"XAF" XAG // json:"XAG" XAU // json:"XAU" XBA // json:"XBA" XBB // json:"XBB" XBC // json:"XBC" XBD // json:"XBD" XCD // json:"XCD" XDR // json:"XDR" XOF // json:"XOF" XPD // json:"XPD" XPF // json:"XPF" XPT // json:"XPT" XSU // json:"XSU" XTS // json:"XTS" XUA // json:"XUA" XXX // json:"XXX" YER // json:"YER" ZAR // json:"ZAR" ZMW // json:"ZMW" ZWG // json:"ZWG" )
func (Currency) AppendText ¶ added in v1.3.0
func (Currency) MarshalText ¶ added in v0.4.0
Example ¶
for _, v := range []Currency{AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BOV, BRL, BSD, BTN, BWP, BYN, BZD, CAD, CDF, CHE, CHF, CHW, CLP, CNY, COP, COU, CRC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRD, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRU, MUR, MVR, MWK, MXN, MXV, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLE, SOS, SRD, SSP, STN, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, USN, UYI, UYU, UZS, VED, VES, VND, VUV, WST, XAF, XAG, XAU, XBA, XBB, XBC, XBD, XCD, XDR, XOF, XPD, XPF, XPT, XSU, XTS, XUA, XXX, YER, ZAR, ZMW, ZWG} {
b, _ := v.MarshalText()
fmt.Printf("%s ", string(b))
}
Output: AED AFN ALL AMD ANG AOA ARS AUD AWG AZN BAM BBD BDT BGN BHD BIF BMD BND BOB BOV BRL BSD BTN BWP BYN BZD CAD CDF CHE CHF CHW CLP CNY COP COU CRC CUP CVE CZK DJF DKK DOP DZD EGP ERN ETB EUR FJD FKP GBP GEL GHS GIP GMD GNF GTQ GYD HKD HNL HRD HTG HUF IDR ILS INR IQD IRR ISK JMD JOD JPY KES KGS KHR KMF KPW KRW KWD KYD KZT LAK LBP LKR LRD LSL LYD MAD MDL MGA MKD MMK MNT MOP MRU MUR MVR MWK MXN MXV MYR MZN NAD NGN NIO NOK NPR NZD OMR PAB PEN PGK PHP PKR PLN PYG QAR RON RSD RUB RWF SAR SBD SCR SDG SEK SGD SHP SLE SOS SRD SSP STN SVC SYP SZL THB TJS TMT TND TOP TRY TTD TWD TZS UAH UGX USD USN UYI UYU UZS VED VES VND VUV WST XAF XAG XAU XBA XBB XBC XBD XCD XDR XOF XPD XPF XPT XSU XTS XUA XXX YER ZAR ZMW ZWG
func (*Currency) UnmarshalText ¶ added in v0.4.0
Example ¶
for _, s := range []string{"AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BOV", "BRL", "BSD", "BTN", "BWP", "BYN", "BZD", "CAD", "CDF", "CHE", "CHF", "CHW", "CLP", "CNY", "COP", "COU", "CRC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "EUR", "FJD", "FKP", "GBP", "GEL", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HRD", "HTG", "HUF", "IDR", "ILS", "INR", "IQD", "IRR", "ISK", "JMD", "JOD", "JPY", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRU", "MUR", "MVR", "MWK", "MXN", "MXV", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLE", "SOS", "SRD", "SSP", "STN", "SVC", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "UGX", "USD", "USN", "UYI", "UYU", "UZS", "VED", "VES", "VND", "VUV", "WST", "XAF", "XAG", "XAU", "XBA", "XBB", "XBC", "XBD", "XCD", "XDR", "XOF", "XPD", "XPF", "XPT", "XSU", "XTS", "XUA", "XXX", "YER", "ZAR", "ZMW", "ZWG"} {
var v Currency
if err := (&v).UnmarshalText([]byte(s)); err != nil {
fmt.Println(err)
}
}
type ErrCurrencyMismatch ¶
type ErrCurrencyMismatch struct {
A, B Currency
}
func NewErrCurrencyMismatch ¶
func NewErrCurrencyMismatch() *ErrCurrencyMismatch
func (*ErrCurrencyMismatch) Error ¶
func (e *ErrCurrencyMismatch) Error() string
Source Files
Click to show internal directories.
Click to hide internal directories.