Table of Contents

RecurrenceRuleBuilder Class

Definition

Namespace
Bodu.Globalization.Recurrence
Assembly
Bodu.Globalization.Recurrence.dll
Package
Bodu.Globalization.Recurrence 1.3.0
Source
RecurrenceRuleBuilder.cs

Builds a RecurrenceRule fluently, as an alternative to parsing its textual form.

public sealed class RecurrenceRuleBuilder
Inheritance
RecurrenceRuleBuilder
Inherited Members
Extension Methods

Remarks

The builder is mutable and single-threaded; each By… or With… method returns the same instance so calls chain. Call Build() to produce the immutable rule. A builder can be reused after Build() and each By… setter replaces any previously supplied values for that rule part.

WithCount(int) and WithUntil(DateTime) are mutually exclusive; supplying one clears the other, matching the RFC 5545 rule that COUNT and UNTIL cannot both appear.

The exceptions a By… setter throws for the values it is given name the rule part rather than the method's parameter: their ParamName is the matching RecurrenceRule property, such as BySecond. The one exception is a null array passed to a ByDay overload, which is reported as days.

Constructors

RecurrenceRuleBuilder(RecurrenceFrequency)

Initializes a new instance of the RecurrenceRuleBuilder class for the specified frequency.

public RecurrenceRuleBuilder(RecurrenceFrequency frequency)

Parameters

frequency RecurrenceFrequency

The base recurrence period of the rule being built.

Methods

Build()

Builds the immutable RecurrenceRule from the configured components.

public RecurrenceRule Build()

Returns

RecurrenceRule

The constructed rule.

ByDay(DayOfWeekSet)

Sets the BYDAY rule part from a set of days of the week, each with no positional ordinal.

public RecurrenceRuleBuilder ByDay(DayOfWeekSet days)

Parameters

days DayOfWeekSet

The days of the week to select on every occurrence of the day within the period.

Returns

RecurrenceRuleBuilder

The same builder instance so calls can be chained.

Remarks

The days are written Monday first, the order RFC 5545's default week start gives them, so Weekdays builds BYDAY=MO,TU,WE,TH,FR.

Exceptions

ArgumentException

Thrown when days is empty.

ByDay(params WeekDayNum[])

Sets the BYDAY rule part from weekday entries.

public RecurrenceRuleBuilder ByDay(params WeekDayNum[] days)

Parameters

days WeekDayNum[]

The weekday entries to select.

Returns

RecurrenceRuleBuilder

The same builder instance so calls can be chained.

Exceptions

ArgumentNullException

Thrown when days is null.

ArgumentOutOfRangeException

Thrown when an entry's day is not a defined DayOfWeek value, or its ordinal is neither zero nor within ±1 to ±53.

ByDay(params DayOfWeek[])

Sets the BYDAY rule part from plain weekdays, each with no positional ordinal.

public RecurrenceRuleBuilder ByDay(params DayOfWeek[] days)

Parameters

days DayOfWeek[]

The weekdays to select on every occurrence of that day within the period.

Returns

RecurrenceRuleBuilder

The same builder instance so calls can be chained.

Exceptions

ArgumentNullException

Thrown when days is null.

ArgumentOutOfRangeException

Thrown when a day is not a defined DayOfWeek value.

ByHour(HourSet)

Sets the BYHOUR rule part from a set of hours, written in ascending order.

public RecurrenceRuleBuilder ByHour(HourSet hours)

Parameters

hours HourSet

The hours to select.

Returns

RecurrenceRuleBuilder

The same builder instance so calls can be chained.

Exceptions

ArgumentException

Thrown when hours is empty.

ByHour(params int[])

Sets the BYHOUR rule part.

public RecurrenceRuleBuilder ByHour(params int[] hours)

Parameters

hours int[]

The hours to select (0-23).

Returns

RecurrenceRuleBuilder

The same builder instance so calls can be chained.

Exceptions

ArgumentNullException

Thrown when hours is null.

ArgumentOutOfRangeException

Thrown when a value is outside the range 0 to 23.

ByMinute(MinuteSet)

Sets the BYMINUTE rule part from a set of minutes, written in ascending order.

public RecurrenceRuleBuilder ByMinute(MinuteSet minutes)

Parameters

minutes MinuteSet

The minutes to select.

Returns

RecurrenceRuleBuilder

The same builder instance so calls can be chained.

Exceptions

ArgumentException

Thrown when minutes is empty.

ByMinute(params int[])

Sets the BYMINUTE rule part.

public RecurrenceRuleBuilder ByMinute(params int[] minutes)

Parameters

minutes int[]

The minutes to select (0-59).

Returns

RecurrenceRuleBuilder

The same builder instance so calls can be chained.

Exceptions

ArgumentNullException

Thrown when minutes is null.

ArgumentOutOfRangeException

Thrown when a value is outside the range 0 to 59.

ByMonth(MonthSet)

Sets the BYMONTH rule part from a set of months, written in ascending order.

public RecurrenceRuleBuilder ByMonth(MonthSet months)

Parameters

months MonthSet

The months to select.

Returns

RecurrenceRuleBuilder

The same builder instance so calls can be chained.

Exceptions

ArgumentException

Thrown when months is empty.

ByMonth(params int[])

Sets the BYMONTH rule part.

public RecurrenceRuleBuilder ByMonth(params int[] months)

Parameters

months int[]

The months to select (1-12).

Returns

RecurrenceRuleBuilder

The same builder instance so calls can be chained.

Exceptions

ArgumentNullException

Thrown when months is null.

ArgumentOutOfRangeException

Thrown when a value is outside the range 1 to 12.

ByMonthDay(DayOfMonthSet)

Sets the BYMONTHDAY rule part from a set of days of the month, written in ascending order.

public RecurrenceRuleBuilder ByMonthDay(DayOfMonthSet monthDays)

Parameters

monthDays DayOfMonthSet

The days of the month to select, counted from the first.

Returns

RecurrenceRuleBuilder

The same builder instance so calls can be chained.

Remarks

A DayOfMonthSet holds the days 1 to 31, so days counted from the end of the month, such as -1 for the last day, are set through ByMonthDay(params int[]).

Exceptions

ArgumentException

Thrown when monthDays is empty.

ByMonthDay(params int[])

Sets the BYMONTHDAY rule part.

public RecurrenceRuleBuilder ByMonthDay(params int[] monthDays)

Parameters

monthDays int[]

The month days to select (1-31 or -31 to -1).

Returns

RecurrenceRuleBuilder

The same builder instance so calls can be chained.

Exceptions

ArgumentNullException

Thrown when monthDays is null.

ArgumentOutOfRangeException

Thrown when a value is zero or outside ±31.

BySecond(SecondSet)

Sets the BYSECOND rule part from a set of seconds, written in ascending order.

public RecurrenceRuleBuilder BySecond(SecondSet seconds)

Parameters

seconds SecondSet

The seconds to select.

Returns

RecurrenceRuleBuilder

The same builder instance so calls can be chained.

Remarks

A SecondSet holds the seconds 0 to 59, so the leap second 60, which BYSECOND also allows, is set through BySecond(params int[]).

Exceptions

ArgumentException

Thrown when seconds is empty.

BySecond(params int[])

Sets the BYSECOND rule part.

public RecurrenceRuleBuilder BySecond(params int[] seconds)

Parameters

seconds int[]

The seconds to select (0-60).

Returns

RecurrenceRuleBuilder

The same builder instance so calls can be chained.

Exceptions

ArgumentNullException

Thrown when seconds is null.

ArgumentOutOfRangeException

Thrown when a value is outside the range 0 to 60.

BySetPos(params int[])

Sets the BYSETPOS rule part.

public RecurrenceRuleBuilder BySetPos(params int[] setPositions)

Parameters

setPositions int[]

The set positions to select (1-366 or -366 to -1).

Returns

RecurrenceRuleBuilder

The same builder instance so calls can be chained.

Exceptions

ArgumentNullException

Thrown when setPositions is null.

ArgumentOutOfRangeException

Thrown when a value is zero or outside ±366.

ByWeekNo(params int[])

Sets the BYWEEKNO rule part.

public RecurrenceRuleBuilder ByWeekNo(params int[] weekNumbers)

Parameters

weekNumbers int[]

The week numbers to select (1-53 or -53 to -1).

Returns

RecurrenceRuleBuilder

The same builder instance so calls can be chained.

Exceptions

ArgumentNullException

Thrown when weekNumbers is null.

ArgumentOutOfRangeException

Thrown when a value is zero or outside ±53.

ByYearDay(params int[])

Sets the BYYEARDAY rule part.

public RecurrenceRuleBuilder ByYearDay(params int[] yearDays)

Parameters

yearDays int[]

The year days to select (1-366 or -366 to -1).

Returns

RecurrenceRuleBuilder

The same builder instance so calls can be chained.

Exceptions

ArgumentNullException

Thrown when yearDays is null.

ArgumentOutOfRangeException

Thrown when a value is zero or outside ±366.

WithCount(int)

Sets the occurrence count and clears any previously set UNTIL bound.

public RecurrenceRuleBuilder WithCount(int count)

Parameters

count int

The maximum number of occurrences.

Returns

RecurrenceRuleBuilder

The same builder instance so calls can be chained.

Exceptions

ArgumentOutOfRangeException

Thrown when count is less than one.

WithInterval(int)

Sets the interval - the positive multiple of the frequency between occurrences.

public RecurrenceRuleBuilder WithInterval(int interval)

Parameters

interval int

The recurrence interval.

Returns

RecurrenceRuleBuilder

The same builder instance so calls can be chained.

Exceptions

ArgumentOutOfRangeException

Thrown when interval is less than one.

WithUntil(DateTime)

Sets the inclusive upper-bound instant and clears any previously set COUNT bound.

public RecurrenceRuleBuilder WithUntil(DateTime until)

Parameters

until DateTime

The instant beyond which no occurrence is produced.

Returns

RecurrenceRuleBuilder

The same builder instance so calls can be chained.

WithWeekStart(DayOfWeek)

Sets the day the week starts on, governing weekly-interval and week-number arithmetic.

public RecurrenceRuleBuilder WithWeekStart(DayOfWeek weekStart)

Parameters

weekStart DayOfWeek

The week-start day.

Returns

RecurrenceRuleBuilder

The same builder instance so calls can be chained.

Exceptions

ArgumentOutOfRangeException

Thrown when weekStart is not a defined DayOfWeek value.

Applies to

ProductVersions
.NET8, 10