Dates Are Harder Than They Look

The Off-By-One That Never Goes Away

From the 1st to the 8th is seven days apart and spans eight days. Both statements are correct, they answer different questions, and virtually every argument about dates traces back to which one was meant.

The distinction has a name. An exclusive count measures the gap between two moments; an inclusive count measures how many days the range covers. A hotel charging for eight nights and a guest counting seven days are both counting correctly, which is precisely why the argument is unresolvable without agreeing the convention first.

Contracts handle this by writing "both dates inclusive" in words, and the fact that lawyers bother is a good indication of how often it matters. The date difference calculator shows both figures rather than picking one, because picking one is exactly the behaviour that causes the problem.

Legal periods add a further wrinkle: many start on the day after service rather than the day itself, and some specify "clear days", excluding both ends. Those are conventions written into the rules rather than facts about the calendar, and no calculator can infer them.

Thirty Days Is Not Thirty Business Days

Thirty calendar days is roughly four and a quarter weeks. Thirty business days is six weeks — and rather more once public holidays are deducted. A supplier working to one while you plan around the other produces a fortnight's disagreement about the same clause.

Counting business days by hand is unreliable past about a fortnight, and the tempting shortcut fails. Multiplying weeks by five ignores the ragged days at each end, and those ends can contribute anywhere from zero to five working days depending on which weekday the range starts. Over a 354-day range the shortcut suggests 253 working days where the true count is 254.

Holidays then come off, and only the ones falling on working days — a public holiday on a Saturday was never a working day, so deducting it double-counts. Where a day in lieu is granted on the following Monday, the Monday is what should be deducted. The days between dates calculator walks the range a day at a time and takes a holiday list, which removes both sources of error.

Whose holidays apply is a question the arithmetic cannot answer. Federal, state, regional and company calendars all differ, and a deadline that crosses a border should be counted against the calendar of whoever has to act.

A Month Is Not a Length

What is one month after 31 January?

There is no correct answer, only conventions. Clamping to the end of the target month gives 28 or 29 February, which is what most people mean and what most well-behaved software does. Rolling over gives 2 or 3 March, which is what naive code produces when it increments the month number and leaves the day alone — the resulting 31 February is silently converted, and every subsequent calculation is a day or three out.

This is why an age or a duration in years and months cannot be converted into days without knowing which months were actually crossed. Twenty-nine calendar months from 15 March 2024 contain 883 days; twenty-nine average months of 30.437 days would suggest 882.67. Close over a long span, because the 31s and the 28s balance out — and badly wrong over a short one, where 1 January to 1 March is 59 days against an average estimate of 60.87.

The age calculator reports both the calendar breakdown and the exact day count for this reason. Use the first for anything a person will read and the second for anything that will be sorted, compared or multiplied.

Work in UTC, Always

The last trap is the one most likely to appear in your own code, and it is the reason every date tool on this site anchors dates at midnight UTC.

A date constructed from local components sits in local time, and in any region observing daylight saving there are two days a year that are not twenty-four hours long. Subtract two such dates and divide by 86,400,000 milliseconds and you get 0.958 or 1.042 days instead of 1. Round it and you are usually fine; floor it and you are occasionally a day out, in a way that reproduces twice a year and never in testing.

Anchoring at midnight UTC makes a day exactly 86,400,000 milliseconds, always. The cost is that a date near midnight local time can belong to a different calendar day than the user expects, which is a display concern rather than an arithmetic one and is much easier to reason about.

Two smaller points worth carrying. Leap years are not simply every four years — a century year is not a leap year unless divisible by 400, so 1900 was not and 2000 was, which is why the mean Gregorian year is 365.2425 days rather than 365.25. And historical dates before the Gregorian changeover need care that no calculator provides: different countries switched in different years and skipped ten or eleven days when they did. The birthday calculator will happily tell you the weekday of a date in 1650, and whether that weekday is the one people living there used depends entirely on where they were.

Four Ways Two Date Tools Disagree

Give the same pair of dates to two calculators and they will occasionally differ. Usually neither is broken; they have made different, defensible choices, and knowing which four choices exist explains almost every disagreement.

Extraction order. Taking years first, then months, then days is the common convention. Extracting the largest unit last gives different and equally consistent results. This is why the same span can legitimately read as two years and five months in one tool and something slightly different in another.

Inclusive or exclusive. Covered above, and still the single most common source of off-by-one differences between any two systems.

The average year. Decimal years can use 365, 365.25 or 365.2425 days. The third is the correct Gregorian mean, and over a century the difference from 365.25 is about three quarters of a day — invisible on a single calculation and visible in a long amortisation schedule.

Month-end clamping. Whether one month after 31 January is 28 February or 3 March. Both behaviours exist in shipped software, and the second is almost always unintentional.

None of these has a universally correct answer, which is why a tool that states its convention is more useful than one that appears to be authoritative. The days between dates calculator shows the inclusive and exclusive counts together rather than choosing for you.

What Every Date Bug Has in Common

The reason date handling produces such durable bugs is not that the rules are complicated. It is that the wrong behaviour is correct almost all the time.

Local-time arithmetic works on 363 days of the year. Month addition without clamping works for 28 days of every month. A business-day estimate from weeks times five is right whenever the range happens to start on a Monday. Each of these passes casual testing, ships, runs correctly for months, and then fails on a specific date in a way that looks like an isolated glitch rather than a systematic fault.

That failure profile is what makes date bugs expensive. A function wrong every time gets found on the first run. A function wrong 0.5% of the time gets found by a customer, months later, and the report — "the deadline showed a day early once" — is nearly impossible to reproduce without knowing which class of error to look for.

Three defences cover most of it. Work in UTC and convert only for display, so a day is always 86,400,000 milliseconds. Never build date arithmetic out of string manipulation. And test the awkward cases deliberately: 29 February, 31 January plus a month, a range spanning a daylight saving transition, a year divisible by 100. Those four inputs find nearly every date bug that exists, and they take about a minute to try.