Calendar add() vs roll() when do we use it?

Question

I know add() adds the specified (signed) amount of time to the given time field, based on the calendar's rules.

And roll() adds the specified (signed) single unit of time on the given time field without changing larger fields.

I can't think of an everyday usage of roll() I would do everything by add().

Can you help me out with examples when do we use roll() and when add()?

EDIT 1

Joda answers are not accepted!

Answer 1

I'm not convinced that the Calendar API is a good candidate for determining use cases. It's well-known for not being particularly useful (and somewhat confusing). See Joda Time for a better API.

Answer 2

• add() - almost always, as you said
• roll() - for example you want to "dispense" events in one month. The algorithm may be to proceed a number of days and place the event, then proceed further. When the end of the month is reached, it should start over from the beginning. Hence roll().

Answer 3

Found in jGuru

• Calendar.roll()
  Changes a specific unit and leaves 'larger' (in terms of time-month is 'larger' than day) units unchanged. The API example is that given a date of August 31, 1999, rolling by (Calendar.MONTH, 8) yields April 30, 1999. That is, the DAY was changed to meet April's maximum, but the 'larger' unit, YEAR, was unchanged.

• Calendar.add()
  Will cause the next 'larger' unit to change, if necessary. That is, given a date of August 31, 1999, add(Calendar.MONTH, 8) yields April 30, 2000. add() also forces a recalculation of milliseconds and all fields.