ICalDateRule

ICalDateRule :: # (opaque)

RFC 5545 DATE recurrence value adapter, profile date-values-v1. Input fields are already extracted property values, not content lines or an ICS document. DTSTART/RDATE/EXDATE/UNTIL use YYYYMMDD, years 0001–9999. DAILY/WEEKLY/MONTHLY/YEARLY, date selectors, WKST, COUNT and UNTIL are supported. Return the same DateRecurrence used by native constructors. Timed values, subdaily frequencies, extensions and implicit YEARLY defaults are unsupported: without BYYEARDAY, a YEARLY BYMONTHDAY rule lacking both BYMONTH and BYWEEKNO is rejected; a YEARLY BYWEEKNO rule lacking both BYMONTHDAY and BYDAY is rejected. No source spelling, full iCalendar or full RFC conformance claim is made. Canonical output preserves the supported definition's meaning, not original spelling.

Example

Parse extracted property values, then use the ordinary recurrence cursor. These inputs are values, not complete DTSTART: lines or an ICS document. Timed values and unsupported extensions return explicit errors.

import time.ICalDateRule
import time.GregorianDate
import time.DateRecurrence

expect {
    rule = ICalDateRule.parse({
        start: "20250131",
        rule: "FREQ=MONTHLY;COUNT=3",
        inclusions: [],
        exclusions: ["20250331"],
    })?
    start = GregorianDate.from_fields({ year: 2025, month: 1, day: 1 })?
    end = GregorianDate.from_fields({ year: 2025, month: 6, day: 1 })?
    cursor = DateRecurrence.cursor(rule, { start, end })?
    batch = DateRecurrence.Cursor.collect(cursor, {
        max_steps: 1000, max_buffered: 31, max_occurrences: 4,
    })?
    batch.dates.map(|date| GregorianDate.to_fields(date).month) == [1.U8, 5]
}

Examples assume a package dependency named time.

profile : Str

Identifier of the supported text profile described above; it does not imply support for the entire standard.

to_parts : DateRecurrence -> Try(Parts, Error)

Export extracted values without expanding occurrences. Reject native definitions outside this profile. Order: FREQ, INTERVAL, termination, BYMONTH, BYWEEKNO, BYYEARDAY, BYMONTHDAY, BYDAY, BYSETPOS, WKST. INTERVAL and WKST are explicit. Numeric sets sort ascending; BYDAY sorts Monday–Sunday, then ordinal. Exceptions are sorted unique individual YYYYMMDD entries. Total output is limited to 65536 bytes. Cost O(s log s + n + output bytes), for supplied selectors s and explicit dates n, independent of series length. Export rejects COUNT values outside the RFC signed-integer range, even when they are valid in a native recurrence definition.

parse : Parts -> Try(DateRecurrence, Error)

At most 65536 input bytes in total and 4096 supplied inclusion/exclusion strings each. RDATE/EXDATE entries may contain comma-separated dates; each expanded list and selector list is limited to 4096 values. Parse O(input bytes + supplied entries), then bounded DateRecurrence construction. Never expand a series here. Names/enumerations are ASCII case-insensitive; whitespace, folded lines, duplicate keys and numeric overflow are errors.

Parts : { start : Str, rule : Str, inclusions : List(Str), exclusions : List(Str) }

Extracted DTSTART, RRULE, RDATE and EXDATE values. Entries are strings, not property lines; inclusion/exclusion strings may contain comma lists.

Error : [Malformed(Str), Duplicate(Str), Missing(Str), Unsupported(Str), OutOfRange(Str), Incompatible(Str), InvalidDate(Str), TooLarge, InvalidRule([InvalidInterval, TooManySelectors, InvalidSelector(Str), InvalidCombination(Str), InvalidCount, InvalidUntil, UnsynchronizedStart, OutOfRange])]

Identifies the offending property or rule component, unsupported combinations and limits; InvalidRule retains native recurrence validation failures.