lua-calendrica

# 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:

  - 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-07-19 03:28:25