CalendarPattern

CalendarPattern :: # (opaque)

Validated Gregorian date selectors within anchored calendar periods. This is the candidate layer: it does not apply DTSTART truncation, COUNT, UNTIL, BYSETPOS, clock selectors, exclusions or zone interpretation. Week ordinals use the date's week-numbering year, which can differ from its civil year. Negative positions count back from that numbering year's end.

definition : CalendarPattern -> Spec

Read validated selector declarations without evaluating a period.

defaults : Frequency -> Spec

Start a pattern specification for the requested frequency with interval one, Monday week start and no explicit selectors. The anchor supplies applicable missing fields when constructing the pattern.

new : GregorianDate, Spec -> Try(CalendarPattern, [InvalidInterval, TooManySelectors, InvalidSelector(Str), InvalidCombination(Str)])

RFC date-selector domains and combinations; at most 4096 supplied values per selector. Duplicates have set meaning and do not duplicate candidates.

period : CalendarPattern, U64 -> Try({ start : GregorianDate, end : GregorianDate }, [OutOfRange])

A whole frequency period, including days before the anchor in period zero. Exclusive end must fit the Gregorian provider. No clamping or clipping. Fixed work independent of index; intermediate arithmetic uses I128.

matches : CalendarPattern, U64, GregorianDate -> Try(Bool, [OutOfRange])

Test one date against one period. Cost is O(s) supplied selector values, with bounded calendar arithmetic; no series scan or candidate lists. BYSETPOS must operate on completed full candidates, after this layer. Weekly defaults retain the anchor weekday; monthly defaults retain its month-day when neither BYDAY nor BYMONTHDAY expands the period. Yearly defaults retain month/day only in the absence of expanding date selectors (an explicit BYMONTH can select multiple copies of the anchor month-day). Standards adapters supply any additional format-specific defaults first.

to_inspect : CalendarPattern -> Str

Return a bounded diagnostic summary without advancing cursors or enumerating occurrences. Use typed accessors for application logic; this text is not a storage format.

Frequency : [Daily, Weekly, Monthly, Yearly]

Calendar periods used to generate candidates. Monthly and yearly expansion skip invalid dates rather than repeatedly clamping an earlier result.

Weekday : [Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday]

Named weekdays used in week-start and weekday selectors; no locale-dependent numbering is assumed.

Spec : {
    frequency : Frequency,
    interval : I64,
    week_start : Weekday,
    by_month : List(U8),
    by_month_day : List(I8),
    by_year_day : List(I16),
    by_week_no : List(I8),
    by_day : List({ ordinal : I8, weekday : Weekday }),
}

Calendar recurrence selectors, period interval and week start. Use defaults as a starting point, then construct a checked pattern before enumeration.

Filter

CalendarPattern.Filter :: # (opaque)

Date restrictions without a frequency's expansion defaults. Subdaily periods use these same selector predicates after choosing their date.

new : Spec -> Try(Filter, [InvalidInterval, TooManySelectors, InvalidSelector(Str), InvalidCombination(Str)])

Validate and normalize calendar predicates for filtering existing dates. This does not create a recurrence period or inherit missing selectors from an anchor.

definition : Filter -> Spec

Read the checked by_month, by_month_day, by_year_day and by_day predicates. The returned frequency, interval and week_start fields do not describe this independent date filter; they must not be used to expand it.

matches : Filter, GregorianDate -> Try(Bool, [OutOfRange])

Test a Gregorian date against the checked predicates. Provider-range failures remain errors rather than being treated as a non-match.

Spec : { by_month : List(U8), by_month_day : List(I8), by_year_day : List(I16), by_day : List(Weekday) }

Calendar predicates for filtering existing dates without recurrence expansion defaults.