Support non-ISO and custom currencies #41

Closed
opened 2026-08-17 13:37:34 +00:00 by rosa · 0 comments
Owner

Problem

Currency is a closed set: the ISO 4217 table generated into the crate by build.rs. There is no way to represent Bitcoin (8 minor digits), loyalty points, in-game currencies, or historical currencies from ISO 4217-3. Every mature money library (Joda-Money, JSR-354, Ruby's money) supports user-defined currencies, and it is among their most-used features.

Recommendation: registry via inventory, not a trait

Keep Currency a single concrete type and let downstream crates register custom currencies with inventory, behind a cargo feature.

The trait design (Money<C: Currency>) is rejected. The type parameter spreads into every public type — MoneyBag, Exchange, ExchangeRate, Parser, Format, the serde impls — and into every downstream signature that mentions money. That trades a large interface cost for a problem the registry solves inside the module.

An explicit registry value (CurrencyRegistry passed to each parser) is also rejected. Serde deserialization has no way to receive such a value, so Deserialize for Money could never see custom currencies. A process-wide collection is what lets FromStr, TryFrom, and serde keep working unchanged, and inventory provides one without mutable global state: submissions are collected during startup, before any lookup runs.

Design sketch

Currency already suits this shape: its fields are inline and Copy, with &'static str name and symbol, so a custom currency is just another Currency value built from statics. Equality stays derived field equality.

// In a downstream crate:
const BTC: Currency = Currency::custom("BTC", 8, "₿", "Bitcoin");
inventory::submit!(BTC);
  • Currency::custom is a const fn, so definitions work in const items and in inventory::submit!.
  • The constant is usable immediately, with or without submission. Submission is what makes the code reachable by lookup: FromStr, TryFrom<&str>, Parser, and Deserialize consult the generated ISO match first, then a OnceLock index built once from inventory::iter.
  • The inventory dependency and the lookup layer sit behind a custom-currencies feature. The default build keeps today's dependency footprint.

Collision policy

  • A submitted code that shadows an ISO code, or two submissions of the same code with different data, is a bug in the program. Building the index panics with a message naming the code. Identical duplicate submissions are tolerated.
  • An unsubmitted custom Currency still works for arithmetic and formatting; only text lookup requires submission.

Breaking changes required

The current code types are ISO-shaped, and custom currencies do not fit them:

  1. IsoAlphabeticCode holds exactly 3 ASCII uppercase letters. USDT, DOGE, and points codes need more. Add a widened CurrencyCode holding 1 to 8 ASCII uppercase letters, stored inline so Currency stays Copy. It is returned by a new Currency::code; ISO codes stay 3 letters within it. alphabetic_code can stay for ISO values or be deprecated.
  2. numeric_code returns IsoNumericCode unconditionally. Custom currencies have none, so the return type becomes Option<IsoNumericCode>.

Both are semver-major. They can land in the same release as the registry.

Accepted trade-offs

  • Registration is compile-time only. Currencies loaded from config or a database at runtime stay out of scope; the &'static str fields already assume static definitions.
  • inventory registers during life-before-main. On its supported platforms (Linux, macOS, Windows, FreeBSD, Android, iOS, WebAssembly) this is transparent. On an unsupported platform the collection is silently empty: custom codes fail to parse or deserialize there, but nothing corrupts. Document this in the feature's docs.
## Problem `Currency` is a closed set: the ISO 4217 table generated into the crate by `build.rs`. There is no way to represent Bitcoin (8 minor digits), loyalty points, in-game currencies, or historical currencies from ISO 4217-3. Every mature money library (Joda-Money, JSR-354, Ruby's `money`) supports user-defined currencies, and it is among their most-used features. ## Recommendation: registry via `inventory`, not a trait Keep `Currency` a single concrete type and let downstream crates register custom currencies with [`inventory`](https://crates.io/crates/inventory), behind a cargo feature. The trait design (`Money<C: Currency>`) is rejected. The type parameter spreads into every public type — `MoneyBag`, `Exchange`, `ExchangeRate`, `Parser`, `Format`, the serde impls — and into every downstream signature that mentions money. That trades a large interface cost for a problem the registry solves inside the module. An explicit registry value (`CurrencyRegistry` passed to each parser) is also rejected. Serde deserialization has no way to receive such a value, so `Deserialize` for `Money` could never see custom currencies. A process-wide collection is what lets `FromStr`, `TryFrom`, and serde keep working unchanged, and `inventory` provides one without mutable global state: submissions are collected during startup, before any lookup runs. ## Design sketch `Currency` already suits this shape: its fields are inline and `Copy`, with `&'static str` name and symbol, so a custom currency is just another `Currency` value built from statics. Equality stays derived field equality. ```rust // In a downstream crate: const BTC: Currency = Currency::custom("BTC", 8, "₿", "Bitcoin"); inventory::submit!(BTC); ``` - `Currency::custom` is a `const fn`, so definitions work in `const` items and in `inventory::submit!`. - The constant is usable immediately, with or without submission. Submission is what makes the code reachable by lookup: `FromStr`, `TryFrom<&str>`, `Parser`, and `Deserialize` consult the generated ISO `match` first, then a `OnceLock` index built once from `inventory::iter`. - The `inventory` dependency and the lookup layer sit behind a `custom-currencies` feature. The default build keeps today's dependency footprint. ### Collision policy - A submitted code that shadows an ISO code, or two submissions of the same code with different data, is a bug in the program. Building the index panics with a message naming the code. Identical duplicate submissions are tolerated. - An unsubmitted custom `Currency` still works for arithmetic and formatting; only text lookup requires submission. ## Breaking changes required The current code types are ISO-shaped, and custom currencies do not fit them: 1. `IsoAlphabeticCode` holds exactly 3 ASCII uppercase letters. `USDT`, `DOGE`, and points codes need more. Add a widened `CurrencyCode` holding 1 to 8 ASCII uppercase letters, stored inline so `Currency` stays `Copy`. It is returned by a new `Currency::code`; ISO codes stay 3 letters within it. `alphabetic_code` can stay for ISO values or be deprecated. 2. `numeric_code` returns `IsoNumericCode` unconditionally. Custom currencies have none, so the return type becomes `Option<IsoNumericCode>`. Both are semver-major. They can land in the same release as the registry. ## Accepted trade-offs - Registration is compile-time only. Currencies loaded from config or a database at runtime stay out of scope; the `&'static str` fields already assume static definitions. - `inventory` registers during life-before-main. On its supported platforms (Linux, macOS, Windows, FreeBSD, Android, iOS, WebAssembly) this is transparent. On an unsupported platform the collection is silently empty: custom codes fail to parse or deserialize there, but nothing corrupts. Document this in the feature's docs.
rosa closed this issue 2026-08-17 14:27:06 +00:00
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#41
No description provided.