This map helps you choose a starting module. It describes the current source; follow your release’s API link for the exact functions available in your package.
Exact time and availability§
For booking availability, start with ExactInterval.parse, project each booking
with ExactInterval.span, and build Coverage. Use Coverage.complement_within
with an explicit opening span to find free windows. Keep an EventCollection
when you also need booking identities: coverage merges occupied time and cannot
recover which booking contributed it.
For a single timestamp, OffsetTimestamp.parse checks its text and to_text
writes the canonical form. A PosixBoundary identifies its position on the
timeline; PosixDelta represents a displacement between positions.
| Task | Modules |
|---|---|
| Parse explicit-offset timestamps | OffsetTimestamp |
| Carry a timeline position or displacement | PosixBoundary, PosixDelta |
| Work with nonempty spans and interval text | PosixSpan, ExactInterval |
| Combine occupied time and find gaps | Coverage |
| Keep event identities | EventCollection |
Calendar meaning and interpretation§
Calendar.Date holds a validated date; Calendar.Delta says how far to shift it
in calendar units; Calendar.Value can describe a whole year or month. These
are separate types: “June 2026” and “one month later” do different jobs.
Import Calendar to access them and Calendar.Arithmetic for date calculations.
For invoice dates, start with GregorianDate and use Calendar.Arithmetic when
advancing a month. Choose the invalid-date policy explicitly: January 31 with
clamping and January 31 with rejection answer different business questions.
Use Calendar.Value when supplied precision, such as a whole month, is part of
the meaning rather than an exact date.
A LocalDateTime describes what a clock shows. FixedOffset places it on a
timeline when you know the offset. ZoneRules handles named-zone appointments,
including skipped and repeated times. Selecting all positions in a local day is
a separate question: a skipped day can be empty, and repeated labels can produce
separate pieces of coverage.
| Task | Modules |
|---|---|
| Construct and convert civil dates | GregorianDate, JulianDate, Calendar.Date |
| Preserve supplied precision | Calendar.Value, QualifiedCalendarValue |
| Advance with an explicit calendar policy | Calendar.Arithmetic, Calendar.Delta |
| Express clock labels and resolve them | ClockTime, LocalDateTime, FixedOffset, ZoneRules |
| Display a Gregorian date or local label in English | EnglishGregorian |
Recurrence, import and storage§
For reusable timed appointments, ScheduleDefinition.from_ical imports a
supported iCalendar definition and from_native accepts a native one. Create a
cursor for the start-date window you want, then call TimedSchedule.collect
with work and output limits. A Limited batch includes the cursor needed to
continue; keep it with the partial output. Schedules
explains what the query selects.
Start with DateRecurrence for date-only rules. The lower-level patterns and
TimedRecurrence are useful when composing selectors or working with starts
without appointment endings; ordinary scheduling need not begin there.
If you’re composing execution inputs directly, TimedSchedule.Endings validates
ending definitions for reuse. The adapters' prepare operations and
TimedSchedule.from_prepared expose that advanced path. To retain a declaration
for later queries, keep its ScheduleDefinition; prepared execution inputs
aren’t a storage format.
| Task | Modules |
|---|---|
| Generate calendar dates | DateRecurrence, CalendarPattern |
| Query reusable timed appointments | ScheduleDefinition, TimedSchedule |
| Compose timed recurrence starts | TimedRecurrence |
| Import extracted iCalendar values | ICalDateRule, ICalTimedRule |
| Preserve imported descriptions | EdtfDate, Ixdtf |
| Explain a supported value | Explanation |
Version 0.3.0 adds CalendarInterval and EdtfInterval
for independently described interval endpoints, including unknown and open
ends. They retain those meanings for storage without claiming resolved
coverage. The archive interval guide
shows the distinction and links the new example.
Choose a release and its API documentation
Developing against main?§
The module source and documentation on main describe the development API. Generate matching local API documentation with a current Roc nightly:
roc docs package/main.roc --output=.roc-time-tmp/api-main
Use documentation matching the package in your application header. Source documentation may describe APIs not yet included in your chosen release.