RecurrenceSet Class

Definition

Namespace

Bodu.Globalization.Recurrence

Assembly

Bodu.Globalization.Recurrence.dll

Package

Bodu.Globalization.Recurrence 1.0.0

Source

RecurrenceSet.Formatting.cs

Represents a composed set of recurring instants: one or more RecurrenceRule streams anchored at a common start, merged with explicit recurrence dates (RDATE) and with exception dates (EXDATE) removed.

public sealed class RecurrenceSet : IEquatable<RecurrenceSet>, IFormattable, IParsable<RecurrenceSet>

Inheritance

object

RecurrenceSet

Implements

IEquatable<RecurrenceSet>

IFormattable

IParsable<RecurrenceSet>

Inherited Members

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

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 occurrence set is the ascending, duplicate-free union of every rule expansion and every explicit date, less any instant that matches an exception date. Each rule is anchored at Start, so the start instant is emitted when a rule (or an explicit date) produces it - it is not added implicitly.

The set can be built programmatically through the constructor, or parsed from an iCalendar property block with Parse(string).

Constructors

RecurrenceSet(DateTime, IEnumerable<RecurrenceRule>, IEnumerable<DateTime>?, IEnumerable<DateTime>?)

Initializes a new instance of the RecurrenceSet class.

public RecurrenceSet(DateTime start, IEnumerable<RecurrenceRule> rules, IEnumerable<DateTime>? dates = null, IEnumerable<DateTime>? exceptionDates = null)

Parameters

start DateTime

The common start instant the rules are anchored to.

rules IEnumerable<RecurrenceRule>

The recurrence rules; may be empty when explicit dates are supplied.

dates IEnumerable<DateTime>

The explicit recurrence dates to add, or null for none.

exceptionDates IEnumerable<DateTime>

The exception dates to remove, or null for none.

Exceptions

ArgumentNullException

Thrown when rules is null.

ArgumentException

Thrown when neither a rule nor an explicit date is supplied.

Properties

Dates

Gets the explicit recurrence dates added to the occurrence set.

public IReadOnlyList<DateTime> Dates { get; }

Property Value

IReadOnlyList<DateTime>

The explicit dates in ascending order.

ExceptionDates

Gets the exception dates removed from the occurrence set.

public IReadOnlyList<DateTime> ExceptionDates { get; }

Property Value

IReadOnlyList<DateTime>

The exception dates in ascending order.

Rules

Gets the recurrence rules that contribute to the occurrence set.

public IReadOnlyList<RecurrenceRule> Rules { get; }

Property Value

IReadOnlyList<RecurrenceRule>

The rules, in the order supplied.

Start

Gets the common start instant the rules are anchored to.

public DateTime Start { get; }

Property Value

DateTime

The start (DTSTART) instant.

Methods

Equals(RecurrenceSet?)

Determines whether this set is equal to another set by comparing the start, rules, dates, and exception dates.

public bool Equals(RecurrenceSet? other)

Parameters

other RecurrenceSet

The set to compare with this instance.

Returns

bool

true when other is non-null with an equal start, equal rules in the same order, and equal date and exception-date lists; otherwise false.

Equals(object?)

Determines whether this set is equal to another object.

public override bool Equals(object? obj)

Parameters

obj object

The object to compare with this instance.

Returns

bool

true when obj is a RecurrenceSet equal to this instance; otherwise false.

GetHashCode()

Returns a hash code derived from the set's start and component counts.

public override int GetHashCode()

Returns

int

A hash code consistent with Equals(RecurrenceSet?).

GetNextOccurrence(DateTime, bool)

Returns the first occurrence of the set that falls after the specified instant.

public DateTime? GetNextOccurrence(DateTime after, bool inclusive = false)

Parameters

after DateTime

The instant the returned occurrence must follow.

inclusive bool

true to allow an occurrence exactly equal to after; otherwise the occurrence must be strictly later.

Returns

DateTime?

The next occurrence, or null when the set produces none.

Exceptions

NotSupportedException

Thrown when a contributing rule uses a sub-daily frequency.

GetNextOccurrence(DateTimeOffset, bool)

Returns the first occurrence of the set that falls after the specified instant, preserving its offset.

public DateTimeOffset? GetNextOccurrence(DateTimeOffset after, bool inclusive = false)

Parameters

after DateTimeOffset

The instant the returned occurrence must follow.

inclusive bool

true to allow an occurrence exactly equal to after; otherwise the occurrence must be strictly later.

Returns

DateTimeOffset?

The next occurrence carrying the offset of after, or null when the set produces none.

Remarks

The set's start and dates are wall-clock values; the query interprets them in the offset of after and performs no other offset conversion.

Exceptions

NotSupportedException

Thrown when a contributing rule uses a sub-daily frequency.

GetOccurrences()

Enumerates the occurrences of the set in ascending chronological order.

public IEnumerable<DateTime> GetOccurrences()

Returns

IEnumerable<DateTime>

The ascending, duplicate-free occurrences with exception dates removed. The sequence is unbounded when any contributing rule is unbounded; use GetOccurrences(DateTime, DateTime) or Take<TSource>(IEnumerable<TSource>, int) to bound it.

Exceptions

NotSupportedException

Thrown when a contributing rule uses a sub-daily frequency.

GetOccurrences(DateTime, DateTime)

Enumerates the occurrences of the set that fall within an inclusive window.

public IEnumerable<DateTime> GetOccurrences(DateTime from, DateTime to)

Parameters

from DateTime

The inclusive lower bound of the window.

to DateTime

The inclusive upper bound of the window.

Returns

IEnumerable<DateTime>

The occurrences within [from, to] in ascending chronological order.

Exceptions

NotSupportedException

Thrown when a contributing rule uses a sub-daily frequency.

GetPreviousOccurrence(DateTime, bool)

Returns the last occurrence of the set that falls before the specified instant.

public DateTime? GetPreviousOccurrence(DateTime before, bool inclusive = false)

Parameters

before DateTime

The instant the returned occurrence must precede.

inclusive bool

true to allow an occurrence exactly equal to before; otherwise the occurrence must be strictly earlier.

Returns

DateTime?

The previous occurrence, or null when none precedes before.

Remarks

Due-ness evaluation is a previous-occurrence comparison - typically lastCompleted < GetPreviousOccurrence(now, inclusive: true) - so missed occurrences coalesce structurally: the answer is a single instant, never a backlog.

Exceptions

NotSupportedException

Thrown when a contributing rule uses a sub-daily frequency.

GetPreviousOccurrence(DateTimeOffset, bool)

Returns the last occurrence of the set that falls before the specified instant, preserving its offset.

public DateTimeOffset? GetPreviousOccurrence(DateTimeOffset before, bool inclusive = false)

Parameters

before DateTimeOffset

The instant the returned occurrence must precede.

inclusive bool

true to allow an occurrence exactly equal to before; otherwise the occurrence must be strictly earlier.

Returns

DateTimeOffset?

The previous occurrence carrying the offset of before, or null when none precedes it.

Remarks

The set's start and dates are wall-clock values; the query interprets them in the offset of before and performs no other offset conversion.

Exceptions

NotSupportedException

Thrown when a contributing rule uses a sub-daily frequency.

Parse(string)

Parses an iCalendar property block containing a DTSTART line, one or more RRULE lines, and optional RDATE / EXDATE lines.

public static RecurrenceSet Parse(string s)

Parameters

s string

The property-block text. Lines other than the recognized recurrence properties are ignored.

Returns

RecurrenceSet

The parsed set.

Exceptions

ArgumentNullException

Thrown when s is null.

FormatException

Thrown when the text is not a valid recurrence-set property block.

ToString()

Returns the canonical iCalendar property-block text of the set: a DTSTART line, one RRULE line per rule, and RDATE / EXDATE lines when explicit or exception dates are present.

public override string ToString()

Returns

string

The canonical property-block text, which round-trips through Parse(string).

Remarks

Lines are separated by CRLF per RFC 5545, with no trailing line break. Explicit and exception dates each render as a single comma-separated line in ascending order.

ToString(string?)

Returns the canonical iCalendar property-block text of the set.

public string ToString(string? format)

Parameters

format string

The format specifier. Only the general specifier ("G" or null) is supported.

Returns

string

The canonical property-block text.

Exceptions

FormatException

Thrown when format is not a supported specifier.

ToString(string?, IFormatProvider?)

Returns the canonical iCalendar property-block text of the set.

public string ToString(string? format, IFormatProvider? formatProvider)

Parameters

format string

The format specifier. Only the general specifier ("G" or null) is supported.

formatProvider IFormatProvider

Unused; property-block text is culture-invariant.

Returns

string

The canonical property-block text.

Exceptions

FormatException

Thrown when format is not a supported specifier.

TryParse(string?, out RecurrenceSet)

Attempts to parse an iCalendar property block.

public static bool TryParse(string? s, out RecurrenceSet result)

Parameters

s string

The property-block text.

result RecurrenceSet

The parsed set, or null on failure.

Returns

bool

true if parsing succeeded; otherwise false.

TryParse(string?, out RecurrenceSet, out string?)

Attempts to parse an iCalendar property block, reporting the parse defect on failure.

public static bool TryParse(string? s, out RecurrenceSet result, out string? failureMessage)

Parameters

s string

The property-block text.

result RecurrenceSet

The parsed set, or null on failure.

failureMessage string

null on success; otherwise a message naming the specific defect, suitable for surfacing to the user verbatim.

Returns

bool

true if parsing succeeded; otherwise false.

Explicit Interface Implementations

Parse(string, IFormatProvider?)

Parses an iCalendar property block.

static RecurrenceSet Parse(string s, IFormatProvider? provider)

Parameters

s string

The property-block text. Lines other than the recognized recurrence properties are ignored.

provider IFormatProvider

Unused; property-block text is culture-invariant.

Returns

RecurrenceSet

The parsed set.

Exceptions

ArgumentNullException

Thrown when s is null.

FormatException

Thrown when the text is not a valid recurrence-set property block.

TryParse(string?, IFormatProvider?, out RecurrenceSet)

Attempts to parse an iCalendar property block.

static bool TryParse(string? s, IFormatProvider? provider, out RecurrenceSet result)

Parameters

s string

The property-block text.

provider IFormatProvider

Unused; property-block text is culture-invariant.

result RecurrenceSet

The parsed set, or null on failure.

Returns

bool

true if parsing succeeded; otherwise false.

Applies to

Product	Versions
.NET	8, 10

See Also

RecurrenceRule