ChineseCalendar is a concrete subclass of Calendar
that implements a traditional Chinese calendar. The traditional Chinese
calendar is a lunisolar calendar: Each month starts on a new moon, and
the months are numbered according to solar events, specifically, to
guarantee that month 11 always contains the winter solstice. In order
to accomplish this, leap months are inserted in certain years. Leap
months are numbered the same as the month they follow. The decision of
which month is a leap month depends on the relative movements of the sun
and moon.
All astronomical computations are performed with respect to a time zone of GMT+8:00 and a longitude of 120 degrees east. Although some calendars implement a historically more accurate convention of using Beijing's local longitude (116 degrees 25 minutes east) and time zone (GMT+7:45:40) for dates before 1929, we do not implement this here.
Years are counted in two different ways in the Chinese calendar. The
first method is by sequential numbering from the 61st year of the reign
of Huang Di, 2637 BCE, which is designated year 1 on the Chinese
calendar. The second method uses 60-year cycles from the same starting
point, which is designated year 1 of cycle 1. In this class, the
EXTENDED_YEAR field contains the sequential year count.
The ERA field contains the cycle number, and the
YEAR field contains the year of the cycle, a value between
1 and 60.
There is some variation in what is considered the starting point of the calendar, with some sources starting in the first year of the reign of Huang Di, rather than the 61st. This gives continuous year numbers 60 years greater and cycle numbers one greater than what this class implements.
Because ChineseCalendar defines an additional field and
redefines the way the ERA field is used, it requires a new
format class, ChineseDateFormat. As always, use the
methods DateFormat.getXxxInstance(Calendar cal,...) to
obtain a formatter for this calendar.
References:
This class should not be subclassed.
ChineseCalendar usually should be instantiated using
com. passing in a ULocale
with the tag "@calendar=chinese".
com.ibm.icu.util.Calendar
| Modifier and Type | Field and Description |
|---|---|
| private transient CalendarAstronomer | astro
We have one instance per object, and we don't synchronize it because Calendar doesn't support multithreaded execution in the first place. |
| private static final TimeZone | CHINA_ZONE
The time zone used for performing astronomical computations. |
| pack-priv static final int[][][] | CHINESE_DATE_PRECEDENCE
Field resolution table that incorporates IS_LEAP_MONTH. |
| private static final int | CHINESE_EPOCH_YEAR
The start year of the Chinese calendar, the 61st year of the reign of Huang Di. |
| private int | epochYear
The start year of this Chinese calendar instance. |
| private static String[] | |
| private transient boolean | hasLeapMonthBetweenWinterSolstices
True if there is a leap month between the Winter Solstice before and after the current date.This is different from leap year because in some year, such as 1813 and 2033, the leap month is after the Winter Solstice of that year. |
| private static final int[][] | LIMITS
Array defining the limits of field values for this class.
|
| private transient CalendarCache | newYearCache
Cache that maps Gregorian year to local days of Chinese new year. |
| private static final long | |
| private static final int | SYNODIC_GAP
Value to be added or subtracted from the local days of a new moon to get close to the next or prior new moon, but not cross it. |
| private transient CalendarCache | winterSolsticeCache
Cache that maps Gregorian year to local days of winter solstice. |
| private TimeZone | zoneAstro
The zone used for the astronomical calculation of this Chinese calendar instance. |
| Access | Constructor and Description |
|---|---|
| public | |
| public | ChineseCalendar(Date
The date to which the new calendar is set. date)Construct a |
| public | ChineseCalendar(int
The value used to set the calendar's year, int YEAR time field.The value used to set the calendar's month, int MONTH time field.
The value is 0-based. e.g., 0 for January.The value used to set the Chinese calendar's isLeapMonth, int IS_LEAP_MONTH
time field.The value used to set the calendar's date)DATE time field.Constructs a |
| public | ChineseCalendar(int
the value used to set the year, int YEAR time field in the calendar.the value used to set the month, int MONTH time field in the calendar.
Note that the month value is 0-based. e.g., 0 for January.the value used to set the isLeapMonth, int IS_LEAP_MONTH time field
in the calendar.the value used to set the date, int DATE time field in the calendar.the value used to set the hour, int HOUR_OF_DAY time field
in the calendar.the value used to set the minute, int MINUTE time field
in the calendar.the value used to set the second)SECOND time field
in the calendar.Constructs a |
| public | ChineseCalendar(int
The value used to set the calendar's era, int ERA time field.The value used to set the calendar's year, int YEAR time field.The value used to set the calendar's month, int MONTH time field.
The value is 0-based. e.g., 0 for January.The value used to set the Chinese calendar's isLeapMonth, int IS_LEAP_MONTH
time field.The value used to set the calendar's date)DATE time field.Constructs a |
| public | ChineseCalendar(int
the value used to set the calendar's era, int ERA time field.the value used to set the year, int YEAR time field in the calendar.the value used to set the month, int MONTH time field in the calendar.
Note that the month value is 0-based. e.g., 0 for January.the value used to set the isLeapMonth, int IS_LEAP_MONTH time field
in the calendar.the value used to set the date, int DATE time field in the calendar.the value used to set the hour, int HOUR_OF_DAY time field
in the calendar.the value used to set the minute, int MINUTE time field
in the calendar.the value used to set the second)SECOND time field
in the calendar.Constructs a |
| public | ChineseCalendar(Locale
The given locale aLocale)Constructs a |
| public | ChineseCalendar(TimeZone
the given time zone zone)Construct a |
| public | ChineseCalendar(TimeZone
the given time zone zone, Locale the given locale aLocale)Construct a |
| public | ChineseCalendar(ULocale
the given ulocale locale)Constructs a |
| public | ChineseCalendar(TimeZone
the given time zone zone, ULocale the given ulocale locale)Construct a |
| protected | ChineseCalendar(TimeZone zone, ULocale locale, int epochYear, TimeZone zoneAstroCalc)
Deprecated
This API is ICU internal only.
Construct a ChineseCalenar based on the current time
with the given time zone, the locale, the epoch year and the time zone
used for astronomical calculation.
|
| Modifier and Type | Method and Description |
|---|---|
| public void | add(int
the time field. field, int the amount to add to the field. amount)Overrides com. |
| private void | computeChineseFields(int
days after January 1, 1970 0:00 astronomical base zone of the
date to compute fields for days, int the Gregorian year of the given date gyear, int the Gregorian month of the given date gmonth, boolean if true, set the EXTENDED_YEAR, ERA, YEAR,
DAY_OF_MONTH, and DAY_OF_YEAR fields. In either case set the MONTH
and IS_LEAP_MONTH fields. setAllFields)Compute fields for the Chinese calendar system. |
| private final long | Returns: milliseconds after January 1, 1970 0:00 GMTdays after January 1, 1970 0:00 in the astronomical base zone days)Convert local days to UTC epoch milliseconds. |
| protected int[][][] | getFieldResolutionTable()
Overrides com. |
| public String | Returns: One of 24 possible strings in {"M01".."M12", "M01L".."M12L"}. |
| public String | |
| protected void | handleComputeFields(int julianDay)
Override Calendar to compute several fields specific to the Chinese
calendar system.
|
| protected int | Returns: the Julian day number of the day before the first day of the given month and yearthe extended year eyear, int the zero-based month. The month is also determined
by reading the IS_LEAP_MONTH field. month, boolean if false, compute the day before the first day of
the given year, otherwise, compute the day before the first day of
the given month useMonth)Implements abstract com. |
| protected DateFormat | handleGetDateFormat(String
the pattern, specific to the pattern, String override, ULocale DateFormat
subclassthe locale for which the symbols should be drawn locale)Overrides com. DateFormat appropriate to this calendar.
|
| protected int | handleGetExtendedYear()
Implements abstract com. |
| protected int | handleGetLimit(int
one of the above field numbers field, int one of limitType)MINIMUM, GREATEST_MINIMUM,
LEAST_MAXIMUM, or MAXIMUMImplements abstract com. |
| protected int | handleGetMonthLength(int extendedYear, int month)
Override Calendar method to return the number of days in the given
extended year and month.
|
| private boolean | hasNoMajorSolarTerm(int
days after January 1, 1970 0:00 Asia/Shanghai of a new
moon newMoon)Return true if the given month lacks a major solar term. |
| public boolean | haveDefaultCentury()
Overrides com.
Deprecated
This API is ICU internal only.
Returns if two digit representation of year in this calendar type
customarily implies a default century (i.e. 03 -> 2003).
|
| public boolean | Returns: true if the date in the fields is in a Temporal proposal defined leap year. False otherwise.Overrides com. ICU |
| protected int | internalGetMonth()
Overrides com.
Deprecated
This API is ICU internal only.
Use this function instead of internalGet(MONTH).
|
| protected int | internalGetMonth(int
a default value used if the MONTH and
ORDINAL_MONTH are both unset. defaultValue)Overrides com.
Deprecated
This API is ICU internal only.
Use this function instead of internalGet(MONTH, defaultValue).
|
| private boolean | isLeapMonthBetween(int
days after January 1, 1970 0:00 astronomical base zone of a
new moon newMoon1, int days after January 1, 1970 0:00 astronomical base zone of a
new moon newMoon2)Return true if there is a leap month on or after month newMoon1 and at or before month newMoon2. |
| private int | majorSolarTerm(int
days after January 1, 1970 0:00 Asia/Shanghai days)Return the major solar term on or before a given date. |
| private final int | Returns: days days after January 1, 1970 0:00 in the astronomical base zonemilliseconds after January 1, 1970 0:00 GMT millis)Convert UTC epoch milliseconds to local days. |
| private int | Returns: days after January 1, 1970 0:00 Asia/Shanghai of the nearest new moon after or beforedaysdays after January 1, 1970 0:00 Asia/Shanghai days, boolean if true, search for a new moon on or after the given
date; otherwise, search for a new moon before it after)Return the closest new moon to the given date, searching either forward or backward in time. |
| private int | Returns: days after January 1, 1970 0:00 astronomical base zone of the Chinese new year of the given year (this will be a new moon)a Gregorian year gyear)Return the Chinese new year of the given Gregorian year. |
| private void | offsetMonth(int
the local days of the first day of the month of the
start position (days after January 1, 1970 0:00 Asia/Shanghai) newMoon, int the 1-based day-of-month of the start position dom, int the number of months to move forward or backward from
the start position delta)Adjust this calendar to be delta months before or after a given start position, pinning the day of month if necessary. |
| private void | readObject(ObjectInputStream stream)
Override readObject.
|
| public void | roll(int
the calendar field to roll. field, int the amount by which the field should be rolled. amount)Overrides com. |
| public void | setTemporalMonthCode(String
One of 25 possible strings in {"M01".. "M12", "M13", "M01L",
"M12L"}. temporalMonth)
Sets The Temporal monthCode which is a string identifier that starts
with the literal grapheme "M" followed by two graphemes representing
the zero-padded month number of the current month in a normal
(non-leap) year and suffixed by an optional literal grapheme "L" if this
is a leap month in a lunisolar calendar.
|
| private int | Returns: the nearest integer number of months between day1 and day2days after January 1, 1970 0:00 Asia/Shanghai day1, int days after January 1, 1970 0:00 Asia/Shanghai day2)Return the nearest integer number of synodic months between two dates. |
| private int | Returns: days after January 1, 1970 0:00 Asia/Shanghai of the winter solstice of the given yeara Gregorian year gyear)Return the major solar term on or after December 15 of the given Gregorian year, that is, the winter solstice of the given year. |
| astro | back to summary |
|---|---|
| private transient CalendarAstronomer astro We have one instance per object, and we don't synchronize it because Calendar doesn't support multithreaded execution in the first place. | |
| CHINA_ZONE | back to summary |
|---|---|
| private static final TimeZone CHINA_ZONE The time zone used for performing astronomical computations. Some sources use a different historically accurate offset of GMT+7:45:40 for years before 1929; we do not do this. | |
| CHINESE_DATE_PRECEDENCE | back to summary |
|---|---|
| pack-priv static final int[][][] CHINESE_DATE_PRECEDENCE Field resolution table that incorporates IS_LEAP_MONTH. | |
| CHINESE_EPOCH_YEAR | back to summary |
|---|---|
| private static final int CHINESE_EPOCH_YEAR The start year of the Chinese calendar, the 61st year of the reign of Huang Di. Some sources use the first year of his reign, resulting in EXTENDED_YEAR values 60 years greater and ERA (cycle) values one greater. | |
| epochYear | back to summary |
|---|---|
| private int epochYear The start year of this Chinese calendar instance. | |
| gTemporalLeapMonthCodes | back to summary |
|---|---|
| private static String[] gTemporalLeapMonthCodes | |
| hasLeapMonthBetweenWinterSolstices | back to summary |
|---|---|
| private transient boolean hasLeapMonthBetweenWinterSolstices True if there is a leap month between the Winter Solstice before and after the current date.This is different from leap year because in some year, such as 1813 and 2033, the leap month is after the Winter Solstice of that year. So this value could be false for a date prior to the Winter Solstice of that year but that year still has a leap month and therefor is a leap year.
| |
| LIMITS | back to summary |
|---|---|
| private static final int[][] LIMITS Hides com. Array defining the limits of field values for this class. Field limits which are invariant with respect to calendar system and defined by Calendar are left blank. Notes ERA 5000000 / 60 = 83333. MONTH There are 12 or 13 lunar months in a year. However, we always number them 0..11, with an intercalated, identically numbered leap month, when necessary. DAY_OF_YEAR In a non-leap year there are 353, 354, or 355 days. In a leap year there are 383, 384, or 385 days. WEEK_OF_YEAR The least maximum occurs if there are 353 days in the year, and the first 6 are the last week of the previous year. Then we have 49 full weeks and 4 days in the last week: 6 + 49*7 + 4 = 353. So the least maximum is 50. The maximum occurs if there are 385 days in the year, and WOY 1 extends 6 days into the prior year. Then there are 54 full weeks, and 6 days in the last week: 1 + 54*7 + 6 = 385. The 6 days of the last week will fall into WOY 1 of the next year. Maximum is 55. WEEK_OF_MONTH In a 29 day month, if the first 7 days make up week 1 that leaves 3 full weeks and 1 day at the end. The least maximum is thus 5. In a 30 days month, if the previous 6 days belong WOM 1 of this month, we have 4 full weeks and 1 days at the end (which technically will be WOM 1 of the next month, but will be reported by time->fields and hence by getActualMaximum as WOM 6 of this month). Maximum is 6. DAY_OF_WEEK_IN_MONTH In a 29 or 30 day month, there are 4 full weeks plus 1 or 2 days at the end, so the maximum is always 5. | |
| newYearCache | back to summary |
|---|---|
| private transient CalendarCache newYearCache Cache that maps Gregorian year to local days of Chinese new year.
| |
| serialVersionUID | back to summary |
|---|---|
| private static final long serialVersionUID | |
| SYNODIC_GAP | back to summary |
|---|---|
| private static final int SYNODIC_GAP Value to be added or subtracted from the local days of a new moon to get close to the next or prior new moon, but not cross it. Must be >= 1 and < CalendarAstronomer.SYNODIC_MONTH. | |
| winterSolsticeCache | back to summary |
|---|---|
| private transient CalendarCache winterSolsticeCache Cache that maps Gregorian year to local days of winter solstice.
| |
| zoneAstro | back to summary |
|---|---|
| private TimeZone zoneAstro The zone used for the astronomical calculation of this Chinese calendar instance. | |
| ChineseCalendar | back to summary |
|---|---|
| public ChineseCalendar() Construct a
| |
| ChineseCalendar | back to summary |
|---|---|
| public ChineseCalendar(Date date) Construct a | |
| ChineseCalendar | back to summary |
|---|---|
| public ChineseCalendar(int year, int month, int isLeapMonth, int date) Constructs a
| |
| ChineseCalendar | back to summary |
|---|---|
| public ChineseCalendar(int year, int month, int isLeapMonth, int date, int hour, int minute, int second) Constructs a
| |
| ChineseCalendar | back to summary |
|---|---|
| public ChineseCalendar(int era, int year, int month, int isLeapMonth, int date) Constructs a
| |
| ChineseCalendar | back to summary |
|---|---|
| public ChineseCalendar(int era, int year, int month, int isLeapMonth, int date, int hour, int minute, int second) Constructs a
| |
| ChineseCalendar | back to summary |
|---|---|
| public ChineseCalendar(Locale aLocale) Constructs a | |
| ChineseCalendar | back to summary |
|---|---|
| public ChineseCalendar(TimeZone zone) Construct a
| |
| ChineseCalendar | back to summary |
|---|---|
| public ChineseCalendar(TimeZone zone, Locale aLocale) Construct a | |
| ChineseCalendar | back to summary |
|---|---|
| public ChineseCalendar(ULocale locale) Constructs a | |
| ChineseCalendar | back to summary |
|---|---|
| public ChineseCalendar(TimeZone zone, ULocale locale) Construct a | |
| ChineseCalendar | back to summary |
|---|---|
| protected ChineseCalendar(TimeZone zone, ULocale locale, int epochYear, TimeZone zoneAstroCalc)
Deprecated This API is ICU internal only. Construct a
| |
| add | back to summary |
|---|---|
| public void add(int field, int amount) Overrides com. Override Calendar to handle leap months properly.
| |
| computeChineseFields | back to summary |
|---|---|
| private void computeChineseFields(int days, int gyear, int gmonth, boolean setAllFields) Compute fields for the Chinese calendar system. This method can
either set all relevant fields, as required by
As a side effect, this method sets
| |
| daysToMillis | back to summary |
|---|---|
| private final long daysToMillis(int days) Convert local days to UTC epoch milliseconds. This is not an accurate conversion in terms that getTimezoneOffset takes the milliseconds in GMT (not local time). In theory, more accurate algorithm can be implemented but practically we do not need to go through that complication as long as the historically timezone changes did not happen around the 'tricky' new moon (new moon around the midnight).
| |
| getFieldResolutionTable | back to summary |
|---|---|
| protected int[][][] getFieldResolutionTable() Overrides com. Override Calendar to add IS_LEAP_MONTH to the field resolution table.
| |
| getTemporalMonthCode | back to summary |
|---|---|
| public String getTemporalMonthCode() Overrides com. Gets The Temporal monthCode value corresponding to the month for the date. The value is a string identifier that starts with the literal grapheme "M" followed by two graphemes representing the zero-padded month number of the current month in a normal (non-leap) year and suffixed by an optional literal grapheme "L" if this is a leap month in a lunisolar calendar. For the Chinese calendar, the values are "M01" .. "M12" for non-leap year and * in leap year with another monthCode in "M01L" .. "M12L". | |
| getType | back to summary |
|---|---|
| public String getType() Overrides com. Doc from com. ICU See type="old type name" for the calendar attribute of locale IDs at http://www.unicode.org/reports/tr35/#Key_Type_Definitions | |
| handleComputeFields | back to summary |
|---|---|
| protected void handleComputeFields(int julianDay) Overrides com. Override Calendar to compute several fields specific to the Chinese calendar system. These are:
Compute the ChineseCalendar-specific field IS_LEAP_MONTH.
| |
| handleComputeMonthStart | back to summary |
|---|---|
| protected int handleComputeMonthStart(int eyear, int month, boolean useMonth) Implements abstract com. Return the Julian day number of day before the first day of the given month in the given extended year. Note This method reads the IS_LEAP_MONTH field to determine whether the given month is a leap month.
| |
| handleGetDateFormat | back to summary |
|---|---|
| protected DateFormat handleGetDateFormat(String pattern, String override, ULocale locale) Overrides com. Doc from com. Creates a
| |
| handleGetExtendedYear | back to summary |
|---|---|
| protected int handleGetExtendedYear() Implements abstract com. Implement abstract Calendar method to return the extended year defined by the current fields. This will use either the ERA and YEAR field as the cycle and year-of-cycle, or the EXTENDED_YEAR field as the continuous year count, depending on which is newer.
| |
| handleGetLimit | back to summary |
|---|---|
| protected int handleGetLimit(int field, int limitType) Implements abstract com. Override Calendar to return the limit value for the given field.
| |
| handleGetMonthLength | back to summary |
|---|---|
| protected int handleGetMonthLength(int extendedYear, int month) Overrides com. Override Calendar method to return the number of days in the given extended year and month. Note This method also reads the IS_LEAP_MONTH field to determine whether or not the given month is a leap month.
| |
| hasNoMajorSolarTerm | back to summary |
|---|---|
| private boolean hasNoMajorSolarTerm(int newMoon) Return true if the given month lacks a major solar term.
| |
| haveDefaultCentury | back to summary |
|---|---|
| public boolean haveDefaultCentury() Overrides com. Doc from com. Deprecated This API is ICU internal only. Returns if two digit representation of year in this calendar type
customarily implies a default century (i.e. 03 -> 2003).
The default implementation returns
| |
| inTemporalLeapYear | back to summary |
|---|---|
| public boolean inTemporalLeapYear() Overrides com. ICU
| |
| internalGetMonth | back to summary |
|---|---|
| protected int internalGetMonth() Overrides com. Doc from com. Deprecated This API is ICU internal only. Use this function instead of internalGet(MONTH). The implementation check the timestamp of MONTH and ORDINAL_MONTH and use the one set later. The subclass should override it to conver the value of ORDINAL_MONTH to MONTH correctly if ORDINAL_MONTH has higher priority.
| |
| internalGetMonth | back to summary |
|---|---|
| protected int internalGetMonth(int defaultValue) Overrides com. Doc from com. Deprecated This API is ICU internal only. Use this function instead of internalGet(MONTH, defaultValue). The implementation check the timestamp of MONTH and ORDINAL_MONTH and use the one set later. The subclass should override it to conver the value of ORDINAL_MONTH to MONTH correctly if ORDINAL_MONTH has higher priority.
| |
| isLeapMonthBetween | back to summary |
|---|---|
| private boolean isLeapMonthBetween(int newMoon1, int newMoon2) Return true if there is a leap month on or after month newMoon1 and at or before month newMoon2.
| |
| majorSolarTerm | back to summary |
|---|---|
| private int majorSolarTerm(int days) Return the major solar term on or before a given date. This will be an integer from 1..12, with 1 corresponding to 330 degrees, 2 to 0 degrees, 3 to 30 degrees,..., and 12 to 300 degrees.
| |
| millisToDays | back to summary |
|---|---|
| private final int millisToDays(long millis) Convert UTC epoch milliseconds to local days.
| |
| newMoonNear | back to summary |
|---|---|
| private int newMoonNear(int days, boolean after) Return the closest new moon to the given date, searching either forward or backward in time.
| |
| newYear | back to summary |
|---|---|
| private int newYear(int gyear) Return the Chinese new year of the given Gregorian year.
| |
| offsetMonth | back to summary |
|---|---|
| private void offsetMonth(int newMoon, int dom, int delta) Adjust this calendar to be delta months before or after a given start position, pinning the day of month if necessary. The start position is given as a local days number for the start of the month and a day-of-month. Used by add() and roll().
| |
| readObject | back to summary |
|---|---|
| private void readObject(ObjectInputStream stream) throws IOException, ClassNotFoundException Hides com. Override readObject. | |
| roll | back to summary |
|---|---|
| public void roll(int field, int amount) Overrides com. Override Calendar to handle leap months properly.
| |
| setTemporalMonthCode | back to summary |
|---|---|
| public void setTemporalMonthCode(String temporalMonth) Overrides com. Sets The Temporal monthCode which is a string identifier that starts with the literal grapheme "M" followed by two graphemes representing the zero-padded month number of the current month in a normal (non-leap) year and suffixed by an optional literal grapheme "L" if this is a leap month in a lunisolar calendar. For the Chinese calendar, the values are "M01" .. "M12" for non-leap year and in leap year with another monthCode in "M01L" .. "M12L". | |
| synodicMonthsBetween | back to summary |
|---|---|
| private int synodicMonthsBetween(int day1, int day2) Return the nearest integer number of synodic months between two dates.
| |
| winterSolstice | back to summary |
|---|---|
| private int winterSolstice(int gyear) Return the major solar term on or after December 15 of the given Gregorian year, that is, the winter solstice of the given year. Computations are relative to Asia/Shanghai time zone.
| |