So I’ll repeat:
What’s Feb 28th + 1 month?
Does the human expect the last day of March? Or the 28th day of March?
The API doesn’t make that clear - I think you could reasonably argue for either.
When you increment the month, the result would be 2021-03-28.
The only time you'd modify the day, is if the day became invalid due to an overflow, during that increment. If, when, you overflow the days you'd set the value of days to the maximum in that month.
If I tell someone, I'll get to that in a month, they expect by this day in the next month, the next calendar page, not 30/31 days.
6÷2(1+2) = ?
We could argue about what the _right_ answer is to that equation, but I call it a trap because it's intentionally confusing and devoid of any context (or the ability to ask a follow up question). There isn't really a situation where you would see that equation and not know the intended way to interpret it... just like your question.
There are a couple of ways that context _could_ be provided though:
I'm writing an automated task that should run once per month, I don't necessarily care what day of the month it runs though since it just cleans up some temp files. If today happens to be Feb 28th, and I say run today, then every month after, I would expect it to run Feb 28th, March 28th, April 28th...
I'm writing an 'end of month' task that needs to run at the end of every month for some bookkeeping reason. If today happens to be Feb 28th, and I say run today, then every month after, I would expect it to run Feb 28th, March 31th, April 30th...
In both of these situations I would program accordingly. Computers don't understand context, that's the job of the human programming it.
I think plus() is a name that is good enough. I can't think of a better name that will help the user understand what will happen in the 2/28 + 1 month case. That's asking too much of a method name. That's what docs are for.
At any rate, these problems have been solved in finance, with proper date and schedule libraries.
.plus .plus .plus isn't correct because "x months" doesn't have a fixed size. You are NOT saying Base .plus(30 days), NOR are you saying Base .plus(4 weeks) ((which BTW, I'd expect to stay on the same weekday)). You're incrementing by an unstable value.
I don’t think so, no—more likely, it should be Pattern(Month)… like how would you express “second Tuesday” as a series of additions?
""" None of the examples in the article use a more vague syntax, such as "0 days before the end of the month". """
As another reply points out, it's incrementing the Month set of buckets. I'll also extend with other results I expect:
2020-12-31 .plus(1 months) => 2021-01-31
2020-12-31 .plus(2 months) => 2021-02-28
2020-12-31 .plus(3 months) => 2021-03-31
2020-12-31 .plus(4 months) => 2021-04-30
I'll go further: JodaTime probably isn't focused on Precision Date Calculations; it behaves very much the way I expect someone working with forms and fields, general CRUD enterprisy software stuff, would want auto-filled dates to work.
""" None of the examples in the article use a more vague syntax, such as "0 days before the end of the month". """
---
They asked:
""" What’s Feb 28th + 1 month?
Does the human expect the last day of March? Or the 28th day of March? """
---
It's implicit, the human only expects the month to change, because the input isn't a descriptive phrase "the end of the month" adjusted or not, it's a literal date. That's why my other test cases show the same behavior for the end of the month.
Programmers exist in a world where things such as leap seconds matter. Normally if you have a timestamp that is just before a leap second, then add exactly a day's worth of seconds, you'd slide back a little in time. This might matter in another context, such as defining the limits of neighboring ranges properly. Also, who's to say the underlying precision is a second?
The intent of the library in question is to behave the way most people would. With imperfect buckets and idealized answers; yet also precision where someone makes the attempt to be specific.
None of the examples in the article use a more vague syntax, such as "0 days before the end of the month". They start with what a human might, a rounded but full date; then apply an interval. So a more clear contrived example might be.
Note how in the second half there are still variably sized months, but the result is what a human would want.