siplot 0.1.0

//! Date-time tick layout on a numeric axis whose data values are epoch
//! seconds (UTC).
//!
//! A faithful port of silx `gui/plot/_utils/dtime_ticklayout.py`. The silx
//! original operates on `datetime.datetime` objects backed by `dateutil`; here
//! the data values are `f64` POSIX timestamps (seconds since 1970-01-01
//! 00:00:00 UTC) and the civil-date arithmetic is implemented directly via the
//! standard "days from civil" algorithm (Howard Hinnant,
//! <http://howardhinnant.github.io/date_algorithms.html>), so there is no
//! `chrono`/timezone dependency.
//!
//! UTC-only: every conversion treats the timestamp as UTC. silx supports a
//! per-axis `tzinfo` (`Axis.setTimeZone`); timezone handling is deferred (the
//! chrome that would render these labels is also deferred, see the wave-4
//! cluster notes).
//!
//! The two entry points mirror the Python module:
//!
//! - [`best_unit`] (`bestUnit`): pick the tick unit + a fractional count for a
//!   duration in seconds.
//! - [`calc_ticks`] (`calcTicks`): given `(min, max)` epoch seconds and a
//!   target tick count, return the tick positions (epoch seconds), the nice
//!   spacing, and the chosen unit.
//!
//! [`format_tick`] mirrors `bestFormatString` + `strftime` for a single tick.

// Constants mirror silx dtime_ticklayout.py:49-54.
const MICROSECONDS_PER_SECOND: f64 = 1_000_000.0;
const SECONDS_PER_MINUTE: f64 = 60.0;
const SECONDS_PER_HOUR: f64 = 60.0 * SECONDS_PER_MINUTE;
const SECONDS_PER_DAY: f64 = 24.0 * SECONDS_PER_HOUR;
const SECONDS_PER_YEAR: f64 = 365.25 * SECONDS_PER_DAY;
const SECONDS_PER_MONTH_AVERAGE: f64 = SECONDS_PER_YEAR / 12.0;

/// The unit a tick step is expressed in (silx `DtUnit`). Discriminants match
/// silx so the `< unit.value` ordering comparisons in `round_to_element` port
/// directly (`YEARS = 0` … `MICRO_SECONDS = 6`).
#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)]
pub enum DtUnit {
    /// Calendar years.
    Years = 0,
    /// Calendar months.
    Months = 1,
    /// Days.
    Days = 2,
    /// Hours.
    Hours = 3,
    /// Minutes.
    Minutes = 4,
    /// Seconds.
    Seconds = 5,
    /// A fraction of a second.
    MicroSeconds = 6,
}

impl DtUnit {
    /// The "nice" step values silx allows for this unit
    /// (`NICE_DATE_VALUES`, dtime_ticklayout.py:288-296). The last entry is the
    /// base used by [`nice_num_generic`].
    fn nice_values(self) -> &'static [f64] {
        match self {
            DtUnit::Years => &[1.0, 2.0, 5.0, 10.0],
            DtUnit::Months => &[1.0, 2.0, 3.0, 4.0, 6.0, 12.0],
            DtUnit::Days => &[1.0, 2.0, 3.0, 7.0, 14.0, 28.0],
            DtUnit::Hours => &[1.0, 2.0, 3.0, 4.0, 6.0, 12.0],
            DtUnit::Minutes => &[1.0, 2.0, 3.0, 5.0, 10.0, 15.0, 30.0],
            DtUnit::Seconds => &[1.0, 2.0, 3.0, 5.0, 10.0, 15.0, 30.0],
            DtUnit::MicroSeconds => &[1.0, 2.0, 3.0, 4.0, 5.0, 10.0],
        }
    }
}

/// A UTC civil date-time decomposed to the resolution silx uses (microseconds).
///
/// This is the Rust stand-in for the `datetime.datetime` objects silx passes
/// around. Fields are not range-validated on construction beyond what
/// [`DateTime::from_civil`] guarantees; callers go through the constructors.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct DateTime {
    /// Civil year (may be negative; proleptic Gregorian).
    pub year: i64,
    /// Month, 1-12.
    pub month: u32,
    /// Day of month, 1-31.
    pub day: u32,
    /// Hour, 0-23.
    pub hour: u32,
    /// Minute, 0-59.
    pub minute: u32,
    /// Second, 0-59.
    pub second: u32,
    /// Microsecond, 0-999_999.
    pub microsecond: u32,
}

/// Number of days from the civil epoch (1970-01-01) to `y-m-d`.
///
/// Howard Hinnant's `days_from_civil`. Valid for any proleptic Gregorian date;
/// `m ∈ [1, 12]`, `d ∈ [1, last day of month]`. Negative results are days
/// before the epoch.
fn days_from_civil(y: i64, m: u32, d: u32) -> i64 {
    // Shift so the year starts in March (leap day at year end).
    let y = if m <= 2 { y - 1 } else { y };
    let era = if y >= 0 { y } else { y - 399 } / 400;
    let yoe = y - era * 400; // [0, 399]
    let doy = (153 * (if m > 2 { m - 3 } else { m + 9 }) as i64 + 2) / 5 + d as i64 - 1; // [0, 365]
    let doe = yoe * 365 + yoe / 4 - yoe / 100 + doy; // [0, 146096]
    era * 146097 + doe - 719468
}

/// Inverse of [`days_from_civil`]: civil `(year, month, day)` for a day count
/// relative to 1970-01-01. Howard Hinnant's `civil_from_days`.
fn civil_from_days(z: i64) -> (i64, u32, u32) {
    let z = z + 719468;
    let era = if z >= 0 { z } else { z - 146096 } / 146097;
    let doe = z - era * 146097; // [0, 146096]
    let yoe = (doe - doe / 1460 + doe / 36524 - doe / 146096) / 365; // [0, 399]
    let y = yoe + era * 400;
    let doy = doe - (365 * yoe + yoe / 4 - yoe / 100); // [0, 365]
    let mp = (5 * doy + 2) / 153; // [0, 11]
    let d = (doy - (153 * mp + 2) / 5 + 1) as u32; // [1, 31]
    let m = if mp < 10 { mp + 3 } else { mp - 9 } as u32; // [1, 12]
    let y = if m <= 2 { y + 1 } else { y };
    (y, m, d)
}

/// Days in `month` of `year` (proleptic Gregorian).
fn days_in_month(year: i64, month: u32) -> u32 {
    match month {
        1 | 3 | 5 | 7 | 8 | 10 | 12 => 31,
        4 | 6 | 9 | 11 => 30,
        2 => {
            let leap = (year % 4 == 0 && year % 100 != 0) || year % 400 == 0;
            if leap { 29 } else { 28 }
        }
        _ => 30,
    }
}

impl DateTime {
    /// Build from civil components without normalization. The day is clamped to
    /// the last valid day of the month (mirrors how silx's `setDateElement`
    /// would otherwise raise; here a clamp keeps tick generation total).
    pub fn from_civil(
        year: i64,
        month: u32,
        day: u32,
        hour: u32,
        minute: u32,
        second: u32,
        microsecond: u32,
    ) -> Self {
        let month = month.clamp(1, 12);
        let day = day.clamp(1, days_in_month(year, month));
        Self {
            year,
            month,
            day,
            hour,
            minute,
            second,
            microsecond,
        }
    }

    /// Decompose an epoch-seconds timestamp (UTC) into civil components.
    ///
    /// Uses floor division so timestamps before the epoch decompose correctly
    /// (e.g. `-0.5` is `1969-12-31 23:59:59.500000`).
    pub fn from_epoch_seconds(epoch: f64) -> Self {
        // Split into whole seconds (floor) and sub-second microseconds so the
        // microsecond field is always in [0, 999_999].
        let whole = epoch.floor();
        let frac = epoch - whole; // [0, 1)
        let microsecond = (frac * MICROSECONDS_PER_SECOND).round() as i64;
        // Rounding can push frac up to a full second.
        let (mut total_secs, microsecond) = if microsecond >= 1_000_000 {
            (whole as i64 + 1, 0u32)
        } else {
            (whole as i64, microsecond as u32)
        };

        let days = total_secs.div_euclid(SECONDS_PER_DAY as i64);
        let sod = total_secs.rem_euclid(SECONDS_PER_DAY as i64); // seconds of day, [0, 86399]
        total_secs = sod;
        let hour = (total_secs / 3600) as u32;
        let minute = ((total_secs % 3600) / 60) as u32;
        let second = (total_secs % 60) as u32;
        let (year, month, day) = civil_from_days(days);
        Self {
            year,
            month,
            day,
            hour,
            minute,
            second,
            microsecond,
        }
    }

    /// Convert back to epoch seconds (UTC). Exact inverse of
    /// [`DateTime::from_epoch_seconds`] for in-range civil dates.
    pub fn to_epoch_seconds(self) -> f64 {
        let days = days_from_civil(self.year, self.month, self.day);
        let secs = days * (SECONDS_PER_DAY as i64)
            + self.hour as i64 * 3600
            + self.minute as i64 * 60
            + self.second as i64;
        secs as f64 + self.microsecond as f64 / MICROSECONDS_PER_SECOND
    }

    /// The integer value of the date element for `unit` (silx
    /// `getDateElement`).
    fn get_element(self, unit: DtUnit) -> i64 {
        match unit {
            DtUnit::Years => self.year,
            DtUnit::Months => self.month as i64,
            DtUnit::Days => self.day as i64,
            DtUnit::Hours => self.hour as i64,
            DtUnit::Minutes => self.minute as i64,
            DtUnit::Seconds => self.second as i64,
            DtUnit::MicroSeconds => self.microsecond as i64,
        }
    }

    /// Return a copy with the element for `unit` set to `value` (silx
    /// `setDateElement`). The day is clamped via [`DateTime::from_civil`].
    fn set_element(self, value: i64, unit: DtUnit) -> Self {
        let mut dt = self;
        match unit {
            DtUnit::Years => dt.year = value,
            DtUnit::Months => dt.month = value as u32,
            DtUnit::Days => dt.day = value as u32,
            DtUnit::Hours => dt.hour = value as u32,
            DtUnit::Minutes => dt.minute = value as u32,
            DtUnit::Seconds => dt.second = value as u32,
            DtUnit::MicroSeconds => dt.microsecond = value as u32,
        }
        DateTime::from_civil(
            dt.year,
            dt.month,
            dt.day,
            dt.hour,
            dt.minute,
            dt.second,
            dt.microsecond,
        )
    }

    /// Round down to `unit`: zero out every element finer than `unit` (silx
    /// `roundToElement`). Years are never rounded; month/day floor to 1, the
    /// time fields floor to 0.
    fn round_to_element(self, unit: DtUnit) -> Self {
        let u = unit as i64;
        let month = if u < DtUnit::Months as i64 {
            1
        } else {
            self.month
        };
        let day = if u < DtUnit::Days as i64 { 1 } else { self.day };
        let hour = if u < DtUnit::Hours as i64 {
            0
        } else {
            self.hour
        };
        let minute = if u < DtUnit::Minutes as i64 {
            0
        } else {
            self.minute
        };
        let second = if u < DtUnit::Seconds as i64 {
            0
        } else {
            self.second
        };
        let microsecond = if u < DtUnit::MicroSeconds as i64 {
            0
        } else {
            self.microsecond
        };
        DateTime::from_civil(self.year, month, day, hour, minute, second, microsecond)
    }

    /// Add `value` of `unit` to this date-time (silx `addValueToDate`). Year and
    /// month additions truncate `value` to an integer (relativedelta has no
    /// fractional year/month); calendar overflow rolls correctly.
    fn add_value(self, value: f64, unit: DtUnit) -> Self {
        match unit {
            DtUnit::Years => {
                let n = value as i64;
                DateTime::from_civil(
                    self.year + n,
                    self.month,
                    self.day,
                    self.hour,
                    self.minute,
                    self.second,
                    self.microsecond,
                )
            }
            DtUnit::Months => {
                let n = value as i64;
                // Total months since year 0, then re-split. relativedelta
                // clamps the day to the target month's length, which
                // from_civil reproduces via its day clamp.
                let total = (self.year) * 12 + (self.month as i64 - 1) + n;
                let year = total.div_euclid(12);
                let month = (total.rem_euclid(12) + 1) as u32;
                DateTime::from_civil(
                    year,
                    month,
                    self.day,
                    self.hour,
                    self.minute,
                    self.second,
                    self.microsecond,
                )
            }
            DtUnit::Days => self.add_seconds(value * SECONDS_PER_DAY),
            DtUnit::Hours => self.add_seconds(value * SECONDS_PER_HOUR),
            DtUnit::Minutes => self.add_seconds(value * SECONDS_PER_MINUTE),
            DtUnit::Seconds => self.add_seconds(value),
            DtUnit::MicroSeconds => self.add_seconds(value / MICROSECONDS_PER_SECOND),
        }
    }

    /// Add a (possibly fractional) number of seconds via the epoch round-trip.
    fn add_seconds(self, seconds: f64) -> Self {
        DateTime::from_epoch_seconds(self.to_epoch_seconds() + seconds)
    }
}

/// The generic nice-number rounding (silx `ticklayout.niceNumGeneric`).
///
/// `nice_fractions` is the unit's allowed step list; its last element is the
/// base of the logarithm. When `is_round` is set, each comparison threshold
/// (except the last) is the average of adjacent nice fractions, so values round
/// to the nearer step instead of always rounding up.
fn nice_num_generic(value: f64, nice_fractions: &[f64], is_round: bool) -> f64 {
    if value == 0.0 {
        return value;
    }

    // roundFractions: average with the next element when rounding; last stays.
    let mut round_fractions: Vec<f64> = nice_fractions.to_vec();
    if is_round {
        for i in 0..round_fractions.len().saturating_sub(1) {
            round_fractions[i] = (nice_fractions[i] + nice_fractions[i + 1]) / 2.0;
        }
    }

    let highest = *nice_fractions.last().expect("nice_fractions is non-empty");
    let value = value.abs();
    let expvalue = (value.ln() / highest.ln()).floor();
    let frac = value / highest.powf(expvalue);

    for (nice_frac, round_frac) in nice_fractions.iter().zip(round_fractions.iter()) {
        if frac <= *round_frac {
            return nice_frac * highest.powf(expvalue);
        }
    }
    // silx asserts unreachable here; clamp to the largest nice fraction.
    highest * highest.powf(expvalue)
}

/// Nice value for a date element (silx `niceDateTimeElement`). For years and
/// months the result is at least 1 and integral (no fractional year/month).
fn nice_date_time_element(value: f64, unit: DtUnit, is_round: bool) -> f64 {
    let elem = nice_num_generic(value, unit.nice_values(), is_round);
    if unit == DtUnit::Years || unit == DtUnit::Months {
        (elem as i64).max(1) as f64
    } else {
        elem
    }
}

/// Pick the best tick unit for a duration (silx `bestUnit`).
///
/// Returns `(count, unit)` where `count` is the duration expressed in `unit`s
/// (fractional). The thresholds (and their per-unit factors) match silx exactly
/// (dtime_ticklayout.py:272-285).
pub fn best_unit(duration_seconds: f64) -> (f64, DtUnit) {
    if duration_seconds > SECONDS_PER_YEAR * 3.0 {
        (duration_seconds / SECONDS_PER_YEAR, DtUnit::Years)
    } else if duration_seconds > SECONDS_PER_MONTH_AVERAGE * 3.0 {
        (duration_seconds / SECONDS_PER_MONTH_AVERAGE, DtUnit::Months)
    } else if duration_seconds > SECONDS_PER_DAY * 2.0 {
        (duration_seconds / SECONDS_PER_DAY, DtUnit::Days)
    } else if duration_seconds > SECONDS_PER_HOUR * 2.0 {
        (duration_seconds / SECONDS_PER_HOUR, DtUnit::Hours)
    } else if duration_seconds > SECONDS_PER_MINUTE * 2.0 {
        (duration_seconds / SECONDS_PER_MINUTE, DtUnit::Minutes)
    } else if duration_seconds > 2.0 {
        (duration_seconds, DtUnit::Seconds)
    } else {
        (
            duration_seconds * MICROSECONDS_PER_SECOND,
            DtUnit::MicroSeconds,
        )
    }
}

/// Round a date down to the nearest nice start tick (silx `findStartDate`).
///
/// Returns `(start, spacing, unit)`. `n_ticks` is the target tick count.
fn find_start_date(d_min: DateTime, d_max: DateTime, n_ticks: usize) -> (DateTime, f64, DtUnit) {
    let min_epoch = d_min.to_epoch_seconds();
    let max_epoch = d_max.to_epoch_seconds();
    debug_assert!(max_epoch >= min_epoch, "d_min should come before d_max");

    if min_epoch == max_epoch {
        // Range smaller than microsecond resolution.
        return (d_min, 1.0, DtUnit::MicroSeconds);
    }

    let length_sec = max_epoch - min_epoch;
    let (length, unit) = best_unit(length_sec);
    let nice_length = nice_date_time_element(length, unit, false);
    let nice_spacing = nice_date_time_element(nice_length / n_ticks as f64, unit, true);

    let d_val = d_min.get_element(unit) as f64;

    let nice_val = if unit == DtUnit::Months || unit == DtUnit::Days {
        ((d_val - 1.0) / nice_spacing).floor() * nice_spacing + 1.0
    } else {
        (d_val / nice_spacing).floor() * nice_spacing
    };

    // silx: dt.MINYEAR == 1. Guard a degenerate year start.
    let nice_val = if unit == DtUnit::Years && nice_val <= 1.0 {
        nice_spacing.max(1.0)
    } else {
        nice_val
    };

    let start = d_min.round_to_element(unit);
    let start = start.set_element(nice_val as i64, unit);

    (start, nice_spacing, unit)
}

/// Generate tick date-times in `[d_min, d_max)` stepping by `step` `unit`s
/// (silx `dateRange`). When `include_first_beyond` is set, the first tick at or
/// past `d_max` is also emitted (silx default for `calcTicks`).
fn date_range(
    d_min: DateTime,
    d_max: DateTime,
    step: f64,
    unit: DtUnit,
    include_first_beyond: bool,
) -> Vec<DateTime> {
    // Year/month/microsecond have integral steps of at least 1.
    let step = if unit == DtUnit::Years || unit == DtUnit::Months || unit == DtUnit::MicroSeconds {
        step.max(1.0)
    } else {
        debug_assert!(step > 0.0, "tickstep is 0");
        step
    };

    let max_epoch = d_max.to_epoch_seconds();
    let mut out = Vec::new();
    let mut dt = d_min;
    // Bound the loop defensively: even a degenerate step cannot exceed the
    // theoretical tick count by much; cap to avoid an infinite loop if the
    // arithmetic ever fails to advance.
    let mut guard = 0usize;
    while dt.to_epoch_seconds() < max_epoch {
        out.push(dt);
        let next = dt.add_value(step, unit);
        if next.to_epoch_seconds() <= dt.to_epoch_seconds() {
            // No forward progress (out of representable range / zero step):
            // stop to stay total.
            dt = next;
            break;
        }
        dt = next;
        guard += 1;
        if guard > 1_000_000 {
            break;
        }
    }
    if include_first_beyond {
        out.push(dt);
    }
    out
}

/// Compute tick positions for a datetime axis (silx `calcTicks`).
///
/// `min`/`max` are epoch seconds (UTC); `n_ticks` is the target tick count (the
/// actual count may differ). Returns `(ticks, spacing, unit)` where `ticks` are
/// epoch seconds. The returned ticks always bracket `[min, max]`: the first is
/// at or below `min` (rounded-down start) and the last is at or beyond `max`
/// (the `include_first_beyond` tick).
pub fn calc_ticks(min: f64, max: f64, n_ticks: usize) -> (Vec<f64>, f64, DtUnit) {
    let n_ticks = n_ticks.max(1);
    let d_min = DateTime::from_epoch_seconds(min);
    let d_max = DateTime::from_epoch_seconds(max);
    let (start, spacing, unit) = find_start_date(d_min, d_max, n_ticks);
    let dates = date_range(start, d_max, spacing, unit, true);
    let ticks = dates.iter().map(|d| d.to_epoch_seconds()).collect();
    (ticks, spacing, unit)
}

/// As [`calc_ticks`] but derives the target tick count from an axis length in
/// pixels and a tick density (silx `calcTicksAdaptive`). At least 2 ticks.
pub fn calc_ticks_adaptive(
    min: f64,
    max: f64,
    axis_length: f64,
    tick_density: f64,
) -> (Vec<f64>, f64, DtUnit) {
    let n = (tick_density * axis_length).round() as i64;
    let n = n.max(2) as usize;
    calc_ticks(min, max, n)
}

/// Zero-pad an integer to `width` digits.
fn pad(value: i64, width: usize) -> String {
    if value < 0 {
        format!("-{:0width$}", -value, width = width)
    } else {
        format!("{value:0width$}")
    }
}

/// Format a single tick (epoch seconds, UTC) for the given `spacing`/`unit`,
/// mirroring silx `bestFormatString` + `datetime.strftime`.
///
/// For [`DtUnit::MicroSeconds`] the silx code additionally strips a common run
/// of trailing zeros across all labels; that cross-label step needs the whole
/// tick set, so it is done in [`format_ticks`]. This single-tick helper returns
/// the raw `%S.%f` form for microseconds.
pub fn format_tick(epoch: f64, spacing: f64, unit: DtUnit) -> String {
    let d = DateTime::from_epoch_seconds(epoch);
    let is_small = spacing < 1.0;
    match unit {
        DtUnit::Years => {
            if is_small {
                // silx uses "%Y-m" here (literal "m"); reproduced faithfully.
                format!("{}-m", pad(d.year, 4))
            } else {
                pad(d.year, 4)
            }
        }
        DtUnit::Months => {
            if is_small {
                format!(
                    "{}-{}-{}",
                    pad(d.year, 4),
                    pad(d.month as i64, 2),
                    pad(d.day as i64, 2)
                )
            } else {
                format!("{}-{}", pad(d.year, 4), pad(d.month as i64, 2))
            }
        }
        DtUnit::Days => {
            if is_small {
                format!("{}:{}", pad(d.hour as i64, 2), pad(d.minute as i64, 2))
            } else {
                format!(
                    "{}-{}-{}",
                    pad(d.year, 4),
                    pad(d.month as i64, 2),
                    pad(d.day as i64, 2)
                )
            }
        }
        DtUnit::Hours => {
            format!("{}:{}", pad(d.hour as i64, 2), pad(d.minute as i64, 2))
        }
        DtUnit::Minutes => {
            if is_small {
                format!(
                    "{}:{}:{}",
                    pad(d.hour as i64, 2),
                    pad(d.minute as i64, 2),
                    pad(d.second as i64, 2)
                )
            } else {
                format!("{}:{}", pad(d.hour as i64, 2), pad(d.minute as i64, 2))
            }
        }
        DtUnit::Seconds => {
            if is_small {
                format!(
                    "{}.{}",
                    pad(d.second as i64, 2),
                    pad(d.microsecond as i64, 6)
                )
            } else {
                format!(
                    "{}:{}:{}",
                    pad(d.hour as i64, 2),
                    pad(d.minute as i64, 2),
                    pad(d.second as i64, 2)
                )
            }
        }
        DtUnit::MicroSeconds => {
            format!(
                "{}.{}",
                pad(d.second as i64, 2),
                pad(d.microsecond as i64, 6)
            )
        }
    }
}

/// Format a whole tick set (silx `formatDatetimes`). For
/// [`DtUnit::MicroSeconds`] this applies silx's cross-label trailing-zero strip:
/// it finds the minimum number of trailing `'0'` shared by every label (capped
/// at 5), drops a leading `'0'` per label, and trims that many trailing chars.
pub fn format_ticks(ticks: &[f64], spacing: f64, unit: DtUnit) -> Vec<String> {
    if unit != DtUnit::MicroSeconds {
        return ticks
            .iter()
            .map(|&t| format_tick(t, spacing, unit))
            .collect();
    }

    let texts: Vec<String> = ticks
        .iter()
        .map(|&t| format_tick(t, spacing, unit))
        .collect();
    if texts.is_empty() {
        return texts;
    }

    let nzeros = texts
        .iter()
        .map(|t| t.len() - t.trim_end_matches('0').len())
        .min()
        .unwrap_or(0);
    let trim = nzeros.min(5);

    texts
        .iter()
        .map(|text| {
            let chars: Vec<char> = text.chars().collect();
            // text[0 if text[0] != '0' else 1 : -min(nzeros, 5)]
            let start = if chars.first() == Some(&'0') { 1 } else { 0 };
            // Python slice with negative stop: end index counted from the end.
            let end = chars.len().saturating_sub(trim);
            if start >= end {
                String::new()
            } else {
                chars[start..end].iter().collect()
            }
        })
        .collect()
}

#[cfg(test)]
mod tests {
    use super::*;

    fn close(a: f64, b: f64, tol: f64) -> bool {
        (a - b).abs() <= tol
    }

    #[test]
    fn civil_epoch_round_trip_known_dates() {
        // (epoch seconds, expected civil). Values cross-checked against known
        // UTC instants.
        let cases = [
            (0.0_f64, (1970, 1, 1, 0, 0, 0)),
            (86_400.0, (1970, 1, 2, 0, 0, 0)),
            // 2000-02-29 (leap day) 12:30:45 UTC.
            (951_827_445.0, (2000, 2, 29, 12, 30, 45)),
            // 2021-01-01 00:00:00 UTC.
            (1_609_459_200.0, (2021, 1, 1, 0, 0, 0)),
            // 2024-02-29 (leap day) 23:59:59 UTC.
            (1_709_251_199.0, (2024, 2, 29, 23, 59, 59)),
        ];
        for (epoch, (y, m, d, hh, mm, ss)) in cases {
            let dt = DateTime::from_epoch_seconds(epoch);
            assert_eq!(
                (dt.year, dt.month, dt.day, dt.hour, dt.minute, dt.second),
                (y, m, d, hh, mm, ss),
                "decompose {epoch}"
            );
            // And the round-trip back is exact.
            assert!(
                close(dt.to_epoch_seconds(), epoch, 1e-6),
                "round-trip {epoch}"
            );
        }
    }

    #[test]
    fn civil_round_trip_before_epoch() {
        // Negative timestamp: 1969-12-31 23:59:59 UTC.
        let dt = DateTime::from_epoch_seconds(-1.0);
        assert_eq!(
            (dt.year, dt.month, dt.day, dt.hour, dt.minute, dt.second),
            (1969, 12, 31, 23, 59, 59)
        );
        assert!(close(dt.to_epoch_seconds(), -1.0, 1e-6));
    }

    #[test]
    fn civil_to_epoch_for_leap_day() {
        // 2000-02-29 is day 11016 from epoch; verify both directions.
        let days = days_from_civil(2000, 2, 29);
        assert_eq!(civil_from_days(days), (2000, 2, 29));
        let dt = DateTime::from_civil(2000, 2, 29, 0, 0, 0, 0);
        assert_eq!(dt.to_epoch_seconds(), days as f64 * SECONDS_PER_DAY);
    }

    #[test]
    fn best_unit_picks_day_for_a_week() {
        // ~7-day range -> DAYS (between 2 days and 2 months threshold).
        let (count, unit) = best_unit(7.0 * SECONDS_PER_DAY);
        assert_eq!(unit, DtUnit::Days);
        assert!(close(count, 7.0, 1e-9), "count={count}");
    }

    #[test]
    fn best_unit_picks_hour_for_six_hours() {
        // ~6-hour range -> HOURS (between 2 hours and 2 days threshold).
        let (count, unit) = best_unit(6.0 * SECONDS_PER_HOUR);
        assert_eq!(unit, DtUnit::Hours);
        assert!(close(count, 6.0, 1e-9), "count={count}");
    }

    #[test]
    fn best_unit_boundary_units() {
        // Each branch boundary: just over the threshold selects the coarser unit.
        assert_eq!(best_unit(SECONDS_PER_YEAR * 3.0 + 1.0).1, DtUnit::Years);
        assert_eq!(
            best_unit(SECONDS_PER_MONTH_AVERAGE * 3.0 + 1.0).1,
            DtUnit::Months
        );
        assert_eq!(best_unit(SECONDS_PER_DAY * 2.0 + 1.0).1, DtUnit::Days);
        assert_eq!(best_unit(SECONDS_PER_HOUR * 2.0 + 1.0).1, DtUnit::Hours);
        assert_eq!(best_unit(SECONDS_PER_MINUTE * 2.0 + 1.0).1, DtUnit::Minutes);
        assert_eq!(best_unit(2.0 + 0.5).1, DtUnit::Seconds);
        // <= 2 seconds falls through to microseconds.
        assert_eq!(best_unit(1.0).1, DtUnit::MicroSeconds);
        assert_eq!(best_unit(0.0).1, DtUnit::MicroSeconds);
    }

    #[test]
    fn calc_ticks_endpoints_bracket_the_range() {
        // A one-week window starting at 2021-01-04 00:00:00 UTC.
        let min = DateTime::from_civil(2021, 1, 4, 0, 0, 0, 0).to_epoch_seconds();
        let max = DateTime::from_civil(2021, 1, 11, 0, 0, 0, 0).to_epoch_seconds();
        let (ticks, _spacing, unit) = calc_ticks(min, max, 5);
        assert_eq!(unit, DtUnit::Days);
        assert!(ticks.len() >= 2, "ticks={ticks:?}");
        // First tick at or below min, last tick at or beyond max (brackets range).
        assert!(ticks[0] <= min + 1e-6, "first {} > min {min}", ticks[0]);
        assert!(
            *ticks.last().unwrap() >= max - 1e-6,
            "last {} < max {max}",
            ticks.last().unwrap()
        );
        // Ticks are strictly increasing.
        for w in ticks.windows(2) {
            assert!(w[1] > w[0], "non-increasing: {:?}", w);
        }
    }

    #[test]
    fn calc_ticks_six_hour_window_uses_hours() {
        let min = DateTime::from_civil(2021, 6, 1, 8, 0, 0, 0).to_epoch_seconds();
        let max = DateTime::from_civil(2021, 6, 1, 14, 0, 0, 0).to_epoch_seconds();
        let (ticks, _spacing, unit) = calc_ticks(min, max, 6);
        assert_eq!(unit, DtUnit::Hours);
        assert!(ticks[0] <= min + 1e-6);
        assert!(*ticks.last().unwrap() >= max - 1e-6);
    }

    #[test]
    fn calc_ticks_degenerate_range_is_total() {
        // min == max: silx returns the microsecond fallback; must not loop.
        let t = DateTime::from_civil(2021, 1, 1, 0, 0, 0, 0).to_epoch_seconds();
        let (ticks, spacing, unit) = calc_ticks(t, t, 5);
        assert_eq!(unit, DtUnit::MicroSeconds);
        assert_eq!(spacing, 1.0);
        // include_first_beyond emits the single start tick.
        assert_eq!(ticks.len(), 1);
        assert!(close(ticks[0], t, 1e-6));
    }

    #[test]
    fn nice_num_generic_matches_default_fractions() {
        // With default-style fractions [1,2,5,10] and isRound=false, frac<=1 -> 1.
        let v = nice_num_generic(1.0, &[1.0, 2.0, 5.0, 10.0], false);
        assert!(close(v, 1.0, 1e-12), "v={v}");
        // 7 rounds up to 10 (frac 7 > 5).
        let v = nice_num_generic(7.0, &[1.0, 2.0, 5.0, 10.0], false);
        assert!(close(v, 10.0, 1e-12), "v={v}");
        // 3 with isRound: thresholds become [1.5, 3.5, 7.5, 10]; 3 <= 3.5 -> 2.
        let v = nice_num_generic(3.0, &[1.0, 2.0, 5.0, 10.0], true);
        assert!(close(v, 2.0, 1e-12), "v={v}");
    }

    #[test]
    fn nice_date_time_element_floors_years_to_one() {
        // A sub-1 nice year value is clamped up to 1.
        let v = nice_date_time_element(0.3, DtUnit::Years, true);
        assert_eq!(v, 1.0);
    }

    #[test]
    fn format_tick_day_unit_is_iso_date() {
        // Days unit, spacing >= 1 -> "%Y-%m-%d".
        let t = DateTime::from_civil(2021, 3, 9, 13, 5, 0, 0).to_epoch_seconds();
        assert_eq!(format_tick(t, 1.0, DtUnit::Days), "2021-03-09");
    }

    #[test]
    fn format_tick_hours_is_hh_mm() {
        let t = DateTime::from_civil(2021, 3, 9, 13, 5, 0, 0).to_epoch_seconds();
        assert_eq!(format_tick(t, 1.0, DtUnit::Hours), "13:05");
    }

    #[test]
    fn format_ticks_microseconds_strips_shared_trailing_zeros() {
        // Two ticks at .100000 and .200000 -> shared 5 trailing zeros stripped,
        // and the leading '0' of the seconds field dropped.
        let base = DateTime::from_civil(2021, 1, 1, 0, 0, 0, 100_000).to_epoch_seconds();
        let t2 = DateTime::from_civil(2021, 1, 1, 0, 0, 0, 200_000).to_epoch_seconds();
        let out = format_ticks(&[base, t2], 0.5, DtUnit::MicroSeconds);
        // Raw labels: "00.100000", "00.200000". Min trailing zeros = 5 (capped).
        // Leading '0' dropped -> start at index 1; trim 5 from the end.
        // "00.100000"[1..len-5] = "0.100000"[.. ] => "0.1" .. let's assert content.
        assert_eq!(out, vec!["0.1".to_string(), "0.2".to_string()]);
    }
}