iztro 0.6.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

//! Deterministic monthly-period (流月) facts derived from natal and target facts.
//!
//! This module derives one 流月 period using the upstream `iztro@2.5.8`
//! horoscope rule: the flowing month stem-branch comes from the target solar
//! date's normal-boundary month pillar, while the temporal Life palace index is
//! derived separately from the yearly index, natal lunar month, natal birth
//! hour, and target lunar month. It does not assemble daily/hourly layers,
//! 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, TemporalPalaceLayout,
    temporal_layout::{
        build_life_branch_palace_layout, map_target_solar_error, monthly_palace_index,
    },
};
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 month pillar and temporal Life palace facts.
#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
pub struct MonthlyPeriod {
    index: usize,
    lunar_month: u8,
    stem_branch: StemBranch,
    palace_branch: EarthlyBranch,
    palace_layout: TemporalPalaceLayout,
}

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

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

    /// Returns the one-based target lunar month this period describes.
    pub const fn lunar_month(&self) -> u8 {
        self.lunar_month
    }

    /// Returns the target month 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 monthly temporal Life palace.
    pub const fn palace_branch(&self) -> EarthlyBranch {
        self.palace_branch
    }

    /// Returns the temporal palace-name layout for this monthly 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_monthly_period(
    natal: &Chart,
    target_solar_year: i32,
    target_solar_month: SolarMonth,
    target_solar_day: SolarDay,
    target_time: BirthTime,
) -> Result<MonthlyPeriod, ChartError> {
    let solar = SolarDate {
        year: target_solar_year,
        month: target_solar_month.value(),
        day: target_solar_day.value(),
    };
    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,
        target_time.iztro_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 index = monthly_palace_index(
        natal,
        target_lunar.year,
        target_lunar.month,
        target_lunar.day,
        target_lunar.is_leap_month,
    );
    let palace_branch = EarthlyBranch::Yin.offset(index as isize);
    let palace_layout = build_life_branch_palace_layout(Scope::Monthly, palace_branch)?;

    Ok(MonthlyPeriod::new(
        index,
        target_lunar.month,
        pillars.monthly,
        palace_branch,
        palace_layout,
    ))
}