com.ibm.icu.util

Class ChineseCalendar

java.lang.Object

com.ibm.icu.util.Calendar

com.ibm.icu.util.ChineseCalendar

All Implemented Interfaces:

Serializable, Cloneable, Comparable<Calendar>

Direct Known Subclasses:

DangiCalendar

public class ChineseCalendar
extends Calendar

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:

• Dershowitz and Reingold, Calendrical Calculations, Cambridge University Press, 1997
• The Calendar FAQ

This class should not be subclassed.

ChineseCalendar usually should be instantiated using Calendar.getInstance(ULocale) passing in a ULocale with the tag "@calendar=chinese".

Author:

Alan Liu

See Also:

Calendar, Serialized Form

Status:

Stable ICU 2.8.

Nested Class Summary

Nested classes/interfaces inherited from class com.ibm.icu.util.Calendar

Calendar.FormatConfiguration, Calendar.WeekData

Field Summary

Fields inherited from class com.ibm.icu.util.Calendar

AM, AM_PM, APRIL, AUGUST, BASE_FIELD_COUNT, DATE, DAY_OF_MONTH, DAY_OF_WEEK, DAY_OF_WEEK_IN_MONTH, DAY_OF_YEAR, DECEMBER, DOW_LOCAL, DST_OFFSET, EPOCH_JULIAN_DAY, ERA, EXTENDED_YEAR, FEBRUARY, FRIDAY, GREATEST_MINIMUM, HOUR, HOUR_OF_DAY, INTERNALLY_SET, IS_LEAP_MONTH, JAN_1_1_JULIAN_DAY, JANUARY, JULIAN_DAY, JULY, JUNE, LEAST_MAXIMUM, MARCH, MAX_DATE, MAX_FIELD_COUNT, MAX_JULIAN, MAX_MILLIS, MAXIMUM, MAY, MILLISECOND, MILLISECONDS_IN_DAY, MIN_DATE, MIN_JULIAN, MIN_MILLIS, MINIMUM, MINIMUM_USER_STAMP, MINUTE, MONDAY, MONTH, NOVEMBER, OCTOBER, ONE_DAY, ONE_HOUR, ONE_MINUTE, ONE_SECOND, ONE_WEEK, ORDINAL_MONTH, PM, RESOLVE_REMAP, SATURDAY, SECOND, SEPTEMBER, SUNDAY, THURSDAY, TUESDAY, UNDECIMBER, UNSET, WALLTIME_FIRST, WALLTIME_LAST, WALLTIME_NEXT_VALID, WEDNESDAY, WEEK_OF_MONTH, WEEK_OF_YEAR, WEEKDAY, WEEKEND, WEEKEND_CEASE, WEEKEND_ONSET, YEAR, YEAR_WOY, ZONE_OFFSET

Constructor Summary

Constructors

Modifier	Constructor and Description
	ChineseCalendar() Construct a ChineseCalendar with the default time zone and locale.
	ChineseCalendar(Date date) Construct a ChineseCalendar with the give date set in the default time zone with the default locale.
	ChineseCalendar(int year, int month, int isLeapMonth, int date) Constructs a ChineseCalendar with the given date set in the default time zone with the default FORMAT locale.
	ChineseCalendar(int era, int year, int month, int isLeapMonth, int date) Constructs a ChineseCalendar with the given date set in the default time zone with the default FORMAT locale.
	ChineseCalendar(int year, int month, int isLeapMonth, int date, int hour, int minute, int second) Constructs a ChineseCalendar with the given date and time set for the default time zone with the default FORMAT locale.
	ChineseCalendar(int era, int year, int month, int isLeapMonth, int date, int hour, int minute, int second) Constructs a ChineseCalendar with the given date and time set for the default time zone with the default FORMAT locale.
	ChineseCalendar(Locale aLocale) Constructs a ChineseCalendar based on the current time in the default time zone with the given locale.
	ChineseCalendar(TimeZone zone) Construct a ChineseCalendar based on the current time in the given time zone with the default FORMAT locale.
	ChineseCalendar(TimeZone zone, Locale aLocale) Construct a ChineseCalendar based on the current time in the given time zone with the given locale.
	ChineseCalendar(TimeZone zone, ULocale locale) Construct a ChineseCalendar based on the current time with the given time zone with the given locale.
protected	ChineseCalendar(TimeZone zone, ULocale locale, int epochYear, TimeZone zoneAstroCalc) Deprecated. This API is ICU internal only.
	ChineseCalendar(ULocale locale) Constructs a ChineseCalendar based on the current time in the default time zone with the given locale.

Method Summary

Modifier and Type	Method and Description
void	add(int field, int amount) Override Calendar to handle leap months properly.
protected int[][][]	getFieldResolutionTable() Override Calendar to add IS_LEAP_MONTH to the field resolution table.
String	getTemporalMonthCode() Gets The Temporal monthCode value corresponding to the month for the date.
String	getType() [icu] Returns the calendar type name string for this Calendar object.
protected void	handleComputeFields(int julianDay) Override Calendar to compute several fields specific to the Chinese calendar system.
protected int	handleComputeMonthStart(int eyear, int month, boolean useMonth) Return the Julian day number of day before the first day of the given month in the given extended year.
protected DateFormat	handleGetDateFormat(String pattern, String override, ULocale locale) Creates a DateFormat appropriate to this calendar.
protected int	handleGetExtendedYear() Implement abstract Calendar method to return the extended year defined by the current fields.
protected int	handleGetLimit(int field, int limitType) Override Calendar to return the limit value for the given field.
protected int	handleGetMonthLength(int extendedYear, int month) Override Calendar method to return the number of days in the given extended year and month.
boolean	haveDefaultCentury() Deprecated. This API is ICU internal only.
boolean	inTemporalLeapYear() [icu] Returns true if the date is in a leap year.
protected int	internalGetMonth() Deprecated. This API is ICU internal only.
protected int	internalGetMonth(int defaultValue) Deprecated. This API is ICU internal only.
void	roll(int field, int amount) Override Calendar to handle leap months properly.
void	setTemporalMonthCode(String 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.

Methods inherited from class com.ibm.icu.util.Calendar

after, before, clear, clear, clone, compareTo, complete, computeFields, computeGregorianFields, computeGregorianMonthStart, computeJulianDay, computeMillisInDay, computeMillisInDayLong, computeTime, computeZoneOffset, computeZoneOffset, equals, fieldDifference, fieldName, floorDivide, floorDivide, floorDivide, floorDivide, get, getActualMaximum, getActualMinimum, getAvailableLocales, getAvailableULocales, getDateAtTimePattern, getDateTimeFormat, getDateTimeFormat, getDateTimePattern, getDayOfWeekType, getDefaultDayInMonth, getDefaultMonthInYear, getDisplayName, getDisplayName, getFieldCount, getFirstDayOfWeek, getGreatestMinimum, getGregorianDayOfMonth, getGregorianDayOfYear, getGregorianMonth, getGregorianYear, getInstance, getInstance, getInstance, getInstance, getInstance, getInstance, getKeywordValuesForLocale, getLeastMaximum, getLimit, getLocale, getMaximum, getMinimalDaysInFirstWeek, getMinimum, getRelatedYear, getRepeatedWallTimeOption, getSkippedWallTimeOption, getStamp, getTime, getTimeInMillis, getTimeZone, getWeekData, getWeekDataForRegion, getWeekendTransition, gregorianMonthLength, gregorianPreviousMonthLength, handleComputeJulianDay, handleCreateFields, handleGetDateFormat, handleGetDateFormat, handleGetDateFormat, handleGetYearLength, hashCode, internalGet, internalGet, internalGetTimeInMillis, internalSet, isEquivalentTo, isEra0CountingBackward, isGregorianLeapYear, isLenient, isSet, isWeekend, isWeekend, julianDayToDayOfWeek, julianDayToMillis, millisToJulianDay, newerField, newestStamp, pinField, prepareGetActual, resolveFields, roll, set, set, set, set, setFirstDayOfWeek, setLenient, setMinimalDaysInFirstWeek, setRelatedYear, setRepeatedWallTimeOption, setSkippedWallTimeOption, setTime, setTimeInMillis, setTimeZone, setWeekData, toString, validateField, validateField, validateFields, weekNumber, weekNumber

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

ChineseCalendar

public ChineseCalendar()

Construct a ChineseCalendar with the default time zone and locale.

Status:

Stable ICU 2.8.

ChineseCalendar

public ChineseCalendar(Date date)

Construct a ChineseCalendar with the give date set in the default time zone with the default locale.

Parameters:

date - The date to which the new calendar is set.

Status:

Stable ICU 4.0.

ChineseCalendar

public ChineseCalendar(int year,
                       int month,
                       int isLeapMonth,
                       int date)

Constructs a ChineseCalendar with the given date set in the default time zone with the default FORMAT locale.

Parameters:

year - The value used to set the calendar's YEAR time field.

month - The value used to set the calendar's MONTH time field. The value is 0-based. e.g., 0 for January.

isLeapMonth - The value used to set the Chinese calendar's Calendar.IS_LEAP_MONTH time field.

date - The value used to set the calendar's DATE time field.

See Also:

ULocale.Category.FORMAT

Status:

Stable ICU 4.0.

ChineseCalendar

public ChineseCalendar(int year,
                       int month,
                       int isLeapMonth,
                       int date,
                       int hour,
                       int minute,
                       int second)

Constructs a ChineseCalendar with the given date and time set for the default time zone with the default FORMAT locale.

Parameters:

year - the value used to set the YEAR time field in the calendar.

month - the value used to set the MONTH time field in the calendar. Note that the month value is 0-based. e.g., 0 for January.

isLeapMonth - the value used to set the Calendar.IS_LEAP_MONTH time field in the calendar.

date - the value used to set the DATE time field in the calendar.

hour - the value used to set the HOUR_OF_DAY time field in the calendar.

minute - the value used to set the MINUTE time field in the calendar.

second - the value used to set the SECOND time field in the calendar.

See Also:

ULocale.Category.FORMAT

Status:

Stable ICU 4.0.

ChineseCalendar

public ChineseCalendar(int era,
                       int year,
                       int month,
                       int isLeapMonth,
                       int date)

Constructs a ChineseCalendar with the given date set in the default time zone with the default FORMAT locale.

Parameters:

era - The value used to set the calendar's ERA time field.

year - The value used to set the calendar's YEAR time field.

month - The value used to set the calendar's MONTH time field. The value is 0-based. e.g., 0 for January.

isLeapMonth - The value used to set the Chinese calendar's Calendar.IS_LEAP_MONTH time field.

date - The value used to set the calendar's DATE time field.

See Also:

ULocale.Category.FORMAT

Status:

Stable ICU 4.6.

ChineseCalendar

public ChineseCalendar(int era,
                       int year,
                       int month,
                       int isLeapMonth,
                       int date,
                       int hour,
                       int minute,
                       int second)

Constructs a ChineseCalendar with the given date and time set for the default time zone with the default FORMAT locale.

Parameters:

era - the value used to set the calendar's ERA time field.

year - the value used to set the YEAR time field in the calendar.

month - the value used to set the MONTH time field in the calendar. Note that the month value is 0-based. e.g., 0 for January.

isLeapMonth - the value used to set the Calendar.IS_LEAP_MONTH time field in the calendar.

date - the value used to set the DATE time field in the calendar.

hour - the value used to set the HOUR_OF_DAY time field in the calendar.

minute - the value used to set the MINUTE time field in the calendar.

second - the value used to set the SECOND time field in the calendar.

See Also:

ULocale.Category.FORMAT

Status:

Stable ICU 4.6.

ChineseCalendar

public ChineseCalendar(Locale aLocale)

Constructs a ChineseCalendar based on the current time in the default time zone with the given locale.

Parameters:

aLocale - The given locale

Status:

Stable ICU 4.0.

ChineseCalendar

public ChineseCalendar(TimeZone zone)

Construct a ChineseCalendar based on the current time in the given time zone with the default FORMAT locale.

Parameters:

zone - the given time zone

See Also:

ULocale.Category.FORMAT

Status:

Stable ICU 4.0.

ChineseCalendar

public ChineseCalendar(TimeZone zone,
                       Locale aLocale)

Construct a ChineseCalendar based on the current time in the given time zone with the given locale.

Parameters:

zone - the given time zone

aLocale - the given locale

Status:

Stable ICU 2.8.

ChineseCalendar

public ChineseCalendar(ULocale locale)

Constructs a ChineseCalendar based on the current time in the default time zone with the given locale.

Parameters:

locale - the given ulocale

Status:

Stable ICU 4.0.

ChineseCalendar

public ChineseCalendar(TimeZone zone,
                       ULocale locale)

Construct a ChineseCalendar based on the current time with the given time zone with the given locale.

Parameters:

zone - the given time zone

locale - the given ulocale

Status:

Stable ICU 3.2.

ChineseCalendar

@Deprecated
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.

Status:

Internal. This API is ICU internal only.

Method Detail

handleGetLimit

protected int handleGetLimit(int field,
                             int limitType)

Override Calendar to return the limit value for the given field.

Specified by:

handleGetLimit in class Calendar

Parameters:

field - one of the above field numbers

limitType - one of MINIMUM, GREATEST_MINIMUM, LEAST_MAXIMUM, or MAXIMUM

Status:

Stable ICU 2.8.

handleGetExtendedYear

protected int handleGetExtendedYear()

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.

Specified by:

handleGetExtendedYear in class Calendar

Returns:

the extended year

Status:

Stable ICU 2.8.

handleGetMonthLength

protected int handleGetMonthLength(int extendedYear,
                                   int month)

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.

Overrides:

handleGetMonthLength in class Calendar

Status:

Stable ICU 2.8.

handleGetDateFormat

protected DateFormat handleGetDateFormat(String pattern,
                                         String override,
                                         ULocale locale)

Creates a DateFormat appropriate to this calendar. This is a framework method for subclasses to override. This method is responsible for creating the calendar-specific DateFormat and DateFormatSymbols objects as needed.

Overrides:

handleGetDateFormat in class Calendar

Parameters:

pattern - the pattern, specific to the DateFormat subclass

locale - the locale for which the symbols should be drawn

Returns:

a DateFormat appropriate to this calendar

Status:

Stable ICU 4.2.

getFieldResolutionTable

protected int[][][] getFieldResolutionTable()

Override Calendar to add IS_LEAP_MONTH to the field resolution table.

Overrides:

getFieldResolutionTable in class Calendar

See Also:

Calendar.resolveFields(int[][][])

Status:

Stable ICU 2.8.

add

public void add(int field,
                int amount)

Override Calendar to handle leap months properly.

Overrides:

add in class Calendar

Parameters:

field - the time field.

amount - the amount to add to the field.

See Also:

Calendar.roll(int, int)

Status:

Stable ICU 2.8.

roll

public void roll(int field,
                 int amount)

Override Calendar to handle leap months properly.

Overrides:

roll in class Calendar

Parameters:

field - the calendar field to roll.

amount - the amount by which the field should be rolled.

See Also:

Calendar.roll(int, boolean), Calendar.add(int, int)

Status:

Stable ICU 2.8.

handleComputeFields

protected void handleComputeFields(int julianDay)

Override Calendar to compute several fields specific to the Chinese calendar system. These are:

• ERA
• YEAR
• MONTH
• DAY_OF_MONTH
• DAY_OF_YEAR
• EXTENDED_YEAR

The DAY_OF_WEEK and DOW_LOCAL fields are already set when this method is called. The getGregorianXxx() methods return Gregorian calendar equivalents for the given Julian day.

Compute the ChineseCalendar-specific field IS_LEAP_MONTH.

Overrides:

handleComputeFields in class Calendar

Status:

Stable ICU 2.8.

handleComputeMonthStart

protected int handleComputeMonthStart(int eyear,
                                      int month,
                                      boolean useMonth)

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.

Specified by:

handleComputeMonthStart in class Calendar

Parameters:

eyear - the extended year

month - the zero-based month. The month is also determined by reading the IS_LEAP_MONTH field.

useMonth - 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

Returns:

the Julian day number of the day before the first day of the given month and year

Status:

Stable ICU 2.8.

getType

public String getType()

[icu] Returns the calendar type name string for this Calendar object. The returned string is the legacy ICU calendar attribute value, for example, "gregorian" or "japanese".

See type="old type name" for the calendar attribute of locale IDs at http://www.unicode.org/reports/tr35/#Key_Type_Definitions

Overrides:

getType in class Calendar

Returns:

legacy calendar type name string

Status:

Stable ICU 3.8.

haveDefaultCentury

@Deprecated
public boolean haveDefaultCentury()

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 true. A subclass may return false if such practice is not applicable (for example, Chinese calendar and Japanese calendar).

Overrides:

haveDefaultCentury in class Calendar

Returns:

true if this calendar has a default century.

Status:

Internal. This API is ICU internal only.

inTemporalLeapYear

public boolean inTemporalLeapYear()

[icu] Returns true if the date is in a leap year. Recalculate the current time field values if the time value has been changed by a call to setTime(). This method is semantically const, but may alter the object in memory. A "leap year" is a year that contains more days than other years (for solar or lunar calendars) or more months than other years (for lunisolar calendars like Hebrew or Chinese), as defined in the ECMAScript Temporal proposal.

Overrides:

inTemporalLeapYear in class Calendar

Returns:

true if the date in the fields is in a Temporal proposal defined leap year. False otherwise.

Status:

Stable ICU 74.

getTemporalMonthCode

public String getTemporalMonthCode()

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".

Overrides:

getTemporalMonthCode in class Calendar

Returns:

One of 24 possible strings in {"M01".."M12", "M01L".."M12L"}.

Status:

Stable ICU 74.

setTemporalMonthCode

public void setTemporalMonthCode(String 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. For the Chinese calendar, the values are "M01" .. "M12" for non-leap year and in leap year with another monthCode in "M01L" .. "M12L".

Overrides:

setTemporalMonthCode in class Calendar

Parameters:

temporalMonth - One of 25 possible strings in {"M01".. "M12", "M13", "M01L", "M12L"}.

Status:

Stable ICU 74.

internalGetMonth

@Deprecated
protected int internalGetMonth()

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.

Overrides:

internalGetMonth in class Calendar

Returns:

the value for the given time field.

Status:

Internal. This API is ICU internal only.

internalGetMonth

@Deprecated
protected int internalGetMonth(int defaultValue)

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.

Overrides:

internalGetMonth in class Calendar

Parameters:

defaultValue - a default value used if the MONTH and ORDINAL_MONTH are both unset.

Returns:

the value for the MONTH.

Status:

Internal. This API is ICU internal only.