Struct Currency
pub struct Currency([u8; 3]);Expand description
An ISO 4217 currency code (three uppercase ASCII letters).
The code is stored inline as the three bytes it is, not in a heap allocation:
Currency::new is the only constructor and it validates the width, so the
representation cannot be handed anything else. That makes Currency Copy and
makes naming a trade’s currency free — it was one heap allocation per pricing
call, and a book valuation makes one per trade.
Tuple Fields§
§0: [u8; 3]Implementations§
§impl Currency
impl Currency
pub fn new(code: &str) -> Result<Self, VocabularyParseError>
pub fn new(code: &str) -> Result<Self, VocabularyParseError>
Constructs a currency from an ISO 4217 code, validating its shape.
§Errors
VocabularyParseError naming the accepted form when code is not
exactly three ASCII uppercase letters. The shape is all that is checked:
a well-formed code naming no real currency is accepted, because this
type is a validated three-byte code and not a registry.
pub fn code(&self) -> &str
pub fn code(&self) -> &str
The ISO 4217 code.
§The re-validation here is deliberate, and it is not free
The bytes came from new, which admits only ASCII uppercase, so
they are valid UTF-8 by construction and from_utf8 can never fail. It runs
anyway, because the alternative is from_utf8_unchecked and this crate has
exactly one unsafe block (core::ad::active_tape); a second one was
weighed against what it buys and declined.
What it costs, measured: lookups/fx_convert_direct is a ~20 ns benchmark
that is little more than two code() calls and a hashed map probe, and it
runs +16% slower than the String representation this replaced —
reproduced isolated, twice. fx_convert_triangulated gives up ~7 points on
the same axis. In absolute terms that is roughly 3 ns per conversion, and a
book pays it once per foreign-currency trade.
So: if a profile ever shows code() mattering somewhere that is not a
micro-benchmark, the fix is known and measured — it is a decision to revisit,
not a discovery to make. Do not swap it silently in either direction.
§Panics
Never in practice. The bytes were validated as ASCII uppercase by
new, so the UTF-8 check above cannot fail; a panic here
would mean a Currency was built bypassing its only constructor.
pub fn minor_units(&self) -> u8
pub fn minor_units(&self) -> u8
The ISO 4217 minor-unit digit count (e.g. USD = 2, JPY = 0).
Currency carries this metadata but no settlement behaviour; FX spot
lag is a per-pair convention modelled in
FxIndex. Unknown codes default to 2 (the most
common ISO 4217 case).
pub fn settlement_center(&self) -> Option<BusinessCenter>
pub fn settlement_center(&self) -> Option<BusinessCenter>
This currency’s default settlement BusinessCenter, or None if the
currency has no modelled center. Supplies the calendar for currencies in
the fallback (unlisted-pair) path; listed pairs use their explicit
calendar expression in FxIndex.