Rules

A rule is one input to a schedule. WorkDay makes time available for work; Break and Holidays are time off. Every rule has a time zone, which is the schedule's unless the rule sets its own. This page covers the three rule types in Rust, Python and JavaScript.

Rules across one weekCopy Anchor Link

The London support desk has three rules: a WorkDay from 09:00 to 17:00, Monday to Friday; a Break from 12:00 to 13:00 on the same days; and Holidays on 25 and 28 December 2026. Times are in Europe/London.

Each tab builds the schedule and counts those 21 hours.

use jiff::civil::{date, time};
use jiff::{SignedDuration, Zoned};
use workclock::{Break, Holidays, Schedule, Weekdays, WorkDay};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let days = Weekdays::MON_TO_FRI;
    let support = Schedule::builder()
        .time_zone("Europe/London")
        .rule(WorkDay::new(time(9, 0, 0, 0), time(17, 0, 0, 0), days))
        .rule(Break::new(time(12, 0, 0, 0), time(13, 0, 0, 0), days))
        .rule(Holidays::new([date(2026, 12, 25), date(2026, 12, 28)]))
        .build()?;

    let thursday: Zoned = "2026-12-24T00:00[Europe/London]".parse()?;
    let next_thursday: Zoned = "2026-12-31T00:00[Europe/London]".parse()?;
    let worked = support.between(&thursday, &next_thursday);
    assert_eq!(worked, SignedDuration::from_hours(21));
    Ok(())
}

WorkDayCopy Anchor Link

A WorkDay has a start, an end, the weekdays it runs on and a time zone.

What a WorkDay produces:

• For each local date whose weekday is in its days, the block from start on that date to end.
• If end is at or before start, the shift is overnight and end falls on the next date. start equal to end is therefore a 24-hour shift.
• A shift belongs to the weekday it starts on. A Friday 22:00–06:00 shift runs into Saturday, and no shift ends on Monday morning unless one starts on Sunday.
• A shift already in progress at the query instant counts from that instant.

Overnight shiftsCopy Anchor Link

A night shift works 22:00–06:00, Monday to Friday, in UTC. Monday's shift counts 8 hours between Monday 22:00 and Tuesday 06:00, and adding 4 hours at Monday 22:00 lands on Tuesday 02:00 (DESIGN.md O1 and O2). businesstimedelta 1.0.1 gives 0 hours and Wednesday 02:00 for the same calls; the migration guide lists every difference.

use jiff::civil::time;
use jiff::{SignedDuration, Timestamp};
use workclock::{Schedule, Weekdays, WorkDay};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let days = Weekdays::MON_TO_FRI;
    let nights = Schedule::builder()
        .rule(WorkDay::new(time(22, 0, 0, 0), time(6, 0, 0, 0), days))
        .build()?;

    let monday: Timestamp = "2026-01-05T22:00:00Z".parse()?;
    let tuesday: Timestamp = "2026-01-06T06:00:00Z".parse()?;
    let worked = nights.between(monday, tuesday);
    assert_eq!(worked, SignedDuration::from_hours(8));

    let end = nights.add(monday, SignedDuration::from_hours(4))?;
    assert_eq!(end.to_string(), "2026-01-06T02:00:00Z");
    Ok(())
}

BreakCopy Anchor Link

A Break has the same shape as a WorkDay, including overnight breaks, but it is time off: its blocks are removed from the working time. A break outside working time has no effect.

• Rust: workclock::Break::new(start, end, days), with .time_zone(name) for its own zone.
• Python: workclock.Break(start, end, days=range(5), *, time_zone=None).
• JavaScript: { type: "break", start, end, days, timeZone }.

HolidaysCopy Anchor Link

Holidays is a set of local dates in a time zone. Each date removes the block from 00:00 on that date to 00:00 on the next date.

• Rust: workclock::Holidays::new(dates) takes any iterator of jiff::civil::Date; duplicates are ignored. .time_zone(name) sets its zone.
• Python: workclock.Holidays(dates, *, time_zone=None) takes datetime.date values; a datetime raises TypeError. A python-holidays object contributes only the years it already holds, so create it with years=...; one that holds no years raises ValueError.
• JavaScript: { type: "holidays", dates: ["2026-12-25"], timeZone }, with dates as YYYY-MM-DD strings.

What a holiday removes:

• Calendar time, not whole shifts. An overnight shift that crosses into a holiday loses only the part after midnight; a shift that starts on a holiday keeps the part after the next midnight (DESIGN.md HO1–HO3).
• A whole local day, so a holiday on the day clocks change for daylight saving time (DST) is shorter or longer than 24 hours by the size of the change, usually one hour.
• Nothing past the last date. Holidays are a finite set; queries after the last one see no time off (DESIGN.md H4).

The dates are read once, when the schedule is built; workclock never calls back into Python or JavaScript per date. Each holiday date also lengthens the search bound by seven days: Errors explains why.

Time zones of rulesCopy Anchor Link

Each rule has its own time zone. A rule without one uses the schedule's, and that includes Holidays: a holiday is a local date in the schedule's zone, not in UTC.

An office in America/Los_Angeles works 09:00–17:00, Monday to Friday, with a holiday on Monday 26 January 2026. With the holiday in the schedule's zone, Monday has no working time (DESIGN.md Z3). With the holiday set to UTC, it removes 16:00 on Sunday to 16:00 on Monday, Los Angeles time, and leaves 1 hour of Monday's working hours (DESIGN.md Z4). That mismatch is behind businesstimedelta issue #9. Each tab shows the UTC holiday:

use jiff::civil::{date, time};
use jiff::{SignedDuration, Zoned};
use workclock::{Holidays, Schedule, Weekdays, WorkDay};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let days = Weekdays::MON_TO_FRI;
    let office = Schedule::builder()
        .time_zone("America/Los_Angeles")
        .rule(WorkDay::new(time(9, 0, 0, 0), time(17, 0, 0, 0), days))
        .rule(Holidays::new([date(2026, 1, 26)]).time_zone("UTC"))
        .build()?;

    let start: Zoned = "2026-01-26T09:00[America/Los_Angeles]".parse()?;
    let end: Zoned = "2026-01-26T17:00[America/Los_Angeles]".parse()?;
    let worked = office.between(&start, &end);
    assert_eq!(worked, SignedDuration::from_hours(1));
    Ok(())
}

Without the holiday's own zone, each tab gives 0 hours. Working hours in each rule's zone, and what happens when clocks change, are on Time zones and DST.

Edge casesCopy Anchor Link

These examples are from DESIGN.md, and the Rust, Python and JavaScript test suites all run them from tests/fixtures/design_examples.json. Unless the row says otherwise, they use the week of Monday 5 January 2026 in UTC, and 9–17 Mon–Fri is a WorkDay from 09:00 to 17:00, Monday to Friday.

See alsoCopy Anchor Link

• Schedules: how rules combine into working time.
• Adding time and Measuring time: add, sub and between.
• Time zones and DST: gaps, overlaps and shifts that span a clock change.
• Errors: what building a schedule with no working time raises.
• DESIGN.md: Rules: the specification.