num

Documentation

Index

• type Amount
  • func AmountFromHumanString(val string) (Amount, error)
  • func AmountFromString(val string) (Amount, error)
  • func MakeAmount(val int64, exp uint32) Amount
  • func NewAmount(val int64, exp uint32) *Amount
  • func (a Amount) Add(a2 Amount) Amount
  • func (a Amount) Compare(a2 Amount) int
  • func (a Amount) Divide(a2 Amount) Amount
  • func (a Amount) Equals(a2 Amount) bool
  • func (a Amount) Exp() uint32
  • func (a Amount) IsZero() bool
  • func (Amount) JSONSchemaType() *jsonschema.Type
  • func (a Amount) MarshalJSON() ([]byte, error)
  • func (a Amount) MarshalText() ([]byte, error)
  • func (a Amount) Multiply(a2 Amount) Amount
  • func (a Amount) Rescale(exp uint32) Amount
  • func (a Amount) Split(x int) (Amount, Amount)
  • func (a Amount) String() string
  • func (a Amount) Subtract(a2 Amount) Amount
  • func (a *Amount) UnmarshalJSON(value []byte) error
  • func (a *Amount) UnmarshalText(value []byte) error
  • func (a Amount) Value() int64
• type Percentage
  • func MakePercentage(value int64, exp uint32) Percentage
  • func NewPercentage(value int64, exp uint32) *Percentage
  • func PercentageFromString(str string) (Percentage, error)
  • func (p Percentage) Equals(p2 Percentage) bool
  • func (p Percentage) Factor() Amount
  • func (p Percentage) From(a Amount) Amount
  • func (Percentage) JSONSchemaType() *jsonschema.Type
  • func (p Percentage) MarshalJSON() ([]byte, error)
  • func (p Percentage) MarshalText() ([]byte, error)
  • func (p Percentage) Of(a Amount) Amount
  • func (p Percentage) String() string
  • func (p Percentage) StringWithoutSymbol() string
  • func (p *Percentage) UnmarshalJSON(value []byte) error
  • func (p *Percentage) UnmarshalText(value []byte) error

Types

type Amount

type Amount struct {
	// contains filtered or unexported fields
}

Amount represents a quantity with decimal places that will not suffer rounding errors like traditional floats. Use cases are assumed to be within the "human managable domain", i.e. for dealing with counts, money, rates, short distances, etc. Implementation is inspired by https://github.com/shopspring/decimal, but simplified to account for the expectations of GoBL.

func AmountFromHumanString

func AmountFromHumanString(val string) (Amount, error)

AmountFromHumanString removes an excess decimal places, commas, or other symbols so that we end up with a simple string that can be parsed.

func AmountFromString

func AmountFromString(val string) (Amount, error)

AmountFromString takes the provided string and tries to convert it into an amount object. Strings must be in a simplified format with no commas and a single `.` to separate the decimal places. Numbers are expected to have a fixed number of decimal places, so if your dealing with a string like `"12.000"`, the accuracy will be assumed to be 3 decimal places. If you're dealing with numbers from humans which may contain symbols, commans, european style fullstops, underscores, etc. then you should use the `AmountFromHumanString` method.

func MakeAmount

func MakeAmount(val int64, exp uint32) Amount

MakeAmount is a helper to make it a little easier to build a new Amount instance. We use "Make" instead of "New" as there are no pointers.

func NewAmount

func NewAmount(val int64, exp uint32) *Amount

NewAmount provides a pointer to an Amount instance. Normally we'd recommend using the `MakeAmount` method.

func (Amount) Add

func (a Amount) Add(a2 Amount) Amount

Add will add the two amounts together using the base's exponential value for the resulting new amount.

func (Amount) Compare

func (a Amount) Compare(a2 Amount) int

Compare two amounts and return an integer value according to the sign of the difference:

-1 if a <  a2
 0 if a == a2
 1 if a >  a2

func (Amount) Divide

func (a Amount) Divide(a2 Amount) Amount

Divide our base amount by the provided amount. We use floating point to do the actual division and then round again to get an int. This prevents rounding errors, but if you want true division with a base and a remainder, use the Split method.

func (Amount) Equals

func (a Amount) Equals(a2 Amount) bool

Equals returns true if the two amounts represent the same value, regardless of the exponential.

func (Amount) Exp

func (a Amount) Exp() uint32

Exp provides the amount's exponent value.

func (Amount) IsZero

func (a Amount) IsZero() bool

IsZero returns true if the value of the amount is 0.

func (Amount) JSONSchemaType

func (Amount) JSONSchemaType() *jsonschema.Type

func (Amount) MarshalJSON

func (a Amount) MarshalJSON() ([]byte, error)

MarshalJSON takes string value of the text and adds quotes around it ready to be used in a JSON object.

func (Amount) MarshalText

func (a Amount) MarshalText() ([]byte, error)

MarshalText provides the byte value of the amount. See also the String() method. We always add quotes around values as number representations do not guarantee that tailing 0s will be maintained. It's important to remember that amounts are typically for humans, and thus it makes sense to consider them as strings.

func (Amount) Multiply

func (a Amount) Multiply(a2 Amount) Amount

Multiply our base amount by the provided amount.

func (Amount) Rescale

func (a Amount) Rescale(exp uint32) Amount

Rescale will multiply or divide the amount's value to match the provided exponential. This method will not round values, value could be lost during conversion.

func (Amount) Split

func (a Amount) Split(x int) (Amount, Amount)

Split divides the amount by x, like Divide, but also provides an additional amount with a remainder so that we avoid rounding errors.

func (Amount) String

func (a Amount) String() string

String returns the simplified string amount.

func (Amount) Subtract

func (a Amount) Subtract(a2 Amount) Amount

Subtract takes away the amount provided from the base.

func (*Amount) UnmarshalJSON

func (a *Amount) UnmarshalJSON(value []byte) error

UnmarshalJSON ensures amounts will be parsed even if defined as numbers in the source JSON.

func (*Amount) UnmarshalText

func (a *Amount) UnmarshalText(value []byte) error

UnmarshalText will decode the amount value, even if it is quoted as a string and will be used for JSON, XML, or any other text unmarshaling.

func (Amount) Value

func (a Amount) Value() int64

Value provides the amount's value

type Percentage

type Percentage struct {
	Amount
}

Percentage wraps around the regular Amount handler to provide support for percentage values, especially useful for tax rates.

func MakePercentage

func MakePercentage(value int64, exp uint32) Percentage

MakePercentage will make a new Percentage instance with the provided value and exponent.

func NewPercentage

func NewPercentage(value int64, exp uint32) *Percentage

NewPercentage provides a new pointer to a Percentage value. Using MakePercentage is recommend, but this is useful for handling nil values.

func PercentageFromString

func PercentageFromString(str string) (Percentage, error)

PercentageFromString builds a percentage value from a provided string. The % symbol will be removed automatically and rescale the stored amount to make future calculations easier. For example, the following two strings will be interpretted equally:

• `0.160`
• `16.0%`

func (Percentage) Equals

func (p Percentage) Equals(p2 Percentage) bool

Equals wraps around the amount comparison to see if the two percentages have the same value.

func (Percentage) Factor

func (p Percentage) Factor() Amount

Factor returns the percentage amount as a factor, essentially adding 1 to the rate.

func (Percentage) From

func (p Percentage) From(a Amount) Amount

From calculates what "percent from" the provided amount would result assuming the rate has already been applied.

func (Percentage) JSONSchemaType

func (Percentage) JSONSchemaType() *jsonschema.Type

func (Percentage) MarshalJSON

func (p Percentage) MarshalJSON() ([]byte, error)

MarshalJSON provides the text value of percentage wrapped in quotes ready to be included in a JSON object.

func (Percentage) MarshalText

func (p Percentage) MarshalText() ([]byte, error)

MarshalText provides the byte value of the amount. See also the String() method.

func (Percentage) Of

func (p Percentage) Of(a Amount) Amount

Of calculates the "percent of" the provided amount. The exponent of the provided amount is used.

func (Percentage) String

func (p Percentage) String() string

String outputs the percentage value in a human readable way including the percentage symbol.

func (Percentage) StringWithoutSymbol

func (p Percentage) StringWithoutSymbol() string

StringWithoutSymbol provides the raw underlying percentage value.

func (*Percentage) UnmarshalJSON

func (p *Percentage) UnmarshalJSON(value []byte) error

UnmarshalJSON ensures we parse percentage numbers correctly from a JSON source.

func (*Percentage) UnmarshalText

func (p *Percentage) UnmarshalText(value []byte) error

UnmarshalText will decode the percentage value, even if it is quoted as a string.