Look up currencies by country code, and list a currency's countries #40

Open
opened 2026-08-16 15:11:25 +00:00 by rosa · 0 comments
Owner

isodata.tsv already carries a used_by_alpha2 column, but build.rs never
reads it. Two additions would put it to work:

  • Currency::countries() — the countries a currency is used in.
  • A reverse lookup from a country code to the currencies used there.

This is a proposal, not a decision. The trade-off in "Cost" below is the part
that needs a call.

Data bugs to fix first

These are worth fixing regardless of whether the API lands.

  1. The NAD row is column-shifted. isodata.tsv:105 reads
    NAD 516 Namibian dollar N$ NA 2 — the country NA sits in
    subunit_symbol, and used_by_alpha2 is empty. Nothing reads either field
    today, so Namibia would silently drop out the moment countries become API.

  2. HR maps only to a dead currency. Croatia appears under HRK, which is
    flagged superseded(EUR), and is absent from the EUR row. A lookup for
    HR would answer with the kuna. BG has the same shape: Bulgaria is listed
    under BGN alone and is not in the EUR row.

One country, several currencies

Nine countries use two currencies that are neither fund, special, nor
superseded: BB, BM, BT, HT, IO, KH, LS, PA, SV. Panama uses
both PAB and USD, and both answers are correct. So the reverse lookup
returns a slice; there is no singular Currency::for_country() to offer.

Coverage is otherwise good: 247 distinct country codes, 246 of them reachable
through a currency with no flags.

Proposed shape

  1. A CountryCode([u8; 2]) newtype, validated as two capital ASCII letters,
    mirroring IsoAlphabeticCode. Without it the API hands back bare &str in a
    crate whose every other code is a validated type.

  2. Currency::countries(self) -> &'static [CountryCode]. One added field, a fat
    pointer; Currency grows by 16 bytes and stays Copy. Note that the derived
    PartialEq and Hash would then walk the slice.

  3. Currency::used_in(code: CountryCode) -> &'static [Currency], generated in
    build.rs as one match arm per country, the way the existing code lookups
    are. Document the order of the results so it is not accidental API.

  4. Expose the flags column as a currency status (fund, special, superseded).
    It only feeds doc text today. A caller handed [CUC, CUP] for Cuba has no
    way to drop the dead one, and country lookup is what makes that omission
    bite.

Cost

The crate tracks one standard today. This makes it track two. used_by_alpha2
is not part of ISO 4217 — that standard names entities in English, not ISO 3166
alpha-2 — so the column is a hand-maintained join against a second standard with
its own churn. Eurozone accessions will rot it quietly, as HR and BG already
show.

`isodata.tsv` already carries a `used_by_alpha2` column, but `build.rs` never reads it. Two additions would put it to work: - `Currency::countries()` — the countries a currency is used in. - A reverse lookup from a country code to the currencies used there. This is a proposal, not a decision. The trade-off in "Cost" below is the part that needs a call. ## Data bugs to fix first These are worth fixing regardless of whether the API lands. 1. **The `NAD` row is column-shifted.** `isodata.tsv:105` reads `NAD 516 Namibian dollar N$ NA 2` — the country `NA` sits in `subunit_symbol`, and `used_by_alpha2` is empty. Nothing reads either field today, so Namibia would silently drop out the moment countries become API. 2. **`HR` maps only to a dead currency.** Croatia appears under `HRK`, which is flagged `superseded(EUR)`, and is absent from the `EUR` row. A lookup for `HR` would answer with the kuna. `BG` has the same shape: Bulgaria is listed under `BGN` alone and is not in the `EUR` row. ## One country, several currencies Nine countries use two currencies that are neither fund, special, nor superseded: `BB`, `BM`, `BT`, `HT`, `IO`, `KH`, `LS`, `PA`, `SV`. Panama uses both `PAB` and `USD`, and both answers are correct. So the reverse lookup returns a slice; there is no singular `Currency::for_country()` to offer. Coverage is otherwise good: 247 distinct country codes, 246 of them reachable through a currency with no flags. ## Proposed shape 1. A `CountryCode([u8; 2])` newtype, validated as two capital ASCII letters, mirroring `IsoAlphabeticCode`. Without it the API hands back bare `&str` in a crate whose every other code is a validated type. 2. `Currency::countries(self) -> &'static [CountryCode]`. One added field, a fat pointer; `Currency` grows by 16 bytes and stays `Copy`. Note that the derived `PartialEq` and `Hash` would then walk the slice. 3. `Currency::used_in(code: CountryCode) -> &'static [Currency]`, generated in `build.rs` as one match arm per country, the way the existing code lookups are. Document the order of the results so it is not accidental API. 4. Expose the `flags` column as a currency status (fund, special, superseded). It only feeds doc text today. A caller handed `[CUC, CUP]` for Cuba has no way to drop the dead one, and country lookup is what makes that omission bite. ## Cost The crate tracks one standard today. This makes it track two. `used_by_alpha2` is not part of ISO 4217 — that standard names entities in English, not ISO 3166 alpha-2 — so the column is a hand-maintained join against a second standard with its own churn. Eurozone accessions will rot it quietly, as `HR` and `BG` already show.
Sign in to join this conversation.
No milestone
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
rosa/lucre#40
No description provided.