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 (
  "log"

  "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)

Or initialize Money using the direct amount.

quarterEuro := money.NewFromFloat(0.25, money.EUR)

Comparison

Go-money provides base compare operations like:

• Equals
• GreaterThan
• GreaterThanOrEqual
• LessThan
• LessThanOrEqual
• Compare

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
twoPounds.Compare(pound) // 1, nil
pound.Compare(twoPounds) // -1, nil
pound.Compare(pound) // 0, nil
pound.Compare(twoEuros) // pound.amount, ErrCurrencyMismatch

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() // false

Positive value

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

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

Negative value

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

pound := money.New(100, money.GBP)
pound.IsNegative() // 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 Currencies
  • func (c Currencies) Add(currency *Currency) Currencies
  • func (c Currencies) CurrencyByCode(code string) *Currency
  • func (c Currencies) CurrencyByNumericCode(code string) *Currency
• type Currency
  • func AddCurrency(code, Grapheme, Template, Decimal, Thousand string, Fraction int) *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 NewFromFloat(amount float64, currency 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) Compare(om *Money) (int, error)
  • 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

Examples

• Money
• Money (Comparisons)
• Money.Absolute
• Money.Add
• Money.Allocate
• Money.AsMajorUnits
• Money.Display
• Money.IsNegative
• Money.IsPositive
• Money.IsZero
• Money.Multiply
• Money.Split
• Money.Subtract
• New

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"
	MGA = "MGA"
	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"
	VES = "VES"
	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"
	ZWD = "ZWD"
	ZWL = "ZWL"
)

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

Variables

var (
	// UnmarshalJSON is injection point of json.Unmarshaller for money.Money
	UnmarshalJSON = defaultUnmarshalJSON
	// MarshalJSON 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")

	// ErrInvalidJSONUnmarshal happens when the default money.UnmarshalJSON fails to unmarshal Money because of invalid data.
	ErrInvalidJSONUnmarshal = errors.New("invalid json unmarshal")
)

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) { ... }

Types

type Amount

type Amount = int64

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

type Currencies

type Currencies map[string]*Currency

func (Currencies) Add

func (c Currencies) Add(currency *Currency) Currencies

Add updates currencies list by adding a given Currency to it.

func (Currencies) CurrencyByCode

func (c Currencies) CurrencyByCode(code string) *Currency

CurrencyByCode returns the currency given the currency code defined as a constant.

func (Currencies) CurrencyByNumericCode

func (c Currencies) CurrencyByNumericCode(code string) *Currency

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

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 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.

Example

package main

import (
	"fmt"
	"log"

	"github.com/Agustincou/go-money"
)

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

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

	parties, err := twoPounds.Split(3)

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

	fmt.Println(parties[0].Display())
	fmt.Println(parties[1].Display())
	fmt.Println(parties[2].Display())

}

Output:
£0.67
£0.67
£0.66

Example (Comparisons)

package main

import (
	"fmt"

	"github.com/Agustincou/go-money"
)

func main() {
	pound := money.New(100, "GBP")
	twoPounds := money.New(200, "GBP")
	twoEuros := money.New(200, "EUR")

	gt, err := pound.GreaterThan(twoPounds)
	fmt.Println(gt, err)

	lt, err := pound.LessThan(twoPounds)
	fmt.Println(lt, err)

	eq, err := twoPounds.Equals(twoEuros)
	fmt.Println(eq, err)

}

Output:
false <nil>
true <nil>
false currencies don't match

func New

func New(amount int64, code string) *Money

New creates and returns new instance of Money.

Example

package main

import (
	"fmt"

	"github.com/Agustincou/go-money"
)

func main() {
	pound := money.New(100, "GBP")

	fmt.Println(pound.Display())

}

Output:
£1.00

func NewFromFloat

func NewFromFloat(amount float64, currency string) *Money

NewFromFloat creates and returns new instance of Money from a float64. Banking standard rounding. Example 1.455 = 1.46

func (*Money) Absolute

func (m *Money) Absolute() *Money

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

Example

package main

import (
	"fmt"

	"github.com/Agustincou/go-money"
)

func main() {
	pound := money.New(-100, "GBP")

	result := pound.Absolute()
	fmt.Println(result.Display())

}

Output:
£1.00

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.

Example

package main

import (
	"fmt"

	"github.com/Agustincou/go-money"
)

func main() {
	pound := money.New(100, "GBP")
	twoPounds := money.New(200, "GBP")

	result, err := pound.Add(twoPounds)
	fmt.Println(result.Display(), err)

}

Output:
£3.00 <nil>

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.

Example

package main

import (
	"fmt"
	"log"

	"github.com/Agustincou/go-money"
)

func main() {
	pound := money.New(100, "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)
	}

	fmt.Println(parties[0].Display())
	fmt.Println(parties[1].Display())
	fmt.Println(parties[2].Display())

}

Output:
£0.34
£0.33
£0.33

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

Example

package main

import (
	"fmt"

	"github.com/Agustincou/go-money"
)

func main() {
	result := money.New(123456789, "EUR").AsMajorUnits()
	fmt.Printf("%.2f", result)

}

Output:
1234567.89

func (*Money) Compare

func (m *Money) Compare(om *Money) (int, error)

Compare function compares two money of the same type

if m.amount > om.amount returns (1, nil)
if m.amount == om.amount returns (0, nil
if m.amount < om.amount returns (-1, nil)

If compare moneys from distinct currency, return (m.amount, ErrCurrencyMismatch)

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.

Example

package main

import (
	"fmt"

	"github.com/Agustincou/go-money"
)

func main() {
	fmt.Println(money.New(123456789, "EUR").Display())

}

Output:
€1,234,567.89

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.

Example

package main

import (
	"fmt"

	"github.com/Agustincou/go-money"
)

func main() {
	pound := money.New(100, "GBP")
	fmt.Println(pound.IsNegative())

}

Output:
false

func (*Money) IsPositive

func (m *Money) IsPositive() bool

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

Example

package main

import (
	"fmt"

	"github.com/Agustincou/go-money"
)

func main() {
	pound := money.New(100, "GBP")
	fmt.Println(pound.IsPositive())

}

Output:
true

func (*Money) IsZero

func (m *Money) IsZero() bool

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

Example

package main

import (
	"fmt"

	"github.com/Agustincou/go-money"
)

func main() {
	pound := money.New(100, "GBP")
	fmt.Println(pound.IsZero())

}

Output:
false

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.

Example

package main

import (
	"fmt"

	"github.com/Agustincou/go-money"
)

func main() {
	pound := money.New(100, "GBP")

	result := pound.Multiply(2)
	fmt.Println(result.Display())

}

Output:
£2.00

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.

Example

package main

import (
	"fmt"
	"log"

	"github.com/Agustincou/go-money"
)

func main() {
	pound := money.New(100, "GBP")
	parties, err := pound.Split(3)

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

	fmt.Println(parties[0].Display())
	fmt.Println(parties[1].Display())
	fmt.Println(parties[2].Display())

}

Output:
£0.34
£0.33
£0.33

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.

Example

package main

import (
	"fmt"

	"github.com/Agustincou/go-money"
)

func main() {
	pound := money.New(100, "GBP")
	twoPounds := money.New(200, "GBP")

	result, err := pound.Subtract(twoPounds)
	fmt.Println(result.Display(), err)

}

Output:
-£1.00 <nil>

func (*Money) UnmarshalJSON

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

UnmarshalJSON is implementation of json.Unmarshaller