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

Usage

// We first want to define the currencies we support
usd, _ := decimal.NewFromString("1") // USD will be our base currency
eur, _ := decimal.NewFromString("0.8")
currencies := trader.Currencies{
    trader.NewCurrency("USD", &usd),
    trader.NewCurrency("EUR", &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
price, _ := decimal.NewFromString("42.42")
amount, _ := t.NewAmount(&price, "USD")
// or amount, _ := trader.NewAmountFromString("42.42", "USD")
// or amount, _ := trader.NewAmountFromFloat(42.42, "USD")

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

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

// The result is:
// USD(42.00) + EUR(USD(42.00)) == USD(42.00) + USD(42.00) = USD(82.00)
fmt.Println(USDPlusEUR.String())

Notes

Trader uses the package github.com/shopspring/decimal to perform its 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, _ := decimal.NewFromString("1") // USD will be our base currency
eur, _ := decimal.NewFromString("0.8")
currencies := Currencies{
	NewCurrency("USD", &usd),
	NewCurrency("EUR", &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.NewAmountFromString("42.42", "USD")

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

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

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

Output:

84.84

Index

• 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) RateTo(code string) (*decimal.Decimal, error)
  • func (a Amount) String(decimals int32) string
  • func (a Amount) Sub(b *Amount) (*Amount, error)
  • func (a Amount) ToCurrency(code string) (*Amount, error)
• type Currencies
  • func (c Currencies) Find(code string) (*Currency, error)
• type Currency
  • func NewCurrency(code string, v *decimal.Decimal) *Currency
  • func (c Currency) DecimalPlaces() int
  • func (c Currency) Is(code string) bool
• type Trader
  • func New(currencies Currencies, code string) (*Trader, error)
  • func (t Trader) Is(trader *Trader) bool
  • func (t *Trader) NewAmount(d *decimal.Decimal, code string) (*Amount, error)
  • func (t *Trader) NewAmountFromFloat(f float64, c string) (*Amount, error)
  • func (t *Trader) NewAmountFromString(s, c string) (*Amount, error)
  • func (t *Trader) SetBaseCurrency(code string) error

Examples

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

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

func (a Amount) RateTo(code string) (*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
usd, _ := decimal.NewFromString("1") // USD will be our base currency
eur, _ := decimal.NewFromString("0.8")

// Create a mock Trader
t, _ := New(Currencies{
	NewCurrency("USD", &usd),
	NewCurrency("EUR", &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 string) (*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 string) (*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 string `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 string, v *decimal.Decimal) *Currency

NewCurrency creates a new Currency structure

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 string) bool

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

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 string) (*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, _ := decimal.NewFromString("1") // USD will be our base currency
eur, _ := decimal.NewFromString("0.8")
currencies := Currencies{
	NewCurrency("USD", &usd),
	NewCurrency("EUR", &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 string) (*Amount, error)

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

Example

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

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

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

func (*Trader) NewAmountFromFloat

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

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

Example

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

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

t.NewAmountFromFloat(42.42, "usd")

func (*Trader) NewAmountFromString

func (t *Trader) NewAmountFromString(s, c string) (*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
usd, _ := decimal.NewFromString("1") // USD will be our base currency
eur, _ := decimal.NewFromString("0.8")

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

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

func (*Trader) SetBaseCurrency

func (t *Trader) SetBaseCurrency(code string) 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