Error handling

Every entry point taking external input returns a Result. Date format, date existence, year range, hour index and the reverse-lookup inputs are all validated up front in the core, so invalid input yields an error value rather than a panic.

#[non_exhaustive]
pub enum IztroError {
    /// Malformed date string, non-existent date, or outside the solar range 1583–9999
    InvalidDate(String),
    /// Hour index outside 0–12
    InvalidTimeIndex(u8),
    /// Invalid reverse-lookup input: mismatched pillar polarity, empty criteria, bad year range
    InvalidArgument(String),
    /// The calendar library did not return a pillar or sign value that should exist
    Internal(String),
}

impl IztroError {
    /// Machine-readable classification of the error
    pub fn code(&self) -> &'static str
}

IztroError implements Display and std::error::Error, so it propagates with ? and prints with {}.

code()

Display gives human-facing wording that may be adjusted between versions; branch on code() in code:

These four values are the same set as Python's IztroError.code and Go's iztro.Error.Code, so branching logic carries across languages verbatim.

let e = by_solar("2000-2-30", 2, Gender::Female, true, Language::EnUS, Config::default())
    .unwrap_err();
println!("{} / {}", e.code(), e);

Output

invalid_date / invalid solar date '2000-2-30': day is out of range for that month

InvalidDate

Triggers

Lunar-only (reachable from by_lunar, get_sign_by_lunar_date and get_major_star_by_lunar_date):

Lunar messages are prefixed invalid lunar date '<input>': and solar ones invalid solar date '<input>': , so the message alone shows which entry point was taken.

Example

let cfg = Config::default();

for date in ["2000-13-1", "2000-2-30", "1500-1-1"] {
    match by_solar(date, 2, Gender::Female, true, Language::EnUS, cfg.clone()) {
        Ok(_) => println!("{date}: ok"),
        Err(e) => println!("{e}"),
    }
}

Output

invalid solar date '2000-13-1': month must be within 1-12
invalid solar date '2000-2-30': day is out of range for that month
invalid solar date '1500-1-1': year must be within 1583-9999

The message carries the original input, so batch jobs can pinpoint which record failed.

Edge cases and pitfalls

InvalidTimeIndex

Trigger An hour index greater than 12.

Example

let err = by_solar("2000-8-16", 13, Gender::Female, true, Language::EnUS, Config::default())
    .unwrap_err();
println!("{err}");

Output

time_index must be 0-12, got 13

Edge cases and pitfalls

InvalidArgument

Triggers Caller mistakes at the reverse-lookup entry points:

Example

let jia_zi = (HeavenlyStem::Jia, EarthlyBranch::Zi);
let err = solar_dates_by_bazi(
    (HeavenlyStem::Jia, EarthlyBranch::Chou), // 甲丑: mismatched polarity
    jia_zi, jia_zi, jia_zi,
    (1900, 2100),
    &Config::default(),
)
.unwrap_err();
println!("{} / {}", err.code(), err);

Output

invalid_argument / invalid yearly pillar: stem and branch must have the same polarity

The semantics of the reverse-lookup entry points are on Reverse lookup.

Internal

Trigger The calendar library lunar_rust did not hand back a pillar or zodiac-sign value that should exist. This is a defect inside the library rather than a caller's mistake.

Why not panic On the wasm target a panic is a trap, and every trap permanently consumes stack space in the module instance. Turning such cases into error values keeps invalid calls from accumulating damage in the wasm instance on the Go side.

Message shape internal error: <detail>, with code() returning internal.

BridgeError

The uniform error shape the bindings (C FFI / wasm / PyO3) report outward. Rust callers generally do not need it — it is the origin of the error objects on the Python and Go sides.

pub struct BridgeError {
    /// invalid_date / invalid_time_index / invalid_argument / internal
    pub code: &'static str,
    /// Human-facing description of the error
    pub message: String,
}

impl BridgeError {
    pub fn invalid_argument(message: impl Into<String>) -> Self
    pub fn internal(message: impl Into<String>) -> Self
}

impl From<IztroError> for BridgeError { /* code and message carry straight over */ }

Its four classes are the same set as IztroError's. The bindings receive strings rather than enums, so the validity of a gender, language, palace name, mutagen or config JSON can only be checked at that layer; those cases land in the invalid_argument class as well.

All three exits serialize it into the same JSON:

{ "error": "invalid solar date '2000-2-30': day is out of range for that month",
  "code": "invalid_date" }

On the Python side that becomes an IztroError (subclassing ValueError, carrying .code); on the Go side an *iztro.Error (carrying Code, comparable with errors.Is against sentinels).

C FFI

In the C ABI exported by x_iztro::ffi, the single query entry point is iztro_query:

// include/x_iztro.h
char *iztro_query(const char *query_json);
void  iztro_free_string(char *s);

It takes a JSON document whose kind selects the query (for example {"kind":"getPalaceNames","soulIndex":0}), returning {"value": <result>} on success and the error JSON with its code shown above on failure. It gathers the lightweight queries, palace derivation, utilities, star placement, data tables, translation and prompt generation behind one symbol instead of exporting one C symbol per function. Keys are camelCase, and stars, stems, branches, palaces and other identifiers are passed and returned as iztro i18n keys.

Every returned string is handed back by the caller through iztro_free_string; these functions never return NULL.

Handling errors

Propagate with ?

fn analyze(date: &str) -> Result<String, IztroError> {
    let chart = by_solar(date, 2, Gender::Female, true, Language::EnUS, Config::default())?;
    Ok(chart.palace(Palace::Soul).unwrap().major_stars
        .iter().map(|s| s.name.clone()).collect::<Vec<_>>().join(","))
}

Match on the variant

fn describe(date: &str, ti: u8) -> String {
    match by_solar(date, ti, Gender::Female, true, Language::EnUS, Config::default()) {
        Ok(chart) => format!("charted: {}", chart.solar_date),
        Err(IztroError::InvalidDate(msg)) => format!("bad date: {msg}"),
        Err(IztroError::InvalidTimeIndex(t)) => format!("hour index {t} out of range"),
        Err(e) => format!("other error [{}]: {e}", e.code()),
    }
}

println!("{}", describe("2000-8-16", 2));
println!("{}", describe("2000-2-30", 2));
println!("{}", describe("2000-8-16", 13));

Output

charted: 2000-8-16
bad date: invalid solar date '2000-2-30': day is out of range for that month
hour index 13 out of range

Convert to your own error type

IztroError implements std::error::Error, so it is caught directly by Box<dyn Error>, anyhow::Error, or thiserror's #[from].

#[derive(Debug, thiserror::Error)]
enum AppError {
    #[error("charting failed: {0}")]
    Chart(#[from] x_iztro::IztroError),
}

About panics

The charting entry points do not panic on invalid external input: dates and hour indices become an IztroError, and even the internal case of the calendar library failing to produce a value goes through IztroError::Internal rather than a panic. The only remaining source of panics would be a logic defect inside the library (a failed assertion, say), and such a case should be reported as a bug.