Concepts

The full specification, with an example for every edge case, is DESIGN.md. This page summarises it.

Rules

A rule produces blocks of time. It is either available (working time) or time off. A schedule's working time is all available blocks merged, minus all time-off blocks, so the order of rules never matters.

• Work day: start time, end time, working weekdays and a time zone. If the end is at or before the start, the shift is overnight and ends the next day; equal times mean a 24-hour shift. A shift belongs to the weekday it starts on, and a shift already in progress at the query time counts.
• Break: same shape as a work day, but subtracts time.
• Holiday: a set of dates. Each date removes 00:00–24:00 local time, so an overnight shift that crosses into a holiday loses only the part after midnight.
• Zones: every rule has a zone and defaults to the schedule's zone, holidays included.

Operations

• between(a, b) is the working time in [a, b). It is negative when b is before a.
• add(t, d) is the earliest instant with exactly d working time after t; sub is its mirror image. Adding zero returns t unchanged.
• next_period(t) is the stretch of working time that contains t, or the first one after it, starting at t if t is inside it; previous_period is its mirror image.
• The batch methods (between_many, add_many, sub_many in Python; betweenMany, addMany, subMany in JavaScript) apply an operation to many inputs in one call, which saves the per-call cost of crossing into Rust.

Time zones and DST

Working hours are wall-clock times in the rule's zone. Durations are elapsed real time, so a night shift is an hour shorter or longer when clocks change. Times that fall in a DST gap move forward by the gap; times that occur twice resolve to the earlier occurrence, as in jiff, RFC 5545 and JavaScript Temporal.

Errors

A schedule without working time is an error when it is built, and every search is bounded, so no call can hang.