5a24289898fd
dates.rs
//! Calendar helpers for ISO 8601 local times (`2026-09-30T14:05:00`): seconds ↔ civil date,
//! weekday and month names, shifting a time by an offset, and grouping a photo list into runs of
//! the same day / month / year (the date headers of the photo grid).
use chrono::Datelike;
use serde::{Deserialize, Serialize};
pub use crate::stacks::iso_seconds;
use crate::{Catalog, PhotoId, SortKey};
pub const WEEKDAYS: [&str; 7] = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"];
pub const MONTHS: [&str; 12] =
["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"];
/// Unix seconds → `YYYY-MM-DDTHH:MM:SS` (UTC, proleptic Gregorian). A time outside chrono's year
/// range still converts: the calendar repeats every 400 years, so the instant is moved into range
/// by whole cycles and only the year is carried (matching the old `civil_from_days`), rather than
/// resetting to the epoch. The callers here stay well inside years 0000–9999.
pub fn civil(secs: i64) -> String {
let (days, sod) = (secs.div_euclid(86_400), secs.rem_euclid(86_400));
let (cycles, rest) = (days.div_euclid(146_097), days.rem_euclid(146_097));
// `rest + 719_163` (1970-01-01 is CE day 719_163) is always a valid CE day, and `sod` < 86_400.
let date = i32::try_from(rest + 719_163).ok().and_then(chrono::NaiveDate::from_num_days_from_ce_opt);
let time = u32::try_from(sod).ok().and_then(|s| chrono::NaiveTime::from_num_seconds_from_midnight_opt(s, 0));
match (date, time) {
(Some(d), Some(t)) => {
let y = i128::from(d.year()) + i128::from(cycles) * 400;
let y = i64::try_from(y).unwrap_or(if y < 0 { i64::MIN } else { i64::MAX });
// `{:04}` rather than `%Y`, which writes a `+` before years past 9999 (the old `{y:04}` did not).
format!("{y:04}-{}", d.and_time(t).format("%m-%dT%H:%M:%S"))
}
_ => "1970-01-01T00:00:00".to_string(), // unreachable
}
}
/// Weekday name of an ISO date (`None` if it doesn't parse).
pub fn weekday(iso: &str) -> Option<&'static str> {
let days = iso_seconds(iso.get(..10)?)?.div_euclid(86_400);
let date = chrono::NaiveDate::from_num_days_from_ce_opt(i32::try_from(days.checked_add(719_163)?).ok()?)?;
Some(WEEKDAYS[date.weekday().num_days_from_monday() as usize])
}
/// Shift an ISO time by `secs`, keeping anything after the seconds (fractions, zone) as it was.
/// A date without a time gets one. `None` if it doesn't parse, or if the result leaves years
/// 0000–9999 (an ISO date here has four year digits, so it couldn't be read back); `secs` may be
/// anything, it never overflows. Stricter than [`iso_seconds`], which reads what it can for sorting:
/// a time cut short, seconds that aren't digits or anything after the zone is `None` here, not
/// written back as a clean-looking time.
pub fn shift_iso(iso: &str, secs: i64) -> Option<String> {
let iso = iso.trim();
let tail = iso.get(tail_start(iso)?..)?;
let base = iso_seconds(iso)?;
// reject impossible dates that the arithmetic silently rolls over (2026-02-30)
if civil(base).get(..10) != iso.get(..10) {
return None;
}
let t = base.checked_add(secs)?;
let (first, last) = (iso_seconds("0000-01-01T00:00:00")?, iso_seconds("9999-12-31T23:59:59")?);
if !(first..=last).contains(&t) {
return None;
}
Some(format!("{}{tail}", civil(t)))
}
/// Where the part of an ISO time that [`shift_iso`] keeps as it was (fraction, zone) starts, or
/// `None` unless `iso` is a date alone (`2026-01-01`) or a date and `HH:MM`, optional `:SS` with
/// an optional fraction (`.5`), and an optional zone (`Z`, `+02:00`, `-0500`, `+02`), and nothing after.
fn tail_start(iso: &str) -> Option<usize> {
let b = iso.as_bytes();
let digits = |x: &[u8]| !x.is_empty() && x.iter().all(u8::is_ascii_digit);
let digits_at = |a: usize, z: usize| b.get(a..z).is_some_and(digits);
let at = |i: usize, c: u8| b.get(i) == Some(&c);
if !(digits_at(0, 4) && at(4, b'-') && digits_at(5, 7) && at(7, b'-') && digits_at(8, 10)) {
return None;
}
if b.len() == 10 {
return Some(10);
}
if !((at(10, b'T') || at(10, b' ')) && digits_at(11, 13) && at(13, b':') && digits_at(14, 16)) {
return None;
}
// the seconds are optional (`10:00+02:00`): without them the tail starts right after the minutes
let start = if !at(16, b':') {
16
} else if digits_at(17, 19) {
19
} else {
return None;
};
let mut zone = b.get(start..)?;
// a fraction only after the seconds: `10:00.5` is half a minute, not half a second
if let ([b'.', rest @ ..], 19) = (zone, start) {
let n = rest.iter().take_while(|c| c.is_ascii_digit()).count();
zone = rest.get(n..)?;
if n == 0 {
return None;
}
}
let ok = match zone {
[] | [b'Z'] => true,
[b'+' | b'-', h1, h2, b':', m1, m2] => digits(&[*h1, *h2, *m1, *m2]),
[b'+' | b'-', hm @ ..] => matches!(hm.len(), 2 | 4) && digits(hm),
_ => false,
};
ok.then_some(start)
}
/// Normalize user input to `YYYY-MM-DDTHH:MM:SS` (accepts a space instead of `T`, missing
/// seconds or time). `None` if it isn't a valid date.
pub fn normalize_iso(s: &str) -> Option<String> {
let t = iso_seconds(s)?;
let out = civil(t);
// reject impossible dates that the arithmetic silently rolls over (2026-02-30)
if out.get(..10) != s.trim().get(..10) {
return None;
}
Some(out)
}
/// Granularity of the grid's date headers.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum GroupBy {
/// Day headers, or months/years when the thumbnails are small (decided by the UI).
#[default]
Auto,
None,
Day,
Month,
Year,
}
impl GroupBy {
pub fn parse(s: &str) -> Option<GroupBy> {
Some(match s.to_ascii_lowercase().as_str() {
"auto" => GroupBy::Auto,
"none" | "off" => GroupBy::None,
"day" => GroupBy::Day,
"month" => GroupBy::Month,
"year" => GroupBy::Year,
_ => return None,
})
}
/// Length of the ISO prefix that identifies a group.
fn prefix(self) -> usize {
match self {
GroupBy::Year => 4,
GroupBy::Month => 7,
_ => 10,
}
}
}
/// A run of consecutive photos with the same date (one header in the grid).
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct DateRun {
/// `2026-09-30` / `2026-09` / `2026`, or empty for photos without a usable date.
pub key: String,
/// "Wednesday, 30 September 2026" / "September 2026" / "2026" / "Unknown Date".
pub label: String,
/// Index of the first photo in the list.
pub start: usize,
pub count: usize,
}
/// A capture time for display: `2022-03-30T22:11:11` → "March 30, 2022 at 10:11:11 PM" (the
/// date alone when there is no time; the input unchanged when it doesn't parse).
pub fn display_time(iso: &str) -> String {
let num = |r: std::ops::Range<usize>| iso.get(r).and_then(|v| v.parse::<u32>().ok());
let (Some(y), Some(mo), Some(d)) = (num(0..4), num(5..7), num(8..10)) else { return iso.to_string() };
let Some(month) = MONTHS.get((mo as usize).wrapping_sub(1)) else { return iso.to_string() };
let date = format!("{month} {d}, {y}");
match (num(11..13), num(14..16), num(17..19)) {
(Some(h), Some(mi), s) => {
let (h12, ampm) = match h {
0 => (12, "AM"),
1..=11 => (h, "AM"),
12 => (12, "PM"),
_ => (h - 12, "PM"),
};
format!("{date} at {h12}:{mi:02}:{:02} {ampm}", s.unwrap_or(0))
}
_ => date,
}
}
/// Header text for a group key.
pub fn group_label(key: &str) -> String {
let month = |k: &str| k.get(5..7).and_then(|m| m.parse::<usize>().ok()).and_then(|m| MONTHS.get(m.wrapping_sub(1)));
// `get` rather than `[..]`: a non-ASCII key must not split a character
let year = key.get(..4).unwrap_or(key);
match key.len() {
10 => match (weekday(key), month(key), key.get(8..10).and_then(|d| d.parse::<u32>().ok())) {
(Some(w), Some(m), Some(d)) => format!("{w}, {d} {m} {year}"),
_ => key.to_string(),
},
7 => month(key).map(|m| format!("{m} {year}")).unwrap_or_else(|| key.to_string()),
4 => key.to_string(),
_ => "Unknown Date".into(),
}
}
impl Catalog {
/// Split `ids` (the grid order) into runs of the same day / month / year for `key`'s date.
/// Members of a stack share the group of the stack's first photo in the list, so a stack is
/// never split by a header. Empty for sort keys without a date and for [`GroupBy::None`]
/// ([`GroupBy::Auto`] means days here).
pub fn date_runs(&self, ids: &[PhotoId], key: SortKey, by: GroupBy) -> Vec<DateRun> {
if !groups_by_date(key, by) || ids.is_empty() {
return Vec::new();
}
date_runs_of(ids, &self.stack_index(), |_, id| self.date_group(id, key, by))
}
/// The date group of photo `id` on its own for [`Catalog::date_runs`] (`2026-09-30` /
/// `2026-09` / `2026`; empty without a usable date): a stack's members take the group of its
/// first photo in the list there.
pub fn date_group(&self, id: PhotoId, key: SortKey, by: GroupBy) -> String {
let Some(p) = self.photo(id) else { return String::new() };
let d = match key {
SortKey::CaptureDate => p.captured.as_deref(),
SortKey::ImportDate => Some(p.imported.as_str()),
SortKey::EditDate => p.edited.as_deref(),
_ => None,
};
d.filter(|d| iso_seconds(d.get(..10).unwrap_or("")).is_some()).and_then(|d| d.get(..by.prefix())).unwrap_or("").to_string()
}
}
/// Whether [`Catalog::date_runs`] has runs for sort key `key` grouped `by`.
pub fn groups_by_date(key: SortKey, by: GroupBy) -> bool {
by != GroupBy::None && matches!(key, SortKey::CaptureDate | SortKey::ImportDate | SortKey::EditDate)
}
/// [`Catalog::date_runs`] from each photo's own group (`group(position, id)`, see
/// [`Catalog::date_group`]) and the stack index ([`Catalog::stack_index`]).
pub fn date_runs_of<K: AsRef<str>>(
ids: &[PhotoId],
stacks: &std::collections::HashMap<PhotoId, (crate::StackId, usize)>,
mut group: impl FnMut(usize, PhotoId) -> K,
) -> Vec<DateRun> {
let mut runs: Vec<DateRun> = Vec::new();
let mut stack_key: std::collections::HashMap<crate::StackId, String> = Default::default();
for (i, id) in ids.iter().enumerate() {
let own;
let k: &str = match stacks.get(id) {
Some((sid, _)) => stack_key.entry(*sid).or_insert_with(|| group(i, *id).as_ref().to_string()),
None => {
own = group(i, *id);
own.as_ref()
}
};
match runs.last_mut() {
Some(r) if r.key == k => r.count += 1,
_ => runs.push(DateRun { label: group_label(k), key: k.to_string(), start: i, count: 1 }),
}
}
runs
}
#[cfg(test)]
mod tests {
use super::*;
use crate::{Op, Photo, Source};
#[test]
fn calendar() {
assert_eq!(civil(0), "1970-01-01T00:00:00");
assert_eq!(civil(951_782_400), "2000-02-29T00:00:00");
// A year past 9999 keeps the plain zero-padded year (no `+`), as the old `{y:04}` did.
assert_eq!(civil(253_402_300_800), "10000-01-01T00:00:00");
// Beyond chrono's year range the old `civil_from_days` still converted; pin that output
// (never the epoch) in both directions and at the i64 extremes.
assert_eq!(civil(10_000_000_000_000), "318857-05-20T17:46:40");
assert_eq!(civil(-10_000_000_000_000), "-314918-08-13T06:13:20");
assert_eq!(civil(i64::MAX), "292277026596-12-04T15:30:07");
assert_eq!(civil(i64::MIN), "-292277022657-01-27T08:29:52");
assert_eq!(weekday("2026-09-30"), Some("Wednesday"));
assert_eq!(weekday("2026-10-01T09:00:00"), Some("Thursday"));
assert_eq!(weekday("2000-02-29"), Some("Tuesday"));
assert_eq!(group_label("2026-09-29"), "Tuesday, 29 September 2026");
assert_eq!(group_label("2026-02"), "February 2026");
assert_eq!(group_label("2026"), "2026");
assert_eq!(group_label(""), "Unknown Date");
// non-ASCII keys of a date's length used to be sliced mid-character
assert_eq!(group_label("2024-01é0"), "2024-01é0");
assert_eq!(group_label("202é01"), "January 202é01");
assert_eq!(shift_iso("2026-12-31T23:30:00", 3600).as_deref(), Some("2027-01-01T00:30:00"));
assert_eq!(shift_iso("2026-03-01T00:00:00.25+02:00", -1).as_deref(), Some("2026-02-28T23:59:59.25+02:00"));
assert_eq!(shift_iso("nope", 5), None);
// hostile shifts never overflow, and a result outside years 0000–9999 (which no ISO date
// here can read back) is refused rather than stored
for secs in [i64::MAX, i64::MIN, i64::MAX / 2, -(i64::MAX / 2)] {
assert_eq!(shift_iso("2026-01-01T00:00:00", secs), None, "{secs}");
}
assert_eq!(shift_iso("9999-12-31T23:59:59", 1), None);
assert_eq!(shift_iso("0000-01-01T00:00:00", -1), None);
assert_eq!(shift_iso("9999-12-31T23:59:58", 1).as_deref(), Some("9999-12-31T23:59:59"));
assert_eq!(normalize_iso("2026-04-01 10:05").as_deref(), Some("2026-04-01T10:05:00"));
assert_eq!(normalize_iso("2026-02-30"), None);
}
#[test]
fn shift_refuses_impossible_dates() {
assert_eq!(shift_iso("2026-02-30T10:00:00", 60), None);
assert_eq!(shift_iso("2026-02-29T10:00:00", 0), None);
assert_eq!(shift_iso("2026-04-31T10:00:00", 0), None);
assert_eq!(shift_iso("2024-02-29T10:00:00", 0).as_deref(), Some("2024-02-29T10:00:00"));
}
#[test]
fn shift_keeps_the_zone_of_a_time_without_seconds() {
assert_eq!(shift_iso("2026-01-01T10:00+02:00", 3600).as_deref(), Some("2026-01-01T11:00:00+02:00"));
assert_eq!(shift_iso("2026-01-01T10:00Z", 60).as_deref(), Some("2026-01-01T10:01:00Z"));
assert_eq!(shift_iso("2026-01-01T10:00", 3600).as_deref(), Some("2026-01-01T11:00:00"));
assert_eq!(shift_iso("2026-01-01T10:00:00.5-05:00", 3600).as_deref(), Some("2026-01-01T11:00:00.5-05:00"));
assert_eq!(iso_seconds("2026-01-01T10:00+02:00"), iso_seconds("2026-01-01T10:00"));
}
#[test]
fn shift_refuses_a_time_it_cant_fully_read() {
for bad in [
"2026-01-01T10:0",
"2026-01-01T10",
"2026-01-01T",
"2026-01-01T10:00:xx",
"2026-01-01T10:00:0",
"2026-01-01T10:00:00+",
"2026-01-01T10:00:00+2",
"2026-01-01T10:00:00+02:0",
"2026-01-01T10:00:00.",
"2026-01-01T10:00:00.5.5",
"2026-01-01T10:00.5",
"2026-01-01T10:00:00ZZ",
"2026-01-01T10:00:00 and more",
"2026-01-01T10:00 and more",
"2026-01-01x10:00:00",
"2026/01/01T10:00:00",
] {
assert_eq!(shift_iso(bad, 3600), None, "{bad} doesn't fully read, so it must not be written back");
}
// multi-byte characters where the time, the seconds and the zone start never panic
for at in [11, 16, 18, 21] {
let mut s = String::from("2026-01-01T10:00:00+02:00");
s.replace_range(at..at + 1, "é");
assert_eq!(shift_iso(&s, 3600), None, "{s}");
assert_eq!(shift_iso(s.get(..at + 2).unwrap(), 3600), None, "{s}");
}
}
#[test]
fn shift_keeps_a_fraction_and_zone_and_reads_back() {
for (from, to) in [
("2026-01-01", "2026-01-01T01:00:00"),
(" 2026-01-01T10:00 ", "2026-01-01T11:00:00"),
("2026-01-01 10:00:30", "2026-01-01T11:00:30"),
("2026-01-01T10:00:30.5", "2026-01-01T11:00:30.5"),
("2026-01-01T10:00:30Z", "2026-01-01T11:00:30Z"),
("2026-01-01T10:00:30+02:00", "2026-01-01T11:00:30+02:00"),
("2026-01-01T10:00:30-0500", "2026-01-01T11:00:30-0500"),
("2026-01-01T10:00:30+02", "2026-01-01T11:00:30+02"),
("2026-01-01T10:00:30.125+02:00", "2026-01-01T11:00:30.125+02:00"),
] {
assert_eq!(shift_iso(from, 3600).as_deref(), Some(to), "{from}");
assert_eq!(shift_iso(to, 0).as_deref(), Some(to), "{to} reads back");
}
}
/// Sorting, grouping and date rules read with `iso_seconds`, which stays lenient: only the
/// write path refuses what it can't fully read.
#[test]
fn reading_stays_lenient_for_sorting() {
let at_ten = iso_seconds("2026-01-01T10:00:00");
assert_eq!(iso_seconds("2026-01-01T10:00:00 and more"), at_ten);
assert_eq!(iso_seconds("2026-01-01T10:00:xx"), at_ten);
assert_eq!(iso_seconds("2026-01-01T10:0"), iso_seconds("2026-01-01"));
}
#[test]
fn impossible_times_are_rejected_not_rolled_over() {
for bad in ["2026-04-01T10:75:00", "2026-04-01 10:00:75", "2026-04-01T10:60", "2026-04-01T24:00:00", "2026-04-01T10:59:60"] {
assert_eq!(normalize_iso(bad), None, "{bad}");
assert_eq!(shift_iso(bad, 5), None, "{bad}");
}
assert_eq!(normalize_iso("2026-04-01T23:59:59").as_deref(), Some("2026-04-01T23:59:59"));
}
#[test]
fn runs_by_day_month_year_keep_stacks_together() {
let mut c = Catalog::new();
let times = ["2026-09-30T18:00:00", "2026-09-30T09:00:00", "2026-09-29T23:59:00", "2026-08-01T10:00:00", "2025-12-31T10:00:00", ""];
let mut ids = Vec::new();
for t in times {
let id = c.alloc_photo_id();
let mut p = Photo::new(id, Source::Demo { scene: 1 }, "a.jpg", "JPEG", 3, 2, "2026-10-01T00:00:00");
p.captured = (!t.is_empty()).then(|| t.to_string());
c.apply(Op::AddPhoto { photo: Box::new(p) }).unwrap();
ids.push(id);
}
let shape = |r: &[DateRun]| r.iter().map(|r| (r.key.clone(), r.start, r.count)).collect::<Vec<_>>();
let day = c.date_runs(&ids, SortKey::CaptureDate, GroupBy::Day);
// the undated photo is grouped under Unknown Date
assert_eq!(
shape(&day),
vec![
("2026-09-30".into(), 0, 2),
("2026-09-29".into(), 2, 1),
("2026-08-01".into(), 3, 1),
("2025-12-31".into(), 4, 1),
(String::new(), 5, 1)
]
);
assert_eq!(day[0].label, "Wednesday, 30 September 2026");
assert_eq!(day[4].label, "Unknown Date");
assert_eq!(c.date_runs(&ids, SortKey::CaptureDate, GroupBy::Auto), day);
assert_eq!(
shape(&c.date_runs(&ids, SortKey::CaptureDate, GroupBy::Month)),
vec![("2026-09".into(), 0, 3), ("2026-08".into(), 3, 1), ("2025-12".into(), 4, 1), (String::new(), 5, 1)]
);
assert_eq!(
shape(&c.date_runs(&ids, SortKey::CaptureDate, GroupBy::Year)),
vec![("2026".into(), 0, 4), ("2025".into(), 4, 1), (String::new(), 5, 1)]
);
assert!(c.date_runs(&ids, SortKey::FileName, GroupBy::Day).is_empty());
assert!(c.date_runs(&ids, SortKey::CaptureDate, GroupBy::None).is_empty());
// edit date: unedited photos have no date
let r = c.date_runs(&ids, SortKey::EditDate, GroupBy::Day);
assert_eq!(shape(&r), vec![(String::new(), 0, 6)]);
assert_eq!(r[0].label, "Unknown Date");
// a stack spanning midnight stays in its first member's group
let op = c.group_ops(ids[1], &[ids[1], ids[2]], false).unwrap();
c.apply(op).unwrap();
let arranged = c.arrange_stacks(&ids[..5]);
assert_eq!(
shape(&c.date_runs(&arranged, SortKey::CaptureDate, GroupBy::Day))[..2],
[("2026-09-30".into(), 0, 3), ("2026-08-01".into(), 3, 1)]
);
}
}
No file is open. Choose one in the tree, or press Ctrl+O (⌘O on a Mac) to find one by name.
Syntax highlighting could not load. The unmodified read-only text remains available above.