apparent_solar_time 0.1.0

Convert standard (wall-clock) datetime to Apparent Solar Time (真太阳时), with full DST support via the IANA tz database. Designed for Chinese astrological calculations (生辰八字).
Documentation
  • Coverage
  • 100%
    8 out of 8 items documented1 out of 5 items with examples
  • Size
  • Source code size: 19.2 kB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 532.1 kB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 4s Average build duration of successful builds.
  • all releases: 4s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • ZhengjunHUO/apparent_solar_time
    0 0 0
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • ZhengjunHUO

apparent_solar_time

将标准时(出生证明上的时间)换算为真太阳时的 Rust 库,用于生辰八字排盘。

公式

真太阳时 = 标准时 + 地理时差 + 均时差
  • 地理时差:4 × (本地经度 − 时区中央经线) 分钟
  • 均时差(Equation of Time):地球椭圆轨道 + 地轴倾斜引起,全年约 ±16 分钟
  • 夏令时:通过 IANA tz 数据库自动处理,包括中国 1986–1991 年的历史夏令时

使用

[dependencies]
apparent_solar_time = { path = "..." }
jiff = "0.2"
use apparent_solar_time::{to_apparent_solar_time, timezone_from_name};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 出生证明:1990年7月15日 12:00,上海(夏令时 CDT = UTC+9)
    let local_dt = jiff::civil::date(1990, 7, 15).at(12, 0, 0, 0);
    let tz = timezone_from_name("Asia/Shanghai")?;
    let solar = to_apparent_solar_time(local_dt, &tz, 121.2)?;
    println!("真太阳时:{solar}");  // ≈ 10:59
    Ok(())
}

参数说明

参数 类型 说明
local_dt jiff::civil::DateTime 出生证明上的日期时间(不含时区)
tz &jiff::tz::TimeZone 出生地 IANA 时区,如 "Asia/Shanghai"
longitude f64 出生地经度,东经为正(如北京 116.4,纽约 -74.0)

纬度无需提供——真太阳时仅与经度有关。

时区名称示例

地区 IANA 名称
北京 / 上海 / 全国统一 Asia/Shanghai
香港 Asia/Hong_Kong
台北 Asia/Taipei
纽约 America/New_York
伦敦 Europe/London

完整列表见 IANA Time Zone Database。

中国夏令时说明

中国于 1986–1991 年实行夏令时(每年四月中旬 → 九月中旬,UTC+9)。 1992 年起废除,全年统一 UTC+8。

本库使用 jiff 内嵌的 IANA tzdb,自动处理这段历史区间。 1990 年 7 月上海出生,出生证明时间即为夏令时时间,无需手动调整。

精度

均时差采用 Spencer (1971) 近似公式,精度约 ±1 分钟,远小于八字时辰边界(30 分钟),满足实际需求。

许可证

MIT