trader

README

trader

Trader takes charge of the amounts handling and currency conversions. It makes operations on amounts in different currencies easy to perform, and uses arbitrary-precision fixed-point decimal numbers.

Installation

go get gopkg.in/processout/trader.v2

Usage

• All ISO 4217 currencies are supported, and they can be found in currency-list.go
• Error handling isn't included here for brevity's sake
• It makes sense that your base currency should always have a comparative value of 1
• Take a look at example_test.go for more examples

import "gopkg.in/processout/trader.v2"

// We first want to define the currencies we support
usd, _ := trader.NewCurrency("USD", decimal.NewFromFloat(1)) // Will be base currency
eur, _ := trader.NewCurrency("eur", decimal.NewFromFloat(0.8))

// We add them to the list
currencies := trader.Currencies{usd, eur}

// We may now create our trader, and set its base currency to the US dollar
t, _ := trader.New(currencies, "usd")

// Now that we have our trader, we can create amounts
amount, _ := t.NewAmount(decimal.NewFromFloat(42.42), "USD")
// or amount, _ := t.NewAmountFromString("42.42", "USD")
// or amount, _ := t.NewAmountFromFloat(42.42, "USD")

// With this amount, we can now do currency conversions
amountEUR, _ := amount.ToCurrency("EUR") // = "33.936"

// We could also add two amounts with different currencies
USDPlusEUR, _ := amount.Add(amountEUR)

// The result is:
// USD(42.42) + EUR(33.936) == USD(42.42) + USD(42.42) = USD(84.84)
fmt.Println(USDPlusEUR.String(2)) // Prints 84.84

Notes

Trader uses the package github.com/processout/decimal to perform its arbitrary-precision calculations.

Documentation

Overview

Package trader takes charge of the amounts handling and currency conversions.

Example

// We first want to define the currencies we support
usd, _ := NewCurrency("USD", decimal.NewFromFloat(1)) // Will be base currency
eur, _ := NewCurrency("eur", decimal.NewFromFloat(0.8))

// We add them to the list
currencies := Currencies{usd, eur}

// We may now create our trader, and set its base currency to the US dollar
t, _ := New(currencies, "usd")

// Now that we have our trader, we can create amounts
amount, _ := t.NewAmount(decimal.NewFromFloat(42.42), "USD")
// or amount, _ := NewAmountFromString("42.42", "USD")
// or amount, _ := NewAmountFromFloat(42.42, "USD")

// With this amount, we can now do currency conversions
amountEUR, _ := amount.ToCurrency("EUR") // = "33.936"

// We could also add two amounts with different currencies
USDPlusEUR, _ := amount.Add(amountEUR)

// The result is:
// USD(42.42) + EUR(33.936) == USD(42.42) + USD(42.42) = USD(84.84)
fmt.Println(USDPlusEUR.String(2)) // Prints 84.84

Index

• func ValidCurrencies() map[CurrencyCode]CurrencyInformation
• type Amount
  • func (a Amount) Add(b Amount) (Amount, error)
  • func (a Amount) Cmp(b Amount) (int, error)
  • func (a Amount) Int64() int64
  • func (a Amount) IsEmpty() bool
  • func (a Amount) RateTo(code CurrencyCode) (decimal.Decimal, error)
  • func (a Amount) String(decimals int32) string
  • func (a Amount) Sub(b Amount) (Amount, error)
  • func (a Amount) ToCurrency(code CurrencyCode) (Amount, error)
• type Currencies
  • func (c Currencies) Find(code CurrencyCode) (Currency, error)
• type Currency
  • func NewCurrency(code CurrencyCode, v decimal.Decimal) (Currency, error)
  • func (c Currency) DecimalPlaces() int
  • func (c Currency) Is(code CurrencyCode) bool
• type CurrencyCode
  • func (c CurrencyCode) Information() *CurrencyInformation
  • func (c CurrencyCode) String() string
  • func (c CurrencyCode) Verify() bool
• type CurrencyInformation
• type Trader
  • func New(currencies Currencies, code CurrencyCode) (Trader, error)
  • func (t Trader) Is(trader Trader) bool
  • func (t Trader) NewAmount(d decimal.Decimal, code CurrencyCode) (Amount, error)
  • func (t *Trader) NewAmountFromFloat(f float64, c CurrencyCode) (Amount, error)
  • func (t *Trader) NewAmountFromString(s string, c CurrencyCode) (Amount, error)
  • func (t *Trader) SetBaseCurrency(code CurrencyCode) error

Examples

• Package
• Amount.String
• New
• Trader.NewAmount
• Trader.NewAmountFromFloat
• Trader.NewAmountFromString

Functions

func ValidCurrencies

func ValidCurrencies() map[CurrencyCode]CurrencyInformation

ValidCurrencies according to the ISO 4217, though it is recommended to pass through Verify() or Information() to access this map. This was parsed from https://en.wikipedia.org/wiki/ISO_4217#cite_note-ReferenceA-6

Types

type Amount

type Amount struct {
	Trader   Trader          `json:"-"`
	Value    decimal.Decimal `json:"value"`
	Currency Currency        `json:"currency"`
}

Amount represents an amount in a given currency

func (Amount) Add

func (a Amount) Add(b Amount) (Amount, error)

Add returns a new Amount corresponding to the sum of a and b. The currency of the returned amount is the same as the Currency of a. The returned Amount will use the Trader of a for any future operation. If the trader of a and b is not the same, an error is returned

func (Amount) Cmp

func (a Amount) Cmp(b Amount) (int, error)

Cmp compares a and b precisely in this order. Returns:

• = 0 if a is equal to b
• < 0 if a is smaller than b
• > 0 if a is greater than b

To compare a and b, b is first converted to the currency of a

func (Amount) Int64

func (a Amount) Int64() int64

Int64 translates an amount into an in64 by adjusting its amount to the lowest possible decimal of its currency (ex: USD: 10.23 -> 1023)

func (Amount) IsEmpty

func (a Amount) IsEmpty() bool

IsEmpty returns true if the amount is empty

func (Amount) RateTo

func (a Amount) RateTo(code CurrencyCode) (decimal.Decimal, error)

RateTo returns the rate that would be applied to convert the amount of a to the target currency. An error is returned if the provided code is not in the Amount Trader currency list

func (Amount) String

func (a Amount) String(decimals int32) string

String returns the amount value with the given number of decimals

Example

// We first want to define the currencies we support
usdRate, _ := decimal.NewFromString("1") // USD will be our base currency
eurRate, _ := decimal.NewFromString("0.8")
usd, _ := NewCurrency("USD", usdRate)
eur, _ := NewCurrency("EUR", eurRate)

// Create a mock Trader
t, _ := New(Currencies{usd, eur}, "USD")

a, _ := t.NewAmountFromFloat(42.42, "usd")

fmt.Println(a.String(3))

Output:

42.420

func (Amount) Sub

func (a Amount) Sub(b Amount) (Amount, error)

Sub returns a new Amount corresponding to the substraction of b from a. The currency of the returned amount is the same as the Currency of a. The returned Amount will use the Trader of a for any future operation. If the trader of a and b is not the same, an error is returned

func (Amount) ToCurrency

func (a Amount) ToCurrency(code CurrencyCode) (Amount, error)

ToCurrency converts the Amount to the given Currency. If the given Currency is the same as the currency one of the Amount, the Amount is returned directly

type Currencies

type Currencies []Currency

Currencies represents a slice of Currencies

func (Currencies) Find

func (c Currencies) Find(code CurrencyCode) (Currency, error)

Find finds a Currency within the Currencies slice from the given currency code, or returns an error if the currency code was not found

type Currency

type Currency struct {
	// Code is the ISO 4217 code of the currency
	Code CurrencyCode `json:"code"`
	// Value is the value of the currency, relative to the base currency
	Value decimal.Decimal `json:"value"`
}

Currency represents a currency and its value relative to the dollar

func NewCurrency

func NewCurrency(code CurrencyCode, v decimal.Decimal) (Currency, error)

NewCurrency creates a new Currency structure, but returns an error if the currency code is not part of ISO 4217

func (Currency) DecimalPlaces

func (c Currency) DecimalPlaces() int

DecimalPlaces returns the number of decimal places a currency has e.g. for USD there are 2 ($12.25), for JPY there are 0 (5412)

func (Currency) Is

func (c Currency) Is(code CurrencyCode) bool

Is returns true if the given code is the code of the Currency, false otherwise

type CurrencyCode

type CurrencyCode string

CurrencyCode represents a currency code in the norm ISO 4217

func (CurrencyCode) Information

func (c CurrencyCode) Information() *CurrencyInformation

Information returns the information about said currency (see CurrencyInformation) If said currency doesn't exist, nil is retured. (Might want to call Verify() first)

func (CurrencyCode) String

func (c CurrencyCode) String() string

String to implement Stringer interface

func (CurrencyCode) Verify

func (c CurrencyCode) Verify() bool

Verify returns whether a currency is valid according to the ISO 4217

type CurrencyInformation

type CurrencyInformation struct {
	// Number is the iso 4217 number of the currency
	Number uint
	// Places is the number of places after decimal separator
	Places int
	// FullName is the full name of the currency
	FullName string
	// Countries is a list of country names using said currency
	Countries []string
}

CurrencyInformation contains all the information relevant to a currency

type Trader

type Trader struct {
	Currencies   Currencies `json:"currencies"`
	BaseCurrency Currency   `json:"base_currency"`
}

Trader is the structure containing the conversions values used to handle the amount conversions

func New

func New(currencies Currencies, code CurrencyCode) (Trader, error)

New creates a new Trader structure, and sets the base currency to the given currency code. This currency code should be provided in the currencies slice, otherwise an error is returned

Example

// We first want to define the currencies we support
usd, _ := NewCurrency("USD", decimal.NewFromFloat(1))
eur, _ := NewCurrency("EUR", decimal.NewFromFloat(0.8))
currencies := Currencies{usd, eur}

// We may now create our trader, and set its base currency to the US dollar
New(currencies, "USD")

func (Trader) Is

func (t Trader) Is(trader Trader) bool

Is compares two trader. If the base currency of t and trader are not the same, returns false. If trader does not contain a currency from t, returns false. If one of the currencies of trader does not have the same value as the one of t, returns false. If the number of currencies supported by t and trader is not the same, returns false. Returns true otherwise

func (Trader) NewAmount

func (t Trader) NewAmount(d decimal.Decimal, code CurrencyCode) (Amount, error)

NewAmount creates a new amount structure from a decimal and a currency

Example

// We first want to define the currencies we support
usdRate, _ := decimal.NewFromString("1") // USD will be our base currency
eurRate, _ := decimal.NewFromString("0.8")
usd, _ := NewCurrency("USD", usdRate)
eur, _ := NewCurrency("EUR", eurRate)

// Create a mock Trader
t, _ := New(Currencies{usd, eur}, "USD")

d, _ := decimal.NewFromString("42.42")
t.NewAmount(d, "usd")

func (*Trader) NewAmountFromFloat

func (t *Trader) NewAmountFromFloat(f float64, c CurrencyCode) (Amount, error)

NewAmountFromFloat creates a new amount structure from a float and a currency

Example

// We first want to define the currencies we support
usdRate, _ := decimal.NewFromString("1") // USD will be our base currency
eurRate, _ := decimal.NewFromString("0.8")
usd, _ := NewCurrency("USD", usdRate)
eur, _ := NewCurrency("EUR", eurRate)

// Create a mock Trader
t, _ := New(Currencies{usd, eur}, "USD")

t.NewAmountFromFloat(42.42, "usd")

func (*Trader) NewAmountFromString

func (t *Trader) NewAmountFromString(s string, c CurrencyCode) (Amount, error)

NewAmountFromString creates a new amount structure from a string and a currency. Returns an error if the string could not be parsed

Example

// We first want to define the currencies we support
usdRate, _ := decimal.NewFromString("1") // USD will be our base currency
eurRate, _ := decimal.NewFromString("0.8")
usd, _ := NewCurrency("USD", usdRate)
eur, _ := NewCurrency("EUR", eurRate)

// Create a mock Trader
t, _ := New(Currencies{usd, eur}, "USD")

t.NewAmountFromString("42.42", "usd")

func (*Trader) SetBaseCurrency

func (t *Trader) SetBaseCurrency(code CurrencyCode) error

SetBaseCurrency sets the base currency for the Trader, from the given Currency code. If the currency code was not found in the currencies of the Trader, an error is returned