Struct Rates 

pub struct Rates { /* private fields */ }

All HMRC rate tables: bundled data plus (with the http feature) fetched periods.

Send + Sync: cloning is cheap, bundled data is shared statics.

Start with Rates::new.

Implementations

impl Rates

pub fn new() -> Rates

The bundled dataset. Infallible and effectively free. The tables live in the binary’s read-only data, nothing is parsed or allocated.

Examples

use hmrc_rates::Rates;

let rates = Rates::new();
assert!(rates.months().count() > 100);

pub fn monthly_rate( &self, code: &str, year_month: impl Into<YearMonth>, ) -> Result<Rate, LookupError>

The monthly rate for code, strictly for that month.

Accepts anything convertible to YearMonth, including chrono::NaiveDate. "GBP" (any case) returns the identity rate for any month.

Examples

use hmrc_rates::Rates;
use rust_decimal::Decimal;

let rates = Rates::new();
let date = chrono::NaiveDate::from_ymd_opt(2025, 8, 15).unwrap();
let rate = rates.monthly_rate("USD", date)?;
let gbp = rate.to_gbp(Decimal::from(100));

pub fn monthly_rate_or_earlier( &self, code: &str, year_month: impl Into<YearMonth>, max_months_back: u32, ) -> Result<Rate, LookupError>

Like Rates::monthly_rate, but walks back to the nearest earlier published month, at most max_months_back steps.

This is the crate’s only fallback, and it is opt-in. Rate::period reveals which month was actually used.

Examples

use hmrc_rates::{Period, Rates};

let rates = Rates::new();
let next = rates.months().next_back().unwrap().next(); // not published yet
assert!(rates.monthly_rate("USD", next).is_err()); // strict lookup fails
let rate = rates.monthly_rate_or_earlier("USD", next, 1)?;
assert_ne!(rate.period(), Period::YearMonth(next)); // the substitution is visible

pub fn monthly( &self, year_month: impl Into<YearMonth>, ) -> Result<Table<'_>, LookupError>

The whole monthly table for one month.

pub fn spot(&self, period: YearEnd) -> Result<Table<'_>, LookupError>

The spot table for a 31 March / 31 December period.

Examples

use hmrc_rates::{Rates, YearEnd};

let rates = Rates::new();
let usd = rates.spot(YearEnd::december(2024))?.rate("USD")?;

pub fn average(&self, period: YearEnd) -> Result<Table<'_>, LookupError>

The yearly-average table for a 31 March / 31 December period.

Examples

use hmrc_rates::{Rates, YearEnd};

let rates = Rates::new();
// Self Assessment style: the average for the year to 31 March 2025.
let eur = rates.average(YearEnd::march(2025))?.rate("EUR")?;

pub fn weekly(&self, date: NaiveDate) -> Result<Table<'_>, LookupError>

The weekly-amendment table whose validity range contains date.

Weekly files list only the currencies HMRC amended that week (series ran 2014-01 to 2016-04, then was discontinued).

Examples

use hmrc_rates::Rates;

let rates = Rates::new();
let date = chrono::NaiveDate::from_ymd_opt(2014, 1, 10).unwrap();
let lira = rates.weekly(date)?.rate("TRY")?;

pub fn months(&self) -> impl DoubleEndedIterator<Item = YearMonth> + use<'_>

All published months, ascending.

pub fn spot_periods(&self) -> impl DoubleEndedIterator<Item = YearEnd> + use<'_>

All published spot periods, ascending.

pub fn average_periods( &self, ) -> impl DoubleEndedIterator<Item = YearEnd> + use<'_>

All published yearly-average periods, ascending.

pub fn weeks(&self) -> impl DoubleEndedIterator<Item = Period> + use<'_>

All weekly-amendment validity ranges, ascending, as Period::Week items.

pub fn currencies( &self, table: RateType, ) -> impl Iterator<Item = Currency> + use<'_>

Every currency that appears anywhere in the given series, ascending.

Trait Implementations

impl Clone for Rates

fn clone(&self) -> Rates

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Rates

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Rates

Available on crate feature bundled only.

fn default() -> Rates

Returns the “default value” for a type.