Our date and time tools rely on the proleptic Gregorian calendar, the Zeller weekday rule, and ISO 8601 for representation and week numbering. This page documents the formulas we apply, the standards we follow, and the edge cases (leap days, leap seconds, daylight saving transitions, locale weekday conventions) we explicitly handle so results stay reproducible and verifiable.
A year is a leap year if it is divisible by 4, except for century years, which must also be divisible by 400. So 2000 is a leap year, but 1900 and 2100 are not. We apply this rule proleptically, which means we extend it backward before 1582 for consistent arithmetic across long date ranges.
To map a Gregorian date to a weekday without iterating, we use Zeller's congruence: h = (q + floor(13(m+1)/5) + K + floor(K/4) + floor(J/4) + 5J) mod 7, where January and February are treated as months 13 and 14 of the previous year. The output is then normalized to ISO weekday numbering, where Monday is 1 and Sunday is 7.
We display canonical dates as YYYY-MM-DD and combined date-times as YYYY-MM-DDTHH:MM:SS with an explicit offset (Z for UTC, ±HH:MM otherwise). This is unambiguous across locales, sorts lexicographically in chronological order, and matches the format most APIs and databases store natively.
Business days exclude Saturday and Sunday. We let users optionally exclude a holiday list, which is applied after weekend filtering. For ranges that span months or years we count by iterating whole weeks plus a remainder, so very long spans stay O(1) per calculation rather than scanning every day.
ISO weeks start on Monday and week 1 of a year is the week containing the first Thursday (equivalently, the week containing January 4). Years therefore have 52 or 53 ISO weeks, and the first or last few days of a Gregorian year can belong to an adjacent ISO week-year. We label such dates as YYYY-Www-D using the ISO week-year, not the calendar year.
All instants are stored as UTC. UTC is maintained by BIPM in cooperation with national timing labs, and leap seconds are announced by IERS Bulletin C when needed to keep UTC within 0.9 seconds of UT1. Our duration math assumes 86,400 SI seconds per day and does not insert leap seconds, which matches the behavior of POSIX time and most operating systems.
Calendar logic is covered by unit tests that include leap years (1900, 2000, 2024), ISO week-year boundaries (December 29 to January 3), and DST transition days in both hemispheres. When IERS announces a new leap second, we update internal documentation but leave UTC arithmetic unchanged, because user expectations for elapsed days and hours match the POSIX model. We re-check this methodology page after every ISO 8601 amendment and at minimum once per calendar year.
