roc-time

Dates, booking availability and schedules with explicit calendar and time-zone choices.

Usable from source today; not yet a published, stable package. APIs may change. Use the compiler pinned in the repository's .roc-version.

Tier 1: Use today

• Booking availability: ExactInterval reads exact booking windows; Coverage subtracts occupied time and finds free windows.
• Date calculations: GregorianDate and CalendarDate support Gregorian/Julian dates; CalendarArithmetic makes month-end policy explicit.
• Clock changes: ZoneRules interprets repeated/skipped local times using explicit rules and policies.
• Schedules: DateRecurrence and TimedSchedule provide bounded, resumable date and appointment queries.
• Archive meaning: EdtfDate preserves date precision and whole-value qualification; Explanation and Persistence explain and save supported values.

Tier 2: Use within supported profiles

• Timestamp text supports complete offset timestamps with up to six fractional digits; leap seconds are outside this POSIX profile.
• EDTF text supports year, year-month and date with whole-value qualifiers. Interval endpoints, masks and sets remain planned.
• IXDTF retains annotations and checks offset assertions against supplied rules. Calendar presentation currently supports Gregorian only.
• Date and timed RFC recurrence adapters accept extracted property values, not complete ICS files. Recurrence export/persistence remains planned.
• The optional IANA zone-data package is a separate source dependency with a declared version and date horizon.

Tier 3: Next priorities

First make adoption straightforward, then fill archive input/output gaps and schedule interchange gaps. Additional calendars follow concrete caller needs; advanced reasoning and styled explanations follow those workflows. See the user-facing roadmap.

Start with a complete task

The booking exchange example reads bookings, computes availability and writes canonical timestamps. The archive search example preserves date precision and uncertainty. The README setup instructions explain the compiler and local dependency; the example catalog lists more applications.

API code blocks import modules through a package dependency named time. Fallible constructors and parsers return Try for invalid input; ? forwards an error from a function returning Try.

Dates, coordinates and limits

A civil date is not an instant. A local clock label needs an explicit offset or zone before it becomes a resolved boundary. Core calculations do not read the clock, use the machine's zone or download a database.

Spans include their start and exclude their end. Calendar days and months differ from coordinate durations across clock changes. A Limited batch is incomplete: resume its cursor to preserve COUNT, exclusions and pending interpretation.