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.
Start with a bounded reservation query§
The equipment reservations source demonstrates recurring appointments with identities and ending times. Run the copy in your release archive, or run the current source from a checkout:
roc examples/reservations/main.roc
There are three choices to make:
Definition: when does the series start, how does it repeat, and which dates are added or excluded?
Interpretation: which timezone rules and repeated/skipped-time policies apply to those local starts?
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.
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 describes the limits for each query.
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.
Editing and exchanging definitions§
The meeting exchange example 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.
API reference§
DateRecurrence, TimedRecurrence, TimedSchedule, ScheduleDefinition and ICalTimedRule appear in the API map.