[bhuvan-somisetty]

Description

When modify_datetime() adds or subtracts months or years, it now clamps the day to the last day of the target month. So Jan 31 + 1 month gives Feb 28 (Feb 29 in a leap year), and Feb 29 + 1 year gives Feb 28. Before, it kept the day as is and blew up with ValueError: day is out of range for month.

Motivation and context

Fixes #8090. This goes through increment_datetime_by_string() / decrement_datetime_by_string(), so anything that steps through time by months or years (t.register with increment=, t.rast.accumulate, etc.) could crash on end-of-month dates.

How has this been tested?

Added cases to grass_temporal_datetime_math_test.py for month-end and Feb 29, both forward and backward. They fail on main and pass with this change. The existing datetime_math tests and doctests still pass.

Screenshots (if appropriate)

Same calls on main vs. this branch:

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing
  functionality to not work as before)

Checklist

• PR title provides summary of the changes and starts with one of the
  pre-defined prefixes
• My code follows the code style
  of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have added tests to cover my changes.

[petrasovaa]

Here is my response AI response:

Thanks for the investigation. I'm going to close this one, though, because clamping changes what a month step means in ways that are worse than the current error.

The main problem shows up in callers that step through time. t.register -i start=2001-01-31 increment="1 months" computes each map's end from the already-clamped start, so the intervals become [01-31, 02-28), [02-28, 03-28), [03-31, 04-30), [04-30, 05-30). They no longer tile: there is a gap between 03-28 and 03-31, and the dataset is silently non-equidistant. Code that re-increments the previous result (t.rast.accumulate, AbstractSpaceTimeDataset.shift) drifts further, 01-31 -> 02-28 -> 03-28 -> 04-28, and shifting forward and back by a month no longer returns to the start. Today those cases fail loudly; with this change they produce wrong intervals without any warning.

There are also two issues in the change itself: months and years are clamped separately and summed as day counts, so 2004-01-31 plus "1 months, 1 years" gives 2005-03-01 instead of 2005-02-28, and a negative multiple of 12 months from January (for example -13 months from 2001-01-01) still ends on month 0 and raises.

Month-end starts with month or year increments are rare and nobody has reported hitting this in practice, so I'd rather keep rejecting them than clamp. If someone has a real workflow that needs month-end monthly stepping, that would be a good reason to revisit, but it needs a decision about how the stepping callers derive their dates, not just a change inside modify_datetime().