currency

package
v0.205.0 Latest Latest
Warning

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

 Go to latest Published: Nov 12, 2024 License: Apache-2.0 Imports: 12 Imported by: 6

README

Currency Reference Data

Currency support in GOBL aims to cover most of the currencies in the world and provide methods to format and work with them.

Much of the inspiration for this package and source data in the /data/currency directory originally came from the excellent and widely used money gem in ruby. A few alterations to source data have been made.

Currencies around the world change more often than expected, please send a PR if you spot anything that is out of date, along with a link that references the source of the change.

Documentation

Overview

Package currency provides models for dealing with currencies.

Index

Constants

View Source 
const (
	// DefaultCurrencyTemplate defines how to output currencies for most
	// common use cases.
	DefaultCurrencyTemplate = "%u%n"
)

Variables

This section is empty.

Functions

func CanConvertInto added in v0.76.0 

func CanConvertInto(rates []*ExchangeRate, to Code) validation.Rule

CanConvertInto will check to see if the currency to be validated can be converted using one of the provided exchange rates.

func Convert added in v0.76.0 

func Convert(rates []*ExchangeRate, from, to Code, amount num.Amount) *num.Amount

Convert will convert the provided amount from one currency into another or return nil if no match can be found. If the currencies are the same, the original amount will be returned.

Types

type Amount added in v0.76.0 

type Amount struct {
	// Label allows for additional information to be added to the
	// currency Amount that may be useful.
	Label string `json:"label,omitempty" jsonschema:"title=Label"`
	// Code defines the currency for this amount.
	Currency Code `json:"currency" jsonschema:"title=Currency"`
	// Value is the amount in the currency.
	Value num.Amount `json:"value" jsonschema:"title=Value"`
}

An Amount represents a monetary value in a specific currency.

func (*Amount) Validate added in v0.76.0 

func (a *Amount) Validate() error

Validate ensures the currency amount looks correct.

type Code 

type Code string

Code is the ISO currency code 

const (
	// United States Dollar ($)
	USD Code = "USD"
	// Euro (€)
	EUR Code = "EUR"
	// British Pound (£)
	GBP Code = "GBP"
	// Australian Dollar ($)
	AUD Code = "AUD"
	// Canadian Dollar ($)
	CAD Code = "CAD"
	// Japanese Yen (¥)
	JPY Code = "JPY"
	// Belarusian Ruble (Br)
	BYR Code = "BYR"
	// Macanese Pataca (P)
	MOP Code = "MOP"
	// Haitian Gourde (G)
	HTG Code = "HTG"
	// Azerbaijani Manat (₼)
	AZN Code = "AZN"
	// Bosnia and Herzegovina Convertible Mark (КМ)
	BAM Code = "BAM"
	// Barbadian Dollar ($)
	BBD Code = "BBD"
	// Bangladeshi Taka (৳)
	BDT Code = "BDT"
	// Bulgarian Lev (лв.)
	BGN Code = "BGN"
	// Bahraini Dinar (د.ب)
	BHD Code = "BHD"
	// Burundian Franc (Fr)
	BIF Code = "BIF"
	// Bermudian Dollar ($)
	BMD Code = "BMD"
	// Brunei Dollar ($)
	BND Code = "BND"
	// Bolivian Boliviano (Bs.)
	BOB Code = "BOB"
	// Brazilian Real (R$)
	BRL Code = "BRL"
	// Bahamian Dollar ($)
	BSD Code = "BSD"
	// Bhutanese Ngultrum (Nu.)
	BTN Code = "BTN"
	// Botswana Pula (P)
	BWP Code = "BWP"
	// Belarusian Ruble (Br)
	BYN Code = "BYN"
	// Argentine Peso ($)
	ARS Code = "ARS"
	// Belize Dollar ($)
	BZD Code = "BZD"
	// Angolan Kwanza (Kz)
	AOA Code = "AOA"
	// Congolese Franc (Fr)
	CDF Code = "CDF"
	// Swiss Franc (CHF)
	CHF Code = "CHF"
	// Unidad de Fomento (UF)
	CLF Code = "CLF"
	// Chilean Peso ($)
	CLP Code = "CLP"
	// Chinese Renminbi Yuan (¥)
	CNY Code = "CNY"
	// Colombian Peso ($)
	COP Code = "COP"
	// Costa Rican Colón (₡)
	CRC Code = "CRC"
	// Cuban Convertible Peso ($)
	CUC Code = "CUC"
	// Cuban Peso ($)
	CUP Code = "CUP"
	// Cape Verdean Escudo ($)
	CVE Code = "CVE"
	// Czech Koruna (Kč)
	CZK Code = "CZK"
	// Djiboutian Franc (Fdj)
	DJF Code = "DJF"
	// Danish Krone (kr.)
	DKK Code = "DKK"
	// Mexican Peso ($)
	MXN Code = "MXN"
	// Algerian Dinar (د.ج)
	DZD Code = "DZD"
	// Egyptian Pound (ج.م)
	EGP Code = "EGP"
	// Eritrean Nakfa (Nfk)
	ERN Code = "ERN"
	// Ethiopian Birr (Br)
	ETB Code = "ETB"
	// Netherlands Antillean Gulden (ƒ)
	ANG Code = "ANG"
	// Fijian Dollar ($)
	FJD Code = "FJD"
	// Falkland Pound (£)
	FKP Code = "FKP"
	// Armenian Dram (դր.)
	AMD Code = "AMD"
	// Georgian Lari (₾)
	GEL Code = "GEL"
	// Ghanaian Cedi (₵)
	GHS Code = "GHS"
	// Gibraltar Pound (£)
	GIP Code = "GIP"
	// Gambian Dalasi (D)
	GMD Code = "GMD"
	// Guinean Franc (Fr)
	GNF Code = "GNF"
	// Guatemalan Quetzal (Q)
	GTQ Code = "GTQ"
	// Guyanese Dollar ($)
	GYD Code = "GYD"
	// Hong Kong Dollar ($)
	HKD Code = "HKD"
	// Honduran Lempira (L)
	HNL Code = "HNL"
	// Malawian Kwacha (MK)
	MWK Code = "MWK"
	// Hungarian Forint (Ft)
	HUF Code = "HUF"
	// Indonesian Rupiah (Rp)
	IDR Code = "IDR"
	// Israeli New Sheqel (₪)
	ILS Code = "ILS"
	// Indian Rupee (₹)
	INR Code = "INR"
	// Iraqi Dinar (ع.د)
	IQD Code = "IQD"
	// Iranian Rial (﷼)
	IRR Code = "IRR"
	// Icelandic Króna (kr.)
	ISK Code = "ISK"
	// Jamaican Dollar ($)
	JMD Code = "JMD"
	// Jordanian Dinar (د.ا)
	JOD Code = "JOD"
	// Albanian Lek (L)
	ALL Code = "ALL"
	// Kenyan Shilling (KSh)
	KES Code = "KES"
	// Kyrgyzstani Som (som)
	KGS Code = "KGS"
	// Cambodian Riel (៛)
	KHR Code = "KHR"
	// Comorian Franc (Fr)
	KMF Code = "KMF"
	// North Korean Won (₩)
	KPW Code = "KPW"
	// South Korean Won (₩)
	KRW Code = "KRW"
	// Kuwaiti Dinar (د.ك)
	KWD Code = "KWD"
	// Cayman Islands Dollar ($)
	KYD Code = "KYD"
	// Kazakhstani Tenge (₸)
	KZT Code = "KZT"
	// Lao Kip (₭)
	LAK Code = "LAK"
	// Lebanese Pound (ل.ل)
	LBP Code = "LBP"
	// Sri Lankan Rupee (₨)
	LKR Code = "LKR"
	// Liberian Dollar ($)
	LRD Code = "LRD"
	// Lesotho Loti (L)
	LSL Code = "LSL"
	// Libyan Dinar (ل.د)
	LYD Code = "LYD"
	// Moroccan Dirham (د.م.)
	MAD Code = "MAD"
	// Moldovan Leu (L)
	MDL Code = "MDL"
	// Malagasy Ariary (Ar)
	MGA Code = "MGA"
	// Macedonian Denar (ден)
	MKD Code = "MKD"
	// Myanmar Kyat (K)
	MMK Code = "MMK"
	// Mongolian Tögrög (₮)
	MNT Code = "MNT"
	// United Arab Emirates Dirham (د.إ)
	AED Code = "AED"
	// Mauritanian Ouguiya (UM)
	MRU Code = "MRU"
	// Mauritian Rupee (₨)
	MUR Code = "MUR"
	// Polish Złoty (zł)
	PLN Code = "PLN"
	// Aruban Florin (ƒ)
	AWG Code = "AWG"
	// Dominican Peso ($)
	DOP Code = "DOP"
	// Malaysian Ringgit (RM)
	MYR Code = "MYR"
	// Mozambican Metical (MTn)
	MZN Code = "MZN"
	// Namibian Dollar ($)
	NAD Code = "NAD"
	// Nigerian Naira (₦)
	NGN Code = "NGN"
	// Nicaraguan Córdoba (C$)
	NIO Code = "NIO"
	// Norwegian Krone (kr)
	NOK Code = "NOK"
	// Nepalese Rupee (Rs.)
	NPR Code = "NPR"
	// New Zealand Dollar ($)
	NZD Code = "NZD"
	// Omani Rial (ر.ع.)
	OMR Code = "OMR"
	// Panamanian Balboa (B/.)
	PAB Code = "PAB"
	// Peruvian Sol (S/)
	PEN Code = "PEN"
	// Papua New Guinean Kina (K)
	PGK Code = "PGK"
	// Philippine Peso (₱)
	PHP Code = "PHP"
	// Pakistani Rupee (₨)
	PKR Code = "PKR"
	// Maldivian Rufiyaa (MVR)
	MVR Code = "MVR"
	// Paraguayan Guaraní (₲)
	PYG Code = "PYG"
	// Qatari Riyal (ر.ق)
	QAR Code = "QAR"
	// Romanian Leu (Lei)
	RON Code = "RON"
	// Serbian Dinar (РСД)
	RSD Code = "RSD"
	// Russian Ruble (₽)
	RUB Code = "RUB"
	// Rwandan Franc (FRw)
	RWF Code = "RWF"
	// Saudi Riyal (ر.س)
	SAR Code = "SAR"
	// Solomon Islands Dollar ($)
	SBD Code = "SBD"
	// Seychellois Rupee (₨)
	SCR Code = "SCR"
	// Sudanese Pound (£)
	SDG Code = "SDG"
	// Swedish Krona (kr)
	SEK Code = "SEK"
	// Singapore Dollar ($)
	SGD Code = "SGD"
	// Saint Helenian Pound (£)
	SHP Code = "SHP"
	// Slovak Koruna (Sk)
	SKK Code = "SKK"
	// New Leone (Le)
	SLE Code = "SLE"
	// Sierra Leonean Leone (Le)
	SLL Code = "SLL"
	// Somali Shilling (Sh)
	SOS Code = "SOS"
	// Surinamese Dollar ($)
	SRD Code = "SRD"
	// South Sudanese Pound (£)
	SSP Code = "SSP"
	// São Tomé and Príncipe Dobra (Db)
	STD Code = "STD"
	// São Tomé and Príncipe Second Dobra (Db)
	STN Code = "STN"
	// Salvadoran Colón (₡)
	SVC Code = "SVC"
	// Syrian Pound (£S)
	SYP Code = "SYP"
	// Swazi Lilangeni (E)
	SZL Code = "SZL"
	// Thai Baht (฿)
	THB Code = "THB"
	// Tajikistani Somoni (ЅМ)
	TJS Code = "TJS"
	// Turkmenistani Manat (T)
	TMT Code = "TMT"
	// Tunisian Dinar (د.ت)
	TND Code = "TND"
	// Tongan Paʻanga (T$)
	TOP Code = "TOP"
	// Turkish Lira (₺)
	TRY Code = "TRY"
	// Trinidad and Tobago Dollar ($)
	TTD Code = "TTD"
	// New Taiwan Dollar ($)
	TWD Code = "TWD"
	// Tanzanian Shilling (Sh)
	TZS Code = "TZS"
	// Ukrainian Hryvnia (₴)
	UAH Code = "UAH"
	// Ugandan Shilling (USh)
	UGX Code = "UGX"
	// Afghan Afghani (؋)
	AFN Code = "AFN"
	// Uruguayan Peso ($U)
	UYU Code = "UYU"
	// Uzbekistan Som (so'm)
	UZS Code = "UZS"
	// Venezuelan Bolívar Soberano (Bs)
	VES Code = "VES"
	// Vietnamese Đồng (₫)
	VND Code = "VND"
	// Vanuatu Vatu (Vt)
	VUV Code = "VUV"
	// Samoan Tala (T)
	WST Code = "WST"
	// Central African Cfa Franc (CFA)
	XAF Code = "XAF"
	// Silver (Troy Ounce) (oz t)
	XAG Code = "XAG"
	// Gold (Troy Ounce) (oz t)
	XAU Code = "XAU"
	// European Composite Unit ()
	XBA Code = "XBA"
	// European Monetary Unit ()
	XBB Code = "XBB"
	// European Unit of Account 9 ()
	XBC Code = "XBC"
	// European Unit of Account 17 ()
	XBD Code = "XBD"
	// East Caribbean Dollar ($)
	XCD Code = "XCD"
	// Special Drawing Rights (SDR)
	XDR Code = "XDR"
	// West African Cfa Franc (Fr)
	XOF Code = "XOF"
	// Palladium (oz t)
	XPD Code = "XPD"
	// Cfp Franc (Fr)
	XPF Code = "XPF"
	// Platinum (oz t)
	XPT Code = "XPT"
	// Codes specifically reserved for testing purposes ()
	XTS Code = "XTS"
	// Yemeni Rial (﷼)
	YER Code = "YER"
	// South African Rand (R)
	ZAR Code = "ZAR"
	// Zambian Kwacha (ZK)
	ZMK Code = "ZMK"
	// Zambian Kwacha (K)
	ZMW Code = "ZMW"
	// Bitcoin Cash (₿)
	BCH Code = "BCH"
	// Bitcoin (₿)
	BTC Code = "BTC"
	// Jersey Pound (£)
	JEP Code = "JEP"
	// Guernsey Pound (£)
	GGP Code = "GGP"
	// Isle of Man Pound (£)
	IMP Code = "IMP"
	// UIC Franc ()
	XFU Code = "XFU"
	// British Penny ()
	GBX Code = "GBX"
	// Chinese Renminbi Yuan Offshore (¥)
	CNH Code = "CNH"
	// USD Coin (USDC)
	USDC Code = "USDC"
)

List of ISO4217 and common currency codes. 

const CodeEmpty Code = ""

CodeEmpty is used when there is no code.

func (Code) Def added in v0.29.0 

func (c Code) Def() *Def

Def provides the currency definition for the code.

func (Code) JSONSchema added in v0.29.0 

func (Code) JSONSchema() *jsonschema.Schema

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

func (Code) String added in v0.76.0 

func (c Code) String() string

Strings provides the currency code as a string.

func (Code) Validate 

func (c Code) Validate() error

Validate ensures the currency code is valid according to the ISO 4217 three-letter list.

type Def 

type Def struct {
	// Priority is an arbitrary number used for ordering of currencies
	// roughly based on popularity.
	Priority int `json:"priority"`
	// Standard ISO 4217 code
	ISOCode Code `json:"iso_code"`
	// ISO numeric code
	ISONumeric string `json:"iso_numeric"`
	// English name of the currency
	Name string `json:"name"`
	// Symbol representation
	Symbol string `json:"symbol"`
	// When presented alongside other currency's with potentially
	// the same symbol, use this representation instead.
	DisambiguateSymbol string `json:"disambiguate_symbol"`
	// Alternative presentation symbols
	AlternateSymbols []string `json:"alternate_symbols"`
	// Name of the currency subunit
	SubunitName string `json:"subunit_name"`
	// Conversion amount to subunit
	Subunits uint32 `json:"subunits"`
	// Template determines how to layout the units and number
	Template string `json:"template"`
	// Decimal mark normally expected in output
	DecimalMark string `json:"decimal_mark"`
	// Thousands separator normally expected in output
	ThousandsSeparator string `json:"thousands_separator"`
	// Smallest acceptable amount of the currency
	SmallestDenomination int `json:"smallest_denomination"`
	// NumeralSystem defines how numbers should be printed out, by default this
	// is 'western'.
	NumeralSystem num.NumeralSystem `json:"numeral_system"`
}

Def helps define how to format a currency as is based on the [Ruby Money Gem's](https://rubymoney.github.io/money/) Currency model.

func ByISONumber added in v0.71.0 

func ByISONumber(n string) *Def

ByISONumber tries to find the currency definition by it's assigned ISO number.

func Definitions added in v0.71.0 

func Definitions() []*Def

Definitions provides an array of all currency definitions ordered by priority.

func Get 

func Get(c Code) *Def

Get provides the code's currency definition, or nil if no match found.

func (*Def) FormatAmount added in v0.71.0 

func (d *Def) FormatAmount(amount num.Amount) string

FormatAmount takes the provided amount and formats it according to the default rules of the currency definition.

func (*Def) FormatPercentage added in v0.71.0 

func (d *Def) FormatPercentage(percentage num.Percentage) string

FormatPercentage takes the provided percentage and formats it according to the decimal and thousands rules of the currency definition.

func (*Def) Formatter added in v0.71.0 

func (d *Def) Formatter(opts ...FormatOption) num.Formatter

Formatter provides a number formatter for the currency definition.

func (*Def) Zero added in v0.52.2 

func (d *Def) Zero() num.Amount

Zero provides the currency's zero amount which is pre-set with the minimum precision for the currency.

type ExchangeRate 

type ExchangeRate struct {
	// Currency code this will be converted from.
	From Code `json:"from" jsonschema:"title=From"`
	// Currency code this exchange rate will convert into.
	To Code `json:"to" jsonschema:"title=To"`
	// At represents the effective date and time at which the exchange rate
	// is determined by the source. The time may be zero if referring to a
	// specific day only.
	At *cal.DateTime `json:"at,omitempty" jsonschema:"title=At"`
	// Source key provides a reference to the source the exchange rate was
	// obtained from. Typically this will be determined by an application
	// used to update exchange rates automatically.
	Source cbc.Key `json:"source,omitempty" jsonschema:"title=Source"`
	// How much is 1 of the "from" currency worth in the "to" currency.
	Amount num.Amount `json:"amount" jsonschema:"title=Amount"`
}

ExchangeRate contains data on the rate to be used when converting amounts from one currency into another.

For reference, naming here is based on the following english grammar examples: - Exchange from USD to EUR. - Convert from USD into EUR.

If the destination or document's currency is EUR and some amounts are defined in USD, the `ExchangeRate` instance may be defined and used as follows: 

  rate := &currency.ExchangeRate{
	From:   currency.USD,
	To:     currency.EUR,
	Amount: "0.875967",
  }

  val := MakeAmount(100, 2) // 100.00 USD
  rate.Convert(val)         // 87.60 EUR

func MatchExchangeRate added in v0.76.0 

func MatchExchangeRate(rates []*ExchangeRate, from, to Code) *ExchangeRate

MatchExchangeRate will attempt to find the matching exchange rate that will convert from one currency into another. Will return nil if no match is found or the currencies are the same.

func (*ExchangeRate) Convert added in v0.76.0 

func (er *ExchangeRate) Convert(amount num.Amount) num.Amount

Convert performs the currency conversion defined by the exchange rate.

func (*ExchangeRate) Validate added in v0.71.0 

func (er *ExchangeRate) Validate() error

Validate ensures the content of the exchange rate looks good.

type FormatOption added in v0.71.0 

type FormatOption func(*Def, num.Formatter) num.Formatter

FormatOption defines how to configure the formatter for common use cases and custom options.

func WithDisambiguateSymbol added in v0.71.0 

func WithDisambiguateSymbol() FormatOption

WithDisambiguateSymbol will override the default symbol to use with one that is unique for the context. Lots of countries for example use "$" as their main currency symbol, using this option will ensure that `US$` is used in output instead.

func WithNumeralSystem added in v0.71.0 

func WithNumeralSystem(ns num.NumeralSystem) FormatOption

WithNumeralSystem will override the default numeral system used to output numbers.

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.