README
¶
Dosh
Dosh is a Go library for representing, manipulating and serializing monetary values.
The API is centered around the Amount
type, which is an immutable monetary value in a specific currency. It is based
on Shopspring's arbitrary-precision Decimal
type, making it suitable for mathematical operations.
Serialization
Amount provides serialization logic for text, binary, JSON and protocol
buffers formats.
Both the text and binary formats are "lossless" insofar as they can encode any amount that can be represented by the internal arbitrary precision decimal.
The JSON and protocol buffers formats are based on the google.type.Money
"well-known" protocol buffers type, which has a fixed precision of 9 decimal
places.
The JSON representation of an amount is obtained by applying Protocol Buffers'
canonical JSON mapping rules to the
Money type. This encoding is widely used throughout Google's APIs, an example
of which can be seen here.
Dosh also provides the protomoney
package, which can be used to perform comparisons and basic mathematical
operations on google.type.Money values directly, without unmarshaling them to
an Amount.
Caveats
Google's money package does not include the source .proto file used to
generate the money.Money type. This makes it difficult to import into
user-defined protocol buffers messages. To that end, the original .proto file
is included in Dosh's protomoney package.
Documentation
¶
Overview ¶
Package dosh represents, manipulates and serializes monetary values.
Index ¶
- func ToProto(a Amount) *money.Money
- type Amount
- func Avg(amounts ...Amount) Amount
- func FromDecimal(c string, m decimal.Decimal) Amount
- func FromInt(c string, m int) Amount
- func FromProto(m *money.Money) Amount
- func FromString(c, m string) Amount
- func Max(amounts ...Amount) Amount
- func Min(amounts ...Amount) Amount
- func Sum(amounts ...Amount) Amount
- func TryFromString(c, m string) (_ Amount, ok bool)
- func Unit(c string) Amount
- func Zero(c string) Amount
- func (a Amount) Abs() Amount
- func (a Amount) Add(b Amount) Amount
- func (a Amount) Ceil() Amount
- func (a Amount) Cmp(b Amount) (c int)
- func (a Amount) CurrencyCode() string
- func (a Amount) Div(b Amount) decimal.Decimal
- func (a Amount) DivScalar(b decimal.Decimal) Amount
- func (a Amount) EqualTo(b Amount) bool
- func (a Amount) Floor() Amount
- func (a Amount) Format(f fmt.State, verb rune)
- func (a Amount) GoString() string
- func (a Amount) GreaterThan(b Amount) bool
- func (a Amount) GreaterThanOrEqualTo(b Amount) bool
- func (a Amount) IdenticalTo(b Amount) bool
- func (a Amount) IsNegative() bool
- func (a Amount) IsPositive() bool
- func (a Amount) IsZero() bool
- func (a Amount) LessThan(b Amount) bool
- func (a Amount) LessThanOrEqualTo(b Amount) bool
- func (a Amount) LexicallyLessThan(b Amount) bool
- func (a Amount) Magnitude() decimal.Decimal
- func (a Amount) MarshalBinary() ([]byte, error)
- func (a Amount) MarshalJSON() ([]byte, error)
- func (a Amount) MarshalProto() (*money.Money, error)
- func (a Amount) MarshalText() (text []byte, err error)
- func (a Amount) Mod(b Amount) decimal.Decimal
- func (a Amount) ModScalar(b decimal.Decimal) Amount
- func (a Amount) MulScalar(b decimal.Decimal) Amount
- func (a Amount) Neg() Amount
- func (a Amount) Round(n int32) Amount
- func (a Amount) RoundBank(n int32) Amount
- func (a Amount) String() string
- func (a Amount) Sub(b Amount) Amount
- func (a Amount) Truncate(n int32) Amount
- func (a *Amount) UnmarshalBinary(data []byte) error
- func (a *Amount) UnmarshalJSON(data []byte) error
- func (a *Amount) UnmarshalProto(pb *money.Money) error
- func (a *Amount) UnmarshalText(text []byte) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Amount ¶
type Amount struct {
// contains filtered or unexported fields
}
Amount represents an immutable amount of money in a specific currency.
The zero-value represents zero US dollars ($0 USD).
An Amount consists of a currency code and a magnitude.
The currency code is a short string that identifies which currency the amount represents. The magnitude is an arbitrary-precision decimal number describing the number of units of that currency.
Currency codes must consist of 3 or more uppercase ASCII letters. Any operation that accepts a currency code will panic if provided with a code that does not meet this criteria. Where possible, currency codes should be an ISO-4217 3-letter code. Non-standard currency codes should begin with an "X".
func Avg ¶
Avg returns the mean of the given amounts.
It panics if amounts is empty, or if the amounts do not use the same currency.
func FromDecimal ¶
FromDecimal returns an Amount with a decimal magnitude
c is the currency code that identifies the currency.
m is the magnitude of the amount, expressed in the currency specified by c.
func FromInt ¶
FromInt returns an Amount with an integer magnitude.
c is the currency code that identifies the currency.
m is the magnitude of the amount, expressed in the currency specified by c.
func FromProto ¶
FromProto unmarshals an amount from its protocol buffers representation, or panics if unable to do so.
func FromString ¶
FromString returns an Amount with a magnitude parsed from a numeric string.
c is the currency code that identifies the currency.
m is the string representation if the magnitude, expressed in the currency specified by c. It must use integer, decimal or scientific notation, otherwise a panic occurs.
func Max ¶
Max returns the largest of the given amounts.
It panics if amounts is empty, or if the amounts do not use the same currency.
func Min ¶
Min returns the smallest of the given amounts.
It panics if amounts is empty, or if the amounts do not use the same currency.
func Sum ¶
Sum returns the sum of the given amounts.
It panics if amounts is empty, or if the amounts do not use the same currency.
func TryFromString ¶
TryFromString returns an Amount with a magnitude parsed from a numeric string.
c is the currency code that identifies the currency.
m is the string representation if the magnitude, expressed in the currency specified by c. It must use integer, decimal or scientific notation, otherwise ok is false, and the returned amount is undefined.
func Unit ¶
Unit returns an Amount with a magnitude of 1 (one).
c is the currency code that identifies the currency.
func Zero ¶
Zero returns an Amount with a magnitude of 0 (zero).
c is the currency code that identifies the currency.
func (Amount) Abs ¶
Abs returns the absolute value of this amount.
That is, if a is negative, it returns its inverse (a positive magnitude), otherwise it returns a unchanged.
func (Amount) Ceil ¶
Ceil returns an amount with a magnitude equal to the the nearest integer greater than or equal to a.Magnitude().
func (Amount) Cmp ¶
Cmp compares a to b and returns a C-style comparison result.
It panics if a and b do not use the same currency.
If a < b then c is negative. If a > b then c is positive. Otherwise; a == b and c is zero.
func (Amount) CurrencyCode ¶
CurrencyCode returns the currency code for the currency in which the amount is specified.
func (Amount) Div ¶
Div returns a / b.
It panics if a and b do not use the same currency.
To divide by a scalar decimal value, use DivScalar() instead.
func (Amount) DivScalar ¶
DivScalar returns a / b, where b is a scalar value.
To divide a by another Amount, use Div() instead.
func (Amount) EqualTo ¶
EqualTo returns true if a and b have the same magnitude.
It panics if a and b do not use the same currency.
To check equality between two amounts that may have differing currencies, use IdenticalTo() instead.
func (Amount) Floor ¶
Floor returns an amount with a magnitude equal to the nearest integer less than or equal to a.Magnitude().
func (Amount) Format ¶
Format implements fmt.Formatter, allowing Amount to be used with fmt.Printf() and its variants.
func (Amount) GreaterThan ¶
GreaterThan returns true if a > b.
It panics if a and b do not use the same currency.
func (Amount) GreaterThanOrEqualTo ¶
GreaterThanOrEqual returns true if a >= b.
It panics if a and b do not use the same currency.
func (Amount) IdenticalTo ¶
Identical returns true if a and b use the same currency and have the same magnitude.
For general comparisons that are expected to be in the same currency, use EqualTo() instead.
func (Amount) IsNegative ¶
IsNegative returns true if the amount has a negative magnitude.
func (Amount) IsPositive ¶
IsPositive returns true if the amount has a positive magnitude.
func (Amount) LessThan ¶
LessThan returns true if a < b.
It panics if a and b do not use the same currency.
func (Amount) LessThanOrEqualTo ¶
LessThanOrEqual returns true if a <= b.
It panics if a and b do not use the same currency.
func (Amount) LexicallyLessThan ¶
LexicallyLessThan returns true if a should appear before b in a sorted list.
There is no requirement that a and b use the same currency.
func (Amount) Magnitude ¶
Magnitude returns the decimal value of the amount without currency information.
func (Amount) MarshalBinary ¶
MarshalBinary mashals an amount to its binary representation.
func (Amount) MarshalJSON ¶
MarshalJSON mashals an amount to its JSON representation.
It uses the canonical JSON format of the protocol buffers money.Money type.
func (Amount) MarshalProto ¶
MarshalProto mashals an amount to its protocol buffers representation.
func (Amount) MarshalText ¶
MarshalText mashals an amount to its text representation.
func (Amount) Mod ¶
Mod returns a % b.
It panics if a and b do not use the same currency.
To find the remainder of dividing by a scalar decimal value, use ModScalar() instead.
func (Amount) ModScalar ¶
ModScalar returns a % b, where b is a scalar decimal value.
To find the remainder of dividing by another Amount, use Mod() instead.
func (Amount) Round ¶
Round returns the amount rounded to n decimal places, rounded away from zero, also known as "commercial rounding".
See https://en.wikipedia.org/wiki/Rounding#Round_half_away_from_zero.
If n is negative the result is rounded to the -n'th integer place. For example, an amount with a magnitude of 543 rounded to -1 places results in an amount with a magnitude of 540.
func (Amount) RoundBank ¶
RoundBank returns the amount rounded to n decimal places, rounded towards even digits, also known as "banker's rounding".
Banker's rounding is commonly used for rounding sales tax amounts. See https://wiki.c2.com/?BankersRounding.
If n is negative the result is rounded to the -n'th integer place. For example, an amount with a magnitude of 543 rounded to -1 places results in an amount with a magnitude of 540.
func (Amount) String ¶
String returns a human-readable representation of the amount, including the currency code.
func (Amount) Truncate ¶
Truncate returns the amount truncated to n decimal places without performing any rounding.
n must be positive.
func (*Amount) UnmarshalBinary ¶
UnmarshalBinary unmarshals an amount from its binary representation.
NOTE: In order to comply with Go's encoding.BinaryUnmarshaler interface, this method mutates the internals of a, violating Amount's immutability guarantee.
func (*Amount) UnmarshalJSON ¶
UnmarshalJSON unmarshals an amount from its protocol buffers representation.
NOTE: In order to comply with Go's json.Unmarshaler interface, this method mutates the internals of a, violating Amount's immutability guarantee.
func (*Amount) UnmarshalProto ¶
UnmarshalProto unmarshals an amount from its protocol buffers representation.
NOTE: For consistency with other UnmarshalXXX() methods, this method mutates the internals of a, violating Amount's immutability guarantee.
func (*Amount) UnmarshalText ¶
UnmarshalText unmarshals an amount from its text representation.
NOTE: In order to comply with Go's encoding.TextUnmarshaler interface, this method mutates the internals of a, violating Amount's immutability guarantee.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
Package protomoney provides basic, low-level mathematical and comparison operations for the "well-known" protocol buffers Money type without conversion to another data type.
|
Package protomoney provides basic, low-level mathematical and comparison operations for the "well-known" protocol buffers Money type without conversion to another data type. |