How to Calculate the Difference Between Two Dates

Subtracting two dates looks like one operation, but the answer depends on what you are counting: whole calendar days, elapsed time, or an inclusive range that counts both endpoints. Choosing the wrong model is the most common source of off-by-one results.

01Three questions to settle first

• Calendar dates or instants? A date has no time zone; an instant does.
• Exclusive or inclusive? The number of elapsed days from Monday to Friday is 4, but 5 calendar days if both ends count.
• Which convention does the consumer expect? Billing periods, leave balances, and APIs often differ.

02How the calculation works

• Convert each calendar date to a day count (its proleptic Gregorian ordinal).
• Subtract the earlier ordinal from the later one for elapsed days.
• To add or subtract days, move along the calendar and then re-derive the year, month, and day.

03Limitations

This guide covers proleptic Gregorian calendar arithmetic in a fixed local calendar. It does not convert between time zones, measure elapsed physical time, or define business-day and holiday rules.