Calendar contracts
Calendar dates, ISO week years and elapsed durations
A date identifies a calendar day, an instant identifies a point on a timeline, and a duration measures an amount of time. They are not interchangeable.
Content updated: · Maintainer and corrections
Count civil days, not assumed 24-hour periods
The date tools use the proleptic Gregorian calendar for years 0001–9999 and reject invalid dates instead of letting Date silently roll them forward. They do not model historical changes between calendars.
A date difference and a count of included days answer different questions. Read the start/end inclusion controls for weekday counts. Monday–Friday excludes weekends only; public holidays, organization calendars and legal deadlines require a separate authority.
An ISO week year is not always the calendar year
ISO weeks begin Monday. Week 1 contains January 4, so dates around New Year can belong to the previous or next week year. Week 53 exists only in particular week years; validate it rather than assuming every year has 53 weeks.
For example, 2021-01-01 is 2020-W53-5. Use the converter's Monday–Sunday range to verify reports. Fiscal weeks, locale conventions and Sunday-first numbering are different systems.
Durations do not wrap at midnight
A total of 27 hours remains 27 hours, not 03:00 on a clock. Use the stated signed input grammar for addition and subtraction. Minutes and seconds must remain in their allowed ranges; a malformed line blocks the complete calculation.
Fixed durations cannot express calendar months or resolve local daylight-saving changes. Keep payroll rounding, billing increments and calendar-date arithmetic separate. Copy the total and its unit together.
2024-02-28 + 1 calendar day = 2024-02-29
2021-01-01 = 2020-W53-5
25:00:00 + 02:30:00 = 27:30:00Data provenance