Calendar.Roll Method
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Overloads
| Roll(CalendarField, Boolean) |
Rolls (up/down) a single unit of time on the given field. |
| Roll(CalendarField, Int32) |
Rolls (up/down) a specified amount time on the given field. |
Roll(CalendarField, Boolean)
Rolls (up/down) a single unit of time on the given field.
[Android.Runtime.Register("roll", "(IZ)V", "", ApiSince=24)]
public void Roll (Android.Icu.Util.CalendarField field, bool up);[<Android.Runtime.Register("roll", "(IZ)V", "", ApiSince=24)>]
member this.Roll : Android.Icu.Util.CalendarField * bool -> unitParameters
- field
- CalendarField
the calendar field to roll.
- up
- Boolean
indicates if the value of the specified time field is to be
rolled up or rolled down. Use true if rolling up,
false otherwise.
- Attributes
Remarks
Rolls (up/down) a single unit of time on the given field. If the field is rolled past its maximum allowable value, it will "wrap" back to its minimum and continue rolling. For example, to roll the current date up by one day, you can call:
roll({@link #DATE}, true)
When rolling on the #YEAR field, it will roll the year value in the range between 1 and the value returned by calling #getMaximum getMaximum(#YEAR).
When rolling on certain fields, the values of other fields may conflict and need to be changed. For example, when rolling the MONTH field for the Gregorian date 1/31/96 upward, the DAY_OF_MONTH field must be adjusted so that the result is 2/29/96 rather than the invalid 2/31/96.
Rolling up always means rolling forward in time (unless the limit of the field is reached, in which case it may pin or wrap), so for the Gregorian calendar, starting with 100 BC and rolling the year up results in 99 BC. When eras have a definite beginning and end (as in the Chinese calendar, or as in most eras in the Japanese calendar) then rolling the year past either limit of the era will cause the year to wrap around. When eras only have a limit at one end, then attempting to roll the year past that limit will result in pinning the year at that limit. Note that for most calendars in which era 0 years move forward in time (such as Buddhist, Hebrew, or Islamic), it is possible for add or roll to result in negative years for era 0 (that is the only way to represent years before the calendar epoch in such calendars).
<b>Note:</b> Calling roll(field, true) N times is <em>not</em> necessarily equivalent to calling roll(field, N). For example, imagine that you start with the date Gregorian date January 31, 1995. If you call roll(Calendar.MONTH, 2), the result will be March 31, 1995. But if you call roll(Calendar.MONTH, true), the result will be February 28, 1995. Calling it one more time will give March 28, 1995, which is usually not the desired result.
<b>Note:</b> You should always use roll and add rather than attempting to perform arithmetic operations directly on the fields of a Calendar. It is quite possible for Calendar subclasses to have fields with non-linear behavior, for example missing months or days during non-leap years. The subclasses' add and roll methods will take this into account, while simple arithmetic manipulations may give invalid results.
Java documentation for android.icu.util.Calendar.roll(int, boolean).
Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.
Applies to
Roll(CalendarField, Int32)
Rolls (up/down) a specified amount time on the given field.
[Android.Runtime.Register("roll", "(II)V", "GetRoll_IIHandler", ApiSince=24)]
public virtual void Roll (Android.Icu.Util.CalendarField field, int amount);[<Android.Runtime.Register("roll", "(II)V", "GetRoll_IIHandler", ApiSince=24)>]
abstract member Roll : Android.Icu.Util.CalendarField * int -> unit
override this.Roll : Android.Icu.Util.CalendarField * int -> unitParameters
- field
- CalendarField
the calendar field to roll.
- amount
- Int32
the amount by which the field should be rolled.
- Attributes
Remarks
Rolls (up/down) a specified amount time on the given field. For example, to roll the current date up by three days, you can call roll(Calendar.DATE, 3). If the field is rolled past its maximum allowable value, it will "wrap" back to its minimum and continue rolling. For example, calling roll(Calendar.DATE, 10) on a Gregorian calendar set to 4/25/96 will result in the date 4/5/96.
When rolling on certain fields, the values of other fields may conflict and need to be changed. For example, when rolling the #MONTH MONTH field for the Gregorian date 1/31/96 by +1, the #DAY_OF_MONTH DAY_OF_MONTH field must be adjusted so that the result is 2/29/96 rather than the invalid 2/31/96.
Rolling by a positive value always means rolling forward in time (unless the limit of the field is reached, in which case it may pin or wrap), so for the Gregorian calendar, starting with 100 BC and rolling the year by + 1 results in 99 BC. When eras have a definite beginning and end (as in the Chinese calendar, or as in most eras in the Japanese calendar) then rolling the year past either limit of the era will cause the year to wrap around. When eras only have a limit at one end, then attempting to roll the year past that limit will result in pinning the year at that limit. Note that for most calendars in which era 0 years move forward in time (such as Buddhist, Hebrew, or Islamic), it is possible for add or roll to result in negative years for era 0 (that is the only way to represent years before the calendar epoch in such calendars).
<strong>[icu] Note:</strong> the ICU implementation of this method is able to roll all fields except for #ERA ERA, #DST_OFFSET DST_OFFSET, and #ZONE_OFFSET ZONE_OFFSET. Subclasses may, of course, add support for additional fields in their overrides of roll.
<b>Note:</b> You should always use roll and add rather than attempting to perform arithmetic operations directly on the fields of a Calendar. It is quite possible for Calendar subclasses to have fields with non-linear behavior, for example missing months or days during non-leap years. The subclasses' add and roll methods will take this into account, while simple arithmetic manipulations may give invalid results.
<b>Subclassing:</b><br> This implementation of roll assumes that the behavior of the field is continuous between its minimum and maximum, which are found by calling #getActualMinimum getActualMinimum and #getActualMaximum getActualMaximum. For most such fields, simple addition, subtraction, and modulus operations are sufficient to perform the roll. For week-related fields, the results of #getFirstDayOfWeek getFirstDayOfWeek and #getMinimalDaysInFirstWeek getMinimalDaysInFirstWeek are also necessary. Subclasses can override these two methods if their values differ from the defaults.
Subclasses that have fields for which the assumption of continuity breaks down must override roll to handle those fields specially. For example, in the Hebrew calendar the month "Adar I" only occurs in leap years; in other years the calendar jumps from Shevat (month #4) to Adar (month #6). The HebrewCalendar#roll HebrewCalendar.roll method takes this into account, so that rolling the month of Shevat by one gives the proper result (Adar) in a non-leap year.
Java documentation for android.icu.util.Calendar.roll(int, int).
Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.