Added in API level 24

ChineseCalendar


open class ChineseCalendar : Calendar
kotlin.Any
   ↳ android.icu.util.Calendar
   ↳ android.icu.util.ChineseCalendar

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 android.icu.util.Calendar#getInstance(ULocale) passing in a ULocale with the tag "@calendar=chinese".

Summary

Inherited constants
Public constructors

Construct a ChineseCalendar with the default time zone and locale.

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

ChineseCalendar(year: Int, month: Int, isLeapMonth: Int, date: Int)

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

ChineseCalendar(year: Int, month: Int, isLeapMonth: Int, date: Int, hour: Int, minute: Int, second: Int)

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

ChineseCalendar(era: Int, year: Int, month: Int, isLeapMonth: Int, date: Int)

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

ChineseCalendar(era: Int, year: Int, month: Int, isLeapMonth: Int, date: Int, hour: Int, minute: Int, second: Int)

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

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

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

ChineseCalendar(zone: TimeZone!, aLocale: Locale!)

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

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

ChineseCalendar(zone: TimeZone!, locale: ULocale!)

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

Public methods
open Unit
add(field: Int, amount: Int)

Override Calendar to handle leap months properly.

open String!

[icu] Returns the calendar type name string for this Calendar object.

open Unit
roll(field: Int, amount: Int)

Override Calendar to handle leap months properly.

Protected methods
open Array<Array<IntArray!>!>!

Override Calendar to add IS_LEAP_MONTH to the field resolution table.

open Unit

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

open Int
handleComputeMonthStart(eyear: Int, month: Int, useMonth: Boolean)

Return the Julian day number of day before the first day of the given month in the given extended year.

open DateFormat!
handleGetDateFormat(pattern: String!, override: String!, locale: ULocale!)

open Int

Implement abstract Calendar method to return the extended year defined by the current fields.

open Int
handleGetLimit(field: Int, limitType: Int)

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

open Int
handleGetMonthLength(extendedYear: Int, month: Int)

Override Calendar method to return the number of days in the given extended year and month.

Inherited functions
Inherited properties

Public constructors

ChineseCalendar

Added in API level 24
ChineseCalendar()

Construct a ChineseCalendar with the default time zone and locale.

ChineseCalendar

Added in API level 24
ChineseCalendar(date: Date!)

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

Parameters
date Date!: The date to which the new calendar is set.

ChineseCalendar

Added in API level 24
ChineseCalendar(
    year: Int,
    month: Int,
    isLeapMonth: Int,
    date: Int)

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

Parameters
year Int: The value used to set the calendar's YEAR time field.
month Int: The value used to set the calendar's MONTH time field. The value is 0-based. e.g., 0 for January.
isLeapMonth Int: The value used to set the Chinese calendar's IS_LEAP_MONTH time field.
date Int: The value used to set the calendar's DATE time field.

ChineseCalendar

Added in API level 24
ChineseCalendar(
    year: Int,
    month: Int,
    isLeapMonth: Int,
    date: Int,
    hour: Int,
    minute: Int,
    second: Int)

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

Parameters
year Int: the value used to set the YEAR time field in the calendar.
month Int: 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 Int: the value used to set the IS_LEAP_MONTH time field in the calendar.
date Int: the value used to set the DATE time field in the calendar.
hour Int: the value used to set the HOUR_OF_DAY time field in the calendar.
minute Int: the value used to set the MINUTE time field in the calendar.
second Int: the value used to set the SECOND time field in the calendar.

ChineseCalendar

Added in API level 24
ChineseCalendar(
    era: Int,
    year: Int,
    month: Int,
    isLeapMonth: Int,
    date: Int)

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

Parameters
era Int: The value used to set the calendar's ERA time field.
year Int: The value used to set the calendar's YEAR time field.
month Int: The value used to set the calendar's MONTH time field. The value is 0-based. e.g., 0 for January.
isLeapMonth Int: The value used to set the Chinese calendar's IS_LEAP_MONTH time field.
date Int: The value used to set the calendar's DATE time field.

ChineseCalendar

Added in API level 24
ChineseCalendar(
    era: Int,
    year: Int,
    month: Int,
    isLeapMonth: Int,
    date: Int,
    hour: Int,
    minute: Int,
    second: Int)

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

Parameters
era Int: the value used to set the calendar's ERA time field.
year Int: the value used to set the YEAR time field in the calendar.
month Int: 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 Int: the value used to set the IS_LEAP_MONTH time field in the calendar.
date Int: the value used to set the DATE time field in the calendar.
hour Int: the value used to set the HOUR_OF_DAY time field in the calendar.
minute Int: the value used to set the MINUTE time field in the calendar.
second Int: the value used to set the SECOND time field in the calendar.

ChineseCalendar

Added in API level 24
ChineseCalendar(aLocale: Locale!)

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

Parameters
aLocale Locale!: The given locale

ChineseCalendar

Added in API level 24
ChineseCalendar(zone: TimeZone!)

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

Parameters
zone TimeZone!: the given time zone

ChineseCalendar

Added in API level 24
ChineseCalendar(
    zone: TimeZone!,
    aLocale: Locale!)

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

Parameters
zone TimeZone!: the given time zone
aLocale Locale!: the given locale

ChineseCalendar

Added in API level 24
ChineseCalendar(locale: ULocale!)

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

Parameters
locale ULocale!: the given ulocale

ChineseCalendar

Added in API level 24
ChineseCalendar(
    zone: TimeZone!,
    locale: ULocale!)

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

Parameters
zone TimeZone!: the given time zone
locale ULocale!: the given ulocale

Public methods

add

Added in API level 24
open fun add(
    field: Int,
    amount: Int
): Unit

Override Calendar to handle leap months properly.

Parameters
field Int: the time field.
amount Int: the amount to add to the field.

getType

Added in API level 24
open fun getType(): String!

[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

Return
String! legacy calendar type name string

roll

Added in API level 24
open fun roll(
    field: Int,
    amount: Int
): Unit

Override Calendar to handle leap months properly.

Parameters
field Int: the calendar field to roll.
amount Int: the amount by which the field should be rolled.

Protected methods

getFieldResolutionTable

Added in API level 24
protected open fun getFieldResolutionTable(): Array<Array<IntArray!>!>!

Override Calendar to add IS_LEAP_MONTH to the field resolution table.

handleComputeFields

Added in API level 24
protected open fun handleComputeFields(julianDay: Int): Unit

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.

handleComputeMonthStart

Added in API level 24
protected open fun handleComputeMonthStart(
    eyear: Int,
    month: Int,
    useMonth: Boolean
): Int

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.

Parameters
eyear Int: the extended year
month Int: the zero-based month. The month is also determined by reading the IS_LEAP_MONTH field.
useMonth 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
Return
Int the Julian day number of the day before the first day of the given month and year

handleGetDateFormat

Added in API level 24
protected open fun handleGetDateFormat(
    pattern: String!,
    override: String!,
    locale: ULocale!
): DateFormat!

handleGetExtendedYear

Added in API level 24
protected open fun handleGetExtendedYear(): Int

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.

Return
Int the extended year

handleGetLimit

Added in API level 24
protected open fun handleGetLimit(
    field: Int,
    limitType: Int
): Int

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

Parameters
field Int: one of the above field numbers
limitType Int: one of MINIMUM, GREATEST_MINIMUM, LEAST_MAXIMUM, or MAXIMUM

handleGetMonthLength

Added in API level 24
protected open fun handleGetMonthLength(
    extendedYear: Int,
    month: Int
): Int

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.