Table of Contents

FixedDatedRateProvider Class

Definition

Namespace
Bodu.Financial.ExchangeRates
Assembly
Bodu.Financial.dll
Package
Bodu.Financial 1.0.0
Source
FixedDatedRateProvider.cs

Provides an immutable IDatedRateProvider facade over an RateBook, applying an explicit provider-priority list to disambiguate pairs that carry observations from more than one publishing source.

public sealed class FixedDatedRateProvider : IDatedRateProvider, IHistoricalRateProvider
Inheritance
FixedDatedRateProvider
Implements
Inherited Members
Extension Methods

Remarks

Use this provider as the read-side hand-off from an RateTableBuilder built during data ingest. The ToBook() method materialises the multi-provider book, and this provider then selects rates from it using either the single available provider per pair, or the supplied priority list.

Lookups walk the provider priority once per pair, perform a FrozenDictionary<TKey, TValue> probe for each candidate (pair, provider), then an BinarySearch<T>(T[], T) over the series' date array. Successful and failing lookups both allocate no managed memory beyond the RateLookupResult on success. 

using Bodu.Financial;

// Construct directly from a handful of observations (one provider per pair).
var provider = new FixedDatedRateProvider(new[]
{
    new ExchangeRate(CurrencyCode.USD, CurrencyCode.EUR, new DateOnly(2024, 3, 1), 0.92m, "ECB"),
    new ExchangeRate(CurrencyCode.USD, CurrencyCode.EUR, new DateOnly(2024, 3, 4), 0.93m, "ECB"),
});

// Resolve the nearest rate within three days of a weekend date.
RateLookupResult result = provider.GetRate(
    "USD", "EUR", new DateOnly(2024, 3, 2), RateLookupOptions.PreviousWithin(3));
decimal rate = result.Rate.Rate;   // 0.92 (resolved from 2024-03-01)

Constructors

FixedDatedRateProvider(RateBook)

Initializes a new instance of the FixedDatedRateProvider class from an immutable RateBook. The book must contain at most one provider per currency pair.

public FixedDatedRateProvider(RateBook book)

Parameters

book RateBook

The immutable book to wrap.

Exceptions

ArgumentNullException

Thrown if book is null.

ArgumentException

Thrown if book contains two providers for the same pair; supply a provider-priority list to disambiguate.

FixedDatedRateProvider(RateBook, IEnumerable<string>)

Initializes a new instance of the FixedDatedRateProvider class from an immutable RateBook and an explicit provider-priority list applied per pair.

public FixedDatedRateProvider(RateBook book, IEnumerable<string> providerPriority)

Parameters

book RateBook

The immutable book to wrap.

providerPriority IEnumerable<string>

The ordered set of providers consulted for every pair. The first provider in this list that has a matching series for the pair wins; providers absent from the list are unreachable through this provider.

Exceptions

ArgumentNullException

Thrown if book or providerPriority is null.

ArgumentException

Thrown if providerPriority is empty or contains a null/whitespace entry.

FixedDatedRateProvider(IEnumerable<ExchangeRate>)

Initializes a new instance of the FixedDatedRateProvider class by materialising the supplied observations into an RateBook first.

public FixedDatedRateProvider(IEnumerable<ExchangeRate> rates)

Parameters

rates IEnumerable<ExchangeRate>

The exchange-rate observations to store, in any order.

Exceptions

ArgumentNullException

Thrown if rates is null.

ArgumentException

Thrown if rates contains rates for the same currency pair from differing providers, or if two rates share the same pair and date.

Fields

IdentityProviderName

The label used as the provider name on synthetic same-currency identity results. Exposed publicly so audit consumers can filter by it without depending on a magic-string literal.

public const string IdentityProviderName = "Identity"

Field Value

string

Properties

Book

Gets the immutable book backing every lookup this provider performs.

public RateBook Book { get; }

Property Value

RateBook

The wrapped RateBook; the same instance for the provider's lifetime.

Remarks

The book is immutable and safe to share or query concurrently. It carries the raw multi-provider series only - the provider-priority policy this provider applies per pair is not part of the book, so rewrapping the book (directly or via ToBuilder()) does not carry the policy across.

HistoryAvailability

Gets the history depth this provider advertises, derived from the wrapped book's contents.

public RateHistoryAvailability HistoryAvailability { get; }

Property Value

RateHistoryAvailability

Since(DateOnly) anchored at the earliest observation date across every series in the book, or Unbounded when the book is empty (an empty book has no floor to declare, and every lookup misses regardless).

Methods

GetRate(string, string, RateLookupOptions?)

Resolves the most recent available exchange rate from fromIsoCode to toIsoCode under options, throwing if no rate is available.

public RateLookupResult GetRate(string fromIsoCode, string toIsoCode, RateLookupOptions? options = null)

Parameters

fromIsoCode string

The source-currency ISO-style code.

toIsoCode string

The destination-currency ISO-style code.

options RateLookupOptions

The lookup rules to apply. null selects the implementation's default most-recent policy.

Returns

RateLookupResult

The resolved RateLookupResult.

Exceptions

ArgumentNullException

Thrown if fromIsoCode or toIsoCode is null.

ArgumentException

Thrown if either ISO code is not a three-character uppercase ASCII code, or if options is invalid.

KeyNotFoundException

Thrown if no rate is available for the request.

GetRate(string, string, DateOnly, RateLookupOptions?)

Resolves the exchange rate from fromIsoCode to toIsoCode on date under options, throwing if no rate is available.

public RateLookupResult GetRate(string fromIsoCode, string toIsoCode, DateOnly date, RateLookupOptions? options = null)

Parameters

fromIsoCode string

The source-currency ISO-style code.

toIsoCode string

The destination-currency ISO-style code.

date DateOnly

The calendar date for which a rate is required.

options RateLookupOptions

The lookup rules to apply, including date-resolution policy and tolerance. null is treated as Exact.

Returns

RateLookupResult

The resolved RateLookupResult.

Exceptions

ArgumentNullException

Thrown if fromIsoCode or toIsoCode is null.

ArgumentException

Thrown if either ISO code is not a three-character uppercase ASCII code, or if options is invalid (for example, Exact with non-zero tolerance).

ArgumentOutOfRangeException

Thrown if options contains a negative tolerance or an undefined enum value.

KeyNotFoundException

Thrown if no rate is available for the request under the supplied options.

GetRateAsync(string, string, RateLookupOptions?, CancellationToken)

Asynchronously resolves the most recent available exchange rate from fromIsoCode to toIsoCode under options, throwing if no rate is available.

public ValueTask<RateLookupResult> GetRateAsync(string fromIsoCode, string toIsoCode, RateLookupOptions? options = null, CancellationToken cancellationToken = default)

Parameters

fromIsoCode string

The source-currency ISO-style code.

toIsoCode string

The destination-currency ISO-style code.

options RateLookupOptions

The lookup rules to apply. null selects the implementation's default most-recent policy.

cancellationToken CancellationToken

A token to observe while awaiting the operation.

Returns

ValueTask<RateLookupResult>

A task that yields the resolved RateLookupResult.

Exceptions

ArgumentNullException

Thrown if fromIsoCode or toIsoCode is null.

ArgumentException

Thrown if either ISO code is not a three-character uppercase ASCII code, or if options is invalid.

KeyNotFoundException

Thrown if no rate is available for the request.

GetRateAsync(string, string, DateOnly, RateLookupOptions?, CancellationToken)

Asynchronously resolves the exchange rate from fromIsoCode to toIsoCode on date under options, throwing if no rate is available.

public ValueTask<RateLookupResult> GetRateAsync(string fromIsoCode, string toIsoCode, DateOnly date, RateLookupOptions? options = null, CancellationToken cancellationToken = default)

Parameters

fromIsoCode string

The source-currency ISO-style code.

toIsoCode string

The destination-currency ISO-style code.

date DateOnly

The calendar date for which a rate is required.

options RateLookupOptions

The lookup rules to apply, including date-resolution policy and tolerance. null is treated as Exact.

cancellationToken CancellationToken

A token to observe while awaiting the operation.

Returns

ValueTask<RateLookupResult>

A task that yields the resolved RateLookupResult.

Exceptions

ArgumentNullException

Thrown if fromIsoCode or toIsoCode is null.

ArgumentException

Thrown if either ISO code is not a three-character uppercase ASCII code, or if options is invalid.

ArgumentOutOfRangeException

Thrown if options contains a negative tolerance or an undefined enum value.

KeyNotFoundException

Thrown if no rate is available for the request under the supplied options.

GetRates(string, string, DateOnly, DateOnly)

Returns every available rate from fromIsoCode to toIsoCode whose observation date falls within the inclusive range startDate to endDate.

public RateRangeResult GetRates(string fromIsoCode, string toIsoCode, DateOnly startDate, DateOnly endDate)

Parameters

fromIsoCode string

The source-currency ISO-style code.

toIsoCode string

The destination-currency ISO-style code.

startDate DateOnly

The inclusive start of the range.

endDate DateOnly

The inclusive end of the range.

Returns

RateRangeResult

An RateRangeResult carrying the rates in the range ordered by date, the requested window, and the observed span; the result is empty when no rates are available.

Remarks

The lookup is range-based and does not apply a date-resolution policy: it returns the observations that exist within the window rather than resolving a single date. An implementation backed by a remote feed may block to fetch on demand, or serve only already-loaded data; use GetRatesAsync(string, string, DateOnly, DateOnly, CancellationToken) to fetch without blocking.

Exceptions

ArgumentNullException

Thrown if fromIsoCode or toIsoCode is null.

ArgumentException

Thrown if either ISO code is not a three-character uppercase ASCII code, or if endDate precedes startDate.

GetRatesAsync(string, string, DateOnly, DateOnly, CancellationToken)

Asynchronously returns every available rate from fromIsoCode to toIsoCode whose observation date falls within the inclusive range startDate to endDate.

public ValueTask<RateRangeResult> GetRatesAsync(string fromIsoCode, string toIsoCode, DateOnly startDate, DateOnly endDate, CancellationToken cancellationToken = default)

Parameters

fromIsoCode string

The source-currency ISO-style code.

toIsoCode string

The destination-currency ISO-style code.

startDate DateOnly

The inclusive start of the range.

endDate DateOnly

The inclusive end of the range.

cancellationToken CancellationToken

A token to observe while awaiting the operation.

Returns

ValueTask<RateRangeResult>

A task that yields an RateRangeResult carrying the rates in the range ordered by date, the requested window, and the observed span; the result is empty when no rates are available.

Remarks

The lookup is range-based and does not apply a date-resolution policy: it returns the observations that exist within the window rather than resolving a single date. Implementations backed by a remote feed may fetch on demand, which is why the method is asynchronous.

Exceptions

ArgumentNullException

Thrown if fromIsoCode or toIsoCode is null.

ArgumentException

Thrown if either ISO code is not a three-character uppercase ASCII code, or if endDate precedes startDate.

TryGetRate(string, string, DateOnly, RateLookupOptions?, out RateLookupResult)

Attempts to resolve the exchange rate from fromIsoCode to toIsoCode on date under options, returning a flag indicating whether a rate was found.

public bool TryGetRate(string fromIsoCode, string toIsoCode, DateOnly date, RateLookupOptions? options, out RateLookupResult result)

Parameters

fromIsoCode string

The source-currency ISO-style code.

toIsoCode string

The destination-currency ISO-style code.

date DateOnly

The calendar date for which a rate is required.

options RateLookupOptions

The lookup rules to apply, including date-resolution policy and tolerance. null is treated as Exact.

result RateLookupResult

When this method returns true, contains the resolved RateLookupResult; otherwise, contains default.

Returns

bool

true if a rate was resolved; otherwise false.

Exceptions

ArgumentNullException

Thrown if fromIsoCode or toIsoCode is null.

ArgumentException

Thrown if either ISO code is not a three-character uppercase ASCII code, or if options is invalid.

ArgumentOutOfRangeException

Thrown if options contains a negative tolerance or an undefined enum value.

Applies to

ProductVersions
.NET8, 10