Documentation
¶
Index ¶
- Constants
- Variables
- func IsEmpty(c *Coin) bool
- type Coin
- func (c Coin) Add(o Coin) (Coin, error)
- func (c *Coin) Clone() *Coin
- func (c Coin) Compare(o Coin) int
- func (*Coin) Descriptor() ([]byte, []int)
- func (c Coin) Divide(pieces int64) (Coin, Coin, error)
- func (c Coin) Equals(o Coin) bool
- func (m *Coin) GetFractional() int64
- func (m *Coin) GetTicker() string
- func (m *Coin) GetWhole() int64
- func (c Coin) ID() string
- func (c Coin) IsGTE(o Coin) bool
- func (c Coin) IsNonNegative() bool
- func (c Coin) IsPositive() bool
- func (c Coin) IsZero() bool
- func (m *Coin) Marshal() (dAtA []byte, err error)
- func (m *Coin) MarshalTo(dAtA []byte) (int, error)
- func (c Coin) Multiply(times int64) (Coin, error)
- func (c Coin) Negative() Coin
- func (*Coin) ProtoMessage()
- func (m *Coin) Reset()
- func (c Coin) SameType(o Coin) bool
- func (c *Coin) Set(raw string) error
- func (m *Coin) Size() (n int)
- func (c Coin) String() string
- func (c Coin) Subtract(amount Coin) (Coin, error)
- func (m *Coin) Unmarshal(dAtA []byte) error
- func (c *Coin) UnmarshalJSON(raw []byte) error
- func (c Coin) Validate() error
- func (m *Coin) XXX_DiscardUnknown()
- func (m *Coin) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)
- func (m *Coin) XXX_Merge(src proto.Message)
- func (m *Coin) XXX_Size() int
- func (m *Coin) XXX_Unmarshal(b []byte) error
- type Coins
- func (cs Coins) Add(c Coin) (Coins, error)
- func (cs Coins) Clone() Coins
- func (cs Coins) Combine(o Coins) (Coins, error)
- func (cs Coins) Contains(c Coin) bool
- func (cs Coins) Count() int
- func (cs Coins) Equals(o Coins) bool
- func (cs Coins) IsEmpty() bool
- func (cs Coins) IsNonNegative() bool
- func (cs Coins) IsPositive() bool
- func (cs Coins) Subtract(c Coin) (Coins, error)
- func (cs Coins) Validate() error
Constants ¶
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 ¶
var ( ErrInvalidLengthCodec = fmt.Errorf("proto: negative length found during unmarshaling") ErrIntOverflowCodec = fmt.Errorf("proto: integer overflow") )
var IsCC = regexp.MustCompile(`^[A-Z]{3,4}$`).MatchString
IsCC is the RegExp to ensure valid currency codes
Functions ¶
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 ParseHumanFormat ¶ added in v0.14.0
ParseHumanFormat parse a human readable coin representation. Accepted format is a string:
"<whole>[.<fractional>] <ticker>"
func (Coin) Add ¶
Add combines two coins. Returns error if they are of different currencies, or if the combination would cause an overflow
func (Coin) Compare ¶
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) Divide ¶
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) GetFractional ¶
func (Coin) IsGTE ¶
IsGTE returns true if c is same type and at least as large as o. It assumes they were already normalized.
func (Coin) IsNonNegative ¶
IsNonNegative returns true if the value is 0 or higher
func (Coin) IsPositive ¶
IsPositive returns true if the value is greater than 0
func (Coin) Multiply ¶
Multiply returns the result of a coin value multiplication. This method can fail if the result would overflow maximum coin value.
func (Coin) Negative ¶
Negative returns the opposite coins value
c.Add(c.Negative()).IsZero() == true
func (*Coin) ProtoMessage ¶
func (*Coin) ProtoMessage()
func (*Coin) Set ¶ added in v0.16.0
Set updates this coin value to what is provided. This method implements flag.Value interface.
func (Coin) 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) UnmarshalJSON ¶ added in v0.13.0
func (Coin) Validate ¶
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_Unmarshal ¶
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 ¶
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 ¶
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) Contains ¶
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) IsNonNegative ¶
IsNonNegative returns true if all coins are positive, but also accepts an empty Coins
func (Coins) IsPositive ¶
IsPositive returns true there is at least one coin and all coins are positive
Source Files