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

<a id="schedules"></a>

# Generate and exchange schedules

A weekly reservation needs a starting date, a repetition rule and any exceptions. When you query next month, you still want the same series: its count and cancellations shouldn’t restart at the beginning of your screenful.

<a id="start-with-a-bounded-reservation-query"></a>

## Start with a bounded reservation query

The [equipment reservations source](https://github.com/lukewilliamboswell/roc-time/tree/main/examples/reservations) demonstrates recurring appointments with identities and ending times. Run the copy in your [release archive](getting-started.md#getting-started), or run the current source from a checkout:

``` sh
roc examples/reservations/main.roc
```

There are three choices to make:

1. **Definition:** when does the series start, how does it repeat, and which dates are added or excluded?


2. **Interpretation:** which timezone rules and repeated/skipped-time policies apply to those local starts?


3. **Query:** which start-date window do you want, and how much work and output can this call produce?


` ScheduleDefinition ` retains the declaration and context for fresh queries. ` TimedSchedule.collect ` collects a bounded batch from a cursor. For dates without clock times or appointment endings, start with ` DateRecurrence `.

A query selects appointment **starts**. A booking starting at 16:00 can end after a 17:00 query boundary. To find every booking overlapping a reporting window, account for bookings that started earlier as well; a start query alone doesn’t answer that question.

<a id="treat-incomplete-output-honestly"></a>

## Treat incomplete output honestly

A batch marked ` Complete ` finished the requested query. A ` Limited ` batch contains partial output and the cursor you need to continue. Keep that cursor: starting again from the next date can lose counting and exception state.

Work and output limits serve different purposes. A rule might examine many dates before finding a match, so “one appointment per batch” doesn’t bound the search. If a budget can’t make progress, increase it or report the incomplete result rather than retrying forever. The [API reference](api.md#api) describes the limits for each query.

<a id="importing-icalendar-values"></a>

## Importing iCalendar values

` ICalDateRule ` and ` ICalTimedRule ` accept supported RFC 5545 property values after your application has extracted them. They don’t read a whole ` .ics ` file, unfold content lines or accept arbitrary parameters. Check the chosen adapter’s profile before importing an external calendar.

For example, a rule’s ` COUNT ` counts its anchored recurrence before exclusions. Canceling one of four rule occurrences doesn’t create a fifth. A ` PERIOD ` addition can instead contribute a separate appointment with its own end. An occurrence’s original local label stays meaningful even if a gap policy moves its resolved start.

Unsupported forms return errors. That lets your importer report which part needs another adapter without quietly changing the schedule.

<a id="editing-and-exchanging-definitions"></a>

## Editing and exchanging definitions

The [meeting exchange example](https://github.com/lukewilliamboswell/roc-time/tree/main/examples/meeting_exchange) edits a weekly meeting, exports its extracted properties, then reimports them across a fixed zone transition. These adapters expose checked definitions and canonical property text, so application code doesn’t have to reconstruct a rule from query output.

Save supported declarations using their standard property serializers and supply interpretation context when loading them. A property string doesn’t embed a zone table, and some native calendar policies can’t be expressed by the selected standard profile. Export rejects those cases rather than dropping the policy.

Repository examples show the development API. Check your release archive and API pages before copying an operation into an application using an older package.

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

## API reference

` DateRecurrence `, ` TimedRecurrence `, ` TimedSchedule `, ` ScheduleDefinition ` and ` ICalTimedRule ` appear in [the API map](api.md#api).