Adding time

add(t, d) returns the earliest instant at or after t with exactly d of working time between them. sub(t, d) returns the latest instant at or before t with exactly d of working time between them. This page covers both in Rust, Python and JavaScript.

Add 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 with an 8-hour SLA uses 30 minutes on Thursday, none on the holidays or the weekend, 7 hours on Tuesday 29 December, and its last 30 minutes on Wednesday 30 December. It is due at 09:30 on Wednesday 30 December 2026, London time.

Each tab adds the 8 hours, then subtracts them again from the due instant. Because 16:30 on Thursday is inside working time, sub returns the instant the ticket was opened.

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 due = support.add(&opened, SignedDuration::from_hours(8))?;
    assert_eq!(due.to_string(), "2026-12-30T09:30:00Z");

    let start = support.sub(due, SignedDuration::from_hours(8))?;
    assert_eq!(start.to_string(), "2026-12-24T16:30:00Z");
    Ok(())
}

What each language takes and returns:

• Rust: workclock::Schedule::add(&self, t: impl Into<jiff::Timestamp>, d: jiff::SignedDuration) returns Result<jiff::Timestamp, workclock::Error>, and sub has the same signature. t can be a jiff::Timestamp or a &jiff::Zoned. For local time, convert the result with due.to_zoned(opened.time_zone().clone()), as crates/workclock/examples/sla.rs does.
• Python: workclock.Schedule.add(dt, delta=None, /, *, hours=0, minutes=0, seconds=0) adds delta (a datetime.timedelta) plus hours, minutes and seconds. dt must be a timezone-aware datetime (a naive one raises ValueError); the result has the same tzinfo as dt. sub takes the same arguments.
• JavaScript: add(t, ms) and sub(t, ms) take a Date or an ISO 8601 string with a UTC offset, and a duration in milliseconds, and return a Date. The duration must be a whole number of milliseconds within ±Number.MAX_SAFE_INTEGER, or they throw RangeError; a string or BigInt duration throws TypeError rather than being converted.

Python's add_many and sub_many, and JavaScript's addMany and subMany, do the same for many instants in one call.

Where the result landsCopy Anchor Link

• On a period's end. add returns the earliest instant with enough working time, so a result that uses up a period lands on the period's end, not on the start of the next one. On the London desk, adding 1 hour at 11:00 on Tuesday 29 December returns 12:00, the start of lunch, not 13:00 (DESIGN.md A2).
• On a period's start, for sub. Subtracting 1 hour at 10:00 on a Monday of a 09:00–17:00 schedule returns 09:00 (DESIGN.md A9).
• From outside working time, add counts from the start of the next working time: 1 hour from 17:00 on Monday is 10:00 on Tuesday (DESIGN.md A3).
• Zero returns t unchanged, even outside working time or inside a break (DESIGN.md A5, A8, A11).
• A negative amount reverses the direction. add(t, -d) is sub(t, d), and sub(t, -d) is add(t, d) (DESIGN.md A6).

Round tripsCopy Anchor Link

For every t and d, between(t, add(t, d)) is d: Measuring time counts exactly the working time add used.

The reverse, sub(add(t, d), d) returning t, holds only when t is inside working time. From outside, sub lands on the start of the working time that add used. On a 09:00–17:00 weekday schedule, adding 1 hour at 10:00 on a Saturday returns 10:00 on Monday, and subtracting 1 hour from that returns 09:00 on Monday, not Saturday (DESIGN.md A4 then A9).

When add and sub failCopy Anchor Link

A schedule that builds always has working time, so the search bound trips only when rules in different zones are kept apart by daylight saving time (DST) changes for more than a year, or, in theory, when decades of holidays all fall on the only working day. Python also raises OutOfRangeError for a result outside the years 1 to 9999 of datetime, or an amount that does not fit in 64-bit microseconds. Every error class is on Errors.

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

• Measuring time: between, the inverse of add.
• Periods: next_period and previous_period, the stretches add and sub walk through.
• Rules: overnight shifts, breaks and holidays.
• Inputs and precision: instant and duration types in each language.
• Errors: the no-working-time and out-of-range errors.
• DESIGN.md: add(t, d) and sub(t, d): the specification.