num

package
v0.50.5 Latest Latest
Warning

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

 Go to latest Published: Jun 14, 2023 License: Apache-2.0 Imports: 8 Imported by: 9

Documentation

Overview

Package num provides support for dealing with amounts and percentages without rounding errors.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

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 manageable 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, commas, 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) Downscale added in v0.25.2 

func (a Amount) Downscale(accuracy uint32) Amount

Downscale decreases the amount's exponent by the provided accuracy.

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) Invert added in v0.13.0 

func (a Amount) Invert() Amount

Invert the value.

func (Amount) IsZero 

func (a Amount) IsZero() bool

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

func (Amount) JSONSchema added in v0.17.0 

func (Amount) JSONSchema() *jsonschema.Schema

JSONSchema provides a representation of the struct for usage in Schema.

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) MatchPrecision added in v0.13.0 

func (a Amount) MatchPrecision(a2 Amount) Amount

MatchPrecision will rescale the exponent value of the amount so that it matches the scale of the provided amount, but *only* if it is higher.

func (Amount) MinimalString added in v0.13.0 

func (a Amount) MinimalString() string

MinimalString provides the amount without any tailing 0s or '.' if one is left over.

func (Amount) Multiply 

func (a Amount) Multiply(a2 Amount) Amount

Multiply our base amount by the provided amount.

func (Amount) Remove added in v0.25.2 

func (a Amount) Remove(percent Percentage) Amount

Remove takes the provided percentage away from the amount assuming it was already applied previously.

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 round values in the case of reducing the exponent.

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) Upscale added in v0.25.2 

func (a Amount) Upscale(accuracy uint32) Amount

Upscale increases the accuracy of the amount by rescaling the exponent by the provided amount.

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 interpreted 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) JSONSchema added in v0.17.0 

func (Percentage) JSONSchema() *jsonschema.Schema

JSONSchema provides a representation of the struct for usage in Schema.

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) Rescale added in v0.50.0 

func (p Percentage) Rescale(exp uint32) Percentage

Rescale will rescale the percentage value to the provided exponent.

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 percent value without a percent symbol.

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.

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.