iztro 0.4.0

Strongly typed Zi Wei Dou Shu chart generation aligned with iztro.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

//! Deterministic hourly-period (流时) facts derived from natal and target facts.
//!
//! This module derives one 流时 period using the upstream `iztro@2.5.8`
//! horoscope rule: the flowing double-hour stem-branch is the target solar
//! date/time's normal-boundary hour pillar, while the temporal Life palace index
//! is derived independently by counting on from the 流日 palace index by the
//! target double-hour. It does not assemble the full horoscope stack, attach
//! temporal decorative arrays, or render narrative text.

use crate::core::error::ChartError;
use crate::core::model::calendar::{BirthTime, SolarDay, SolarMonth};
use crate::core::model::chart::{
    Chart, PALACE_COUNT, TemporalPalaceLayout,
    temporal_layout::{
        build_life_branch_palace_layout, daily_palace_index, map_target_solar_error,
    },
};
use crate::core::model::star::mutagen::Scope;
use lunar_lite::{
    EarthlyBranch, MonthDivide, SolarDate, StemBranch, StemBranchOptions, YearDivide,
    four_pillars_from_solar_date_with_options, solar_to_lunar,
};
use serde::{Deserialize, Serialize};

/// One 流时 period with independent hour pillar and temporal Life palace facts.
#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
pub struct HourlyPeriod {
    index: usize,
    time_index: u8,
    stem_branch: StemBranch,
    palace_branch: EarthlyBranch,
    palace_layout: TemporalPalaceLayout,
}

impl HourlyPeriod {
    fn new(
        index: usize,
        time_index: u8,
        stem_branch: StemBranch,
        palace_branch: EarthlyBranch,
        palace_layout: TemporalPalaceLayout,
    ) -> Self {
        Self {
            index,
            time_index,
            stem_branch,
            palace_branch,
            palace_layout,
        }
    }

    /// Returns the zero-based upstream hourly index in Yin-first order.
    pub const fn index(&self) -> usize {
        self.index
    }

    /// Returns the upstream `timeIndex` (0..=12) this period describes.
    pub const fn time_index(&self) -> u8 {
        self.time_index
    }

    /// Returns the target hour stem-branch pair used for flow stars and mutagens.
    pub const fn stem_branch(&self) -> StemBranch {
        self.stem_branch
    }

    /// Returns the branch selected as the hourly temporal Life palace.
    pub const fn palace_branch(&self) -> EarthlyBranch {
        self.palace_branch
    }

    /// Returns the temporal palace-name layout for this hourly period.
    pub const fn palace_layout(&self) -> &TemporalPalaceLayout {
        &self.palace_layout
    }
}

/// Builds one 流时 period from natal chart facts and a target solar date/time.
pub fn build_hourly_period(
    natal: &Chart,
    target_solar_year: i32,
    target_solar_month: SolarMonth,
    target_solar_day: SolarDay,
    target_time: BirthTime,
) -> Result<HourlyPeriod, ChartError> {
    let solar = SolarDate {
        year: target_solar_year,
        month: target_solar_month.value(),
        day: target_solar_day.value(),
    };
    let time_index = target_time.iztro_time_index();
    let target_lunar = solar_to_lunar(solar).map_err(|err| {
        map_target_solar_error(
            err,
            target_solar_year,
            target_solar_month.value(),
            target_solar_day.value(),
        )
    })?;
    let pillars = four_pillars_from_solar_date_with_options(
        solar,
        time_index,
        StemBranchOptions {
            year: YearDivide::Normal,
            month: MonthDivide::Normal,
        },
    )
    .map_err(|err| {
        map_target_solar_error(
            err,
            target_solar_year,
            target_solar_month.value(),
            target_solar_day.value(),
        )
    })?;

    let daily_index = daily_palace_index(
        natal,
        target_lunar.year,
        target_lunar.month,
        target_lunar.day,
        target_lunar.is_leap_month,
    );
    let index =
        (daily_index as isize + time_index as isize).rem_euclid(PALACE_COUNT as isize) as usize;
    let palace_branch = EarthlyBranch::Yin.offset(index as isize);
    let palace_layout = build_life_branch_palace_layout(Scope::Hourly, palace_branch)?;

    Ok(HourlyPeriod::new(
        index,
        time_index,
        pillars.hourly,
        palace_branch,
        palace_layout,
    ))
}