# `Currency`

An active ISO 4217 currency, written as its code, `GBP`.

[Money and banking](types.md#money-and-banking); not ordered; since Jadpo 0.1.0.

## Make one

Pick one of its variants, `Currency.aed`.

`text.parse(raw, as: Currency)` reads one from its text; text that isn't one at all fails `malformed`, such as `pound`, `XYZ` or `XAU`.

This operation gives one: `money.currency`.

## Variants

170 variants, each with the code its text is written in. `aed` (`AED`), `afn` (`AFN`), `all_` (`ALL`), `amd` (`AMD`), `ang` (`ANG`), `aoa` (`AOA`), `ars` (`ARS`), `aud` (`AUD`), `awg` (`AWG`), `azn` (`AZN`), `bam` (`BAM`), `bbd` (`BBD`), `bdt` (`BDT`), `bgn` (`BGN`), `bhd` (`BHD`), `bif` (`BIF`), `bmd` (`BMD`), `bnd` (`BND`), `bob` (`BOB`), `bov` (`BOV`), `brl` (`BRL`), `bsd` (`BSD`), `btn` (`BTN`), `bwp` (`BWP`), `byn` (`BYN`), `bzd` (`BZD`), `cad` (`CAD`), `cdf` (`CDF`), `che` (`CHE`), `chf` (`CHF`), `chw` (`CHW`), `clf` (`CLF`), `clp` (`CLP`), `cny` (`CNY`), `cop` (`COP`), `cou` (`COU`), `crc` (`CRC`), `cuc` (`CUC`), `cup` (`CUP`), `cve` (`CVE`), `czk` (`CZK`), `djf` (`DJF`), `dkk` (`DKK`), `dop` (`DOP`), `dzd` (`DZD`), `egp` (`EGP`), `ern` (`ERN`), `etb` (`ETB`), `eur` (`EUR`), `fjd` (`FJD`), `fkp` (`FKP`), `gbp` (`GBP`), `gel` (`GEL`), `ghs` (`GHS`), `gip` (`GIP`), `gmd` (`GMD`), `gnf` (`GNF`), `gtq` (`GTQ`), `gyd` (`GYD`), `hkd` (`HKD`), `hnl` (`HNL`), `hrk` (`HRK`), `htg` (`HTG`), `huf` (`HUF`), `idr` (`IDR`), `ils` (`ILS`), `inr` (`INR`), `iqd` (`IQD`), `irr` (`IRR`), `isk` (`ISK`), `jmd` (`JMD`), `jod` (`JOD`), `jpy` (`JPY`), `kes` (`KES`), `kgs` (`KGS`), `khr` (`KHR`), `kmf` (`KMF`), `kpw` (`KPW`), `krw` (`KRW`), `kwd` (`KWD`), `kyd` (`KYD`), `kzt` (`KZT`), `lak` (`LAK`), `lbp` (`LBP`), `lkr` (`LKR`), `lrd` (`LRD`), `lsl` (`LSL`), `lyd` (`LYD`), `mad` (`MAD`), `mdl` (`MDL`), `mga` (`MGA`), `mkd` (`MKD`), `mmk` (`MMK`), `mnt` (`MNT`), `mop` (`MOP`), `mru` (`MRU`), `mur` (`MUR`), `mvr` (`MVR`), `mwk` (`MWK`), `mxn` (`MXN`), `mxv` (`MXV`), `myr` (`MYR`), `mzn` (`MZN`), `nad` (`NAD`), `ngn` (`NGN`), `nio` (`NIO`), `nok` (`NOK`), `npr` (`NPR`), `nzd` (`NZD`), `omr` (`OMR`), `pab` (`PAB`), `pen` (`PEN`), `pgk` (`PGK`), `php` (`PHP`), `pkr` (`PKR`), `pln` (`PLN`), `pyg` (`PYG`), `qar` (`QAR`), `ron` (`RON`), `rsd` (`RSD`), `rub` (`RUB`), `rwf` (`RWF`), `sar` (`SAR`), `sbd` (`SBD`), `scr` (`SCR`), `sdg` (`SDG`), `sek` (`SEK`), `sgd` (`SGD`), `shp` (`SHP`), `sle` (`SLE`), `sll` (`SLL`), `sos` (`SOS`), `srd` (`SRD`), `ssp` (`SSP`), `stn` (`STN`), `svc` (`SVC`), `syp` (`SYP`), `szl` (`SZL`), `thb` (`THB`), `tjs` (`TJS`), `tmt` (`TMT`), `tnd` (`TND`), `top` (`TOP`), `try` (`TRY`), `ttd` (`TTD`), `twd` (`TWD`), `tzs` (`TZS`), `uah` (`UAH`), `ugx` (`UGX`), `usd` (`USD`), `usn` (`USN`), `uyi` (`UYI`), `uyu` (`UYU`), `uyw` (`UYW`), `uzs` (`UZS`), `ved` (`VED`), `ves` (`VES`), `vnd` (`VND`), `vuv` (`VUV`), `wst` (`WST`), `xaf` (`XAF`), `xcd` (`XCD`), `xcg` (`XCG`), `xof` (`XOF`), `xpf` (`XPF`), `yer` (`YER`), `zar` (`ZAR`), `zmw` (`ZMW`), `zwg` (`ZWG`), `zwl` (`ZWL`).

## Text, JSON and storage

`text.from` writes its canonical text, the one form `text.parse` reads back. JSON sends its canonical text as a string.

| Text | JSON |
|---|---|
| `GBP` | `"GBP"` |
| `HRK` | `"HRK"` |
| `JPY` | `"JPY"` |

It is stored in one column named for the field, of type `text`. `HRK` is stored as `'HRK'`.

## Shown to people

`text.format(value, locale:)` shows it to people in their locale.

With `locale: Locale.en_gb`:

| Value | Shown |
|---|---|
| `GBP` | `British Pound` |
| `HRK` | `Croatian Kuna` |
| `JPY` | `Japanese Yen` |

## Operations

- `money.currency(value: Money) -> Currency`: The currency `value` is in.
- `money.from_minor(amount: Int, currency: Currency) -> Money`: `amount` minor units of `currency`: `money.from_minor(1050, Currency.gbp)` is £10.50.
- `money.of(amount: Decimal, currency: Currency) -> Money`: `amount` major units of `currency`, a `Decimal`: `money.of(10.50, Currency.gbp)` is £10.50. It fails with `too_many_places` for more places than the currency has (10.505 in pounds), unless the currency is written out and the amount proved to have no more.
- `money.sum(items: List<Money>, currency: Currency) -> Money`: The items added up in `currency`, the zero an empty list gives. It fails with `currency_mismatch` for an item in another currency, unless the items' type fixes `currency`.

Like every standard type, it also has the contract's own operations: `text.parse`, `text.from`, `text.format`, `json.read`, `json.write` and `==`. It isn't ordered, so `<` and sorting don't take it. [Every standard type meets one contract](../topics/every-standard-type-meets-one-contract.md) says how they work.