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: · Maintained by Hung Chi-Hsueh · 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.
Month and year arithmetic needs a policy
A calendar month is not 30 fixed days. This calculator moves directly to the target month/year, then clamps the original day to that month's last valid date: 2024-01-31 + 1 month = 2024-02-29, and + 2 months = 2024-03-31. Repeating one-month steps instead reaches March 29; these are different workflows.
Clamping is not reversible: adding then subtracting a month may not recover the original day. Leap-day year arithmetic also clamps February 29 to February 28 in a common year. Use the separate age calculator for its explicitly stated birthday policy, not a duration or a legal-age determination.
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