coin

package
v0.25.1-staging Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 8, 2020 License: Apache-2.0 Imports: 12 Imported by: 18

Documentation

Index

Constants

View Source 
const (
	// MaxInt is the largest whole value we accept
	MaxInt int64 = 999999999999999 // 10^15-1
	// MinInt is the lowest whole value we accept
	MinInt = -MaxInt

	// FracUnit is the smallest numbers we divide by
	FracUnit int64 = 1000000000 // fractional units = 10^9
	// MaxFrac is the highest possible fractional value
	MaxFrac = FracUnit - 1
	// MinFrac is the lowest possible fractional value
	MinFrac = -MaxFrac
)

Variables

View Source 
var (
	ErrInvalidLengthCodec = fmt.Errorf("proto: negative length found during unmarshaling")
	ErrIntOverflowCodec   = fmt.Errorf("proto: integer overflow")
)
View Source 
var IsCC = regexp.MustCompile(`^[A-Z]{3,4}$`).MatchString

IsCC is the RegExp to ensure valid currency codes

Functions

func IsEmpty 

func IsEmpty(c *Coin) bool

IsEmpty returns true on null or zero amount

Types

type Coin 

type Coin struct {
	// Whole coins, -10^15 < integer < 10^15
	Whole int64 `protobuf:"varint,1,opt,name=whole,proto3" json:"whole,omitempty"`
	// Billionth of coins. 0 <= abs(fractional) < 10^9
	// If fractional != 0, must have same sign as integer
	Fractional int64 `protobuf:"varint,2,opt,name=fractional,proto3" json:"fractional,omitempty"`
	// Ticker is 3-4 upper-case letters and
	// all Coins of the same currency can be combined
	Ticker string `protobuf:"bytes,3,opt,name=ticker,proto3" json:"ticker,omitempty"`
}

Coin can hold any amount between -1 billion and +1 billion at steps of 10^-9. It is a fixed-point decimal representation and uses integers to avoid rounding associated with floats.

Every code has a denomination, which is just a

If you want anything more complex, you should write your own type, possibly borrowing from this code.

func NewCoin 

func NewCoin(whole int64, fractional int64, ticker string) Coin

NewCoin creates a new coin object

func NewCoinp 

func NewCoinp(whole, fractional int64, ticker string) *Coin

NewCoinp returns a pointer to a new coin.

func ParseHumanFormat added in v0.14.0 

func ParseHumanFormat(h string) (Coin, error)

ParseHumanFormat parse a human readable coin representation. Accepted format is a string: 

"<whole>[.<fractional>] <ticker>"

func (Coin) Add 

func (c Coin) Add(o Coin) (Coin, error)

Add combines two coins. Returns error if they are of different currencies, or if the combination would cause an overflow

func (*Coin) Clone 

func (c *Coin) Clone() *Coin

Clone provides an independent copy of a coin pointer

func (Coin) Compare 

func (c Coin) Compare(o Coin) int

Compare will check values of two coins, without inspecting the currency code. It is up to the caller to determine if they want to check this. It also assumes they were already normalized.

Returns 1 if c is larger, -1 if o is larger, 0 if equal

func (*Coin) Descriptor 

func (*Coin) Descriptor() ([]byte, []int)

func (Coin) Divide 

func (c Coin) Divide(pieces int64) (Coin, Coin, error)

Split divides the value of a coin into given amount of pieces and returns a single piece. It might be that a precise splitting is not possible. Any leftover of a fractional value is returned as well. For example splitting 4 EUR into 3 pieces will result in a single piece being 1.33 EUR and 1 cent returned as the rest (leftover). 

4 = 1.33 x 3 + 1

func (Coin) Equals 

func (c Coin) Equals(o Coin) bool

Equals returns true if all fields are identical

func (*Coin) GetFractional 

func (m *Coin) GetFractional() int64

func (*Coin) GetTicker 

func (m *Coin) GetTicker() string

func (*Coin) GetWhole 

func (m *Coin) GetWhole() int64

func (Coin) ID 

func (c Coin) ID() string

ID returns a coin ticker name.

func (Coin) IsGTE 

func (c Coin) IsGTE(o Coin) bool

IsGTE returns true if c is same type and at least as large as o. It assumes they were already normalized.

func (Coin) IsNonNegative 

func (c Coin) IsNonNegative() bool

IsNonNegative returns true if the value is 0 or higher

func (Coin) IsPositive 

func (c Coin) IsPositive() bool

IsPositive returns true if the value is greater than 0

func (Coin) IsZero 

func (c Coin) IsZero() bool

IsZero returns true amounts are 0

func (*Coin) Marshal 

func (m *Coin) Marshal() (dAtA []byte, err error)

func (*Coin) MarshalTo 

func (m *Coin) MarshalTo(dAtA []byte) (int, error)

func (Coin) Multiply 

func (c Coin) Multiply(times int64) (Coin, error)

Multiply returns the result of a coin value multiplication. This method can fail if the result would overflow maximum coin value.

func (Coin) Negative 

func (c Coin) Negative() Coin

Negative returns the opposite coins value 

c.Add(c.Negative()).IsZero() == true

func (*Coin) ProtoMessage 

func (*Coin) ProtoMessage()

func (*Coin) Reset 

func (m *Coin) Reset()

func (Coin) SameType 

func (c Coin) SameType(o Coin) bool

SameType returns true if they have the same currency

func (*Coin) Set added in v0.16.0 

func (c *Coin) Set(raw string) error

Set updates this coin value to what is provided. This method implements flag.Value interface.

func (*Coin) Size 

func (m *Coin) Size() (n int)

func (Coin) String 

func (c Coin) String() string

String provides a human readable representation of the coin. This function is meant mostly for testing and debugging. For a valid coin the result is a valid human readable format that can be parsed back. For an invalid coin (ie. without a ticker) a readable representation is returned but it cannot be parsed back using the human readable format parser.

func (Coin) Subtract 

func (c Coin) Subtract(amount Coin) (Coin, error)

Subtract given amount.

func (*Coin) Unmarshal 

func (m *Coin) Unmarshal(dAtA []byte) error

func (*Coin) UnmarshalJSON added in v0.13.0 

func (c *Coin) UnmarshalJSON(raw []byte) error

func (Coin) Validate 

func (c Coin) Validate() error

Validate ensures that the coin is in the valid range and valid currency code. It accepts negative values, so you may want to make other checks in your business logic

func (*Coin) XXX_DiscardUnknown 

func (m *Coin) XXX_DiscardUnknown()

func (*Coin) XXX_Marshal 

func (m *Coin) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)

func (*Coin) XXX_Merge 

func (m *Coin) XXX_Merge(src proto.Message)

func (*Coin) XXX_Size 

func (m *Coin) XXX_Size() int

func (*Coin) XXX_Unmarshal 

func (m *Coin) XXX_Unmarshal(b []byte) error

type Coins 

type Coins []*Coin

Coins represents a set of coins. Most operations on the coin set require normalized form. Make sure to normalize you collection before using.

func CombineCoins 

func CombineCoins(cs ...Coin) (Coins, error)

CombineCoins creates a Coins containing all given coins. It will sort them and combine duplicates to produce a normalized form regardless of input.

TODO: deprecate in favor of `Coins.Combine()`

func NormalizeCoins 

func NormalizeCoins(cs Coins) (Coins, error)

NormalizeCoins is a cleanup operation that merge and orders set of coin instances into a unified form. This includes merging coins of the same currency and sorting coins according to the ticker name. If given set of coins is normalized this operation return what was given. Otherwise a new instance of a slice can be returned.

func (Coins) Add 

func (cs Coins) Add(c Coin) (Coins, error)

Add modifies the Coins, to increase the holdings by c

func (Coins) Clone 

func (cs Coins) Clone() Coins

Clone returns a copy that can be safely modified

func (Coins) Combine 

func (cs Coins) Combine(o Coins) (Coins, error)

Combine will create a new Coins adding all the coins of s and o together.

func (Coins) Contains 

func (cs Coins) Contains(c Coin) bool

Contains returns true if there is at least that much coin in the Coins. If it returns true, then: 

s.Remove(c).IsNonNegative() == true

func (Coins) Count 

func (cs Coins) Count() int

Count returns the number of unique currencies in the Coins

func (Coins) Equals 

func (cs Coins) Equals(o Coins) bool

Equals returns true if both Coins contain same coins

func (Coins) IsEmpty 

func (cs Coins) IsEmpty() bool

IsEmpty returns if nothing is in the Coins

func (Coins) IsNonNegative 

func (cs Coins) IsNonNegative() bool

IsNonNegative returns true if all coins are positive, but also accepts an empty Coins

func (Coins) IsPositive 

func (cs Coins) IsPositive() bool

IsPositive returns true there is at least one coin and all coins are positive

func (Coins) Subtract 

func (cs Coins) Subtract(c Coin) (Coins, error)

Subtract modifies the Coins, to decrease the holdings by c. The resulting Coins may have negative amounts

func (Coins) Validate 

func (cs Coins) Validate() error

Validate requires that all coins are in alphabetical order and that each coin is valid in it's own right

Zero amounts should not be present

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.