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.2 2026-09-21

Functions

chinese_new_year (g_year) Fixed date of Chinese New Year in Gregorian year g_year.
chinese_related_year (cycle, year) Gregorian year in which Chinese year year of cycle begins (CLDR’s related Gregorian 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_related_year (cycle, year)
Gregorian year in which Chinese year year of cycle begins (CLDR’s related Gregorian year). The inverse of the elapsed years in dragon_festival.

Parameters:

  • cycle number Cycle number.
  • year number Year within cycle (1..60).

Returns:

    number Gregorian year.
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:

  • c_name1 table Sexagesimal name {stem, branch}.
  • c_name2 table Sexagesimal name {stem, branch}.

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.

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.
generated by LDoc 1.5.0 Last updated 2026-10-01 02:01:33