[CaptainOfCoit]

> This Elixir version introduces the Duration data type and APIs to shift dates, times, and date times by a given duration, considering different calendars and time zones.

> We chose the name “shift” for this operation (instead of “add”) since working with durations does not obey properties such as associativity. For instance, adding one month and then one month does not give the same result as adding two months:

I'm not exactly sure why adding one month and then one month would give a different result compared to just adding two months. Don't you in reality want the same thing? Why is "shift" more useful than "add"?

[Tao3300]

"One month" is a tricky unit because it's not always the same size. They have a good example right there. What's a month after Jan 31? Feb 28 or 29. A month after that? Mar 28 or 29.

What's two months after Jan 31? Mar 31.

Maybe you think it should behave otherwise, but they picked a way and changed the name so you wouldn't think of the addition operation and its expected properties.

[icedchai]

There are edge cases near month end.

I once wrote a billing system for my own small business. If the customer signed up for a monthly plan near month end, on a day >= 28, their next billing date was always on the 28th to keep things simple.

[bhaney]

There's a code example immediately after your quote specifically for addressing your confusion