Periods

A period is a maximal stretch of working time, written [start, end): it includes start but not end. next_period and previous_period return the period at, after or before an instant; JavaScript names them nextPeriod and previousPeriod. This page covers Rust, Python and JavaScript.

Which period is returnedCopy Anchor Link

• next_period(t) returns the period that contains t, starting at t. If t is outside working time, it returns the first period that starts after t. A period that ends at t does not contain it.
• previous_period(t) returns the period that contains the instant just before t, ending at t. Otherwise it returns the last period that ends before t. A period that starts at t is skipped.
• A period is one stretch of working time, whichever rules produce it. An overnight shift is one period across midnight, and shifts that touch or overlap form one period. Breaks and holidays split working time into separate periods.

The London support desk from the README works 09:00–17:00 Monday to Friday in Europe/London, with a break from 12:00 to 13:00, and is closed on 25 and 28 December 2026. Each [====) is one period, in London time:

              09:00            12:00   13:00            17:00
Thu 24 Dec    [================)       [================)
Fri 25 Dec    holiday
Sat 26 Dec    weekend
Sun 27 Dec    weekend
Mon 28 Dec    holiday
Tue 29 Dec    [================)       [================)

From 11:00 on Tuesday 29 December, next_period returns 11:00–12:00: the morning period, starting at 11:00. From 09:00 on Tuesday, previous_period skips the period that starts at 09:00 and returns 13:00–17:00 on Thursday 24 December, past both holidays and the weekend.

Return valuesCopy Anchor Link

Find the next and previous periodCopy Anchor Link

use jiff::civil::{date, time};
use jiff::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 now: Zoned = "2026-12-29T11:00[Europe/London]".parse()?;
    let next = support.next_period(&now)?;
    assert_eq!(next.start.to_string(), "2026-12-29T11:00:00Z");
    assert_eq!(next.end.to_string(), "2026-12-29T12:00:00Z");

    let morning: Zoned = "2026-12-29T09:00[Europe/London]".parse()?;
    let previous = support.previous_period(&morning)?;
    assert_eq!(previous.start.to_string(), "2026-12-24T13:00:00Z");
    assert_eq!(previous.end.to_string(), "2026-12-24T17:00:00Z");
    Ok(())
}

London's offset from UTC is zero in December, so the UTC instants in the Rust and JavaScript tabs are also London wall-clock times.

Long periods and errorsCopy Anchor Link

Every search stops at the search bound: 366 days, plus seven days per holiday date in the schedule.

• Round-the-clock schedules. A period is capped at the search bound. next_period returns at most the bound from the period's start, and previous_period at most the bound up to its end. Only schedules that work round the clock have periods that long (P19–P21).
• No working time. next_period fails with the no-working-time error if no period starts within the search bound after t, and previous_period if none ends within the bound before t (P22, P23). That is workclock::Error::NoWorkingTime in Rust and NoWorkingTimeError in Python and JavaScript.
• End of the supported range. If the search reaches the end of the supported range (the start, for previous_period) before finding working time, the result is the out-of-range error: workclock::Error::OutOfRange, or OutOfRangeError in Python and JavaScript (P24). A period that runs into either end of the range stops there.

Errors lists every error class in each language.

Edge casesCopy Anchor Link

These are the period examples from DESIGN.md. Each ID is a case in tests/fixtures/design_examples.json, which the Rust, Python and JavaScript test suites all run. Unless noted, dates are in the week of Monday 5 January 2026, times are UTC, and 9–17 Mon–Fri is a WorkDay from 09:00 to 17:00, Monday to Friday.

In P20 and P21 each period would otherwise run one day past the bound. P22's schedule builds because the break missed the shift while São Paulo kept summer time; since Brazil dropped it in 2019, the break covers the whole shift.

See alsoCopy Anchor Link

• Adding time: add and sub, which walk through the same periods.
• Rules: overnight shifts, breaks and holidays, which decide where periods start and end.
• Errors: the no-working-time and out-of-range errors in each language.
• DESIGN.md: next_period(t) and previous_period(t), the specification.