Measuring time

between(a, b) returns the working time in [a, b): the time from a up to, but not including, b that the schedule counts. It is negative when b is before a. This page covers between in Rust, Python and JavaScript.

Count working timeCopy Anchor Link

A support desk in London works 09:00–17:00 on weekdays with a lunch hour, and is closed on 25 and 28 December 2026. A ticket opened at 16:30 on Thursday 24 December 2026, London time. By 11:00 on Tuesday 29 December it has used 2 hours 30 minutes of working time:

Each tab counts that time, then swaps the two instants to get the same amount with a minus sign.

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 opened: Zoned = "2026-12-24T16:30[Europe/London]".parse()?;
    let now: Zoned = "2026-12-29T11:00[Europe/London]".parse()?;
    let used = support.between(&opened, &now);
    assert_eq!(used, SignedDuration::from_mins(150));
    assert_eq!(support.between(&now, &opened), -used);
    Ok(())
}

What each language takes and returns:

The supported range is -009999-01-02T01:59:59Z to 9999-12-30T22:00:00Z. Python's between_many and JavaScript's betweenMany measure many pairs in one call.

The sign of the resultCopy Anchor Link

• a before b: the working time in [a, b), zero or more.
• a after b: minus between(b, a). The result is signed, like b - a for two instants, which resolves businesstimedelta issue #12.
• a equal to b: zero.

So between(a, b) is always -between(b, a), and an amount of time passed to add comes back from between: between(t, add(t, d)) is d for every t and d (Adding time).

What is countedCopy Anchor Link

between counts working time only, so the same calls hold for every rule:

• A break inside the span is left out, and a span that starts inside a break counts from the break's end (DESIGN.md K1, K2).
• Holidays and days not in a WorkDay's days count nothing (DESIGN.md H1, B3).
• An overnight shift counts across midnight, on the weekday it starts on (DESIGN.md O1, O5, O6).
• Durations are elapsed real time, so a night shift is an hour shorter or longer when clocks change for daylight saving time (DST) (DESIGN.md D1, D2). Time zones and DST has the details.

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

• Adding time: add and sub, the inverse of between.
• Periods: the stretches of working time between adds up.
• Rules: what WorkDay, Break and Holidays count.
• Inputs and precision: instant and duration types in each language.
• DESIGN.md: between(a, b): the specification.