The Chinese Lunisolar Calendar

The header file defining the implementation of Chinese Lunisolar Calendar is kcalendarsystemchinese.h. It has defined two classes:

KCalendarSystemChinese

Class definition in the public domain, publicly inherited from KCalendarSystem. It re-implements the virtual functions defined in the KCalendarSystem class. The re-implemented functions are defined in the public domain of the class.

virtual QString calendarType() const

Returns the calendar system type.

virtual QDate epoch() const

Returns a QDate holding the epoch of the calendar system. Chinese epoch is defined on Julian Day 758326. (8th March 2637 BCE in Julian Calendar)

virtual QDate earliestValidDate() const

Returns the earliest date valid in this calendar system implementation, i.e. the epoch of the calendar system as the Chinese calendar is not proleptic

virtual QDate latestValidDate() const

Returns the latest date valid in this calendar system implementation, i.e. 30th December 9999 in Chinese Calendar (which becomes 5th February 7303 in Gregorian Calendar).

virtual bool isValid(int year, int month, int day) const

Returns whether a given date is valid in this calendar system.

virtual bool isValid(const QDate &date) const

Returns whether a given date is valid in this calendar system.

virtual bool isLeapYear(int year) const

Returns whether a given year is a leap year.

virtual bool isLeapYear(const QDate &date) const

Returns whether a given year(taken from the QDate) is a leap year.

virtual QString monthName(double month, int year, MonthNameFormat format = LongName) const

Gets specific calendar type month name for a given month number If an invalid month is specified, QString() is returned. The double data type is used for the month to implement functionalities requiring leap months in the Chinese calendar.

virtual QString monthName(const QDate &date, MonthNameFormat format = LongName) const

Gets specific calendar type month name for a given date.

virtual QString weekDayName(int weekDay, WeekDayNameFormat format = LongDayName) const

Gets specific calendar type week day name. If an invalid week day is specified, QString() is returned.

virtual QString weekDayName(const QDate &date, WeekDayNameFormat format = LongDayName) const

Gets specific calendar type week day name.

virtual int weekDayOfPray() const

Returns the weekday of pray for this calendar system, i.e. Sunday (7th day of the Chinese Week).

virtual bool isLunar() const

Returns whether the calendar is lunar. (False)

virtual bool isLunisolar() const

Returns whether the calendar is lunisolar. (True)

virtual bool isSolar() const

Returns whether the calendar is solar. (False)

virtual bool isProleptic() const

Returns whether the calendar is proleptic, i.e, supports dates before the epoch. (False)

KCalendarSystemChinesePrivate

Class definition in the private domain, publicy inherited from KCalendarSystemPrivate. It re-implements the virtual functions defined in the KCalendarSystem class. The re-implemented functions are defined in the public domain of the class.

virtual AstroLocale* chineseLocation(int date)

Defines the Chinese Locale(as explained in the previous section) for implementing the Chinese Calendar

double midnightInChina(int date)

Computes the Chinese Universal Time for implementing astronomical calculations

int currentMajorSolarTerm(int date)

Returns the major solar term number at the given date, after computing the solar longitude at the given date.

int winterSolsticeOnOrAfter(int date)

Returns the date of December Solstice on or after the given date.

int chineseNewMoonOnOrAfter(int date)

Returns the date when the New Moon is observed at the Chinese Locale on or after the given date.

int chineseNewMoonBefore(int date)

Returns the date when the New Moon is observed at the Chinese Locale before the given date.

bool noMajorSolarTerm(int date)

Checks whether the month containing the given date has a major solar term or not.

bool priorLeapMonth(int m1, int m2)

Checks whether there is a leap month from the date m1(inclusive) to date m2.

int newYearInSui(int date)

Returns the starting date of Chinese New Year after December Solstice.

int newYearOnOrBefore(int date)

Returns the date of Chinese New Year on or before the given date.

void chineseDateToJulianDay(int year, double month, bool leap, int day, int &jd)

Converts Chinese date to Julian day.

void julianDayToChineseDate(int &year, double &month, bool &leap, int &day, int jd)

Converts Julian day to Chinese date. An indicator value (o.5) is added to the month to denote that it is a leap month.

virtual KLocale::CalendarSystem calendarSystem() const

Returns the calendar type.

virtual int monthsInYear(int year) const

Returns the number of months in the year used by this calendar system.

virtual int daysInMonth(int year, double month) const

Returns the number of days in a month used by this calendar system. The double data type implements functionalities for leap months.

virtual int daysInYear(int year) const

Returns the number of days in a year used by this calendar system.

virtual int daysInWeek() const

Returns the number of days in a week used by this calendar system, i.e, 7.

virtual bool isLeapYear(int year) const

Checks whether a year is a leap year or not.

virtual bool hasLeapMonths() const

Returns true is this calendar system has leap months. The Chinese calendar has leap months.

virtual bool hasYearZero() const

Returns true is this calendar system uses year 0. The Chinese calendar doesn't have a year 0.

virtual int maxDaysInWeek() const

Returns the maximum number of days in a week in this calendar system, i.e, 7.

virtual int maxMonthsInYear() const

Returns the maximum number of months in a year in this calendar system, i.e. 13.

virtual int earliestValidYear() const

Returns the earliest valid year in this calendar system, i.e., year 1.

virtual int latestValidYear() const

Returns the latest valid year in this calendar system, i.e., year 9999.

virtual QString monthName(double month, int year, Locale::DateTimeComponentFormat format, bool possessive) const

Gets specific calendar type month name for a given month number If an invalid month is specified, QString() is returned.

virtual QString weekDayName(int weekDay, KLocale::DateTimeComponentFormat format) const

Gets specific calendar type weekday name for a given month number If an invalid weekday is specified, QString() is returned.

Astronomical Implementation

Re-implementations of the functions dateToJulianDay() and julianDayToDate() using the functions defined in the Astro Library.

bool julianDayToDate(int jd, int &year, double &month, double &day) const

Returns the date implemented in this calendar system from Julian day. It implements the previously defined julianDayToChineseDate() function. The double data type for month and days implement the functionalities of leap months and leap days (as in the Hindu Calendar).

bool dateToJulianDay(int &jd, int year, double month, double day) const

Returns the Julian day from the date in this calendar system. It implements the previously defined chineseDateToJulianDay() function.

Astro Library

Most of the astronomical functions have already been described in the implementation of Chinese Calendar. A few functions were appended to the Astro Library, namely:

astro.h

int roundOff(double value)

Rounds off the double value to the integer value

astrolunar.h

double newMoonBefore(double time)

Returns the moment of a New Moon occurrence before the given time

double newMoonAtOrAfter(double time)

Returns the moment of a New Moon occurrence at or after the given time

astrosolar.h

double estimatePriorSolarLongitude(double longitude, double time)

This function has an important role to play in implementing astronomical solar calendars, as it determines a particular solar longitude on or before the given date. The solar longitude can correspondingly help to find the day of the New Year as per the astronomical calendar.

The calculations for implementing the Chinese Calendar have been derived from the public domain Lisp code/Mathematical functions of Calendrical Calculations by Edward M. Reingold on the Illinois Institute of Technology website, and from the book Astronomical Algorithms by Jean Meeus.