IcalRecurrenceRule Struct

Definition

Namespace: DataStandardizer.File.iCal

A RECUR value (RFC 5545 §3.3.10): a recurrence rule, such as FREQ=MONTHLY;BYDAY=-1FR;COUNT=6. The type parses, checks and formats a rule, and GetOccurrences expands it into occurrences in local time. The RecurrenceRules property of IcalEvent, IcalTodo, IcalJournal and IcalTimeZoneObservance holds values of this type.

Syntax

public readonly partial struct IcalRecurrenceRule : IEquatable<IcalRecurrenceRule>, ISpanFormattable

Remarks

Immutable. A rule is built from a frequency with the With methods, each of which returns a new rule. For example:

var rule = new IcalRecurrenceRule(IcalRecurrenceFrequency.Monthly)
    .WithByDay(new IcalRecurrenceDay(DayOfWeek.Friday, -1))
    .WithCount(6);

The With methods check each value, but not the constraints between rule parts, which a rule under construction may break for a while. IsValid checks those, and Parse, TryParse, TryFormat, ToString(IcalValueFormat) and GetOccurrences refuse a rule that breaks them.

Rule parts.

Rule part Read with Set with Values
FREQ Frequency constructor, WithFrequency An IcalRecurrenceFrequency. Required.
UNTIL UntilDate, UntilDateTime WithUntil, WithoutEnd A DATE, or a DATE-TIME that is floating or in UTC.
COUNT Count WithCount, WithoutEnd 1 to int.MaxValue.
INTERVAL Interval WithInterval 1 to int.MaxValue. Defaults to 1.
BYSECOND GetBySecond WithBySecond 0 to 60.
BYMINUTE GetByMinute WithByMinute 0 to 59.
BYHOUR GetByHour WithByHour 0 to 23.
BYDAY GetByDay WithByDay IcalRecurrenceDay values, with an ordinal of -53 to 53.
BYMONTHDAY GetByMonthDay WithByMonthDay 1 to 31 or -31 to -1.
BYYEARDAY GetByYearDay WithByYearDay 1 to 366 or -366 to -1.
BYWEEKNO GetByWeekNo WithByWeekNo ISO 8601 week numbers, 1 to 53 or -53 to -1.
BYMONTH GetByMonth WithByMonth 1 to 12.
BYSETPOS GetBySetPos WithBySetPos 1 to 366 or -366 to -1.
WKST WeekStart WithWeekStart A DayOfWeek. Monday when not given.

UNTIL and COUNT exclude each other: WithUntil removes COUNT, and WithCount removes UNTIL.

Validity. IsValid checks the constraints of RFC 5545 §3.3.10 that apply between rule parts:

  • FREQ is given.
  • UNTIL and COUNT are not both given.
  • A BYDAY value with an ordinal is given only when FREQ is MONTHLY or YEARLY, and not with BYWEEKNO when FREQ is YEARLY.
  • BYMONTHDAY is not given when FREQ is WEEKLY.
  • BYYEARDAY is not given when FREQ is DAILY, WEEKLY or MONTHLY.
  • BYWEEKNO is given only when FREQ is YEARLY.
  • BYSETPOS is given only with another BYxxx rule part.

Constraints that depend on DTSTART, such as the value type of UNTIL, are not checked by IsValid. The default value has no frequency, so it is not valid.

Parsing. Rule part names and values are not case-sensitive. Each rule part may appear once. Parsing is strict: an empty rule part (such as a trailing ;), white space, an unknown rule part (including extensions such as RSCALE from RFC 7529), a COUNT or INTERVAL of 0, or an out-of-range value makes the whole value invalid. A parsed rule must also pass IsValid.

Normal form. The values of each BYxxx rule part are held as a set, so their order and any repeats are not kept. They are written in a fixed order: positive values in increasing order, then negative ones in decreasing order (1,2,-1,-2), and BYDAY values grouped by day from Sunday. The rule parts are written in a fixed order too, starting with FREQ as RFC 5545 requires: FREQ, UNTIL, COUNT, INTERVAL, BYSECOND, BYMINUTE, BYHOUR, BYDAY, BYMONTHDAY, BYYEARDAY, BYWEEKNO, BYMONTH, BYSETPOS, WKST. An INTERVAL of 1 is written if it was given, and left out if it was not.

Forms. A rule has only the Text form of IcalValueFormat. In a jCal document (RFC 7265 §3.6.10) a rule is a JSON object with a member for each rule part, and in an xCal document (RFC 6321 §3.6.10) a recur element with a child element for each rule part. So parsing or formatting in the Json or Xml form throws NotSupportedException. JcalReader, JcalWriter, XcalReader and XcalWriter map the object and the elements to and from the text form.

Parsing from a string. Parse and TryParse take a ReadOnlySpan<char>; there are no string overloads. A string converts to ReadOnlySpan<char> implicitly on .NET Core 2.1 and later and on .NET Standard 2.1. On .NET Framework, call AsSpan() on the string. The type does not implement IParsable<T> or ISpanParsable<T>, because parsing needs an IcalValueFormat.

Formatting. ToString() doesn’t check the rule, so it also shows a rule that is not valid. ToString(IcalValueFormat) and TryFormat throw InvalidOperationException for a rule that is not valid. On the net10.0 build the type implements ISpanFormattable, and an interpolated string such as $"{rule}" formats through ISpanFormattable.TryFormat. So, on that build, interpolating a rule that is not valid throws InvalidOperationException, where rule.ToString() does not.

Allocation. The rule parts are held inline, so TryParse from a span and TryFormat into a span do not allocate (covered by IcalValueAllocationTests). The Get methods return a new array on each call. ToString allocates a buffer, starting at 128 characters and doubling until the rule fits, and the result string.

Expanding occurrences. GetOccurrences applies the rule in local time throughout. Occurrences are wall-clock values with the kind and time zone of start, and resolving them to UTC, including any that fall in a daylight saving gap or overlap, is left to the caller. The components’ own GetOccurrences methods, such as IcalEvent.GetOccurrences, do that, and add RDATE and EXDATE. Specifically:

  • The BYxxx rule parts are applied as the table in RFC 5545 §3.3.10 sets out, followed by BYSETPOS, WKST, COUNT and UNTIL. Where no rule part gives the day or time, it is taken from start.
  • An invalid date is skipped, not clamped, so FREQ=MONTHLY;BYMONTHDAY=30 has no occurrence in February. A second of 60 is never generated.
  • Only the occurrences the rule generates are given. RFC 5545 counts DTSTART as the first occurrence of a recurrence set, but if start does not match the rule it is not given here, and adding it is left to the caller.
  • from is inclusive and to is exclusive. Both are compared with occurrences by their wall-clock fields, whatever their kind.
  • COUNT counts from start, whatever from is.
  • UNTIL is compared by its wall-clock fields when it is floating, or when it and start are both in UTC. A DATE UNTIL includes the whole of that day. When UNTIL is in UTC and start is not, use the overload that takes toUtc, which converts each occurrence to UTC to compare it with UNTIL. For a DATE start, a DATE-TIME UNTIL is compared by its date.
  • The occurrences end at 9999-12-31, the last date.
  • The occurrences are generated as they are enumerated, in increasing order.

The arguments and the rule are checked when GetOccurrences is called, not when the result is enumerated.

MaxRecurrenceIterations. A rule that steps through more consecutive periods than IcalOptions.MaxRecurrenceIterations without an occurrence throws InvalidOperationException while it is enumerated. A period is one step of the rule’s frequency, such as a year for FREQ=YEARLY. So a rule that can never match, such as FREQ=SECONDLY;BYMONTH=2;BYMONTHDAY=30, ends with an exception rather than running for a very long time. The default is 100,000, and the value must be at least 1. The overloads without options use the default.

Constructors

Constructor Notes
IcalRecurrenceRule(IcalRecurrenceFrequency frequency) Creates a rule with a frequency and no other rule parts. Throws ArgumentOutOfRangeException if frequency is not an IcalRecurrenceFrequency member.

Properties

Property Signature Notes
Count int? Count { get; } The number of occurrences (COUNT); or null if the rule does not give one.
Frequency IcalRecurrenceFrequency Frequency { get; } The frequency (FREQ); or 0 for the default value, which has none.
Interval int Interval { get; } The interval (INTERVAL), in units of Frequency. 1 if the rule does not give one.
IsValid bool IsValid { get; } true if the rule meets the constraints listed under Validity.
UntilDate IcalDate? UntilDate { get; } The last date (UNTIL) when it is a DATE; or null if the rule has no UNTIL or it is a DATE-TIME.
UntilDateTime IcalDateTime? UntilDateTime { get; } The last date-time (UNTIL) when it is a DATE-TIME, which is floating or in UTC; or null if the rule has no UNTIL or it is a DATE.
WeekStart DayOfWeek? WeekStart { get; } The day the week starts on (WKST); or null if the rule does not give one, in which case it is Monday.

Methods

Parsing

Method Returns Notes
Parse(ReadOnlySpan<char> value, IcalValueFormat format) IcalRecurrenceRule Static. Parses a rule and checks it against the constraints under Validity. Throws FormatException if value is not a valid rule; NotSupportedException if format is Json or Xml; or ArgumentOutOfRangeException if format is not an IcalValueFormat member.
TryParse(ReadOnlySpan<char> value, IcalValueFormat format, out IcalRecurrenceRule result) bool Static. false if value is not a valid rule. Throws NotSupportedException if format is Json or Xml, or ArgumentOutOfRangeException if format is not an IcalValueFormat member. Does not allocate.

Formatting

Method Returns Notes
ToString() string The Text form. Does not check the rule, so it also shows a rule that is not valid.
ToString(IcalValueFormat format) string The rule in format. Throws InvalidOperationException if the rule is not valid; NotSupportedException if format is Json or Xml; or ArgumentOutOfRangeException if format is not an IcalValueFormat member.
TryFormat(Span<char> destination, out int charsWritten, IcalValueFormat format) bool Writes the rule in format. Returns false, with charsWritten 0, if destination is too short. Throws InvalidOperationException if the rule is not valid; NotSupportedException if format is Json or Xml; or ArgumentOutOfRangeException if format is not an IcalValueFormat member. Does not allocate.

Reading the BYxxx rule parts

Each method returns a new array of the values in the order they are written, or an empty array if the rule does not give the rule part.

Method Returns Notes
GetByDay() IcalRecurrenceDay[] BYDAY, grouped by day from Sunday.
GetByHour() int[] BYHOUR, 0 to 23.
GetByMinute() int[] BYMINUTE, 0 to 59.
GetByMonth() int[] BYMONTH, 1 to 12.
GetByMonthDay() int[] BYMONTHDAY, 1 to 31 or -31 to -1.
GetBySecond() int[] BYSECOND, 0 to 60.
GetBySetPos() int[] BYSETPOS, 1 to 366 or -366 to -1.
GetByWeekNo() int[] BYWEEKNO, 1 to 53 or -53 to -1.
GetByYearDay() int[] BYYEARDAY, 1 to 366 or -366 to -1.

Building a rule

Each method returns a copy of the rule with the change; the rule it is called on is not changed. For the BYxxx methods, the values replace the rule part’s values, and passing null or no values removes the rule part. Repeated values are kept once.

Method Returns Notes
WithByDay(params IcalRecurrenceDay[] values) IcalRecurrenceRule Sets BYDAY.
WithByHour(params int[] values) IcalRecurrenceRule Sets BYHOUR. Throws ArgumentOutOfRangeException if a value is not 0 to 23.
WithByMinute(params int[] values) IcalRecurrenceRule Sets BYMINUTE. Throws ArgumentOutOfRangeException if a value is not 0 to 59.
WithByMonth(params int[] values) IcalRecurrenceRule Sets BYMONTH. Throws ArgumentOutOfRangeException if a value is not 1 to 12.
WithByMonthDay(params int[] values) IcalRecurrenceRule Sets BYMONTHDAY. Throws ArgumentOutOfRangeException if a value is not 1 to 31 or -31 to -1.
WithBySecond(params int[] values) IcalRecurrenceRule Sets BYSECOND. Throws ArgumentOutOfRangeException if a value is not 0 to 60.
WithBySetPos(params int[] values) IcalRecurrenceRule Sets BYSETPOS. Throws ArgumentOutOfRangeException if a value is not 1 to 366 or -366 to -1.
WithByWeekNo(params int[] values) IcalRecurrenceRule Sets BYWEEKNO. Throws ArgumentOutOfRangeException if a value is not 1 to 53 or -53 to -1.
WithByYearDay(params int[] values) IcalRecurrenceRule Sets BYYEARDAY. Throws ArgumentOutOfRangeException if a value is not 1 to 366 or -366 to -1.
WithCount(int count) IcalRecurrenceRule Sets COUNT and removes UNTIL. Throws ArgumentOutOfRangeException if count is less than 1.
WithFrequency(IcalRecurrenceFrequency frequency) IcalRecurrenceRule Sets FREQ. Throws ArgumentOutOfRangeException if frequency is not an IcalRecurrenceFrequency member.
WithInterval(int interval) IcalRecurrenceRule Sets INTERVAL. An interval of 1 is written, although it is the default. Throws ArgumentOutOfRangeException if interval is less than 1.
WithoutEnd() IcalRecurrenceRule Removes UNTIL and COUNT, so the rule repeats forever.
WithUntil(IcalDate until) IcalRecurrenceRule Sets UNTIL to a DATE and removes COUNT. RFC 5545 requires a DATE UNTIL when DTSTART is a DATE.
WithUntil(IcalDateTime until) IcalRecurrenceRule Sets UNTIL to a DATE-TIME and removes COUNT. It should be floating if DTSTART is floating, and otherwise in UTC. Throws ArgumentException if until is zoned.
WithWeekStart(DayOfWeek? weekStart) IcalRecurrenceRule Sets WKST, or removes it when weekStart is null. Throws ArgumentOutOfRangeException if weekStart is not a DayOfWeek member.

Expanding occurrences

All overloads return the occurrences in increasing order, generated as they are enumerated. See Expanding occurrences under Remarks for how the rule is applied.

Method Returns Notes
GetOccurrences(IcalDateTime start, IcalDateTime? from, IcalDateTime? to) IEnumerable<IcalDateTime> Occurrences from a date-time start (DTSTART), with its kind and time zone. from is the earliest occurrence to give, inclusive, or null to start at start; to is the end, exclusive, or null for none. Uses the default MaxRecurrenceIterations. Throws InvalidOperationException if the rule is not valid; ArgumentException if the rule has neither COUNT nor UNTIL and to is null, or its UNTIL is in UTC and start is not.
GetOccurrences(IcalDateTime start, IcalDateTime? from, IcalDateTime? to, IcalOptions options) IEnumerable<IcalDateTime> As above, with options.MaxRecurrenceIterations. Also throws ArgumentNullException if options is null, or ArgumentException if options.MaxRecurrenceIterations is less than 1.
GetOccurrences(IcalDateTime start, IcalDateTime? from, IcalDateTime? to, Func<IcalDateTime, IcalDateTime> toUtc, IcalOptions options) IEnumerable<IcalDateTime> As above, and handles a UNTIL in UTC when start is not in UTC. toUtc converts an occurrence to UTC, and the wall-clock fields of what it returns are taken as UTC. It is called only in that case. For a VTIMEZONE observance, whose DTSTART is floating, it subtracts the observance’s TZOFFSETFROM; for a zoned start it resolves the time zone. Throws ArgumentNullException if toUtc or options is null; InvalidOperationException if the rule is not valid; or ArgumentException if the rule has neither COUNT nor UNTIL and to is null, or options.MaxRecurrenceIterations is less than 1.
GetOccurrences(IcalDate start, IcalDate? from, IcalDate? to) IEnumerable<IcalDate> Occurrences from an all-day DTSTART. Uses the default MaxRecurrenceIterations. Throws InvalidOperationException if the rule is not valid; ArgumentException if the rule has neither COUNT nor UNTIL and to is null, or it has a frequency below DAILY, or BYHOUR, BYMINUTE or BYSECOND, none of which a date can have.
GetOccurrences(IcalDate start, IcalDate? from, IcalDate? to, IcalOptions options) IEnumerable<IcalDate> As above, with options.MaxRecurrenceIterations. Also throws ArgumentNullException if options is null, or ArgumentException if options.MaxRecurrenceIterations is less than 1.

Enumerating any of these throws InvalidOperationException when more consecutive periods than MaxRecurrenceIterations give no occurrence.

Equality

Method Returns Notes
Equals(IcalRecurrenceRule other) bool true for the same rule parts with the same sets of values. Order and repeats of BYxxx values don’t matter. An INTERVAL of 1 that was given doesn’t equal one left out, and a DATE UNTIL doesn’t equal a DATE-TIME UNTIL.
Equals(object? obj) bool true when obj is an equal IcalRecurrenceRule.
GetHashCode() int Consistent with Equals.

Explicit interface implementations (.NET)

Member Returns Notes
ISpanFormattable.TryFormat(Span<char> destination, out int charsWritten, ReadOnlySpan<char> format, IFormatProvider? provider) bool Calls TryFormat with the form named by format: empty or T for Text, in either case. J and X name the Json and Xml forms, which throw NotSupportedException. provider is ignored. Throws FormatException for any other format string, or InvalidOperationException if the rule is not valid.
IFormattable.ToString(string? format, IFormatProvider? formatProvider) string Calls ToString(IcalValueFormat) with the form named by format, as above.

Operators

Operator Returns Notes
==(IcalRecurrenceRule left, IcalRecurrenceRule right) bool Same as left.Equals(right).
!=(IcalRecurrenceRule left, IcalRecurrenceRule right) bool Same as !left.Equals(right).

Applies to

Targets netstandard1.1, netstandard2.0, netstandard2.1, and net10.0. ISpanFormattable and its explicit members are implemented on the net10.0 build only. The nullable reference annotations apply to the netstandard2.1 and net10.0 builds.

See also


This site uses Just the Docs, a documentation theme for Jekyll.