gedcomkit 0.1.2

//! Reading a GEDCOM date payload without ever rewriting it.
//!
//! The payload is preserved exactly and parsed into a
//! structured view beside it, used for sorting, timelines, and plausibility
//! checks. An expression the parser does not understand keeps its text, is
//! marked [`DateKind::Unparsed`], is still displayed, and is never coerced.
//!
//! The forms below are not taken from the specification alone. Public
//! compatibility corpora contain many date shapes beyond the specification's
//! own `5 JAN 1882`. Files hold `5 January 1882`, `4 juillet 1764`, `21. Januar 1809`,
//! `rundt 1645`, `8.2.1664`, `Feb 11 th 1809`, `about May 1703`, `<1802>`,
//! `Infant`, and `DEAD`. Anything a genealogist typed once is in there
//! somewhere, so the parser is generous where it can be certain and honest
//! where it cannot.

use crate::Node;
use std::fmt;

/// The calendar a date is expressed in.
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
#[non_exhaustive]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
pub enum Calendar {
    /// The default when nothing says otherwise.
    #[default]
    Gregorian,
    /// `@#DJULIAN@` in 5.5.1, `JULIAN` in 7.0.
    Julian,
    /// `@#DHEBREW@` / `HEBREW`.
    Hebrew,
    /// `@#DFRENCH R@` / `FRENCH_R`.
    FrenchRepublican,
    /// `@#DROMAN@`, which no producer in the corpus emits.
    Roman,
    /// A calendar escape the reader does not recognize, kept as written.
    Unknown,
}

impl Calendar {
    /// The name to show a user.
    #[must_use]
    pub const fn label(self) -> &'static str {
        match self {
            Self::Gregorian => "Gregorian",
            Self::Julian => "Julian",
            Self::Hebrew => "Hebrew",
            Self::FrenchRepublican => "French Republican",
            Self::Roman => "Roman",
            Self::Unknown => "unrecognized calendar",
        }
    }
}

/// What kind of claim the expression makes about when something happened.
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
#[non_exhaustive]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
pub enum DateKind {
    /// A single date, as precisely as it was given.
    #[default]
    Exact,
    /// `ABT`, and the several dozen ways files spell "about".
    About,
    /// `CAL` — worked out from another date.
    Calculated,
    /// `EST` — a guess the recorder owned up to.
    Estimated,
    /// `BEF`.
    Before,
    /// `AFT`.
    After,
    /// `BET … AND …`.
    Between,
    /// `FROM … TO …`, or either half alone.
    Period,
    /// `INT` — someone's reading of an unclear original.
    Interpreted,
    /// The parser could not read it. The text is still there.
    Unparsed,
}

impl DateKind {
    /// The word to put in front of the date when showing it.
    #[must_use]
    pub const fn label(self) -> &'static str {
        match self {
            Self::Exact => "",
            Self::About => "about",
            Self::Calculated => "calculated",
            Self::Estimated => "estimated",
            Self::Before => "before",
            Self::After => "after",
            Self::Between => "between",
            Self::Period => "during",
            Self::Interpreted => "interpreted as",
            Self::Unparsed => "as written",
        }
    }
}

/// How much of a date is known.
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq, Ord, PartialOrd)]
#[non_exhaustive]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
pub enum Precision {
    /// Nothing usable was recovered.
    #[default]
    None,
    /// A year.
    Year,
    /// A year and a month.
    Month,
    /// A year, a month, and a day.
    Day,
}

/// A point on the calendar, to whatever precision was given.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))]
pub struct DatePoint {
    /// The year. Negative for years before the common era.
    pub year: i32,
    /// The month, 1–12, when given.
    pub month: Option<u8>,
    /// The day, 1–31, when given.
    pub day: Option<u8>,
}

impl DatePoint {
    const fn year(year: i32) -> Self {
        Self {
            year,
            month: None,
            day: None,
        }
    }

    /// A point built by a caller, for writing a date the file does not yet
    /// hold. `None` when the pieces cannot be a calendar date: a month
    /// outside 1–12, a day outside 1–31, or a day given without its month.
    #[must_use]
    pub fn from_ymd(year: i32, month: Option<u8>, day: Option<u8>) -> Option<Self> {
        if let Some(month) = month
            && !(1..=12).contains(&month)
        {
            return None;
        }
        match day {
            Some(_) if month.is_none() => return None,
            Some(day) if !(1..=31).contains(&day) => return None,
            _ => (),
        }
        Some(Self { year, month, day })
    }

    /// The point as a GEDCOM `DATE` payload: `5 JAN 1882`, `JAN 1882`, or
    /// `1882` — the specification's own spelling, which both 5.5.1 and 7.0
    /// accept. This is the inverse the parser lacks by design: reading never
    /// rewrites a payload, so producing one is an explicit act.
    ///
    /// A negative year renders with GEDCOM 7's `BCE` epoch (`44 BCE`), which
    /// 5.5.1 has no spelling for.
    ///
    /// ```
    /// use gedcomkit::dates::DatePoint;
    ///
    /// let point = DatePoint::from_ymd(1882, Some(1), Some(5)).expect("valid");
    /// assert_eq!(point.to_gedcom(), "5 JAN 1882");
    /// assert_eq!(format!("ABT {}", DatePoint::from_ymd(1900, None, None).expect("valid").to_gedcom()), "ABT 1900");
    /// ```
    #[must_use]
    pub fn to_gedcom(&self) -> String {
        let (era_year, era) = if self.year < 0 {
            (-self.year, " BCE")
        } else {
            (self.year, "")
        };
        match (self.month, self.day) {
            (Some(month), Some(day)) => {
                format!("{day} {} {era_year}{era}", month_abbreviation(month))
            }
            (Some(month), None) => format!("{} {era_year}{era}", month_abbreviation(month)),
            _ => format!("{era_year}{era}"),
        }
    }

    /// How much of this point is known.
    #[must_use]
    pub const fn precision(&self) -> Precision {
        match (self.month, self.day) {
            (Some(_), Some(_)) => Precision::Day,
            (Some(_), None) => Precision::Month,
            _ => Precision::Year,
        }
    }

    /// A single number that orders points correctly, with an absent month or
    /// day sorting to the start of its period.
    #[must_use]
    pub fn sort_key(&self) -> i64 {
        let month = self.month.map_or(0, i64::from);
        let day = self.day.map_or(0, i64::from);
        i64::from(self.year) * 10_000 + month * 100 + day
    }
}

impl fmt::Display for DatePoint {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        match (self.month, self.day) {
            (Some(month), Some(day)) => {
                write!(formatter, "{day} {} {}", month_name(month), self.year)
            }
            (Some(month), None) => write!(formatter, "{} {}", month_name(month), self.year),
            _ => write!(formatter, "{}", self.year),
        }
    }
}

/// A GEDCOM date payload, read.
#[derive(Clone, Debug, Eq, PartialEq)]
#[non_exhaustive]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))]
pub struct GedcomDate {
    /// The payload exactly as the file wrote it. Never modified.
    pub original: String,
    /// The calendar, Gregorian unless an escape says otherwise.
    pub calendar: Calendar,
    /// What kind of claim the expression makes.
    pub kind: DateKind,
    /// The earliest instant the expression admits, when one was recovered.
    pub earliest: Option<DatePoint>,
    /// The latest instant the expression admits, when one was recovered. Equal
    /// to `earliest` for an exact date.
    pub latest: Option<DatePoint>,
    /// Text the expression carried that is not part of the date: a 7.0
    /// `PHRASE`, a parenthesized 5.5.1 phrase, or the whole payload when it
    /// could not be read at all.
    pub phrase: Option<String>,
}

impl GedcomDate {
    /// Reads a `DATE` payload.
    ///
    /// ```
    /// use gedcomkit::dates::{DateKind, GedcomDate};
    ///
    /// let date = GedcomDate::parse("ABT 5 January 1882");
    /// assert_eq!(date.kind, DateKind::About);
    /// assert_eq!(date.year_hint(), Some(1882));
    /// assert_eq!(date.display(), "about 5 January 1882");
    /// // The payload itself is never rewritten.
    /// assert_eq!(date.original, "ABT 5 January 1882");
    ///
    /// // What cannot be read says so and keeps its text.
    /// assert_eq!(GedcomDate::parse("Infant").kind, DateKind::Unparsed);
    /// ```
    #[must_use]
    pub fn parse(payload: &str) -> Self {
        let original = payload.to_owned();
        let (calendar, rest) = split_calendar(payload.trim());
        let (rest, phrase) = split_phrase(&rest);
        let mut date = parse_expression(&rest).unwrap_or_else(|| Self {
            original: original.clone(),
            calendar,
            kind: DateKind::Unparsed,
            earliest: None,
            latest: None,
            phrase: Some(payload.trim().to_owned()),
        });
        date.original = original;
        date.calendar = calendar;
        if let Some(phrase) = phrase {
            date.phrase = Some(phrase);
        }
        date
    }

    /// Whether anything usable was recovered.
    #[must_use]
    pub const fn is_parsed(&self) -> bool {
        !matches!(self.kind, DateKind::Unparsed)
    }

    /// How much of the date is known.
    #[must_use]
    pub fn precision(&self) -> Precision {
        self.earliest
            .map_or(Precision::None, |point| point.precision())
    }

    /// The year to file this date under, for a timeline or a sort.
    ///
    /// An unparsed expression still offers one when it contains something that
    /// can only be a year: `19 Jun 1820 age 26` files under 1820. That is a
    /// hint, not a reading, and the interface must not present it as the date.
    #[must_use]
    pub fn year_hint(&self) -> Option<i32> {
        if let Some(point) = self.earliest {
            return Some(point.year);
        }
        four_digit_year(&self.original)
    }

    /// A single number that orders dates on a timeline, or `None` when nothing
    /// orderable was found.
    #[must_use]
    pub fn sort_key(&self) -> Option<i64> {
        self.earliest
            .map(|point| point.sort_key())
            .or_else(|| self.year_hint().map(|year| i64::from(year) * 10_000))
    }

    /// The date in the interface's own words, for a caller that wants one
    /// string. The original payload stays available and is what an editor
    /// shows.
    #[must_use]
    pub fn display(&self) -> String {
        match (self.kind, self.earliest, self.latest) {
            (DateKind::Unparsed, ..) => self.original.trim().to_owned(),
            (DateKind::Exact, Some(point), _) => point.to_string(),
            (DateKind::Between, Some(from), Some(to)) => format!("between {from} and {to}"),
            (DateKind::Period, Some(from), Some(to)) => format!("from {from} to {to}"),
            (DateKind::Period, Some(from), None) => format!("from {from}"),
            (DateKind::Period, None, Some(to)) => format!("to {to}"),
            (kind, Some(point), _) | (kind, None, Some(point)) => {
                format!("{} {point}", kind.label())
            }
            _ => self.original.trim().to_owned(),
        }
    }
}

fn parse_expression(input: &str) -> Option<GedcomDate> {
    let trimmed = input.trim();
    if trimmed.is_empty() {
        return None;
    }

    let build = |kind: DateKind, earliest: Option<DatePoint>, latest: Option<DatePoint>| {
        Some(GedcomDate {
            original: String::new(),
            calendar: Calendar::Gregorian,
            kind,
            earliest,
            latest,
            phrase: None,
        })
    };

    // Two-sided forms first: `BET x AND y`, `FROM x TO y`. The separators are
    // matched case-insensitively and in every spelling the corpus shows.
    if let Some((left, right)) = split_keyword(trimmed, &["AND"])
        && let Some(prefix) = strip_keyword(left, &["BET", "BETWEEN", "ENTRE", "ZWISCHEN"])
    {
        let from = parse_point(prefix);
        let to = parse_point(right);
        if from.is_some() || to.is_some() {
            return build(DateKind::Between, from, to);
        }
    }
    if let Some((left, right)) = split_keyword(trimmed, &["TO"])
        && let Some(prefix) = strip_keyword(left, &["FROM", "DE", "VON"])
    {
        let from = parse_point(prefix);
        let to = parse_point(right);
        if from.is_some() || to.is_some() {
            return build(DateKind::Period, from, to);
        }
    }

    // `FROM x` opens an interval and `TO x` closes one, so neither fits the
    // generic prefix loop below.
    if let Some(rest) = strip_keyword(trimmed, &["FROM", "SINCE"]) {
        return build(DateKind::Period, parse_point(rest), None);
    }
    if let Some(rest) = strip_keyword(trimmed, &["TO", "UNTIL"]) {
        return build(DateKind::Period, None, parse_point(rest));
    }

    // One-sided prefixes.
    for (kind, words) in PREFIXES {
        if let Some(rest) = strip_keyword(trimmed, words) {
            let point = parse_point(rest)?;
            return match kind {
                DateKind::Before => build(DateKind::Before, None, Some(point)),
                DateKind::After => build(DateKind::After, Some(point), None),
                other => build(*other, Some(point), Some(point)),
            };
        }
    }

    // `<1802>` is one producer's way of saying "uncertain".
    if let Some(inner) = trimmed
        .strip_prefix('<')
        .and_then(|rest| rest.strip_suffix('>'))
    {
        let point = parse_point(inner)?;
        return build(DateKind::About, Some(point), Some(point));
    }

    let point = parse_point(trimmed)?;
    build(DateKind::Exact, Some(point), Some(point))
}

/// Prefixes in every spelling the surveyed exports show, English first.
/// A trailing full stop is handled by the matcher, not listed here.
const PREFIXES: &[(DateKind, &[&str])] = &[
    (
        DateKind::About,
        &[
            "ABT",
            "ABOUT",
            "CIRCA",
            "CA",
            "APPROX",
            "ENVIRON",
            "UM",
            "RUNDT",
            "OMKRING",
            "CERCA",
            "VERSO",
            "PROBABLEMENT",
        ],
    ),
    (DateKind::Calculated, &["CAL", "CALCULATED"]),
    (DateKind::Estimated, &["EST", "ESTIMATED"]),
    (
        DateKind::Before,
        &["BEF", "BEFORE", "AVANT", "VOR", "PRIMA", "ANTES"],
    ),
    (
        DateKind::After,
        &["AFT", "AFTER", "APRES", "APRÈS", "NACH", "DOPO", "DESPUES"],
    ),
    (DateKind::Interpreted, &["INT", "INTERPRETED"]),
];

/// Splits off a calendar escape. 5.5.1 writes `@#DJULIAN@`, 7.0 writes the
/// name as a bare word.
fn split_calendar(input: &str) -> (Calendar, String) {
    if let Some(rest) = input.strip_prefix("@#D")
        && let Some((name, remainder)) = rest.split_once('@')
    {
        return (calendar_from(name), remainder.trim().to_owned());
    }
    for (name, calendar) in [
        ("GREGORIAN", Calendar::Gregorian),
        ("JULIAN", Calendar::Julian),
        ("HEBREW", Calendar::Hebrew),
        ("FRENCH_R", Calendar::FrenchRepublican),
        ("ROMAN", Calendar::Roman),
    ] {
        if let Some(rest) = input.strip_prefix(name)
            && rest.starts_with(' ')
        {
            return (calendar, rest.trim().to_owned());
        }
    }
    (Calendar::Gregorian, input.to_owned())
}

fn calendar_from(name: &str) -> Calendar {
    match name.trim().to_ascii_uppercase().as_str() {
        "GREGORIAN" => Calendar::Gregorian,
        "JULIAN" => Calendar::Julian,
        "HEBREW" => Calendar::Hebrew,
        "FRENCH R" | "FRENCH_R" => Calendar::FrenchRepublican,
        "ROMAN" => Calendar::Roman,
        _ => Calendar::Unknown,
    }
}

/// Splits off a 5.5.1 parenthesized phrase, which may be the whole payload.
fn split_phrase(input: &str) -> (String, Option<String>) {
    let trimmed = input.trim();
    let Some(open) = trimmed.find('(') else {
        return (trimmed.to_owned(), None);
    };
    let Some(close) = trimmed.rfind(')') else {
        return (trimmed.to_owned(), None);
    };
    if close < open {
        return (trimmed.to_owned(), None);
    }
    let phrase = trimmed[open + 1..close].trim().to_owned();
    let rest = format!("{} {}", &trimmed[..open], &trimmed[close + 1..]);
    (
        rest.trim().to_owned(),
        (!phrase.is_empty()).then_some(phrase),
    )
}

/// Finds a bare keyword used as a separator, case-insensitively.
fn split_keyword<'a>(input: &'a str, words: &[&str]) -> Option<(&'a str, &'a str)> {
    let upper = input.to_ascii_uppercase();
    for word in words {
        let needle = format!(" {word} ");
        if let Some(position) = upper.find(&needle) {
            return Some((&input[..position], &input[position + needle.len()..]));
        }
    }
    None
}

/// Strips a leading keyword, with or without a trailing full stop.
fn strip_keyword<'a>(input: &'a str, words: &[&str]) -> Option<&'a str> {
    let trimmed = input.trim();
    let upper = trimmed.to_ascii_uppercase();
    for word in words {
        for suffix in [" ", ". ", "."] {
            let needle = format!("{word}{suffix}");
            if upper.len() > needle.len() && upper.starts_with(&needle) {
                let rest = trimmed[needle.len()..].trim();
                if !rest.is_empty() {
                    return Some(rest);
                }
            }
        }
    }
    None
}

/// Reads one point: a year, a month and year, or a day, month, and year.
fn parse_point(input: &str) -> Option<DatePoint> {
    let cleaned = input.trim().trim_end_matches([',', '.', ';']).trim();
    if cleaned.is_empty() {
        return None;
    }

    // GEDCOM 7's epoch: `44 BCE` is the year before 43 BCE. The point's year
    // is negated, which is exactly what [`DatePoint::to_gedcom`] writes back.
    if let Some(rest) = cleaned
        .strip_suffix("BCE")
        .or_else(|| cleaned.strip_suffix("bce"))
        .map(str::trim_end)
        .filter(|rest| !rest.is_empty())
    {
        let mut point = parse_point(rest)?;
        point.year = -point.year;
        return Some(point);
    }

    // `8.2.1664` and `4/18/1616`. Both appear in the corpus; the first is
    // day-first European and the second is month-first American, and the only
    // way to tell them apart is the separator, which is what producers use.
    if let Some(point) = parse_numeric(cleaned) {
        return Some(point);
    }

    // A dual year — `1740/41`, `1679/1683` — is one day written under two
    // calendars, not two dates. The historical year is the first.
    if let Some(point) = parse_dual_year(cleaned) {
        return Some(point);
    }

    // Producers lose the space between pieces — `19JUL1818`, `21 Nov1896`,
    // and `5 Novem1886` all appear in real exports — so a run of
    // digits and a run of letters are separated before anything is matched.
    let tokens: Vec<String> = cleaned
        .split([' ', '\u{a0}', ','])
        .flat_map(split_runs)
        .filter(|token| {
            !matches!(
                token.to_ascii_lowercase().as_str(),
                "de" | "of" | "den" | "le"
            )
        })
        .collect();
    let tokens: Vec<&str> = tokens.iter().map(String::as_str).collect();

    match tokens.as_slice() {
        [year] => parse_year(year).map(DatePoint::year),
        [month, year] => {
            let year = parse_year(year)?;
            Some(DatePoint {
                year,
                month: Some(month_number(month)?),
                day: None,
            })
        }
        [first, second, year] => {
            let year = parse_year(year)?;
            // Day-first is tried first because `5 January 1882` would
            // otherwise read its `5` as May.
            let (month, day) = month_number(second).map_or_else(
                || month_number(first).map(|month| (month, second)),
                |month| Some((month, first)),
            )?;
            Some(DatePoint {
                year,
                month: Some(month),
                day: Some(parse_day(day)?),
            })
        }
        [first, second, third, fourth] => {
            // `Feb 11 th 1809`, and `April 15 , 1873` once punctuation splits.
            let year = parse_year(fourth)?;
            let month = month_number(first).or_else(|| month_number(second))?;
            let day = parse_day(second).or_else(|| parse_day(third))?;
            Some(DatePoint {
                year,
                month: Some(month),
                day: Some(day),
            })
        }
        _ => None,
    }
}

fn parse_numeric(input: &str) -> Option<DatePoint> {
    for (separator, month_first) in [('.', false), ('/', true), ('-', false)] {
        let parts: Vec<&str> = input.split(separator).collect();
        if parts.len() != 3 {
            continue;
        }
        if !parts
            .iter()
            .all(|part| !part.is_empty() && part.bytes().all(|byte| byte.is_ascii_digit()))
        {
            continue;
        }
        // A four-digit first part is a year, whatever the separator: ISO order.
        if parts[0].len() == 4 {
            let year = parts[0].parse::<i32>().ok()?;
            return Some(DatePoint {
                year,
                month: parse_month_number(parts[1]),
                day: parse_day(parts[2]),
            });
        }
        let year = parse_year(parts[2])?;
        let (day, month) = if month_first {
            (parts[1], parts[0])
        } else {
            (parts[0], parts[1])
        };
        return Some(DatePoint {
            year,
            month: parse_month_number(month),
            day: parse_day(day),
        });
    }
    None
}

/// `1740/41` and `1679/1683`: the Julian and Gregorian readings of one year.
fn parse_dual_year(input: &str) -> Option<DatePoint> {
    let (first, second) = input.split_once('/')?;
    let digits = |value: &str| !value.is_empty() && value.bytes().all(|byte| byte.is_ascii_digit());
    if !digits(first) || !digits(second) || !(3..=4).contains(&first.len()) {
        return None;
    }
    Some(DatePoint::year(first.parse::<i32>().ok()?))
}

/// Splits a token at every boundary between digits and non-digits, dropping
/// anything that is only punctuation.
fn split_runs(token: &str) -> Vec<String> {
    let mut runs = Vec::new();
    let mut current = String::new();
    let mut in_digits = false;
    for character in token.chars() {
        let digit = character.is_ascii_digit();
        if !current.is_empty() && digit != in_digits {
            runs.push(std::mem::take(&mut current));
        }
        in_digits = digit;
        current.push(character);
    }
    if !current.is_empty() {
        runs.push(current);
    }
    runs.retain(|run| run.chars().any(char::is_alphanumeric));
    runs
}

fn parse_year(token: &str) -> Option<i32> {
    let cleaned = token.trim_matches(|character: char| !character.is_ascii_digit());
    if cleaned.is_empty() {
        return None;
    }
    // `1740/41` and `1699/1700` are dual years: the same day under two
    // calendars. The first is the historical year and is what we file under.
    let first = cleaned.split('/').next()?;
    let year = first.parse::<i32>().ok()?;
    (0..=9999).contains(&year).then_some(year)
}

fn parse_day(token: &str) -> Option<u8> {
    let cleaned = token.trim_matches(|character: char| !character.is_ascii_digit());
    let day = cleaned.parse::<u8>().ok()?;
    (1..=31).contains(&day).then_some(day)
}

fn parse_month_number(token: &str) -> Option<u8> {
    let month = token.trim().parse::<u8>().ok()?;
    (1..=12).contains(&month).then_some(month)
}

/// The month names the corpus actually contains: GEDCOM's own abbreviations,
/// English in full, and the French, German, Norwegian, Italian, and Spanish
/// forms that a `FamilySearch` export carries through from the original record.
fn month_number(token: &str) -> Option<u8> {
    let key = token
        .trim_matches(|character: char| !character.is_alphanumeric())
        .to_lowercase();
    if key.is_empty() {
        return None;
    }
    if let Some(month) = parse_month_number(&key) {
        return Some(month);
    }
    for (index, names) in MONTH_NAMES.iter().enumerate() {
        if names.iter().any(|name| *name == key) {
            return u8::try_from(index + 1).ok();
        }
    }
    // Any unambiguous prefix of an English month, which covers `Novem` and
    // `Sept` without inviting a wrong guess.
    for (index, names) in MONTH_NAMES.iter().enumerate() {
        if key.len() >= 3 && names[1].starts_with(&key) {
            return u8::try_from(index + 1).ok();
        }
    }
    None
}

/// Per month: the GEDCOM abbreviation, the English name, then the other
/// languages found in the surveyed exports.
const MONTH_NAMES: [&[&str]; 12] = [
    &[
        "jan", "january", "janvier", "januar", "januari", "gennaio", "enero", "jänner",
    ],
    &[
        "feb", "february", "février", "fevrier", "februar", "februari", "febbraio", "febrero",
    ],
    &[
        "mar", "march", "mars", "märz", "marz", "maerz", "marzo", "marts",
    ],
    &["apr", "april", "avril", "aprile", "abril"],
    &["may", "mai", "maggio", "mayo", "mei"],
    &["jun", "june", "juin", "juni", "giugno", "junio"],
    &["jul", "july", "juillet", "juli", "luglio", "julio"],
    &["aug", "august", "août", "aout", "agosto", "augusti"],
    &[
        "sep",
        "september",
        "septembre",
        "settembre",
        "septiembre",
        "sept",
    ],
    &[
        "oct", "october", "octobre", "oktober", "ottobre", "octubre", "okt",
    ],
    &["nov", "november", "novembre", "noviembre"],
    &[
        "dec",
        "december",
        "décembre",
        "decembre",
        "dezember",
        "dicembre",
        "diciembre",
        "des",
    ],
];

/// The GEDCOM month abbreviation, `JAN` through `DEC`.
fn month_abbreviation(month: u8) -> &'static str {
    const NAMES: [&str; 12] = [
        "JAN", "FEB", "MAR", "APR", "MAY", "JUN", "JUL", "AUG", "SEP", "OCT", "NOV", "DEC",
    ];
    NAMES
        .get(usize::from(month.saturating_sub(1)))
        .copied()
        .unwrap_or("")
}

fn month_name(month: u8) -> &'static str {
    const NAMES: [&str; 12] = [
        "January",
        "February",
        "March",
        "April",
        "May",
        "June",
        "July",
        "August",
        "September",
        "October",
        "November",
        "December",
    ];
    NAMES
        .get(usize::from(month.saturating_sub(1)))
        .copied()
        .unwrap_or("")
}

/// When a record was last changed or created, read from a `CHAN` or `CREA`
/// structure: the `DATE` beneath it, and the `TIME` beneath that.
#[derive(Clone, Debug, Eq, PartialEq)]
#[non_exhaustive]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))]
pub struct Timestamp {
    /// The `DATE` payload, parsed. `original` holds it exactly as written.
    pub date: GedcomDate,
    /// The `TIME` payload exactly as written — `10:31:12`, when given.
    pub time: Option<String>,
}

impl Timestamp {
    /// The timestamp in the interface's words: the date's display form, with
    /// the time appended when there is one.
    #[must_use]
    pub fn display(&self) -> String {
        self.time.as_ref().map_or_else(
            || self.date.display(),
            |time| format!("{} {time}", self.date.display()),
        )
    }
}

/// A record's last-change timestamp: its `CHAN` structure read, falling back
/// to `CREA` — GEDCOM 7's creation date — when no change was recorded.
///
/// ```
/// let document = gedcomkit::Document::parse(
///     "0 HEAD\n0 @I1@ INDI\n1 CHAN\n2 DATE 5 JAN 2026\n3 TIME 10:31:12\n0 TRLR\n",
/// )?;
/// let record = document.record("@I1@").expect("record");
/// let changed = gedcomkit::dates::changed(record).expect("timestamp");
/// assert_eq!(changed.display(), "5 January 2026 10:31:12");
/// # Ok::<(), gedcomkit::GedcomError>(())
/// ```
#[must_use]
pub fn changed(record: &Node) -> Option<Timestamp> {
    ["CHAN", "CREA"]
        .iter()
        .find_map(|tag| record.first(tag))
        .and_then(timestamp_of)
}

/// Reads the `DATE`/`TIME` pair beneath any structure that carries one — a
/// `CHAN`, a `CREA`, or a vendor's own stamp.
#[must_use]
pub fn timestamp_of(node: &Node) -> Option<Timestamp> {
    let date = node.first("DATE")?;
    Some(Timestamp {
        time: date.value_of("TIME").or_else(|| node.value_of("TIME")),
        date: GedcomDate::parse(&date.logical_value()),
    })
}

/// Builds the structure that records a timestamp.
///
/// `CHAN` (or `CREA`, or a vendor tag) with `DATE` and, when given, `TIME`
/// beneath it. The crate does no I/O and reads no clock; the caller supplies
/// the moment.
///
/// ```
/// use gedcomkit::dates::{DatePoint, timestamp_node};
///
/// let point = DatePoint::from_ymd(2026, Some(9), Some(6)).expect("valid");
/// let node = timestamp_node("CHAN", point, Some("10:31:12"));
/// let text = gedcomkit::Document { records: vec![node] }.to_text();
/// assert_eq!(text, "0 CHAN\n1 DATE 6 SEP 2026\n2 TIME 10:31:12\n");
/// ```
#[must_use]
pub fn timestamp_node(tag: &str, point: DatePoint, time: Option<&str>) -> Node {
    let mut date = Node::with_value("DATE", point.to_gedcom());
    if let Some(time) = time {
        date = date.child(Node::with_value("TIME", time));
    }
    Node::new(tag).child(date)
}

/// The first standalone four-digit run that could be a year.
fn four_digit_year(input: &str) -> Option<i32> {
    let bytes = input.as_bytes();
    let mut index = 0;
    while index < bytes.len() {
        if !bytes[index].is_ascii_digit() {
            index += 1;
            continue;
        }
        let start = index;
        while index < bytes.len() && bytes[index].is_ascii_digit() {
            index += 1;
        }
        if index - start == 4
            && let Ok(year) = input[start..index].parse::<i32>()
            && (1000..=2999).contains(&year)
        {
            return Some(year);
        }
    }
    None
}

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

    fn parsed(payload: &str) -> GedcomDate {
        GedcomDate::parse(payload)
    }

    #[test]
    fn the_payload_is_never_modified() {
        let date = parsed("  ABT 1900  ");
        assert_eq!(date.original, "  ABT 1900  ");
    }

    #[test]
    fn specification_forms_read_as_written() {
        assert_eq!(parsed("1821").earliest, Some(DatePoint::year(1821)));
        let exact = parsed("5 JAN 1882");
        assert_eq!(exact.kind, DateKind::Exact);
        assert_eq!(
            exact.earliest,
            Some(DatePoint {
                year: 1882,
                month: Some(1),
                day: Some(5)
            })
        );
        assert_eq!(parsed("ABT 1900").kind, DateKind::About);
        assert_eq!(parsed("EST 1630").kind, DateKind::Estimated);
        assert_eq!(parsed("CAL 1824").kind, DateKind::Calculated);
        assert_eq!(parsed("BEF 1815").kind, DateKind::Before);
        assert_eq!(parsed("AFT 1649").kind, DateKind::After);
    }

    #[test]
    fn ranges_and_periods_keep_both_ends() {
        let between = parsed("BET 1898 AND 1902");
        assert_eq!(between.kind, DateKind::Between);
        assert_eq!(between.earliest, Some(DatePoint::year(1898)));
        assert_eq!(between.latest, Some(DatePoint::year(1902)));

        let period = parsed("from 1701 to 1742");
        assert_eq!(period.kind, DateKind::Period);
        assert_eq!(period.earliest, Some(DatePoint::year(1701)));
        assert_eq!(period.latest, Some(DatePoint::year(1742)));
    }

    #[test]
    fn the_forms_the_requirement_corpus_actually_contains() {
        // Every one of these was measured in family.ged on 2026-09-04.
        type Case = (&'static str, i32, Option<u8>, Option<u8>, DateKind);
        let cases: &[Case] = &[
            ("5 January 1882", 1882, Some(1), Some(5), DateKind::Exact),
            ("22 March 1635", 1635, Some(3), Some(22), DateKind::Exact),
            ("about 1575", 1575, None, None, DateKind::About),
            ("Abt 1872", 1872, None, None, DateKind::About),
            ("abt. 1625", 1625, None, None, DateKind::About),
            ("rundt 1645", 1645, None, None, DateKind::About),
            ("um 1660", 1660, None, None, DateKind::About),
            ("environ 1830", 1830, None, None, DateKind::About),
            ("4 juillet 1764", 1764, Some(7), Some(4), DateKind::Exact),
            ("21. Januar 1809", 1809, Some(1), Some(21), DateKind::Exact),
            ("22. März 1873", 1873, Some(3), Some(22), DateKind::Exact),
            ("16 gennaio 1847", 1847, Some(1), Some(16), DateKind::Exact),
            (
                "13 de enero de 1855",
                1855,
                Some(1),
                Some(13),
                DateKind::Exact,
            ),
            ("January 1652", 1652, Some(1), None, DateKind::Exact),
            ("8.2.1664", 1664, Some(2), Some(8), DateKind::Exact),
            ("4/18/1616", 1616, Some(4), Some(18), DateKind::Exact),
            ("<1802>", 1802, None, None, DateKind::About),
            (
                "before 29 March 1795",
                1795,
                Some(3),
                Some(29),
                DateKind::Before,
            ),
            ("Vor Februar 1843", 1843, Some(2), None, DateKind::Before),
            ("19JUL1818", 1818, Some(7), Some(19), DateKind::Exact),
            ("21 Nov1896", 1896, Some(11), Some(21), DateKind::Exact),
            ("April 15, 1873", 1873, Some(4), Some(15), DateKind::Exact),
            ("07 October 1853,", 1853, Some(10), Some(7), DateKind::Exact),
            ("1679/1683", 1679, None, None, DateKind::Exact),
            ("ABT Oct 1803", 1803, Some(10), None, DateKind::About),
            (
                "About 21 Jun 1969",
                1969,
                Some(6),
                Some(21),
                DateKind::About,
            ),
        ];

        for (payload, year, month, day, kind) in cases {
            let date = parsed(payload);
            assert_eq!(date.kind, *kind, "kind of {payload:?}");
            let point = date
                .earliest
                .or(date.latest)
                .unwrap_or_else(|| panic!("{payload:?} produced no point"));
            assert_eq!(point.year, *year, "year of {payload:?}");
            assert_eq!(point.month, *month, "month of {payload:?}");
            assert_eq!(point.day, *day, "day of {payload:?}");
        }
    }

    #[test]
    fn what_cannot_be_read_keeps_its_text_and_says_so() {
        for payload in ["Infant", "DEAD", "Unknown", "1799 or 12 April 1811"] {
            let date = parsed(payload);
            assert_eq!(date.kind, DateKind::Unparsed, "{payload:?}");
            assert_eq!(date.display(), payload);
            assert_eq!(date.phrase.as_deref(), Some(payload));
        }
    }

    #[test]
    fn an_unreadable_expression_can_still_offer_a_year_to_sort_by() {
        let date = parsed("19 Jun 1820 age 26");
        assert_eq!(date.kind, DateKind::Unparsed);
        assert_eq!(date.year_hint(), Some(1820));
        assert!(date.sort_key().is_some());
    }

    #[test]
    fn a_calendar_escape_is_recognized_in_both_versions() {
        let five = parsed("@#DJULIAN@ 12 FEB 1740");
        assert_eq!(five.calendar, Calendar::Julian);
        assert_eq!(five.earliest.expect("point").day, Some(12));

        let seven = parsed("JULIAN 12 FEB 1740");
        assert_eq!(seven.calendar, Calendar::Julian);
    }

    #[test]
    fn an_interpretation_keeps_its_phrase() {
        let date = parsed("INT 1900 (the year the church burned)");
        assert_eq!(date.kind, DateKind::Interpreted);
        assert_eq!(date.earliest, Some(DatePoint::year(1900)));
        assert_eq!(date.phrase.as_deref(), Some("the year the church burned"));
    }

    #[test]
    fn a_version_seven_bce_year_reads_negative_and_writes_back() {
        let date = parsed("44 BCE");
        assert_eq!(date.kind, DateKind::Exact);
        assert_eq!(date.earliest, Some(DatePoint::year(-44)));
        assert_eq!(date.earliest.expect("point").to_gedcom(), "44 BCE");

        let about = parsed("ABT 100 BCE");
        assert_eq!(about.kind, DateKind::About);
        assert_eq!(about.earliest, Some(DatePoint::year(-100)));

        // Earlier BCE years sort earlier.
        assert!(
            parsed("100 BCE").sort_key() < parsed("44 BCE").sort_key(),
            "100 BCE came after 44 BCE"
        );
    }

    #[test]
    fn a_before_only_date_sorts_at_its_boundary_year() {
        // `BEF 1815` has no earliest instant; it is filed at the year named,
        // which is the boundary of what it admits. Asserted so a change to
        // this compromise is a decision rather than an accident.
        let date = parsed("BEF 1815");
        assert_eq!(date.earliest, None);
        assert_eq!(date.year_hint(), Some(1815));
        assert_eq!(date.sort_key(), Some(1815 * 10_000));
    }

    #[test]
    fn dates_sort_by_the_earliest_instant_they_admit() {
        let mut dates = ["1900", "5 JAN 1882", "ABT 1875", "BET 1890 AND 1895"]
            .map(parsed)
            .to_vec();
        dates.sort_by_key(GedcomDate::sort_key);

        let order: Vec<&str> = dates.iter().map(|date| date.original.as_str()).collect();
        assert_eq!(
            order,
            ["ABT 1875", "5 JAN 1882", "BET 1890 AND 1895", "1900"]
        );
    }
}