README
¶
Money
GoMoney provides ability to work with monetary value using a currency's smallest unit. Package allows you to use basic Money operations like rounding, splitting or allocating without losing a penny. You shouldn't use float for monetary values, since they always carry small rounding differences.
package main
import "github.com/rhymond/go-money"
func main() {
pound := money.New(100, "GBP")
twoPounds := pound.Add(pound)
parties, _ := twoPounds.Split(3)
parties[0].Display() // £0.67
parties[1].Display() // £0.67
parties[2].Display() // £0.66
}
Quick start
Get the package via
$ go get github.com/rhymond/go-money
Features
- Provides a Money struct which stores information about an Money amount value and it's currency.
- Provides a
Money.Amountstruct 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.Currencyinstances providing a high level of flexibility.
Usage
Instantiation
Initialise Money by using smallest unit value (e.g 100 represents 1 pound). Use ISO 4217 Currency Code to set money Currency
pound := money.New(100, "GBP")
Comparison
Go-money lets you to use base compare operations like:
- Equals
- GreaterThan
- GreaterThanOrEqual
- LessThan
- LessThanOrEqual
In order to use them currencies must be equal
pound := money.New(100, "GBP")
twoPounds := money.New(200, "GBP")
twoEuros := money.New(200, "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 zero use IsZero()
pound := money.New(100, "GBP")
result := pound.IsZero(pound) // false
Positive value
To assert if Money value is more than zero IsPositive()
pound := money.New(100, "GBP")
pound.IsPositive(pound) // true
Negative value
To assert if Money value is less than zero IsNegative()
pound := money.New(100, "GBP")
pound.IsNegative(pound) // false
Operations
- Add
- Subtract
- Divide
- Multiply
- Absolute
- Negative
In Order to use operations between Money structures Currencies must be equal
Addition
Additions can be performed using Add().
pound := money.New(100, "GBP")
twoPounds := money.New(200, "GBP")
result, err := pound.Add(twoPounds).Display() // £3.00, nil
Subtraction
Subtraction can be performed using Subtract().
pound := money.New(100, "GBP")
twoPounds := money.New(200, "GBP")
result, err := pound.Subtract(twoPounds).Display() // -£3.00, nil
Multiplication
Multiplication can be performed using Multiply().
pound := money.New(100, "GBP")
result, err := pound.Multiply(2).Display() // £4.00, nil
Division
Division can be performed using Divide().
pound := money.New(100, "GBP")
result, err := pound.Divide(2).Display() // £4.00, nil
There is possibilities to lose pennies by using division operation e.g:
money.New(100, "GBP").Divide(3).Display() // £0.33
In order to split amount without losing pennies use Split() operation.
Absolute
Return absolute value of Money structure
pound := money.New(-100, "GBP")
result, err := pound.Absolute().Display() // £1.00
Negative
Return negative value of Money structure
pound := money.New(100, "GBP")
result, err := pound.Negative().Display() // -£1.00
Allocation
- Split
- Allocate
Splitting
In order to split Money for parties without losing any penny 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, "GBP")
parties, err := pound.Split(3)
parties[0].Display() // £0.34
parties[1].Display() // £0.33
parties[2].Display() // £0.33
Allocation
To perform allocation operation use Allocate().
It lets split money by given ratios without losing pennies and as Split operations distributes leftover pennies amongst the parties with round-robin principle.
pound := money.New(100, "GBP")
parties, err := pound.Split([]int{33, 33, 33})
parties[0].Display() // £0.34
parties[1].Display() // £0.33
parties[2].Display() // £0.33
Format
To format and return Money as string use Display().
money.New(123456789, "EUR").Display() // €1,234,567.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 ¶
- type Formatter
- type Money
- func (m *Money) Absolute() *Money
- func (m *Money) Add(om *Money) *Money
- func (m *Money) Allocate(rs []int) ([]*Money, error)
- func (m *Money) Display() (string, error)
- func (m *Money) Divide(div int) *Money
- 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) Multiply(mul int) *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
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Formatter ¶
type Formatter struct {
Fraction int
Decimal string
Thousand string
Grapheme string
Template string
}
Formatter stores Money formatting information
func NewFormatter ¶
NewFormatter creates new Formatter instance
type Money ¶
type Money struct {
// contains filtered or unexported fields
}
Money stores money information
func (*Money) Absolute ¶
Absolute returns new Money struct from given Money using absolute monetary value
func (*Money) Add ¶
Add returns new Money struct with value representing sum of Self and Other Money
func (*Money) Allocate ¶
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) Display ¶ added in v0.1.0
Display lets represent Money struct as string in given Currency value
func (*Money) Divide ¶
Divide returns new Money struct with value representing Self division value by given divider
func (*Money) GreaterThan ¶
GreaterThan checks whether the value of Money is greater than the other
func (*Money) GreaterThanOrEqual ¶
GreaterThanOrEqual checks whether the value of Money is greater or equal than the other
func (*Money) IsNegative ¶
IsNegative returns boolean of whether the value of Money is negative
func (*Money) IsPositive ¶
IsPositive returns boolean of whether the value of Money is positive
func (*Money) LessThanOrEqual ¶
LessThanOrEqual checks whether the value of Money is less or equal than the other
func (*Money) Multiply ¶
Multiply returns new Money struct with value representing Self multiplied value by multiplier
func (*Money) Negative ¶
Negative returns new Money struct from given Money using negative monetary value
func (*Money) SameCurrency ¶
SameCurrency check if given Money is equals by currency
Source Files