中国的农历同时考虑到月球绕行地球与地球绕行太阳的情形,不像西历那样有着明显的规律,虽然农历本身的干支年是 60 年循环一次,但是每个年份在每次循环中,所含的各个月份之天数有可能是不一样的,甚至连该年有没有闰月,有闰月的话是闰几月也都不能固定,单讲哪个干支年也无法确定究竟是第几次循环的,因此通常还会搭配其它历法或是纪年法来使用,现在的话当然就是搭配西历来用啦!

Chinese Lunisolar Calendar

「Chinese Lunisolar Calendar」是笔者开发的套件,以不同的结构体分别抽象化了西历的年、月、日和农历的西历年和农历的月和日。农历的部份仰赖三个数据集合,也就是农历每年的大月、闰月、以及农历新年与该年所属西历年新年的天数差距,因此能够支持的农历日期范围是有限的。目前有公元 1901 年到 2100 年的数据,可以支持的农历日期范围为西历的公元 1901 年 2 月 19 日至公元 2101 年 1 月 28 日。

这个套件实现了西历和农历的转换,以及用农历日期和时间来计算八字重量的功能。除此之外,也可以将西历或是农历日期与中文字符串互转,同时支持繁体中文和简体中文。

Crates.io

Cargo.toml

chinese-lunisolar-calendar = "*"

使用方法

产生 SolarDate 结构实体的例子如下:

use chinese_lunisolar_calendar::chrono::prelude::*;

use chinese_lunisolar_calendar::SolarDate;

let solar_date = SolarDate::from_naive_date(NaiveDate::from_ymd(2019, 1, 15)).unwrap();

assert_eq!("二零一九年一月十五日", solar_date.to_chinese_string());
assert_eq!("二〇一九年一月十五日", solar_date.to_chinese_string_2());

产生 LunisolarDate 结构实体的例子如下:

use chinese_lunisolar_calendar::chrono::prelude::*;

use chinese_lunisolar_calendar::{ChineseVariant, LunisolarDate};

let lunisolar_date = LunisolarDate::from_naive_date(NaiveDate::from_ymd(2019, 1, 15)).unwrap();

assert_eq!(2019, lunisolar_date.get_solar_year().to_u16());
assert_eq!("二零一八 戊戌、狗年 腊月 初十", lunisolar_date.to_chinese_string(ChineseVariant::Traditional));
assert_eq!("二零一八 戊戌、狗年 腊月 初十", lunisolar_date.to_chinese_string(ChineseVariant::Simple));
assert_eq!("二〇一八 戊戌、狗年 腊月 初十", lunisolar_date.to_chinese_string_2(ChineseVariant::Traditional));
assert_eq!("二〇一八 戊戌、狗年 腊月 初十", lunisolar_date.to_chinese_string_2(ChineseVariant::Simple));

assert_eq!(4.3, lunisolar_date.get_ba_zi_weight_by_time(NaiveTime::from_hms(15, 30, 0)));

当然,除了 from_naive_date 关联函数之外,还有更多方便的以 from_ 开头的关联函数可以产生 SolarDate 或是 LunisolarDate 的结构实体。

SolarDate 结构实体和 LunisolarDate 结构实体也可以轻易互转。程序如下:

let lunisolar_date = solar_date.to_lunisolar_date().unwrap();
let solar_date = lunisolar_date.to_solar_date();

LunisolarDate 结构实体可以透过其 get_ba_zi_weight 方法再加上表示时辰的地支,或是 get_ba_zi_weight_by_time 方法再加上时间数据,来计算出八字重量。程序如下:

let weight = lunisolar_date.get_ba_zi_weight(EarthlyBranch::Ninth);
let weight = lunisolar_date.get_ba_zi_weight_by_time(NaiveTime::from_hms(15, 30, 0));