Module calendrica-chinese
Chinese calendar conversions.
Ported from "Calendrical Calculations" (4th edition) by Nachum Dershowitz and Edward M. Reingold. Original Lisp code (CALENDRICA 4.0) is Apache 2.0 licensed.
Info:
- Release: 0.1 2026-07-19
Functions
| chinese_new_year (g_year) | Fixed date of Chinese New Year in Gregorian year `g_year`. |
| chinese_from_fixed (date) | Chinese date {cycle, year, month, leap, day} of fixed `date`. |
| fixed_from_chinese (c_date) | Fixed date of Chinese date `c_date`. |
| japanese_from_fixed (date) | Japanese date {cycle, year, month, leap, day} of fixed `date`. |
| fixed_from_japanese (j_date) | Fixed date of Japanese date `j_date`. |
| korean_from_fixed (date) | Korean date {year, month, leap, day} of fixed `date`. |
| fixed_from_korean (k_date) | Fixed date of Korean date `k_date`. |
| vietnamese_from_fixed (date) | Vietnamese date {cycle, year, month, leap, day} of fixed `date`. |
| fixed_from_vietnamese (v_date) | Fixed date of Vietnamese date `v_date`. |
| dragon_festival (g_year) | Fixed date of the Dragon Festival (Double Fifth) in Gregorian year `g_year`. |
| qing_ming (g_year) | Fixed date of Qingming (Clear and Bright) in Gregorian year `g_year`. |
| current_major_solar_term (date) | Major solar term (zhongqi, 1..12) in effect on fixed `date`. |
| major_solar_term_on_or_after (date) | Moment (Beijing time) of first major solar term on or after fixed `date`. |
| current_minor_solar_term (date) | Minor solar term (jieqi, 1..12) in effect on fixed `date`. |
| minor_solar_term_on_or_after (date) | Moment (Beijing time) of first minor solar term on or after fixed `date`. |
| chinese_year_name (year) | Sexagesimal name {stem, branch} for Chinese year `year` of any cycle. |
| chinese_month_name (month, year) | Sexagesimal name {stem, branch} for `month` of Chinese `year`. |
| chinese_day_name (date) | Chinese sexagesimal day-name {stem, branch} for fixed `date`. |
| chinese_day_name_on_or_before (name, date) | Latest fixed date on or before `date` with the given Chinese sexagesimal `name`. |
| chinese_sexagesimal_name (n) | The n-th name of the Chinese sexagesimal cycle. |
| chinese_name_difference (c_name1, c_name2) | Number of names from `c_name1` to the next occurrence of `c_name2` in the sexagesimal cycle. |
| chinese_age (birthdate, date) | Age in Chinese reckoning at fixed `date` given Chinese `birthdate`. |
| chinese_year_marriage_augury (cycle, year) | Marriage augury type for Chinese year `year` of `cycle`. |
Fields
| WIDOW | Year type: no major solar term in either adjacent month (most auspicious). |
| BLIND | Year type: no major solar term in the current month. |
| BRIGHT | Year type: major solar term in the current month only. |
| DOUBLE_BRIGHT | Year type: major solar term in both the current and an adjacent month. |
Functions
- chinese_new_year (g_year)
-
Fixed date of Chinese New Year in Gregorian year `g_year`.
Parameters:
- g_year number Gregorian year.
Returns:
-
number
Fixed date.
- chinese_from_fixed (date)
-
Chinese date {cycle, year, month, leap, day} of fixed `date`.
Parameters:
- date number Fixed date.
Returns:
-
table
{cycle, year, month, leap, day}
- fixed_from_chinese (c_date)
-
Fixed date of Chinese date `c_date`.
Parameters:
- c_date table Chinese date {cycle, year, month, leap, day}.
Returns:
-
number
Fixed date.
- japanese_from_fixed (date)
-
Japanese date {cycle, year, month, leap, day} of fixed `date`.
Uses Tokyo meridian (pre-1888) or JST zone (1888+).
Parameters:
- date number Fixed date.
Returns:
-
table
{cycle, year, month, leap, day}
- fixed_from_japanese (j_date)
-
Fixed date of Japanese date `j_date`.
Parameters:
- j_date table Japanese date {cycle, year, month, leap, day}.
Returns:
-
number
Fixed date.
- korean_from_fixed (date)
-
Korean date {year, month, leap, day} of fixed `date`.
Uses Seoul city hall meridian with historically accurate time zones.
Year is the continuous Korean year (cycle * 60 + sexagesimal_year - 364).
Parameters:
- date number Fixed date.
Returns:
-
table
{year, month, leap, day}
- fixed_from_korean (k_date)
-
Fixed date of Korean date `k_date`.
Parameters:
- k_date table Korean date {year, month, leap, day}.
Returns:
-
number
Fixed date.
- vietnamese_from_fixed (date)
-
Vietnamese date {cycle, year, month, leap, day} of fixed `date`.
Uses Hanoi meridian (UTC+8 before 1968, UTC+7 after).
Parameters:
- date number Fixed date.
Returns:
-
table
{cycle, year, month, leap, day}
- fixed_from_vietnamese (v_date)
-
Fixed date of Vietnamese date `v_date`.
Parameters:
- v_date table Vietnamese date {cycle, year, month, leap, day}.
Returns:
-
number
Fixed date.
- dragon_festival (g_year)
-
Fixed date of the Dragon Festival (Double Fifth) in Gregorian year `g_year`.
Parameters:
- g_year number Gregorian year.
Returns:
-
number
Fixed date.
- qing_ming (g_year)
-
Fixed date of Qingming (Clear and Bright) in Gregorian year `g_year`.
Parameters:
- g_year number Gregorian year.
Returns:
-
number
Fixed date.
- current_major_solar_term (date)
-
Major solar term (zhongqi, 1..12) in effect on fixed `date`.
Parameters:
- date number Fixed date.
Returns:
-
number
Solar term index (1..12).
- major_solar_term_on_or_after (date)
-
Moment (Beijing time) of first major solar term on or after fixed `date`.
Parameters:
- date number Fixed date.
Returns:
-
number
Moment.
- current_minor_solar_term (date)
-
Minor solar term (jieqi, 1..12) in effect on fixed `date`.
Parameters:
- date number Fixed date.
Returns:
-
number
Solar term index (1..12).
- minor_solar_term_on_or_after (date)
-
Moment (Beijing time) of first minor solar term on or after fixed `date`.
Parameters:
- date number Fixed date.
Returns:
-
number
Moment.
- chinese_year_name (year)
-
Sexagesimal name {stem, branch} for Chinese year `year` of any cycle.
Parameters:
- year number Year within cycle (1..60).
Returns:
-
table
{stem, branch}
- chinese_month_name (month, year)
-
Sexagesimal name {stem, branch} for `month` of Chinese `year`.
Parameters:
- month number Month number.
- year number Year within cycle.
Returns:
-
table
{stem, branch}
- chinese_day_name (date)
-
Chinese sexagesimal day-name {stem, branch} for fixed `date`.
Parameters:
- date number Fixed date.
Returns:
-
table
{stem, branch}
- chinese_day_name_on_or_before (name, date)
-
Latest fixed date on or before `date` with the given Chinese sexagesimal `name`.
Parameters:
- name table Sexagesimal name {stem, branch}.
- date number Fixed date.
Returns:
-
number
Fixed date.
- chinese_sexagesimal_name (n)
-
The n-th name of the Chinese sexagesimal cycle.
Parameters:
- n number Position in cycle.
Returns:
-
table
{stem, branch}
- chinese_name_difference (c_name1, c_name2)
-
Number of names from `c_name1` to the next occurrence of `c_name2` in the sexagesimal cycle.
Parameters:
Returns:
-
number
Count (1..60).
- chinese_age (birthdate, date)
-
Age in Chinese reckoning at fixed `date` given Chinese `birthdate`.
Returns BOGUS if date is before birthdate.
Parameters:
- birthdate table Chinese date {cycle, year, month, leap, day}.
- date number Fixed date.
Returns:
-
number
Age (or BOGUS).
- chinese_year_marriage_augury (cycle, year)
-
Marriage augury type for Chinese year `year` of `cycle`.
Returns one of WIDOW, BLIND, BRIGHT, or DOUBLE_BRIGHT.
Parameters:
- cycle number Cycle number.
- year number Year within cycle (1..60).
Returns:
-
number
Augury constant.