> Documentation version: 0.4.0. [HTML page](https://lukewilliamboswell.github.io/roc-time/api.html)

<a id="api"></a>

# Find the right API

This map helps you choose a starting module. It describes the current source;
follow your [release’s API link](https://github.com/lukewilliamboswell/roc-time/releases)
for the exact functions available in your package.

<a id="exact-time-and-availability"></a>

## 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 ` |

<a id="calendar-meaning-and-interpretation"></a>

## 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 ` |

<a id="recurrence-import-and-storage"></a>

## 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](schedules.md#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](profiles.md#archive-interval-descriptions-in-development)
shows the distinction and links the new example.

[Choose a release and its API documentation](https://github.com/lukewilliamboswell/roc-time/releases)

<a id="developing-against-main"></a>

## Developing against main?

The [module source and documentation on main](https://github.com/lukewilliamboswell/roc-time/tree/main/package) describe the development API. Generate matching local API documentation with a current Roc nightly:

``` sh
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.