RateSeriesBuilder Class

Definition

Namespace

Bodu.Financial.ExchangeRates

Assembly

Bodu.Financial.dll

Package

Bodu.Financial 1.0.0

Source

RateSeriesBuilder.cs

Provides a mutable construction and editing surface for an RateSeries, maintaining strictly ascending unique observation dates and strictly positive rates while supporting single-observation edits and bulk import.

public sealed class RateSeriesBuilder

Inheritance

object

RateSeriesBuilder

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

ComparableExtensions.AtLeast<T>(T, T, IComparer<T>)

ComparableExtensions.AtMost<T>(T, T, IComparer<T>)

ComparableExtensions.IsEqualTo<T>(T, T, IComparer<T>)

ComparableExtensions.Max<T>(T, T, IComparer<T>)

ComparableExtensions.Min<T>(T, T, IComparer<T>)

Remarks

The builder is the natural entry point for assembling rate observations imperatively (manual data entry, streaming import, merge with prior history). After mutations complete, call ToSeries() to produce an immutable RateSeries snapshot for use in production lookup. Further mutations on the builder do not affect previously produced snapshots, and vice versa.

Instances are not thread-safe; concurrent mutation requires external synchronisation.

using Bodu.Financial.Currencies;
using Bodu.Financial.ExchangeRates;

var builder = new RateSeriesBuilder(new CurrencyPair(CurrencyCode.AUD, CurrencyCode.USD), "Treasury");

builder.Add(new DateOnly(2024, 3, 14), 0.6604m);
builder.Add(new DateOnly(2024, 3, 15), 0.6580m);
builder.Upsert(new DateOnly(2024, 3, 15), 0.6582m);   // corrects the existing observation

// Freeze the observations; later builder mutations do not affect the snapshot.
RateSeries series = builder.ToSeries();

Constructors

RateSeriesBuilder(CurrencyPair, string)

Initializes a new instance of the RateSeriesBuilder class with no observations.

public RateSeriesBuilder(CurrencyPair pair, string provider)

Parameters

pair CurrencyPair

The currency pair this builder is editing.

provider string

The non-empty identifier of the publishing source.

Exceptions

ArgumentNullException

Thrown if provider is null.

ArgumentException

Thrown if provider is empty or white-space.

RateSeriesBuilder(RateSeries)

Initializes a new instance of the RateSeriesBuilder class seeded from the supplied immutable series.

public RateSeriesBuilder(RateSeries series)

Parameters

series RateSeries

The series to copy observations from.

Exceptions

ArgumentNullException

Thrown if series is null.

Properties

Count

Gets the number of observations currently held.

public int Count { get; }

Property Value

int

A non-negative count.

FetchedAtUtc

Gets or sets the UTC instant at which the load that produced this series downloaded its source data, or null when not tracked.

public DateTimeOffset? FetchedAtUtc { get; set; }

Property Value

DateTimeOffset?

The fetch instant when known; otherwise null.

Remarks

The value is carried verbatim onto the RateSeries produced by ToSeries() and from there onto every ExchangeRate the series materializes. Editing the observation buffer does not change it; assign it explicitly to stamp a fresh load instant.

IsEmpty

Gets a value indicating whether the builder holds no observations.

public bool IsEmpty { get; }

Property Value

bool

true if the builder is empty; otherwise false.

Pair

Gets the currency pair this builder is editing.

public CurrencyPair Pair { get; }

Property Value

CurrencyPair

The series pair.

Provider

Gets the identifier of the source the builder represents.

public string Provider { get; }

Property Value

string

A non-empty provider identifier.

Methods

Add(DateOnly, decimal)

Inserts a new observation; throws if an observation already exists for date.

public void Add(DateOnly date, decimal rate)

Parameters

date DateOnly

The observation date.

rate decimal

The observed rate.

Exceptions

ArgumentOutOfRangeException

Thrown if rate is zero or negative.

ArgumentException

Thrown if an observation already exists for date.

AddRange(IEnumerable<RateObservation>)

Inserts a batch of observations, rejecting duplicate dates inside the batch and dates already present in the builder. On any validation failure the builder remains unchanged.

public void AddRange(IEnumerable<RateObservation> observations)

Parameters

observations IEnumerable<RateObservation>

The observations to insert.

Exceptions

ArgumentNullException

Thrown if observations is null.

ArgumentOutOfRangeException

Thrown if any rate in observations is zero or negative.

ArgumentException

Thrown if the batch contains a duplicate date or a date already present in the builder.

AddRange(IEnumerable<(DateOnly Date, decimal Rate)>)

Tuple-shaped overload of AddRange(IEnumerable<RateObservation>) for import sources that hand the builder raw (date, rate) pairs.

public void AddRange(IEnumerable<(DateOnly Date, decimal Rate)> rates)

Parameters

rates IEnumerable<(DateOnly Date, decimal Rate)>

The observations to insert.

Exceptions

ArgumentNullException

Thrown if rates is null.

ArgumentOutOfRangeException

Thrown if any rate in rates is zero or negative.

ArgumentException

Thrown if the batch contains a duplicate date or a date already present in the builder.

ContainsDate(DateOnly)

Reports whether an observation exists for date.

public bool ContainsDate(DateOnly date)

Parameters

date DateOnly

The observation date to query.

Returns

bool

true if an observation exists; otherwise false.

GetObservations()

Enumerates the observations in strictly ascending date order.

public IEnumerable<RateObservation> GetObservations()

Returns

IEnumerable<RateObservation>

A lazy sequence of RateObservation values.

Remove(DateOnly)

Removes the observation for date if present.

public bool Remove(DateOnly date)

Parameters

date DateOnly

The observation date to remove.

Returns

bool

true if an observation was removed; false if none existed.

Set(DateOnly, decimal)

Updates the rate for an existing observation; throws if no observation exists for date.

public void Set(DateOnly date, decimal rate)

Parameters

date DateOnly

The observation date to update.

rate decimal

The new rate.

Exceptions

ArgumentOutOfRangeException

Thrown if rate is zero or negative.

KeyNotFoundException

Thrown if no observation exists for date.

ToSeries()

Produces an immutable RateSeries snapshot of the current observations.

public RateSeries ToSeries()

Returns

RateSeries

A new RateSeries reflecting the builder's current state.

Exceptions

InvalidOperationException

Thrown if the builder is empty; an immutable series must contain at least one observation.

TryAdd(DateOnly, decimal)

Attempts to insert a new observation; returns false if one already exists for date.

public bool TryAdd(DateOnly date, decimal rate)

Parameters

date DateOnly

The observation date.

rate decimal

The observed rate.

Returns

bool

true if the observation was inserted; false if one already existed.

Exceptions

ArgumentOutOfRangeException

Thrown if rate is zero or negative.

TryGetRate(DateOnly, out decimal)

Attempts to retrieve the rate observed exactly on date.

public bool TryGetRate(DateOnly date, out decimal rate)

Parameters

date DateOnly

The observation date to query.

rate decimal

When this method returns true, the rate observed on date; otherwise default.

Returns

bool

true if an observation exists; otherwise false.

TrySet(DateOnly, decimal)

Attempts to update the rate for an existing observation; returns false if none exists.

public bool TrySet(DateOnly date, decimal rate)

Parameters

date DateOnly

The observation date to update.

rate decimal

The new rate.

Returns

bool

true if the rate was updated; false if no observation existed.

Exceptions

ArgumentOutOfRangeException

Thrown if rate is zero or negative.

Upsert(DateOnly, decimal)

Inserts a new observation or replaces the rate of an existing one for date.

public void Upsert(DateOnly date, decimal rate)

Parameters

date DateOnly

The observation date.

rate decimal

The rate to record.

Exceptions

ArgumentOutOfRangeException

Thrown if rate is zero or negative.

UpsertRange(IEnumerable<RateObservation>)

Merges a batch of observations into the builder: inserts new dates and replaces rates for dates already present. Rejects duplicate dates within the batch. On any validation failure the builder remains unchanged.

public void UpsertRange(IEnumerable<RateObservation> observations)

Parameters

observations IEnumerable<RateObservation>

The observations to merge.

Exceptions

ArgumentNullException

Thrown if observations is null.

ArgumentOutOfRangeException

Thrown if any rate in observations is zero or negative.

ArgumentException

Thrown if the batch contains a duplicate date.

UpsertRange(IEnumerable<(DateOnly Date, decimal Rate)>)

Tuple-shaped overload of UpsertRange(IEnumerable<RateObservation>) for import sources that hand the builder raw (date, rate) pairs.

public void UpsertRange(IEnumerable<(DateOnly Date, decimal Rate)> rates)

Parameters

rates IEnumerable<(DateOnly Date, decimal Rate)>

The observations to merge.

Exceptions

ArgumentNullException

Thrown if rates is null.

ArgumentOutOfRangeException

Thrown if any rate in rates is zero or negative.

ArgumentException

Thrown if the batch contains a duplicate date.

Applies to

Product	Versions
.NET	8, 10