Table of Contents

NotableDateRuleBuilder Class

Definition

Namespace
Bodu.Globalization.Calendar.Builder
Assembly
Bodu.Globalization.Calendar.Builder.dll
Package
Bodu.Globalization.Calendar.Builder 1.0.0
Source
NotableDateRuleBuilder.cs

Provides a fluent surface for authoring a single rule: its selection scalars, applicability scope, exactly one calculation strategy, rule-specific tags, and the adjustment policies applied to its occurrences.

public sealed class NotableDateRuleBuilder
Inheritance
NotableDateRuleBuilder
Inherited Members
Extension Methods

Examples

// U.S. Thanksgiving: the fourth Thursday of November, scoped to the United States.
definition.AddRule("us", r => r
    .ForTerritory("US")
    .DayOfWeekInMonth(11, DayOfWeek.Thursday, WeekOrdinal.Fourth)
    .AsNonWorking());

Remarks

A rule must declare exactly one calculation strategy - for example Fixed(int, int, bool, bool), DayOfWeekInMonth(int, DayOfWeek, WeekOrdinal), WeekdayNearDate(int, int, DayOfWeek, WeekdayProximity), OffsetFromRule(string, int, string?), or Algorithm(string). Scope the rule to a calendar, territories, or a year window with the For… / …Year(s) members, and attach reusable adjustment policies with WithAdjustment(string). Configure the builder inside AddRule(string, Action<NotableDateRuleBuilder>).

Methods

AddTag(string)

Adds a single tag to the rule.

public NotableDateRuleBuilder AddTag(string tag)

Parameters

tag string

The tag value.

Returns

NotableDateRuleBuilder

The same NotableDateRuleBuilder instance, enabling chained calls.

Exceptions

ArgumentException

tag is null, empty, or white-space.

Algorithm(string)

Configures the rule with an algorithm strategy that resolves its date from a named built-in or custom algorithm.

public NotableDateRuleBuilder Algorithm(string key)

Parameters

key string

The algorithm key, for example "western-easter".

Returns

NotableDateRuleBuilder

The same NotableDateRuleBuilder instance, enabling chained calls.

Exceptions

ArgumentException

key is null, empty, or white-space.

InvalidOperationException

A strategy has already been configured on this rule.

AnchorYear(int)

Sets the anchor year used by interval recurrence.

public NotableDateRuleBuilder AnchorYear(int year)

Parameters

year int

The anchor year.

Returns

NotableDateRuleBuilder

The same NotableDateRuleBuilder instance, enabling chained calls.

AsNonWorking(bool)

Sets whether occurrences of the rule are non-working days.

public NotableDateRuleBuilder AsNonWorking(bool value = true)

Parameters

value bool

The non-working flag.

Returns

NotableDateRuleBuilder

The same NotableDateRuleBuilder instance, enabling chained calls.

DailyInterval(DateOnly, int)

Configures the rule with a daily-interval recurrence.

public NotableDateRuleBuilder DailyInterval(DateOnly anchorDate, int intervalDays = 1)

Parameters

anchorDate DateOnly

The anchor date that defines occurrence zero and the phase of the series.

intervalDays int

The number of calendar days between consecutive occurrences.

Returns

NotableDateRuleBuilder

The same NotableDateRuleBuilder instance, enabling chained calls.

Exceptions

InvalidOperationException

An occurrence source has already been configured on this rule.

DayOfWeekInMonth(int, DayOfWeek, WeekOrdinal)

Configures the rule with a day-of-week-in-month strategy.

public NotableDateRuleBuilder DayOfWeekInMonth(int month, DayOfWeek dayOfWeek, WeekOrdinal weekOrdinal)

Parameters

month int

The one-based month number.

dayOfWeek DayOfWeek

The day of the week to select.

weekOrdinal WeekOrdinal

The ordinal position of the weekday within the month.

Returns

NotableDateRuleBuilder

The same NotableDateRuleBuilder instance, enabling chained calls.

Exceptions

ArgumentOutOfRangeException

month is outside 1 to 12.

InvalidOperationException

A strategy has already been configured on this rule.

DayOfYear(int)

Configures the rule with a day-of-year strategy.

public NotableDateRuleBuilder DayOfYear(int ordinal)

Parameters

ordinal int

The signed ordinal position of the day within the year.

Returns

NotableDateRuleBuilder

The same NotableDateRuleBuilder instance, enabling chained calls.

Exceptions

InvalidOperationException

An occurrence source has already been configured on this rule.

EveryYears(int)

Sets the recurrence interval in years for the rule's applicability.

public NotableDateRuleBuilder EveryYears(int years)

Parameters

years int

The interval between applicable years.

Returns

NotableDateRuleBuilder

The same NotableDateRuleBuilder instance, enabling chained calls.

Exceptions

ArgumentOutOfRangeException

years is less than 1.

ExceptYears(params int[])

Replaces the rule's exception year list with the supplied years.

public NotableDateRuleBuilder ExceptYears(params int[] years)

Parameters

years int[]

The years for which the rule is suppressed.

Returns

NotableDateRuleBuilder

The same NotableDateRuleBuilder instance, enabling chained calls.

Exceptions

ArgumentNullException

years is null.

Fixed(int, int, bool, bool)

Configures the rule with a fixed day-of-month strategy using a numeric month.

public NotableDateRuleBuilder Fixed(int month, int day, bool skipLeapMonth = false, bool sweepCalendarYears = false)

Parameters

month int

The one-based month number.

day int

The day of the month.

skipLeapMonth bool

A value indicating whether a leap month is skipped on lunisolar calendars.

sweepCalendarYears bool

A value indicating whether the date is swept across adjacent calendar years.

Returns

NotableDateRuleBuilder

The same NotableDateRuleBuilder instance, enabling chained calls.

Exceptions

ArgumentOutOfRangeException

month is outside 1 to 12 or day is outside 1 to 31.

InvalidOperationException

A strategy has already been configured on this rule.

Fixed(string, int, bool, bool)

Configures the rule with a fixed day-of-month strategy using a month name or numeric month token.

public NotableDateRuleBuilder Fixed(string month, int day, bool skipLeapMonth = false, bool sweepCalendarYears = false)

Parameters

month string

The full English month name or numeric month token.

day int

The day of the month.

skipLeapMonth bool

A value indicating whether a leap month is skipped on lunisolar calendars.

sweepCalendarYears bool

A value indicating whether the date is swept across adjacent calendar years.

Returns

NotableDateRuleBuilder

The same NotableDateRuleBuilder instance, enabling chained calls.

Exceptions

ArgumentException

month is null, empty, or white-space.

ArgumentOutOfRangeException

day is outside 1 to 31.

InvalidOperationException

A strategy has already been configured on this rule.

ForCalendar(CalendarSystem)

Sets the calendar system of the rule's applicability.

public NotableDateRuleBuilder ForCalendar(CalendarSystem calendar)

Parameters

calendar CalendarSystem

The calendar system.

Returns

NotableDateRuleBuilder

The same NotableDateRuleBuilder instance, enabling chained calls.

ForTerritories(params string[])

Replaces the rule's territory scope with the supplied collection of territory codes.

public NotableDateRuleBuilder ForTerritories(params string[] codes)

Parameters

codes string[]

The ISO territory codes.

Returns

NotableDateRuleBuilder

The same NotableDateRuleBuilder instance, enabling chained calls.

Exceptions

ArgumentNullException

codes is null.

ForTerritory(string)

Adds a single territory code to the rule's applicability.

public NotableDateRuleBuilder ForTerritory(string code)

Parameters

code string

The ISO territory code, for example "US" or "AU-WA".

Returns

NotableDateRuleBuilder

The same NotableDateRuleBuilder instance, enabling chained calls.

Exceptions

ArgumentException

code is null, empty, or white-space.

FromYear(int)

Sets the inclusive lower year bound of the rule's applicability.

public NotableDateRuleBuilder FromYear(int year)

Parameters

year int

The first year for which the rule applies.

Returns

NotableDateRuleBuilder

The same NotableDateRuleBuilder instance, enabling chained calls.

IsoWeekDate(int, DayOfWeek)

Configures the rule with an ISO-week-date strategy.

public NotableDateRuleBuilder IsoWeekDate(int week, DayOfWeek dayOfWeek)

Parameters

week int

The one-based ISO-8601 week number.

dayOfWeek DayOfWeek

The weekday within the ISO week.

Returns

NotableDateRuleBuilder

The same NotableDateRuleBuilder instance, enabling chained calls.

Exceptions

InvalidOperationException

An occurrence source has already been configured on this rule.

MonthlyDay(int, int, DateOnly?, InvalidDayOfMonthBehavior)

Configures the rule with a monthly day-of-month recurrence.

public NotableDateRuleBuilder MonthlyDay(int dayOfMonth, int intervalMonths = 1, DateOnly? anchorDate = null, InvalidDayOfMonthBehavior invalidDayBehavior = InvalidDayOfMonthBehavior.Skip)

Parameters

dayOfMonth int

The one-based day of the month.

intervalMonths int

The number of months between consecutive occurrences.

anchorDate DateOnly?

The anchor whose year and month define month zero, or null.

invalidDayBehavior InvalidDayOfMonthBehavior

How a month without the requested day is handled.

Returns

NotableDateRuleBuilder

The same NotableDateRuleBuilder instance, enabling chained calls.

Exceptions

InvalidOperationException

An occurrence source has already been configured on this rule.

MonthlyWeekday(DayOfWeek, WeekOrdinal, int, DateOnly?)

Configures the rule with a monthly ordinal-weekday recurrence.

public NotableDateRuleBuilder MonthlyWeekday(DayOfWeek dayOfWeek, WeekOrdinal weekOrdinal, int intervalMonths = 1, DateOnly? anchorDate = null)

Parameters

dayOfWeek DayOfWeek

The weekday to select in each participating month.

weekOrdinal WeekOrdinal

The ordinal position of the weekday within the month.

intervalMonths int

The number of months between consecutive occurrences.

anchorDate DateOnly?

The anchor whose year and month define month zero, or null.

Returns

NotableDateRuleBuilder

The same NotableDateRuleBuilder instance, enabling chained calls.

Exceptions

InvalidOperationException

An occurrence source has already been configured on this rule.

NthWeekdayFromRule(string, DayOfWeek, int, int, string?)

Configures the rule with an nth-weekday-from-rule strategy.

public NotableDateRuleBuilder NthWeekdayFromRule(string notableDateRef, DayOfWeek dayOfWeek, int ordinal, int referenceYearOffset = 0, string? ruleRef = null)

Parameters

notableDateRef string

The identifier of the referenced concept.

dayOfWeek DayOfWeek

The weekday to seek.

ordinal int

The signed ordinal count of matching weekdays from the reference.

referenceYearOffset int

The signed year offset applied to the reference.

ruleRef string

The identifier of the referenced rule, or null.

Returns

NotableDateRuleBuilder

The same NotableDateRuleBuilder instance, enabling chained calls.

Exceptions

ArgumentException

notableDateRef is null, empty, or white-space.

InvalidOperationException

An occurrence source has already been configured on this rule.

OffsetFromRule(string, int, string?)

Configures the rule with an offset-from-rule strategy that derives its date from another rule's occurrence.

public NotableDateRuleBuilder OffsetFromRule(string notableDateRef, int offsetDays, string? ruleRef = null)

Parameters

notableDateRef string

The identifier of the concept whose rule supplies the anchor date.

offsetDays int

The signed day offset from the anchor occurrence.

ruleRef string

The identifier of the anchor rule within the referenced concept, or null.

Returns

NotableDateRuleBuilder

The same NotableDateRuleBuilder instance, enabling chained calls.

Exceptions

ArgumentException

notableDateRef is null, empty, or white-space.

InvalidOperationException

A strategy has already been configured on this rule.

OnlyYears(params int[])

Replaces the rule's exclusive year list with the supplied years.

public NotableDateRuleBuilder OnlyYears(params int[] years)

Parameters

years int[]

The years for which the rule applies.

Returns

NotableDateRuleBuilder

The same NotableDateRuleBuilder instance, enabling chained calls.

Exceptions

ArgumentNullException

years is null.

OrdinalDayOfMonth(int, int)

Configures the rule with an ordinal-day-of-month strategy.

public NotableDateRuleBuilder OrdinalDayOfMonth(int month, int ordinal)

Parameters

month int

The one-based month number.

ordinal int

The signed ordinal position of the day within the month.

Returns

NotableDateRuleBuilder

The same NotableDateRuleBuilder instance, enabling chained calls.

Exceptions

InvalidOperationException

An occurrence source has already been configured on this rule.

RelativeWeekdayInMonth(int, DayOfWeek, WeekOrdinal, DayOfWeek, WeekdayProximity)

Configures the rule with a relative-weekday-in-month strategy.

public NotableDateRuleBuilder RelativeWeekdayInMonth(int month, DayOfWeek dayOfWeek, WeekOrdinal weekOrdinal, DayOfWeek relativeDayOfWeek, WeekdayProximity direction)

Parameters

month int

The one-based month number.

dayOfWeek DayOfWeek

The anchor day of the week.

weekOrdinal WeekOrdinal

The ordinal position of the anchor weekday within the month.

relativeDayOfWeek DayOfWeek

The weekday selected relative to the anchor.

direction WeekdayProximity

The proximity rule relative to the anchor weekday.

Returns

NotableDateRuleBuilder

The same NotableDateRuleBuilder instance, enabling chained calls.

Exceptions

ArgumentOutOfRangeException

month is outside 1 to 12.

InvalidOperationException

A strategy has already been configured on this rule.

ToYear(int)

Sets the inclusive upper year bound of the rule's applicability.

public NotableDateRuleBuilder ToYear(int year)

Parameters

year int

The last year for which the rule applies.

Returns

NotableDateRuleBuilder

The same NotableDateRuleBuilder instance, enabling chained calls.

UntilDate(Action<NotableDateRuleBuilder>, DateBoundary, DateBoundary, EndDateSelection)

Configures the rule with a calculated end-date duration whose end anchor is produced by a second strategy.

public NotableDateRuleBuilder UntilDate(Action<NotableDateRuleBuilder> endStrategy, DateBoundary startBoundary = DateBoundary.Inclusive, DateBoundary endBoundary = DateBoundary.Inclusive, EndDateSelection selection = EndDateSelection.FirstOnOrAfterStart)

Parameters

endStrategy Action<NotableDateRuleBuilder>

A configurator that selects the end strategy via one strategy method.

startBoundary DateBoundary

Whether the start anchor is included in the span.

endBoundary DateBoundary

Whether the end anchor is included in the span.

selection EndDateSelection

How the end anchor is selected relative to the start anchor.

Returns

NotableDateRuleBuilder

The same NotableDateRuleBuilder instance, enabling chained calls.

Exceptions

ArgumentNullException

endStrategy is null.

InvalidOperationException

A fixed duration is already configured, a calculated duration is already configured, or the configurator did not select a strategy.

WeekdayNearDate(int, int, DayOfWeek, WeekdayProximity)

Configures the rule with a weekday-near-date strategy.

public NotableDateRuleBuilder WeekdayNearDate(int month, int day, DayOfWeek dayOfWeek, WeekdayProximity direction)

Parameters

month int

The one-based month number.

day int

The reference day of the month.

dayOfWeek DayOfWeek

The day of the week to select.

direction WeekdayProximity

The proximity rule relative to the reference date.

Returns

NotableDateRuleBuilder

The same NotableDateRuleBuilder instance, enabling chained calls.

Exceptions

ArgumentOutOfRangeException

month is outside 1 to 12 or day is outside 1 to 31.

InvalidOperationException

A strategy has already been configured on this rule.

WeekdayNearRule(string, DayOfWeek, WeekdayProximity, int, string?)

Configures the rule with a weekday-near-rule strategy that seeks a weekday relative to another rule's occurrence.

public NotableDateRuleBuilder WeekdayNearRule(string notableDateRef, DayOfWeek dayOfWeek, WeekdayProximity direction, int referenceYearOffset = 0, string? ruleRef = null)

Parameters

notableDateRef string

The identifier of the referenced concept.

dayOfWeek DayOfWeek

The weekday to seek.

direction WeekdayProximity

The proximity rule relative to the reference.

referenceYearOffset int

The signed year offset applied to the reference.

ruleRef string

The identifier of the referenced rule, or null.

Returns

NotableDateRuleBuilder

The same NotableDateRuleBuilder instance, enabling chained calls.

Exceptions

ArgumentException

notableDateRef is null, empty, or white-space.

InvalidOperationException

An occurrence source has already been configured on this rule.

Weekly(IEnumerable<DayOfWeek>, int, DateOnly?)

Configures the rule with a weekly recurrence on the supplied weekdays.

public NotableDateRuleBuilder Weekly(IEnumerable<DayOfWeek> daysOfWeek, int intervalWeeks = 1, DateOnly? anchorDate = null)

Parameters

daysOfWeek IEnumerable<DayOfWeek>

The weekdays to generate occurrences on.

intervalWeeks int

The number of weeks between consecutive occurrences.

anchorDate DateOnly?

The anchor date that phases each weekday series, or null.

Returns

NotableDateRuleBuilder

The same NotableDateRuleBuilder instance, enabling chained calls.

Exceptions

ArgumentNullException

daysOfWeek is null.

InvalidOperationException

An occurrence source has already been configured on this rule.

WithAdjustment(string)

Adds a single adjustment policy reference to the rule.

public NotableDateRuleBuilder WithAdjustment(string policyRef)

Parameters

policyRef string

The identifier of the adjustment policy to apply.

Returns

NotableDateRuleBuilder

The same NotableDateRuleBuilder instance, enabling chained calls.

Exceptions

ArgumentException

policyRef is null, empty, or white-space.

WithAdjustments(params string[])

Replaces the rule's adjustment policy references with the supplied collection.

public NotableDateRuleBuilder WithAdjustments(params string[] policyRefs)

Parameters

policyRefs string[]

The identifiers of the adjustment policies to apply.

Returns

NotableDateRuleBuilder

The same NotableDateRuleBuilder instance, enabling chained calls.

Exceptions

ArgumentNullException

policyRefs is null.

WithCategory(NotableDateCategory)

Sets the category override of the rule.

public NotableDateRuleBuilder WithCategory(NotableDateCategory category)

Parameters

category NotableDateCategory

The category that overrides the concept's category.

Returns

NotableDateRuleBuilder

The same NotableDateRuleBuilder instance, enabling chained calls.

WithComment(string)

Sets the authoring comment of the rule.

public NotableDateRuleBuilder WithComment(string comment)

Parameters

comment string

The comment text.

Returns

NotableDateRuleBuilder

The same NotableDateRuleBuilder instance, enabling chained calls.

Exceptions

ArgumentNullException

comment is null.

WithDurationDays(int)

Sets the duration override of the rule.

public NotableDateRuleBuilder WithDurationDays(int durationDays)

Parameters

durationDays int

The duration in days.

Returns

NotableDateRuleBuilder

The same NotableDateRuleBuilder instance, enabling chained calls.

Exceptions

ArgumentOutOfRangeException

durationDays is less than 1.

WithPriority(int)

Sets the selection priority of the rule.

public NotableDateRuleBuilder WithPriority(int priority)

Parameters

priority int

The numeric selection priority.

Returns

NotableDateRuleBuilder

The same NotableDateRuleBuilder instance, enabling chained calls.

WithTags(params string[])

Replaces the rule's tags with the supplied collection.

public NotableDateRuleBuilder WithTags(params string[] tags)

Parameters

tags string[]

The tag values.

Returns

NotableDateRuleBuilder

The same NotableDateRuleBuilder instance, enabling chained calls.

Exceptions

ArgumentNullException

tags is null.

WorkingDayInMonth(int, int)

Configures the rule with a working-day-in-month strategy.

public NotableDateRuleBuilder WorkingDayInMonth(int month, int ordinal)

Parameters

month int

The one-based month number.

ordinal int

The signed ordinal position of the working day within the month.

Returns

NotableDateRuleBuilder

The same NotableDateRuleBuilder instance, enabling chained calls.

Exceptions

InvalidOperationException

An occurrence source has already been configured on this rule.

WorkingDayOffsetFromRule(string, int, int, string?)

Configures the rule with a working-day-offset-from-rule strategy.

public NotableDateRuleBuilder WorkingDayOffsetFromRule(string notableDateRef, int offsetWorkingDays, int referenceYearOffset = 0, string? ruleRef = null)

Parameters

notableDateRef string

The identifier of the referenced concept.

offsetWorkingDays int

The signed number of working days from the reference.

referenceYearOffset int

The signed year offset applied to the reference.

ruleRef string

The identifier of the referenced rule, or null.

Returns

NotableDateRuleBuilder

The same NotableDateRuleBuilder instance, enabling chained calls.

Exceptions

ArgumentException

notableDateRef is null, empty, or white-space.

InvalidOperationException

An occurrence source has already been configured on this rule.

Applies to

ProductVersions
.NET8, 10

See Also

NotableDateDefinitionBuilder
AdjustmentPolicyBuilder
Authoring notable date rules (guide)
NotableDateRule and adjustment-policy reference (guide)