organicmaps/icu
13
Fork 0
mirror of https://github.com/unicode-org/icu.git synced 2025-04-21 12:40:02 +00:00
Code Issues 1 Projects Releases Wiki Activity Actions 1

ICU-9226 Better documentation for add and roll functions/methods

Browse source 
X-SVN-Rev: 31967
This commit is contained in:
Peter Edberg 2012-06-19 07:09:54 +00:00
parent c63be1f302
commit 43d3e4e099
2 changed files with 70 additions and 16 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

74
icu4c/source/i18n/unicode/calendar.h
View file

@ -527,6 +527,9 @@ public:
* the month or Calendar::MONTH field, other fields like date might conflict and
* need to be changed. For instance, adding 1 month on the date 01/31/96 will result
* in 02/29/96.
* Adding a positive value always means moving forward in time, so for the Gregorian calendar,
* starting with 100 BC and adding +1 to year results in 99 BC (even though this actually reduces
* the numeric value of the field itself).
*
* @param field Specifies which date field to modify.
* @param amount The amount of time to be added to the field, in the natural unit
@ -546,6 +549,9 @@ public:
* the month or Calendar::MONTH field, other fields like date might conflict and
* need to be changed. For instance, adding 1 month on the date 01/31/96 will result
* in 02/29/96.
* Adding a positive value always means moving forward in time, so for the Gregorian calendar,
* starting with 100 BC and adding +1 to year results in 99 BC (even though this actually reduces
* the numeric value of the field itself).
*
* @param field Specifies which date field to modify.
* @param amount The amount of time to be added to the field, in the natural unit
@ -567,10 +573,19 @@ public:
* value returned by getMaximum(Calendar::YEAR). When rolling on the month or
* Calendar::MONTH field, other fields like date might conflict and, need to be
* changed. For instance, rolling the month up on the date 01/31/96 will result in
* 02/29/96. Rolling up always means rolling forward in time; e.g., rolling the year
* up on "100 BC" will result in "99 BC", for Gregorian calendar. When rolling on the
* hour-in-day or Calendar::HOUR_OF_DAY field, it will roll the hour value in the range
* between 0 and 23, which is zero-based.
* 02/29/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 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).
* When rolling on the hour-in-day or Calendar::HOUR_OF_DAY field, it will roll the
* hour value in the range between 0 and 23, which is zero-based.
* <P>
* NOTE: Do not use this method -- use roll(EDateFields, int, UErrorCode&) instead.
*
@ -593,10 +608,19 @@ public:
* value returned by getMaximum(Calendar::YEAR). When rolling on the month or
* Calendar::MONTH field, other fields like date might conflict and, need to be
* changed. For instance, rolling the month up on the date 01/31/96 will result in
* 02/29/96. Rolling up always means rolling forward in time; e.g., rolling the year
* up on "100 BC" will result in "99 BC", for Gregorian calendar. When rolling on the
* hour-in-day or Calendar::HOUR_OF_DAY field, it will roll the hour value in the range
* between 0 and 23, which is zero-based.
* 02/29/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 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).
* When rolling on the hour-in-day or Calendar::HOUR_OF_DAY field, it will roll the
* hour value in the range between 0 and 23, which is zero-based.
* <P>
* NOTE: Do not use this method -- use roll(UCalendarDateFields, int, UErrorCode&) instead.
*
@ -616,10 +640,19 @@ public:
* roll(Calendar::DATE, +1, status). When rolling on the month or
* Calendar::MONTH field, other fields like date might conflict and, need to be
* changed. For instance, rolling the month up on the date 01/31/96 will result in
* 02/29/96. Rolling by a positive value always means rolling forward in time;
* e.g., rolling the year by +1 on "100 BC" will result in "99 BC", for Gregorian
* calendar. When rolling on the hour-in-day or Calendar::HOUR_OF_DAY field, it will
* roll the hour value in the range between 0 and 23, which is zero-based.
* 02/29/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
* 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).
* When rolling on the hour-in-day or Calendar::HOUR_OF_DAY field, it will roll the
* hour value in the range between 0 and 23, which is zero-based.
* <P>
* The only difference between roll() and add() is that roll() does not change
* the value of more significant fields when it reaches the minimum or maximum
@ -640,10 +673,19 @@ public:
* roll(Calendar::DATE, +1, status). When rolling on the month or
* Calendar::MONTH field, other fields like date might conflict and, need to be
* changed. For instance, rolling the month up on the date 01/31/96 will result in
* 02/29/96. Rolling by a positive value always means rolling forward in time;
* e.g., rolling the year by +1 on "100 BC" will result in "99 BC", for Gregorian
* calendar. When rolling on the hour-in-day or Calendar::HOUR_OF_DAY field, it will
* roll the hour value in the range between 0 and 23, which is zero-based.
* 02/29/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
* 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).
* When rolling on the hour-in-day or Calendar::HOUR_OF_DAY field, it will roll the
* hour value in the range between 0 and 23, which is zero-based.
* <P>
* The only difference between roll() and add() is that roll() does not change
* the value of more significant fields when it reaches the minimum or maximum

12
icu4c/source/i18n/unicode/ucal.h
View file

@ -1064,6 +1064,9 @@ ucal_equivalentTo(const UCalendar* cal1,
/**
* Add a specified signed amount to a particular field in a UCalendar.
* This can modify more significant fields in the calendar.
* Adding a positive value always means moving forward in time, so for the Gregorian calendar,
* starting with 100 BC and adding +1 to year results in 99 BC (even though this actually reduces
* the numeric value of the field itself).
* @param cal The UCalendar to which to add.
* @param field The field to which to add the signed value; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
* UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
@ -1085,6 +1088,15 @@ ucal_add(UCalendar* cal,
/**
* Add a specified signed amount to a particular field in a UCalendar.
* This will not modify more significant fields in the calendar.
* Rolling by a positive value always means moving forward in time (unless the limit of the
* field is reached, in which case it may pin or wrap), so for 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).
* @param cal The UCalendar to which to add.
* @param field The field to which to add the signed value; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
* UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,