money

README

Money

GoMoney provides ability to work with monetary value using a currency's smallest unit. This package provides basic and precise Money operations such as rounding, splitting and allocating. Monetary values should not be stored as floats due to small rounding differences.

package main

import "github.com/Rhymond/go-money"

func main() {
    pound := money.New(100, money.GBP)
    twoPounds, err := pound.Add(pound)

    if err != nil {
        log.Fatal(err)
    }

    parties, err := twoPounds.Split(3)

    if err != nil {
        log.Fatal(err)
    }

    parties[0].Display() // £0.67
    parties[1].Display() // £0.67
    parties[2].Display() // £0.66
}

Quick start

Get the package:

$ go get github.com/Rhymond/go-money

Features

• Provides a Money struct which stores information about an Money amount value and its currency.
• Provides a Money.Amount struct which encapsulates all information about a monetary unit.
• Represents monetary values as integers, in cents. This avoids floating point rounding errors.
• Represents currency as Money.Currency instances providing a high level of flexibility.

Usage

Initialization

Initialize Money by using smallest unit value (e.g 100 represents 1 pound). Use ISO 4217 Currency Code to set money Currency. Note that constants are also provided for all ISO 4217 currency codes.

pound := money.New(100, money.GBP)

Comparison

Go-money provides base compare operations like:

• Equals
• GreaterThan
• GreaterThanOrEqual
• LessThan
• LessThanOrEqual

Comparisons must be made between the same currency units.

pound := money.New(100, money.GBP)
twoPounds := money.New(200, money.GBP)
twoEuros := money.New(200, money.EUR)

pound.GreaterThan(twoPounds) // false, nil
pound.LessThan(twoPounds) // true, nil
twoPounds.Equals(twoEuros) // false, error: Currencies don't match

Asserts

• IsZero
• IsNegative
• IsPositive

Zero value

To assert if Money value is equal to zero use IsZero()

pound := money.New(100, money.GBP)
result := pound.IsZero(pound) // false

Positive value

To assert if Money value is more than zero use IsPositive()

pound := money.New(100, money.GBP)
pound.IsPositive(pound) // true

Negative value

To assert if Money value is less than zero use IsNegative()

pound := money.New(100, money.GBP)
pound.IsNegative(pound) // false

Operations

• Add
• Subtract
• Multiply
• Absolute
• Negative

Comparisons must be made between the same currency units.

Addition

Additions can be performed using Add().

pound := money.New(100, money.GBP)
twoPounds := money.New(200, money.GBP)

result, err := pound.Add(twoPounds) // £3.00, nil

Subtraction

Subtraction can be performed using Subtract().

pound := money.New(100, money.GBP)
twoPounds := money.New(200, money.GBP)

result, err := pound.Subtract(twoPounds) // -£1.00, nil

Multiplication

Multiplication can be performed using Multiply().

pound := money.New(100, money.GBP)

result := pound.Multiply(2) // £2.00

Absolute

Return absolute value of Money structure

pound := money.New(-100, money.GBP)

result := pound.Absolute() // £1.00

Negative

Return negative value of Money structure

pound := money.New(100, money.GBP)

result := pound.Negative() // -£1.00

Allocation

• Split
• Allocate

Splitting

In order to split Money for parties without losing any pennies due to rounding differences, use Split().

After division leftover pennies will be distributed round-robin amongst the parties. This means that parties listed first will likely receive more pennies than ones that are listed later.

pound := money.New(100, money.GBP)
parties, err := pound.Split(3)

if err != nil {
    log.Fatal(err)
}

parties[0].Display() // £0.34
parties[1].Display() // £0.33
parties[2].Display() // £0.33

Allocation

To perform allocation operation use Allocate().

It splits money using the given ratios without losing pennies and as Split operations distributes leftover pennies amongst the parties with round-robin principle.

pound := money.New(100, money.GBP)
// Allocate is variadic function which can receive ratios as
// slice (int[]{33, 33, 33}...) or separated by a comma integers
parties, err := pound.Allocate(33, 33, 33)

if err != nil {
    log.Fatal(err)
}

parties[0].Display() // £0.34
parties[1].Display() // £0.33
parties[2].Display() // £0.33

Format

To format and return Money as a string use Display().

money.New(123456789, money.EUR).Display() // €1,234,567.89

To format and return Money as a float64 representing the amount value in the currency's subunit use AsMajorUnits().

money.New(123456789, money.EUR).AsMajorUnits() // 1234567.89

Contributing

Thank you for considering contributing! Please use GitHub issues and Pull Requests for contributing.

License

The MIT License (MIT). Please see License File for more information.

Documentation

Index

• Constants
• Variables
• type Amount
• type Currency
  • func AddCurrency(code, Grapheme, Template, Decimal, Thousand string, Fraction int) *Currency
  • func CurrencyByNumericCode(code string) *Currency
  • func GetCurrency(code string) *Currency
  • func (c *Currency) Formatter() *Formatter
• type Formatter
  • func NewFormatter(fraction int, decimal, thousand, grapheme, template string) *Formatter
  • func (f *Formatter) Format(amount int64) string
  • func (f *Formatter) ToMajorUnits(amount int64) float64
• type Money
  • func New(amount int64, code string) *Money
  • func (m *Money) Absolute() *Money
  • func (m *Money) Add(om *Money) (*Money, error)
  • func (m *Money) Allocate(rs ...int) ([]*Money, error)
  • func (m *Money) Amount() int64
  • func (m *Money) AsMajorUnits() float64
  • func (m *Money) Currency() *Currency
  • func (m *Money) Display() string
  • func (m *Money) Equals(om *Money) (bool, error)
  • func (m *Money) GreaterThan(om *Money) (bool, error)
  • func (m *Money) GreaterThanOrEqual(om *Money) (bool, error)
  • func (m *Money) IsNegative() bool
  • func (m *Money) IsPositive() bool
  • func (m *Money) IsZero() bool
  • func (m *Money) LessThan(om *Money) (bool, error)
  • func (m *Money) LessThanOrEqual(om *Money) (bool, error)
  • func (m Money) MarshalJSON() ([]byte, error)
  • func (m *Money) Multiply(mul int64) *Money
  • func (m *Money) Negative() *Money
  • func (m *Money) Round() *Money
  • func (m *Money) SameCurrency(om *Money) bool
  • func (m *Money) Split(n int) ([]*Money, error)
  • func (m *Money) Subtract(om *Money) (*Money, error)
  • func (m *Money) UnmarshalJSON(b []byte) error

Constants

const (
	AED = "AED"
	AFN = "AFN"
	ALL = "ALL"
	AMD = "AMD"
	ANG = "ANG"
	AOA = "AOA"
	ARS = "ARS"
	AUD = "AUD"
	AWG = "AWG"
	AZN = "AZN"
	BAM = "BAM"
	BBD = "BBD"
	BDT = "BDT"
	BGN = "BGN"
	BHD = "BHD"
	BIF = "BIF"
	BMD = "BMD"
	BND = "BND"
	BOB = "BOB"
	BRL = "BRL"
	BSD = "BSD"
	BTN = "BTN"
	BWP = "BWP"
	BYN = "BYN"
	BYR = "BYR"
	BZD = "BZD"
	CAD = "CAD"
	CDF = "CDF"
	CHF = "CHF"
	CLF = "CLF"
	CLP = "CLP"
	CNY = "CNY"
	COP = "COP"
	CRC = "CRC"
	CUC = "CUC"
	CUP = "CUP"
	CVE = "CVE"
	CZK = "CZK"
	DJF = "DJF"
	DKK = "DKK"
	DOP = "DOP"
	DZD = "DZD"
	EEK = "EEK"
	EGP = "EGP"
	ERN = "ERN"
	ETB = "ETB"
	EUR = "EUR"
	FJD = "FJD"
	FKP = "FKP"
	GBP = "GBP"
	GEL = "GEL"
	GGP = "GGP"
	GHC = "GHC"
	GHS = "GHS"
	GIP = "GIP"
	GMD = "GMD"
	GNF = "GNF"
	GTQ = "GTQ"
	GYD = "GYD"
	HKD = "HKD"
	HNL = "HNL"
	HRK = "HRK"
	HTG = "HTG"
	HUF = "HUF"
	IDR = "IDR"
	ILS = "ILS"
	IMP = "IMP"
	INR = "INR"
	IQD = "IQD"
	IRR = "IRR"
	ISK = "ISK"
	JEP = "JEP"
	JMD = "JMD"
	JOD = "JOD"
	JPY = "JPY"
	KES = "KES"
	KGS = "KGS"
	KHR = "KHR"
	KMF = "KMF"
	KPW = "KPW"
	KRW = "KRW"
	KWD = "KWD"
	KYD = "KYD"
	KZT = "KZT"
	LAK = "LAK"
	LBP = "LBP"
	LKR = "LKR"
	LRD = "LRD"
	LSL = "LSL"
	LTL = "LTL"
	LVL = "LVL"
	LYD = "LYD"
	MAD = "MAD"
	MDL = "MDL"
	MKD = "MKD"
	MMK = "MMK"
	MNT = "MNT"
	MOP = "MOP"
	MUR = "MUR"
	MVR = "MVR"
	MWK = "MWK"
	MXN = "MXN"
	MYR = "MYR"
	MZN = "MZN"
	NAD = "NAD"
	NGN = "NGN"
	NIO = "NIO"
	NOK = "NOK"
	NPR = "NPR"
	NZD = "NZD"
	OMR = "OMR"
	PAB = "PAB"
	PEN = "PEN"
	PGK = "PGK"
	PHP = "PHP"
	PKR = "PKR"
	PLN = "PLN"
	PYG = "PYG"
	QAR = "QAR"
	RON = "RON"
	RSD = "RSD"
	RUB = "RUB"
	RUR = "RUR"
	RWF = "RWF"
	SAR = "SAR"
	SBD = "SBD"
	SCR = "SCR"
	SDG = "SDG"
	SEK = "SEK"
	SGD = "SGD"
	SHP = "SHP"
	SKK = "SKK"
	SLL = "SLL"
	SOS = "SOS"
	SRD = "SRD"
	SSP = "SSP"
	STD = "STD"
	SVC = "SVC"
	SYP = "SYP"
	SZL = "SZL"
	THB = "THB"
	TJS = "TJS"
	TMT = "TMT"
	TND = "TND"
	TOP = "TOP"
	TRL = "TRL"
	TRY = "TRY"
	TTD = "TTD"
	TWD = "TWD"
	TZS = "TZS"
	UAH = "UAH"
	UGX = "UGX"
	USD = "USD"
	UYU = "UYU"
	UZS = "UZS"
	VEF = "VEF"
	VND = "VND"
	VUV = "VUV"
	WST = "WST"
	XAF = "XAF"
	XAG = "XAG"
	XAU = "XAU"
	XCD = "XCD"
	XDR = "XDR"
	XOF = "XOF"
	XPF = "XPF"
	YER = "YER"
	ZAR = "ZAR"
	ZMW = "ZMW"
	BOV = "BOV"
	COU = "COU"
	MGA = "MGA"
	MRU = "MRU"
	XUA = "XUA"
	MXV = "MXV"
	STN = "STN"
	XSU = "XSU"
	CHE = "CHE"
	CHW = "CHW"
	USN = "USN"
	UYI = "UYI"
	UYW = "UYW"
	VES = "VES"
	VED = "VED"
	ZWL = "ZWL"
	ZWD = "ZWD"
	XBA = "XBA"
	XBB = "XBB"
	XBC = "XBC"
	XBD = "XBD"
	XTS = "XTS"
	XXX = "XXX"
	XPD = "XPD"
	XPT = "XPT"
)

Constants for active currency codes according to the ISO 4217 standard.

Variables

var (
	// UnmarshalJSONFunc is injection point of json.Unmarshaller for money.Money
	UnmarshalJSON = defaultUnmarshalJSON
	// MarshalJSONFunc is injection point of json.Marshaller for money.Money
	MarshalJSON = defaultMarshalJSON

	// ErrCurrencyMismatch happens when two compared Money don't have the same currency.
	ErrCurrencyMismatch = errors.New("currencies don't match")
)

Injection points for backward compatibility. If you need to keep your JSON marshal/unmarshal way, overwrite them like below.

money.UnmarshalJSON = func (m *Money, b []byte) error { ... }
money.MarshalJSON = func (m Money) ([]byte, error) { ... }

var (
	// ErrCurrencyNotFound happens when it wasn't possible to find the currency by the given parameter.
	ErrCurrencyNotFound = errors.New("currency not found")
)

Types

type Amount

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

Amount is a datastructure that stores the amount being used for calculations.

type Currency

type Currency struct {
	Code        string
	NumericCode string
	Fraction    int
	Grapheme    string
	Template    string
	Decimal     string
	Thousand    string
}

Currency represents money currency information required for formatting.

func AddCurrency

func AddCurrency(code, Grapheme, Template, Decimal, Thousand string, Fraction int) *Currency

AddCurrency lets you insert or update currency in currencies list.

func CurrencyByNumericCode

func CurrencyByNumericCode(code string) *Currency

CurrencyByNumericCode returns the currency given the numeric code defined in ISO-4271.

func GetCurrency

func GetCurrency(code string) *Currency

GetCurrency returns the currency given the code.

func (*Currency) Formatter

func (c *Currency) Formatter() *Formatter

Formatter returns currency formatter representing used currency structure.

type Formatter

type Formatter struct {
	Fraction int
	Decimal  string
	Thousand string
	Grapheme string
	Template string
}

Formatter stores Money formatting information.

func NewFormatter

func NewFormatter(fraction int, decimal, thousand, grapheme, template string) *Formatter

NewFormatter creates new Formatter instance.

func (*Formatter) Format

func (f *Formatter) Format(amount int64) string

Format returns string of formatted integer using given currency template.

func (*Formatter) ToMajorUnits

func (f *Formatter) ToMajorUnits(amount int64) float64

ToMajorUnits returns float64 representing the value in sub units using the currency data

type Money

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

Money represents monetary value information, stores currency and amount value.

func New

func New(amount int64, code string) *Money

New creates and returns new instance of Money.

func (*Money) Absolute

func (m *Money) Absolute() *Money

Absolute returns new Money struct from given Money using absolute monetary value.

func (*Money) Add

func (m *Money) Add(om *Money) (*Money, error)

Add returns new Money struct with value representing sum of Self and Other Money.

func (*Money) Allocate

func (m *Money) Allocate(rs ...int) ([]*Money, error)

Allocate returns slice of Money structs with split Self value in given ratios. It lets split money by given ratios without losing pennies and as Split operations distributes leftover pennies amongst the parties with round-robin principle.

func (*Money) Amount

func (m *Money) Amount() int64

Amount returns a copy of the internal monetary value as an int64.

func (*Money) AsMajorUnits

func (m *Money) AsMajorUnits() float64

AsMajorUnits lets represent Money struct as subunits (float64) in given Currency value

func (*Money) Currency

func (m *Money) Currency() *Currency

Currency returns the currency used by Money.

func (*Money) Display

func (m *Money) Display() string

Display lets represent Money struct as string in given Currency value.

func (*Money) Equals

func (m *Money) Equals(om *Money) (bool, error)

Equals checks equality between two Money types.

func (*Money) GreaterThan

func (m *Money) GreaterThan(om *Money) (bool, error)

GreaterThan checks whether the value of Money is greater than the other.

func (*Money) GreaterThanOrEqual

func (m *Money) GreaterThanOrEqual(om *Money) (bool, error)

GreaterThanOrEqual checks whether the value of Money is greater or equal than the other.

func (*Money) IsNegative

func (m *Money) IsNegative() bool

IsNegative returns boolean of whether the value of Money is negative.

func (*Money) IsPositive

func (m *Money) IsPositive() bool

IsPositive returns boolean of whether the value of Money is positive.

func (*Money) IsZero

func (m *Money) IsZero() bool

IsZero returns boolean of whether the value of Money is equals to zero.

func (*Money) LessThan

func (m *Money) LessThan(om *Money) (bool, error)

LessThan checks whether the value of Money is less than the other.

func (*Money) LessThanOrEqual

func (m *Money) LessThanOrEqual(om *Money) (bool, error)

LessThanOrEqual checks whether the value of Money is less or equal than the other.

func (Money) MarshalJSON

func (m Money) MarshalJSON() ([]byte, error)

MarshalJSON is implementation of json.Marshaller

func (*Money) Multiply

func (m *Money) Multiply(mul int64) *Money

Multiply returns new Money struct with value representing Self multiplied value by multiplier.

func (*Money) Negative

func (m *Money) Negative() *Money

Negative returns new Money struct from given Money using negative monetary value.

func (*Money) Round

func (m *Money) Round() *Money

Round returns new Money struct with value rounded to nearest zero.

func (*Money) SameCurrency

func (m *Money) SameCurrency(om *Money) bool

SameCurrency check if given Money is equals by currency.

func (*Money) Split

func (m *Money) Split(n int) ([]*Money, error)

Split returns slice of Money structs with split Self value in given number. After division leftover pennies will be distributed round-robin amongst the parties. This means that parties listed first will likely receive more pennies than ones that are listed later.

func (*Money) Subtract

func (m *Money) Subtract(om *Money) (*Money, error)

Subtract returns new Money struct with value representing difference of Self and Other Money.

func (*Money) UnmarshalJSON

func (m *Money) UnmarshalJSON(b []byte) error

UnmarshalJSON is implementation of json.Unmarshaller