Crate lunar_lite 

lunar-lite is a small library for Chinese lunisolar date conversion.

It converts between the Gregorian (solar) calendar and the Chinese lunar calendar, and exposes the sexagenary cycle (六十甲子) of Heavenly Stems and Earthly Branches.

Examples

use lunar_lite::{solar_to_lunar, lunar_to_solar, SolarDate, LunarDate};

let solar = SolarDate { year: 2024, month: 2, day: 10 };
let lunar = solar_to_lunar(solar).unwrap();
assert_eq!(lunar, LunarDate { year: 2024, month: 1, day: 1, is_leap_month: false });

// Round-trips back to the original solar date.
assert_eq!(lunar_to_solar(lunar).unwrap(), solar);

Supported range

lunar-lite uses a small internal astronomical backend for new-moon and solar-term calculation, with tyme4rs-compatible calendar behaviour. Portions of the astronomical calculation kernel are adapted from MIT-licensed 6tail/tyme4rs; see THIRD_PARTY_LICENSES.md.

• Solar conversion supports Gregorian years 1..=9999.
• Lunar-month facts (leap_month, lunar_month_days) accept lunar years -1..=9999.
• Full lunar-to-solar conversion additionally requires the resulting solar date to fall in solar years 1..=9999. Every lunar year -1 date lands before solar year 1, so lunar_to_solar reports LunarError::SolarYearOutOfRange there.
• Dates before 1582-10-15 use Julian-calendar semantics; the historical Gregorian reform gap 1582-10-05..=1582-10-14 is invalid.

Solar years outside 1..=9999 return LunarError::SolarYearOutOfRange; lunar years outside -1..=9999 return LunarError::LunarYearOutOfRange.

Support across the full 1..=9999 range means this crate returns a deterministic, tyme-compatible model result for every date in that range, not that every result is historically or astronomically authoritative. The underlying ΔT and calibration tables are most accurate near the modern era and extrapolate for years far from it; extreme-year output should be read as “what the tyme-compatible model computes,” not as ground truth.

Lunar month helpers

leap_month, has_leap_month, lunar_month_days, and validate_lunar_date expose calendar facts only. They do not encode downstream chart-placement policy for how consumers should interpret leap months. Invalid month and leap-month selections return LunarError::InvalidLunarMonth from lunar_month_days, while validate_lunar_date reports full-date failures as LunarError::InvalidLunarDate.

Exact LiChun datetime

li_chun_datetime returns the exact astronomical datetime of 立春 (LiChun, Start of Spring) for a given Gregorian year. This is a public primitive for downstream crates that need second-level LiChun precision.

Note: this does not change YearDivide::Exact semantics in the four-pillar API, which remains date-level for compatibility.

use lunar_lite::li_chun_datetime;

let dt = li_chun_datetime(2000).unwrap();
assert_eq!((dt.date.year, dt.date.month, dt.date.day), (2000, 2, 4));
assert_eq!((dt.hour, dt.minute, dt.second), (20, 40, 24));

Features

• serde: derive Serialize/Deserialize for the public date and stem-branch types.

Structs

FourPillars

The four pillars (年柱, 月柱, 日柱, 时柱) of a date and time.

LunarDate

A date in the Chinese lunar calendar.

SolarDate

A solar-calendar date using tyme-compatible Julian/Gregorian reform semantics.

SolarTermDateTime

The exact date and wall-clock time at which a solar term occurs.

StemBranch

A valid Heavenly Stem / Earthly Branch pair in the sexagenary cycle.

StemBranchOptions

Options controlling the year and month pillar boundaries.

Enums

EarthlyBranch

One of the twelve Earthly Branches.

HeavenlyStem

One of the ten Heavenly Stems.

LunarError

Errors from date conversion and validation.

MonthDivide

How to resolve the month pillar across the month boundary.

StemBranchError

Errors from constructing a StemBranch.

YearDivide

How to resolve the year pillar across the year boundary.

Constants

EARTHLY_BRANCHES

Canonical cyclic ordering of the twelve Earthly Branches.

HEAVENLY_STEMS

Canonical cyclic ordering of the ten Heavenly Stems.

Functions

four_pillars_from_solar_date

Computes the four pillars for a Gregorian solar date and 时辰 index, using the default (StemBranchOptions::default, i.e. Exact/Exact, matching lunar-lite@0.2.8).

four_pillars_from_solar_date_with_options

Computes the four pillars for a Gregorian solar date and 时辰 index with explicit StemBranchOptions.

has_leap_month

Returns whether a lunar year has a leap month.

is_early_zi

Returns true if time_index is the early 子时 (0, 00:00–00:59).

is_late_zi

Returns true if time_index is the late 子时 (12, 23:00–23:59).

leap_month

Returns the leap month number for a lunar year, if that year has one.

li_chun_datetime

Returns the exact datetime of 立春 (LiChun, Start of Spring) for year.

lunar_month_days

Returns the number of days in a regular or leap lunar month.

lunar_to_solar

Converts a Chinese lunar date to its Gregorian (solar) date.

lunar_year_branch

Returns the Earthly Branch of a Chinese lunar year (生年支).

lunar_year_stem

Returns the Heavenly Stem of a Chinese lunar year (生年干).

lunar_year_stem_branch

Returns the stem-branch of a Chinese lunar year.

normalize_lunar_date

Normalizes a lunar date and verifies that it actually exists.

solar_to_lunar

Converts a Gregorian (solar) date to its Chinese lunar date.

time_index

Returns the double-hour (時辰) index for a wall-clock time.

time_index_to_branch

Returns the Earthly Branch (时支) for a 时辰 index.

validate_lunar_date

Validates that a lunar date exists exactly as supplied.