Adding days, weeks and months: where date arithmetic gets ambiguous

Adding a number of days to a date is one of the few operations in this field that is genuinely simple. Adding months is not simple at all, and the difference catches people out because both are written the same way in everyday language.

Days and weeks: no ambiguity

Days are countable and equal in the calendar, so adding 45 days to a date has exactly one answer, leap years included. Weeks are just days in sevens, and they have the useful property of preserving the weekday: any multiple of seven days from a Tuesday is a Tuesday. If you need a deadline that lands on the same weekday, count in weeks rather than in months.

Months: three defensible answers

What is one month after 31 January? There is no arithmetic fact to appeal to, only conventions:

• Clamp to the end of the month. 28 February, or 29 in a leap year. This is what most date libraries and most contracts do.
• Overflow into the next month. 3 March, by adding the notional 31 days. Rare in software, but it appears in some hand calculations.
• Treat it as invalid and require the caller to decide. Strictly correct and usually impractical.

The clamping convention has a consequence worth knowing: adding one month twice is not the same as adding two months once. From 31 January, month by month, you get 28 February and then 28 March. Adding two months in one step gives 31 March. Neither is a bug, and any system that does repeated monthly arithmetic should say which it does.

Years are months in twelves, with one edge case

Adding a year to 29 February has the same problem, and the same clamping answer: 28 February in a common year. This is exactly the leap-day birthday question in another guise, and it is why some legal texts spell out the convention rather than leaving it to arithmetic.

Order of operations matters

"Three months and ten days from now" gives different results depending on which you add first, when the month step lands on a clamped date. Fix an order, and state it: adding months first and then days is the more common convention, because it keeps the month arithmetic away from the day arithmetic.

Do not add hours when you mean days

Adding 30 times 24 hours to a local date and time will be an hour out if a clock change falls in the window. Adding 30 days in the calendar will not. Keep calendar arithmetic in calendar units and reserve hours for genuine durations.

For the practical case, the add days to a date tool counts in days and weeks, so the result is exact and the weekday it lands on is visible, which is usually the thing you actually wanted to know.