craft-libs/crates/metadata/src/datetime.rs

//! Capture date/time with optional UTC offset (Exif `DateTimeOriginal` + `OffsetTimeOriginal`, ISO 8601 in XMP).

use serde::{Deserialize, Serialize};

/// A civil date-time as recorded by the camera; `offset_minutes` is the UTC offset when known.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
pub struct DateTime {
    pub year: u16,
    pub month: u8,
    pub day: u8,
    pub hour: u8,
    pub minute: u8,
    pub second: u8,
    /// Sub-second part in milliseconds.
    pub millis: u16,
    pub offset_minutes: Option<i16>,
    /// How much of the date was stated. XMP dates may stop at the year (`1983`) or the month
    /// (`1983-04`), as for a scanned print whose day isn't known; the missing parts read as 1 and
    /// the time as midnight, and the date writes back as stated.
    #[serde(default, skip_serializing_if = "DatePrecision::is_full")]
    pub precision: DatePrecision,
}

/// How much of a [`DateTime`] was stated.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum DatePrecision {
    /// The day at least (a time of day may be midnight because none was given).
    #[default]
    Full,
    /// The year and month only (`1983-04`).
    Month,
    /// The year only (`1983`).
    Year,
}

impl DatePrecision {
    pub fn is_full(&self) -> bool {
        *self == DatePrecision::Full
    }
}

fn num(s: &str) -> Option<u32> {
    if s.is_empty() || !s.bytes().all(|b| b.is_ascii_digit()) {
        return None;
    }
    s.parse().ok()
}

impl DateTime {
    fn valid(self) -> Option<Self> {
        // A timestamp must represent a real Gregorian calendar day, not just
        // numbers in the range 1..=31. Invalid dates would otherwise be
        // accepted from EXIF/XMP and silently normalized during time arithmetic.
        // chrono rejects impossible days (leap years and all); the time is checked
        // by hand so a leap second (`second == 60`) stays acceptable.
        let day_ok = self.year > 0 && chrono::NaiveDate::from_ymd_opt(i32::from(self.year), u32::from(self.month), u32::from(self.day)).is_some();
        let ok = day_ok && self.hour < 24 && self.minute < 60 && self.second < 61 && self.offset_minutes.is_none_or(|o| o.unsigned_abs() <= 18 * 60);
        ok.then_some(self)
    }

    /// Exif form `YYYY:MM:DD HH:MM:SS` (also tolerates `-` date separators and a missing time).
    pub fn parse_exif(s: &str) -> Option<DateTime> {
        let s = s.trim().trim_end_matches('\0');
        let (d, t) = s.split_once([' ', 'T']).unwrap_or((s, ""));
        let dp: Vec<&str> = d.split([':', '-']).collect();
        if dp.len() != 3 {
            return None;
        }
        let (hour, minute, second) = if t.is_empty() {
            (0, 0, 0)
        } else {
            let mut parts = t.split(':');
            let hour = num(parts.next()?.trim())?;
            let minute = parts.next().map(|part| num(part.trim())).unwrap_or(Some(0))?;
            let second = parts.next().map(|part| num(part.trim())).unwrap_or(Some(0))?;
            // A fourth value cannot be represented; accepting only the prefix could turn a
            // malformed DateTimeOriginal into a plausible capture time and block fallbacks.
            if parts.next().is_some() {
                return None;
            }
            (hour, minute, second)
        };
        DateTime {
            year: num(dp[0])?.try_into().ok()?,
            month: num(dp[1])?.try_into().ok()?,
            day: num(dp[2])?.try_into().ok()?,
            hour: hour.try_into().ok()?,
            minute: minute.try_into().ok()?,
            second: second.try_into().ok()?,
            millis: 0,
            offset_minutes: None,
            precision: DatePrecision::Full,
        }
        .valid()
    }

    /// Exif `OffsetTime*` form `+HH:MM` / `-HH:MM` (or `Z`).
    pub fn parse_offset(s: &str) -> Option<i16> {
        let s = s.trim().trim_end_matches('\0');
        if s == "Z" {
            return Some(0);
        }
        let (sign, rest) = match s.as_bytes().first()? {
            b'+' => (1, &s[1..]),
            b'-' => (-1, &s[1..]),
            _ => return None,
        };
        let (h, m) = match rest.split_once(':') {
            Some((h, m)) if m.len() == 2 => (num(h)?, num(m)?),
            Some(_) => return None,
            None if rest.len() == 4 => (num(rest.get(..2)?)?, num(rest.get(2..)?)?),
            None => (num(rest)?, 0),
        };
        if h > 18 || m > 59 || (h == 18 && m > 0) {
            return None;
        }
        Some(sign * (h * 60 + m) as i16)
    }

    /// Set the sub-second part from an Exif `SubSecTime*` string (digits are a decimal fraction).
    pub fn with_subsec(mut self, s: &str) -> DateTime {
        let digits: String = s.trim().chars().take_while(|c| c.is_ascii_digit()).take(3).collect();
        if !digits.is_empty() {
            let v: u16 = digits.parse().unwrap_or(0);
            self.millis = v * 10u16.pow(3 - digits.len() as u32);
        }
        self
    }

    /// ISO 8601 (XMP date): `YYYY`, `YYYY-MM`, `YYYY-MM-DD`, `YYYY-MM-DDThh:mm[:ss[.s+]][TZD]`. A
    /// year or a month alone keeps its [`DatePrecision`].
    pub fn parse_iso(s: &str) -> Option<DateTime> {
        let s = s.trim();
        let (d, t) = match s.split_once('T') {
            Some((d, t)) if !t.is_empty() => (d, t),
            Some(_) => return None,
            None => (s, ""),
        };
        let dp: Vec<&str> = d.split('-').collect();
        let year = num(dp.first()?)?.try_into().ok()?;
        let month = dp.get(1).map(|m| num(m)).unwrap_or(Some(1))?.try_into().ok()?;
        let day = dp.get(2).map(|m| num(m)).unwrap_or(Some(1))?.try_into().ok()?;
        if dp.len() > 3 {
            return None;
        }
        let precision = match dp.len() {
            1 => DatePrecision::Year,
            2 => DatePrecision::Month,
            _ => DatePrecision::Full,
        };
        let mut dt = DateTime { year, month, day, precision, ..Default::default() };
        if !t.is_empty() {
            // a time of day needs the day it is on
            if !dt.precision.is_full() {
                return None;
            }
            let (clock, off) = match t.find(['Z', '+', '-']) {
                Some(i) => (&t[..i], Some(&t[i..])),
                None => (t, None),
            };
            let mut cp = clock.split(':');
            let hour = cp.next()?;
            let minute = cp.next()?;
            if hour.len() != 2 || minute.len() != 2 {
                return None;
            }
            dt.hour = num(hour)?.try_into().ok()?;
            dt.minute = num(minute)?.try_into().ok()?;
            if let Some(sec) = cp.next() {
                let (whole, fraction) = match sec.split_once('.') {
                    Some((whole, fraction)) => {
                        if fraction.is_empty() || !fraction.bytes().all(|b| b.is_ascii_digit()) {
                            return None;
                        }
                        (whole, Some(fraction))
                    }
                    None => (sec, None),
                };
                dt.second = num(whole)?.try_into().ok()?;
                if let Some(fraction) = fraction {
                    dt = dt.with_subsec(fraction);
                }
            }
            if cp.next().is_some() {
                return None;
            }
            if let Some(o) = off {
                dt.offset_minutes = Some(Self::parse_offset(o)?);
            }
        }
        dt.valid()
    }

    /// Whether the day was stated: Exif's date form can't say a year or a month alone, so only a
    /// full date is written there.
    pub fn is_full(&self) -> bool {
        self.precision.is_full()
    }

    /// Exif form `YYYY:MM:DD HH:MM:SS`.
    pub fn to_exif(&self) -> String {
        format!("{:04}:{:02}:{:02} {:02}:{:02}:{:02}", self.year, self.month, self.day, self.hour, self.minute, self.second)
    }

    /// ISO 8601 with milliseconds when non-zero and the offset when known; a year or a month
    /// alone as stated (`1983`, `1983-04`).
    pub fn to_iso(&self) -> String {
        match self.precision {
            DatePrecision::Year => return format!("{:04}", self.year),
            DatePrecision::Month => return format!("{:04}-{:02}", self.year, self.month),
            DatePrecision::Full => {}
        }
        let mut s = format!("{:04}-{:02}-{:02}T{:02}:{:02}:{:02}", self.year, self.month, self.day, self.hour, self.minute, self.second);
        if self.millis != 0 {
            s += &format!(".{:03}", self.millis);
        }
        if let Some(o) = self.offset_minutes {
            let sign = if o < 0 { '-' } else { '+' };
            let o = o.unsigned_abs();
            s += &format!("{sign}{:02}:{:02}", o / 60, o % 60);
        }
        s
    }

    /// Seconds since 1970-01-01T00:00:00 of the civil time (UTC when the offset is known, else "local" seconds).
    pub fn unix_seconds(&self) -> i64 {
        // Every `DateTime` reaching here is a real calendar day (`valid()` ran in the parsers);
        // an out-of-range one (built by hand) reads as the epoch rather than panicking.
        let days = chrono::NaiveDate::from_ymd_opt(i32::from(self.year), u32::from(self.month), u32::from(self.day))
            .zip(chrono::NaiveDate::from_ymd_opt(1970, 1, 1))
            .map(|(d, epoch)| (d - epoch).num_days())
            .unwrap_or(0);
        days * 86400 + self.hour as i64 * 3600 + self.minute as i64 * 60 + self.second as i64 - self.offset_minutes.unwrap_or(0) as i64 * 60
    }
}

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

    #[test]
    fn offset_rejects_short_minute_field() {
        assert_eq!(DateTime::parse_offset("+08:5"), None);
        assert_eq!(DateTime::parse_offset("+1:2"), None);
        assert_eq!(DateTime::parse_offset("+08:05"), Some(485));
        assert_eq!(DateTime::parse_offset("-05:30"), Some(-330));
    }

    #[test]
    fn exif_forms() {
        let d = DateTime::parse_exif("2024:06:01 13:45:59").unwrap();
        assert_eq!((d.year, d.month, d.day, d.hour, d.minute, d.second), (2024, 6, 1, 13, 45, 59));
        assert_eq!(d.to_exif(), "2024:06:01 13:45:59");
        assert!(DateTime::parse_exif("0000:00:00 00:00:00").is_none());
        assert!(DateTime::parse_exif("    :  :     :  :  ").is_none());
        assert!(DateTime::parse_exif("2024:13:01 00:00:00").is_none());
        // Invalid calendar days must never enter persisted capture metadata.
        for value in ["2023:02:29", "2024:02:30", "2024:04:31", "1900:02:29", "2024:01:00"] {
            assert!(DateTime::parse_exif(value).is_none(), "{value}");
        }
        assert!(DateTime::parse_exif("2024:02:29").is_some());
        assert!(DateTime::parse_exif("2000:02:29").is_some());
        for value in ["2023-02-29", "2024-02-30", "1900-02-29", "2024-06-31T10:00:00Z"] {
            assert!(DateTime::parse_iso(value).is_none(), "{value}");
        }
        assert!(DateTime::parse_iso("2000-02-29T23:59:59Z").is_some());
        assert_eq!(DateTime::parse_exif("2024-06-01").unwrap().hour, 0);
        assert_eq!(DateTime::parse_exif("2024:06:01 13:45:59").unwrap().with_subsec("5").millis, 500);
        assert_eq!(DateTime::parse_exif("2024:06:01 13:45:59").unwrap().with_subsec("0123").millis, 12);
    }

    #[test]
    fn exif_clock_rejects_extra_components() {
        for value in
            ["2026:01:01 12:34:56:99", "2026:01:01 12:34:56:junk", "2026:01:01 12:34:56:", "2026:01:01 12:34:56::", "2026:01:01 12:34:56:99:junk"]
        {
            assert!(DateTime::parse_exif(value).is_none(), "accepted malformed EXIF clock {value:?}");
        }
    }

    #[test]
    fn exif_clock_supported_forms_keep_their_meaning() {
        for (value, expected) in [
            ("2026:01:01", "2026-01-01T00:00:00"),
            ("2026:01:01 12", "2026-01-01T12:00:00"),
            ("2026:01:01 12:34", "2026-01-01T12:34:00"),
            ("2026:01:01 12:34:56", "2026-01-01T12:34:56"),
            ("2026-01-01T12:34:56", "2026-01-01T12:34:56"),
            (" 2026:01:01 12:34:56\0", "2026-01-01T12:34:56"),
            ("2026:01:01T12:34:60", "2026-01-01T12:34:60"),
        ] {
            assert_eq!(DateTime::parse_exif(value).map(|date| date.to_iso()), Some(expected.to_string()), "{value:?}");
        }
    }

    /// XMP dates may stop at the year or the month (a scanned print's `photoshop:DateCreated`):
    /// read with that precision, written back as stated, and never as an Exif date.
    #[test]
    fn a_year_or_month_alone_reads_and_writes_as_stated() {
        for (iso, precision) in [("1983", DatePrecision::Year), ("1983-04", DatePrecision::Month)] {
            let d = DateTime::parse_iso(iso).unwrap();
            assert_eq!((d.year, d.month, d.day, d.precision), (1983, if iso.len() == 7 { 4 } else { 1 }, 1, precision), "{iso}");
            assert!(!d.is_full());
            assert_eq!(d.to_iso(), iso);
            let meta = crate::Metadata { capture_time: Some(d), ..Default::default() };
            let xmp = crate::write_xmp(&meta);
            assert!(!xmp.contains("DateTimeOriginal"), "{xmp}");
            assert_eq!(crate::parse_xmp(&xmp).unwrap().metadata.capture_time, Some(d), "{xmp}");
            assert_eq!(crate::read_exif(&crate::write_exif(&meta)).capture_time, None, "Exif can't say {iso}");
        }
        for not in ["0000", "1983-00", "1983-13", "1983-04T10:00:00", "1983T10:00"] {
            assert_eq!(DateTime::parse_iso(not), None, "{not}");
        }
        let full = DateTime::parse_iso("1983-04-12").unwrap();
        assert!(full.is_full());
        assert_eq!(full.to_iso(), "1983-04-12T00:00:00");
    }

    #[test]
    fn offsets() {
        assert_eq!(DateTime::parse_offset("+02:00"), Some(120));
        assert_eq!(DateTime::parse_offset("-05:30"), Some(-330));
        assert_eq!(DateTime::parse_offset("Z"), Some(0));
        assert_eq!(DateTime::parse_offset("+0930"), Some(570));
        assert_eq!(DateTime::parse_offset("+18:00"), Some(1080));
        assert_eq!(DateTime::parse_offset("-18:00"), Some(-1080));
        assert_eq!(DateTime::parse_offset("+18:01"), None);
        assert_eq!(DateTime::parse_offset("-18:01"), None);
        assert_eq!(DateTime::parse_offset("   :  "), None);
        assert_eq!(DateTime::parse_offset("+99:00"), None);
    }

    #[test]
    fn extreme_offsets_do_not_overflow() {
        // `DateTime` deserializes with public fields, so an offset can arrive without passing `valid()`
        let d = DateTime { offset_minutes: Some(i16::MIN), ..DateTime::parse_iso("2024-06-01T13:45:59").unwrap() };
        assert_eq!(d.to_iso(), "2024-06-01T13:45:59-546:08");
        assert_eq!(d.valid(), None);
    }

    #[test]
    fn unicode_offsets_are_rejected_without_panicking() {
        for offset in ["+1€", "-1€", "+€1", "-€1"] {
            assert_eq!(DateTime::parse_offset(offset), None);
            let date = format!("2024-06-01T13:45:59{offset}");
            let metadata = crate::Metadata { capture_time: DateTime::parse_iso("2024-06-01T13:45:59Z"), ..Default::default() };
            let xmp = crate::write_xmp(&metadata).replace("2024-06-01T13:45:59+00:00", &date);
            assert!(crate::parse_xmp(&xmp).unwrap().metadata.capture_time.is_none());
        }
    }

    #[test]
    fn iso_roundtrip() {
        for s in ["2024-06-01T13:45:59", "2024-06-01T13:45:59.250+02:00", "1999-12-31T23:59:00-05:30", "2024-02-29T00:00:00Z"] {
            let d = DateTime::parse_iso(s).unwrap();
            let again = DateTime::parse_iso(&d.to_iso()).unwrap();
            assert_eq!(d, again, "{s}");
        }
        assert_eq!(DateTime::parse_iso("2024-02-29T00:00:00Z").unwrap().to_iso(), "2024-02-29T00:00:00+00:00");
        let d = DateTime::parse_iso("2019").unwrap();
        assert_eq!((d.year, d.month, d.day), (2019, 1, 1));
        assert_eq!(DateTime::parse_iso("2019-07-04T10:11").unwrap().minute, 11);
        assert!(DateTime::parse_iso("nonsense").is_none());
        assert!(DateTime::parse_iso("2019-07-04Tab:cd").is_none());
    }

    #[test]
    fn iso_rejects_incomplete_or_unconsumed_clock_text() {
        for value in [
            "2026-01-01T",
            "2026-01-01T12:34:56:99Z",
            "2026-01-01T12:34:56.Z",
            "2026-01-01T12:34:56.123junkZ",
            "2026-01-01T12:34:56.1.2Z",
            "2026-01-01T12:34:56.12 3Z",
            "2026-01-01T12:34:56:99Z",
            "2026-01-01T12::34Z",
        ] {
            assert!(DateTime::parse_iso(value).is_none(), "accepted malformed timestamp {value:?}");
        }
    }

    #[test]
    fn iso_rejects_single_digit_clock_fields() {
        for value in ["2024-06-01T1:02:03Z", "2024-06-01T01:2:03Z"] {
            assert!(DateTime::parse_iso(value).is_none(), "accepted malformed timestamp {value:?}");
        }
    }

    #[test]
    fn iso_validates_clock_while_preserving_supported_forms() {
        assert_eq!(DateTime::parse_iso("2019").unwrap().to_iso(), "2019");
        assert_eq!(DateTime::parse_iso("2019-07").unwrap().to_iso(), "2019-07");
        assert_eq!(DateTime::parse_iso("2019-07-04").unwrap().to_iso(), "2019-07-04T00:00:00");
        assert_eq!(DateTime::parse_iso("2019-07-04T10:11").unwrap().to_iso(), "2019-07-04T10:11:00");
        assert_eq!(DateTime::parse_iso("2019-07-04T10:11:12").unwrap().to_iso(), "2019-07-04T10:11:12");
        assert_eq!(DateTime::parse_iso("2019-07-04T10:11:12Z").unwrap().offset_minutes, Some(0));
        assert_eq!(DateTime::parse_iso("2019-07-04T10:11:12-05:30").unwrap().offset_minutes, Some(-330));
        assert_eq!(DateTime::parse_iso("2019-07-04T10:11:12.123456Z").unwrap().millis, 123);
        assert_eq!(DateTime::parse_iso(" 2019-07-04T10:11:12.5Z ").unwrap().millis, 500);
        assert_eq!(DateTime::parse_iso("2019-07-04T10:11:60Z").unwrap().second, 60);
    }

    #[test]
    fn unix() {
        assert_eq!(DateTime::parse_iso("1970-01-01T00:00:00Z").unwrap().unix_seconds(), 0);
        assert_eq!(DateTime::parse_iso("2000-03-01T00:00:00Z").unwrap().unix_seconds(), 951868800);
        assert_eq!(DateTime::parse_iso("2000-03-01T02:00:00+02:00").unwrap().unix_seconds(), 951868800);
    }
}