wikioxide 0.1.0

//! `{{#time:}}` — MediaWiki date/time formatting.
//!
//! A faithful, dependency-free port of the format codes handled by MediaWiki's
//! `Language::sprintfDate` (the engine behind the `#time` parser function). The
//! calendar math is pure proleptic-Gregorian arithmetic (Howard Hinnant's
//! `civil_from_days` algorithm) with floor division so pre-1970 / negative
//! timestamps round toward negative infinity like PHP's `gmdate`.
//!
//! The caller has already shifted [`format_time`]'s `unix_secs` to the instant it
//! wants rendered (UTC, or a local wall-clock via the caller's offset), so this
//! module always formats as if UTC and never applies a timezone itself.

/// The result of formatting a `{{#time:}}` string.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct TimeOutput {
    /// The rendered date/time.
    pub(crate) text: String,
    /// Whether the format string used a code this implementation does not support (the
    /// caller emits a warning and the code is left literal).
    pub(crate) unsupported: bool,
}

/// Number of seconds in a day.
const SECS_PER_DAY: i64 = 86_400;

/// English three-letter weekday abbreviations, indexed by `wday` (`0` = Sunday).
const WEEKDAY_ABBR: [&str; 7] = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];

/// English full weekday names, indexed by `wday` (`0` = Sunday).
const WEEKDAY_FULL: [&str; 7] = [
    "Sunday",
    "Monday",
    "Tuesday",
    "Wednesday",
    "Thursday",
    "Friday",
    "Saturday",
];

/// English three-letter month abbreviations, indexed by `month - 1`.
const MONTH_ABBR: [&str; 12] = [
    "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec",
];

/// English full month names, indexed by `month - 1`.
const MONTH_FULL: [&str; 12] = [
    "January",
    "February",
    "March",
    "April",
    "May",
    "June",
    "July",
    "August",
    "September",
    "October",
    "November",
    "December",
];

/// A civil (broken-down) date/time derived from a Unix timestamp, in UTC.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
struct Civil {
    /// Proleptic-Gregorian year (may be negative for years before 1 CE).
    year: i64,
    /// Month of year, `1..=12`.
    month: i64,
    /// Day of month, `1..=31`.
    day: i64,
    /// Hour of day, `0..=23`.
    hour: i64,
    /// Minute of hour, `0..=59`.
    minute: i64,
    /// Second of minute, `0..=59`.
    second: i64,
    /// Day of week, `0` = Sunday .. `6` = Saturday.
    wday: i64,
    /// Zero-based day of year (`0` = January 1st).
    yday: i64,
    /// ISO-8601 week number, `1..=53`.
    iso_week: i64,
}

/// Converts a count of days since the Unix epoch into a `(year, month, day)` triple
/// using Hinnant's `civil_from_days`; valid across the full proleptic-Gregorian range.
fn civil_from_days(z: i64) -> (i64, i64, i64) {
    let z = z + 719_468;
    let era = if z >= 0 { z } else { z - 146_096 }.div_euclid(146_097);
    let doe = z - era * 146_097;
    let yoe = (doe - doe / 1_460 + doe / 36_524 - doe / 146_096) / 365;
    let y = yoe + era * 400;
    let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
    let mp = (5 * doy + 2) / 153;
    let d = doy - (153 * mp + 2) / 5 + 1;
    let m = if mp < 10 { mp + 3 } else { mp - 9 };
    (y + i64::from(m <= 2), m, d)
}

/// Inverse of [`civil_from_days`]: the day count since the Unix epoch for a civil date.
fn days_from_civil(y: i64, m: i64, d: i64) -> i64 {
    let y = y - i64::from(m <= 2);
    let era = if y >= 0 { y } else { y - 399 }.div_euclid(400);
    let yoe = y - era * 400;
    let mp = if m > 2 { m - 3 } else { m + 9 };
    let doy = (153 * mp + 2) / 5 + d - 1;
    let doe = yoe * 365 + yoe / 4 - yoe / 100 + doy;
    era * 146_097 + doe - 719_468
}

/// Whether `year` is a Gregorian leap year.
fn is_leap(year: i64) -> bool {
    (year % 4 == 0 && year % 100 != 0) || year % 400 == 0
}

/// Number of days in `month` (`1..=12`) of `year`.
fn days_in_month(year: i64, month: i64) -> i64 {
    match month {
        1 | 3 | 5 | 7 | 8 | 10 | 12 => 31,
        4 | 6 | 9 | 11 => 30,
        _ => {
            if is_leap(year) {
                29
            } else {
                28
            }
        }
    }
}

/// The unbounded ISO week number a date maps to, before year-boundary correction.
///
/// For dates in the first/last days of a year this can fall outside `1..=weeks_in_year`,
/// which [`iso_week`] then reassigns to the neighbouring ISO year.
fn raw_iso_week(y: i64, m: i64, d: i64) -> i64 {
    let z = days_from_civil(y, m, d);
    let wday = (z.rem_euclid(7) + 4) % 7;
    let iso_wd = if wday == 0 { 7 } else { wday };
    let doy1 = z - days_from_civil(y, 1, 1) + 1;
    (doy1 - iso_wd + 10).div_euclid(7)
}

/// Number of ISO weeks in `year` (either 52 or 53); December 28th is always in the
/// final ISO week of its year, so its raw week count is the year's week count.
fn weeks_in_year(year: i64) -> i64 {
    raw_iso_week(year, 12, 28)
}

/// The ISO-8601 week number for a date, corrected across year boundaries.
fn iso_week(y: i64, m: i64, d: i64) -> i64 {
    let raw = raw_iso_week(y, m, d);
    if raw < 1 {
        weeks_in_year(y - 1)
    } else if raw > weeks_in_year(y) {
        1
    } else {
        raw
    }
}

/// Breaks a Unix timestamp down into its UTC civil components.
fn civil_from_unix(unix_secs: i64) -> Civil {
    let days = unix_secs.div_euclid(SECS_PER_DAY);
    let secs = unix_secs.rem_euclid(SECS_PER_DAY);
    let (year, month, day) = civil_from_days(days);
    let wday = (days.rem_euclid(7) + 4) % 7;
    let yday = days - days_from_civil(year, 1, 1);
    Civil {
        year,
        month,
        day,
        hour: secs / 3_600,
        minute: (secs % 3_600) / 60,
        second: secs % 60,
        wday,
        yday,
        iso_week: iso_week(year, month, day),
    }
}

/// Formats `year` as a decimal padded to at least four digits (PHP `Y` semantics).
fn format_year(year: i64) -> String {
    if year < 0 {
        format!("-{:04}", -year)
    } else {
        format!("{year:04}")
    }
}

/// Maps a 24-hour hour to its 12-hour clock value (`0` and `12` both become `12`).
fn hour12(hour: i64) -> i64 {
    let h = hour % 12;
    if h == 0 { 12 } else { h }
}

/// Renders a single supported single-character format code into `out`.
///
/// Returns `true` if `code` was a recognised, supported code (and something was
/// written); `false` if `code` is not a supported single-char code, leaving `out`
/// untouched so the caller can decide between "literal" and "unsupported".
fn render_code(code: char, c: &Civil, unix_secs: i64, out: &mut String) -> bool {
    match code {
        'Y' => out.push_str(&format_year(c.year)),
        'y' => out.push_str(&format!("{:02}", c.year.rem_euclid(100))),
        'n' => out.push_str(&c.month.to_string()),
        'm' => out.push_str(&format!("{:02}", c.month)),
        'M' => out.push_str(MONTH_ABBR[(c.month - 1) as usize]),
        'F' => out.push_str(MONTH_FULL[(c.month - 1) as usize]),
        'j' => out.push_str(&c.day.to_string()),
        'd' => out.push_str(&format!("{:02}", c.day)),
        'z' => out.push_str(&c.yday.to_string()),
        'D' => out.push_str(WEEKDAY_ABBR[c.wday as usize]),
        'l' => out.push_str(WEEKDAY_FULL[c.wday as usize]),
        'N' => out.push_str(&(if c.wday == 0 { 7 } else { c.wday }).to_string()),
        'w' => out.push_str(&c.wday.to_string()),
        'W' => out.push_str(&format!("{:02}", c.iso_week)),
        'H' => out.push_str(&format!("{:02}", c.hour)),
        'G' => out.push_str(&c.hour.to_string()),
        'h' => out.push_str(&format!("{:02}", hour12(c.hour))),
        'g' => out.push_str(&hour12(c.hour).to_string()),
        'i' => out.push_str(&format!("{:02}", c.minute)),
        's' => out.push_str(&format!("{:02}", c.second)),
        'A' => out.push_str(if c.hour < 12 { "AM" } else { "PM" }),
        'a' => out.push_str(if c.hour < 12 { "am" } else { "pm" }),
        'U' => out.push_str(&unix_secs.to_string()),
        'L' => out.push_str(if is_leap(c.year) { "1" } else { "0" }),
        't' => out.push_str(&days_in_month(c.year, c.month).to_string()),
        'r' => out.push_str(&format_rfc2822(c)),
        'c' => out.push_str(&format_iso8601(c)),
        _ => return false,
    }
    true
}

/// Renders the `r` code: an RFC 2822 / RFC 5322 date, always at `+0000` (UTC).
fn format_rfc2822(c: &Civil) -> String {
    format!(
        "{}, {:02} {} {} {:02}:{:02}:{:02} +0000",
        WEEKDAY_ABBR[c.wday as usize],
        c.day,
        MONTH_ABBR[(c.month - 1) as usize],
        format_year(c.year),
        c.hour,
        c.minute,
        c.second,
    )
}

/// Renders the `c` code: an ISO 8601 date-time, always at the `+00:00` offset (UTC).
fn format_iso8601(c: &Civil) -> String {
    format!(
        "{}-{:02}-{:02}T{:02}:{:02}:{:02}+00:00",
        format_year(c.year),
        c.month,
        c.day,
        c.hour,
        c.minute,
        c.second,
    )
}

/// Finds the index of the closing `"` for a double-quoted run opened at `open`.
fn find_closing_quote(chars: &[char], open: usize) -> Option<usize> {
    chars[open + 1..]
        .iter()
        .position(|&c| c == '"')
        .map(|rel| open + 1 + rel)
}

/// Whether `ch` is a MediaWiki `#time` format code that this port recognises but does
/// not implement (chiefly the timezone codes and the ISO week-year `o`). Such codes are
/// emitted literally *and* set the `unsupported` flag; any other character is a plain
/// literal.
fn is_unsupported_code(ch: char) -> bool {
    matches!(ch, 'o' | 'e' | 'I' | 'O' | 'P' | 'T' | 'Z')
}

/// Formats `unix_secs` — already adjusted to the desired instant (UTC, or local via the
/// caller's offset) — per a MediaWiki `{{#time:}}` format string.
pub(crate) fn format_time(format: &str, unix_secs: i64) -> TimeOutput {
    let c = civil_from_unix(unix_secs);
    let chars: Vec<char> = format.chars().collect();
    let mut out = String::with_capacity(format.len());
    let mut unsupported = false;
    let mut i = 0;

    while i < chars.len() {
        let ch = chars[i];
        match ch {
            // Backslash escapes the next character as a literal (a trailing backslash
            // is itself literal).
            '\\' => {
                i += 1;
                if i < chars.len() {
                    out.push(chars[i]);
                    i += 1;
                }
            }
            // A double-quoted run is emitted verbatim with the quotes removed; an
            // unmatched opening quote is treated as a literal quote character.
            '"' => {
                if let Some(close) = find_closing_quote(&chars, i) {
                    for &qc in &chars[i + 1..close] {
                        out.push(qc);
                    }
                    i = close + 1;
                } else {
                    out.push('"');
                    i += 1;
                }
            }
            // `x`-prefixed extended codes.
            'x' => {
                match chars.get(i + 1).copied() {
                    // Genitive month name — approximated to the full English name.
                    Some('g') => {
                        out.push_str(MONTH_FULL[(c.month - 1) as usize]);
                        i += 2;
                    }
                    // "Format next number raw": a no-op for ASCII output, so it simply
                    // passes through and the following code renders normally.
                    Some('n') => {
                        i += 2;
                    }
                    // `xx` is a literal `x`.
                    Some('x') => {
                        out.push('x');
                        i += 2;
                    }
                    // Any other letter is a recognised-but-unsupported extended code
                    // (roman/hebrew numerals, non-Gregorian calendars): emit both
                    // characters literally and flag it.
                    Some(l) if l.is_ascii_alphabetic() => {
                        out.push('x');
                        out.push(l);
                        unsupported = true;
                        i += 2;
                    }
                    // `x` before a non-letter (or end of string) is a literal `x`.
                    _ => {
                        out.push('x');
                        i += 1;
                    }
                }
            }
            _ => {
                if render_code(ch, &c, unix_secs, &mut out) {
                    i += 1;
                } else {
                    if is_unsupported_code(ch) {
                        unsupported = true;
                    }
                    out.push(ch);
                    i += 1;
                }
            }
        }
    }

    TimeOutput {
        text: out,
        unsupported,
    }
}

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

    /// 2000-01-01T00:00:00Z (a Saturday) — the canonical reference instant.
    const Y2K: i64 = 946_684_800;

    /// Formats and asserts on the text only, ignoring the unsupported flag.
    fn f(fmt: &str, secs: i64) -> String {
        format_time(fmt, secs).text
    }

    #[test]
    fn civil_decodes_epoch() {
        let c = civil_from_unix(0);
        assert_eq!(c.year, 1970);
        assert_eq!(c.month, 1);
        assert_eq!(c.day, 1);
        assert_eq!(c.wday, 4); // Thursday
        assert_eq!(c.yday, 0);
    }

    #[test]
    fn civil_decodes_y2k() {
        let c = civil_from_unix(Y2K);
        assert_eq!((c.year, c.month, c.day), (2000, 1, 1));
        assert_eq!((c.hour, c.minute, c.second), (0, 0, 0));
        assert_eq!(c.wday, 6); // Saturday
    }

    #[test]
    fn date_codes_match_live_api() {
        assert_eq!(f("Y-m-d", Y2K), "2000-01-01");
        assert_eq!(f("y", Y2K), "00");
        assert_eq!(f("n j", Y2K), "1 1");
        assert_eq!(f("M F", Y2K), "Jan January");
        assert_eq!(f("D l", Y2K), "Sat Saturday");
        assert_eq!(f("N w", Y2K), "6 6");
        assert_eq!(f("W z", Y2K), "52 0");
        assert_eq!(f("L t", Y2K), "1 31");
    }

    #[test]
    fn time_codes_match_live_api() {
        assert_eq!(f("H:i:s", Y2K), "00:00:00");
        assert_eq!(f("G g h", Y2K), "0 12 12");
        assert_eq!(f("A a", Y2K), "AM am");
        assert_eq!(f("U", Y2K), "946684800");
    }

    #[test]
    fn afternoon_twelve_hour_clock() {
        // 2000-01-01T13:00:00Z
        let pm = Y2K + 13 * 3_600;
        assert_eq!(f("h g H G A a", pm), "01 1 13 13 PM pm");
    }

    #[test]
    fn rfc2822_and_iso8601() {
        assert_eq!(f("r", Y2K), "Sat, 01 Jan 2000 00:00:00 +0000");
        assert_eq!(f("c", Y2K), "2000-01-01T00:00:00+00:00");
    }

    #[test]
    fn pre_1970_uses_floor_division() {
        // unix -1 == 1969-12-31T23:59:59Z, a Wednesday, day-of-year 364, ISO week 1.
        assert_eq!(
            f("Y-m-d H:i:s D N w W z", -1),
            "1969-12-31 23:59:59 Wed 3 3 01 364"
        );
    }

    #[test]
    fn leap_day_2000() {
        // 2000-02-29T00:00:00Z, a Tuesday.
        let feb29 = 951_782_400;
        assert_eq!(f("d F Y t L z N", feb29), "29 February 2000 29 1 59 2");
    }

    #[test]
    fn iso_week_year_boundary() {
        // 2021-01-04 is a Monday in ISO week 01.
        assert_eq!(f("W", 1_609_718_400), "01");
    }

    #[test]
    fn leap_year_flag_and_non_leap() {
        assert_eq!(f("L", Y2K), "1");
        // 1970 is not a leap year.
        assert_eq!(f("L", 0), "0");
        // 1900 is a century non-leap year: 1900-01-01T00:00:00Z == -2208988800.
        assert_eq!(f("L t", -2_208_988_800), "0 31");
    }

    #[test]
    fn days_in_february_leap_and_common() {
        // February 2000 (leap) vs February 2001 (common).
        assert_eq!(f("t", 949_363_200), "29"); // 2000-02-01
        assert_eq!(f("t", 980_985_600), "28"); // 2001-02-01
    }

    #[test]
    fn all_month_names_and_days() {
        // Walk the first of each month in the leap year 2000, checking M/F/t/n together.
        let expected = [
            ("Jan", "January", 31),
            ("Feb", "February", 29),
            ("Mar", "March", 31),
            ("Apr", "April", 30),
            ("May", "May", 31),
            ("Jun", "June", 30),
            ("Jul", "July", 31),
            ("Aug", "August", 31),
            ("Sep", "September", 30),
            ("Oct", "October", 31),
            ("Nov", "November", 30),
            ("Dec", "December", 31),
        ];
        let mut secs = Y2K; // 2000-01-01T00:00:00Z
        for (month, (abbr, full, days)) in expected.iter().enumerate() {
            assert_eq!(
                f("n M F t", secs),
                format!("{} {abbr} {full} {days}", month + 1)
            );
            secs += days * SECS_PER_DAY;
        }
    }

    #[test]
    fn backslash_escapes_next_char() {
        assert_eq!(f("\\Y=Y", Y2K), "Y=2000");
        // A trailing backslash is dropped (nothing to escape).
        assert_eq!(f("d\\", Y2K), "01");
    }

    #[test]
    fn double_quoted_run_is_literal() {
        assert_eq!(f("\"literal Y\"", Y2K), "literal Y");
        assert_eq!(f("Y\" at \"H", Y2K), "2000 at 00");
    }

    #[test]
    fn unmatched_quote_is_literal() {
        assert_eq!(f("Y\"m", Y2K), "2000\"01");
    }

    #[test]
    fn xg_genitive_is_full_month() {
        assert_eq!(f("xg", Y2K), "January");
    }

    #[test]
    fn xn_is_transparent_and_supported() {
        let out = format_time("xnj xnm", Y2K);
        assert_eq!(out.text, "1 01");
        assert!(!out.unsupported);
    }

    #[test]
    fn xx_digraph_is_literal_x() {
        let out = format_time("xx", Y2K);
        assert_eq!(out.text, "x");
        assert!(!out.unsupported);
    }

    #[test]
    fn x_before_non_letter_is_literal() {
        let out = format_time("x-", Y2K);
        assert_eq!(out.text, "x-");
        assert!(!out.unsupported);
        // A trailing `x` is also literal.
        assert_eq!(format_time("x", Y2K).text, "x");
    }

    #[test]
    fn extended_code_is_unsupported() {
        let out = format_time("xN", Y2K);
        assert_eq!(out.text, "xN");
        assert!(out.unsupported);
    }

    #[test]
    fn unsupported_single_codes_are_flagged() {
        for code in ['o', 'e', 'I', 'O', 'P', 'T', 'Z'] {
            let out = format_time(&code.to_string(), Y2K);
            assert_eq!(out.text, code.to_string());
            assert!(out.unsupported, "{code} should be unsupported");
        }
    }

    #[test]
    fn literal_punctuation_is_not_unsupported() {
        let out = format_time("- : / .", Y2K);
        assert_eq!(out.text, "- : / .");
        assert!(!out.unsupported);
    }

    #[test]
    fn supported_format_is_not_flagged() {
        assert!(!format_time("Y-m-d", Y2K).unsupported);
    }

    #[test]
    fn year_padding_and_negatives() {
        // Year 500 CE: 0500-01-01T00:00:00Z == -46388678400.
        assert_eq!(f("Y", -46_388_678_400), "0500");
        // 2-digit year of 2021.
        assert_eq!(f("y", 1_609_718_400), "21");
    }

    #[test]
    fn negative_year_formats_with_sign() {
        // format_year is exercised directly for a BCE year.
        assert_eq!(format_year(-44), "-0044");
        assert_eq!(format_year(12_345), "12345");
    }

    #[test]
    fn weekday_cycle_is_correct() {
        // Seven consecutive days starting at a known Saturday (Y2K).
        let expected = ["Sat", "Sun", "Mon", "Tue", "Wed", "Thu", "Fri"];
        for (offset, name) in expected.iter().enumerate() {
            assert_eq!(
                f("D l N w", Y2K + offset as i64 * SECS_PER_DAY)
                    .split(' ')
                    .next()
                    .unwrap(),
                *name
            );
        }
    }

    #[test]
    fn iso_weekday_and_full_names_all_days() {
        // Sun..Sat across a week; checks l, N, w for every weekday index.
        let expected = [
            ("Sunday", "7", "0"),
            ("Monday", "1", "1"),
            ("Tuesday", "2", "2"),
            ("Wednesday", "3", "3"),
            ("Thursday", "4", "4"),
            ("Friday", "5", "5"),
            ("Saturday", "6", "6"),
        ];
        // 2000-01-02 is a Sunday.
        let sunday = Y2K + SECS_PER_DAY;
        for (offset, (full, n, w)) in expected.iter().enumerate() {
            assert_eq!(
                f("l N w", sunday + offset as i64 * SECS_PER_DAY),
                format!("{full} {n} {w}")
            );
        }
    }

    #[test]
    fn day_of_year_end_of_year() {
        // 2000-12-31 is day-of-year 365 (2000 is a leap year).
        assert_eq!(f("z", 978_220_800), "365");
    }

    #[test]
    fn iso_week_53_year() {
        // 2020-12-31 is a Thursday in ISO week 53.
        assert_eq!(f("W", 1_609_372_800), "53");
    }

    #[test]
    fn empty_format_is_empty() {
        let out = format_time("", Y2K);
        assert_eq!(out.text, "");
        assert!(!out.unsupported);
    }

    #[test]
    fn days_in_month_all_lengths() {
        assert_eq!(days_in_month(2001, 4), 30);
        assert_eq!(days_in_month(2001, 1), 31);
        assert_eq!(days_in_month(2000, 2), 29);
        assert_eq!(days_in_month(2001, 2), 28);
    }
}