Skip to main content

day_localization/
datetime.rs

1// Copyright © The Daybrite Project
2// SPDX-License-Identifier: MPL-2.0
3
4//! Locale-aware dates and times outside a message (docs/localization.md "Dates outside a
5//! message"), backed by the same icu4x formatter as the Fluent `DATETIME()` builtin.
6//!
7//! A chart's time axis, a table's date column and a "last updated" readout all need a date in the
8//! reader's own form (`Mar 5` in English, `5 mars` in French, `05.03.` in German, `03/05` in
9//! Japanese, and `3:30 PM` against `15:30` for the clock) with no message to hang it on. Assembled
10//! by hand from an English month list it is wrong in most locales, in the words, in the order,
11//! and in the hour cycle.
12//!
13//! [`DateFields`] names *which* parts to show, which is the decision the caller actually has (an
14//! axis spanning years shows years, one spanning hours shows clock times); the locale decides how
15//! they are written. Formatters are cached per (locale, fields) in a thread-local; any failure
16//! degrades to an ISO-8601 rendering rather than an error or a blank.
17
18use std::cell::RefCell;
19use std::collections::HashMap;
20
21use icu_calendar::cal::Gregorian;
22use icu_datetime::FixedCalendarDateTimeFormatter;
23use icu_datetime::fieldsets::enums::CompositeDateTimeFieldSet;
24
25/// Which parts of an instant to write. The locale decides their order, words and punctuation.
26#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
27pub enum DateFields {
28    /// `2026`.
29    Year,
30    /// `Mar 2026` · `mars 2026` · `03/2026` · `2026/03`.
31    YearMonth,
32    /// `Mar` · `mars` · `Mär` · `3月`: a month on its own, for a column of months (a calendar heat
33    /// map's header) whose years are elsewhere.
34    Month,
35    /// `Mar 5` · `5 mars` · `05.03.` · `03/05`.
36    MonthDay,
37    /// `Mar 5, 2026` · `5 mars 2026` · `05.03.2026` · `2026/03/05`.
38    YearMonthDay,
39    /// `3:30 PM` · `15:30`: the clock in the locale's own hour cycle.
40    HourMinute,
41    /// `3:30:15 PM` · `15:30:15`.
42    HourMinuteSecond,
43}
44
45type Formatter = FixedCalendarDateTimeFormatter<Gregorian, CompositeDateTimeFieldSet>;
46
47day_reactive::tls_slots! {
48    datetime;
49    /// `None` = construction failed for that locale (negative-cached to avoid re-trying per call).
50    static FORMATTERS: RefCell<HashMap<(String, DateFields), Option<Formatter>>> =
51        RefCell::new(HashMap::new());
52}
53
54fn build(locale: &str, fields: DateFields) -> Option<Formatter> {
55    use icu_datetime::fieldsets::builder::{DateFields as Icu, FieldSetBuilder};
56    use icu_datetime::options::{Length, TimePrecision};
57
58    let parsed: icu_locale_core::Locale = locale.parse().ok()?;
59    let mut b = FieldSetBuilder::new();
60    // Medium: the locale's medium date form, an abbreviated month name where the locale writes
61    // one (`Mar 5`, `5 mars`) and its own numeric form where it does not (`05.03.`, `03/05`).
62    // Long would spell English months out in full, too wide for an axis; short would turn
63    // `Mar 5` into the ambiguous `3/5`.
64    b.length = Some(Length::Medium);
65    match fields {
66        DateFields::Year => b.date_fields = Some(Icu::Y),
67        DateFields::YearMonth => b.date_fields = Some(Icu::YM),
68        DateFields::Month => b.date_fields = Some(Icu::M),
69        DateFields::MonthDay => b.date_fields = Some(Icu::MD),
70        DateFields::YearMonthDay => b.date_fields = Some(Icu::YMD),
71        DateFields::HourMinute => b.time_precision = Some(TimePrecision::Minute),
72        DateFields::HourMinuteSecond => b.time_precision = Some(TimePrecision::Second),
73    }
74    let field_set = b.build_composite_datetime().ok()?;
75    Formatter::try_new((&parsed).into(), field_set).ok()
76}
77
78/// The ISO-8601 rendering of the requested fields, for every failure path.
79fn iso(fields: DateFields, (y, m, d): (i32, u8, u8), (hh, mm, ss): (u8, u8, u8)) -> String {
80    match fields {
81        DateFields::Year => format!("{y:04}"),
82        DateFields::YearMonth => format!("{y:04}-{m:02}"),
83        DateFields::Month => format!("{m:02}"),
84        DateFields::MonthDay => format!("{m:02}-{d:02}"),
85        DateFields::YearMonthDay => format!("{y:04}-{m:02}-{d:02}"),
86        DateFields::HourMinute => format!("{hh:02}:{mm:02}"),
87        DateFields::HourMinuteSecond => format!("{hh:02}:{mm:02}:{ss:02}"),
88    }
89}
90
91/// Write the instant `epoch_seconds` (seconds since 1970-01-01T00:00:00Z, read as UTC civil
92/// time, the convention of the Fluent `DATETIME()` builtin and of chart time axes) in `locale`,
93/// showing `fields` (untracked).
94#[must_use]
95pub fn format_date_in(locale: &str, epoch_seconds: f64, fields: DateFields) -> String {
96    if !epoch_seconds.is_finite() {
97        return format!("{epoch_seconds}");
98    }
99    let (Some(date), Some(time)) = crate::intl::from_epoch_seconds(epoch_seconds.floor() as i64)
100    else {
101        return format!("{epoch_seconds}");
102    };
103    let (Ok(d), Ok(t)) = (
104        icu_calendar::Date::try_new_gregorian(date.0, date.1, date.2),
105        icu_time::Time::try_new(time.0, time.1, time.2, 0),
106    ) else {
107        return iso(fields, date, time);
108    };
109    FORMATTERS.with(|c| {
110        let mut map = c.borrow_mut();
111        let formatter = map
112            .entry((locale.to_string(), fields))
113            .or_insert_with(|| build(locale, fields));
114        match formatter {
115            Some(f) => f
116                .format(&icu_time::DateTime { date: d, time: t })
117                .to_string(),
118            None => iso(fields, date, time),
119        }
120    })
121}
122
123/// [`format_date_in`] in the current locale (tracked, like [`crate::format_decimal`]), so a label
124/// inside a reactive closure re-renders when the locale switches.
125#[must_use]
126pub fn format_date(epoch_seconds: f64, fields: DateFields) -> String {
127    let locale = crate::locale().get();
128    format_date_in(&locale, epoch_seconds, fields)
129}
130
131#[cfg(test)]
132mod tests {
133    use super::*;
134
135    /// 2026-03-05T15:30:15Z.
136    const T: f64 = 1_772_724_615.0;
137
138    fn f(locale: &str, fields: DateFields) -> String {
139        // The exact spaces (a no-break space before `PM`, a narrow one in French) are CLDR's to
140        // choose; the assertions compare with them folded to plain spaces.
141        format_date_in(locale, T, fields).replace(['\u{a0}', '\u{202f}'], " ")
142    }
143
144    #[test]
145    fn a_month_and_day_are_written_the_locales_way() {
146        assert_eq!(f("en", DateFields::MonthDay), "Mar 5");
147        assert_eq!(f("fr", DateFields::MonthDay), "5 mars");
148        // German's and Japanese medium dates are numeric in CLDR: the locale's own form.
149        assert_eq!(f("de", DateFields::MonthDay), "05.03.");
150        assert_eq!(f("ja", DateFields::MonthDay), "03/05");
151    }
152
153    #[test]
154    fn a_month_and_year_are_written_the_locales_way() {
155        assert_eq!(f("en", DateFields::YearMonth), "Mar 2026");
156        assert_eq!(f("fr", DateFields::YearMonth), "mars 2026");
157        assert_eq!(f("de", DateFields::YearMonth), "03/2026");
158        assert_eq!(f("ja", DateFields::YearMonth), "2026/03");
159        assert_eq!(f("en", DateFields::Year), "2026");
160        assert_eq!(f("ja", DateFields::Year), "2026年");
161    }
162
163    #[test]
164    fn a_month_alone_is_the_locales_abbreviated_name() {
165        assert_eq!(f("en", DateFields::Month), "Mar");
166        assert_eq!(f("fr", DateFields::Month), "mars");
167        assert_eq!(f("de", DateFields::Month), "Mär");
168        assert_eq!(f("ja", DateFields::Month), "3月");
169        assert_eq!(f("ru", DateFields::Month), "март");
170    }
171
172    #[test]
173    fn a_full_date_follows_the_locales_order() {
174        assert_eq!(f("en", DateFields::YearMonthDay), "Mar 5, 2026");
175        assert_eq!(f("fr", DateFields::YearMonthDay), "5 mars 2026");
176        assert_eq!(f("de", DateFields::YearMonthDay), "05.03.2026");
177    }
178
179    #[test]
180    fn the_clock_keeps_the_locales_hour_cycle() {
181        assert_eq!(f("en", DateFields::HourMinute), "3:30 PM");
182        assert_eq!(f("fr", DateFields::HourMinute), "15:30");
183        assert_eq!(f("de", DateFields::HourMinute), "15:30");
184        assert_eq!(f("en", DateFields::HourMinuteSecond), "3:30:15 PM");
185        assert_eq!(f("fr", DateFields::HourMinuteSecond), "15:30:15");
186    }
187
188    #[test]
189    fn an_instant_before_the_epoch_and_a_non_finite_one_degrade_sensibly() {
190        // 1969-12-31T23:00:00Z: the day before the epoch, not the epoch's own day.
191        assert_eq!(
192            format_date_in("en", -3600.0, DateFields::YearMonthDay),
193            "Dec 31, 1969"
194        );
195        assert_eq!(format_date_in("en", f64::NAN, DateFields::Year), "NaN");
196    }
197
198    #[test]
199    fn an_unparseable_locale_falls_back_to_iso() {
200        assert_eq!(
201            format_date_in("", T, DateFields::YearMonthDay),
202            "2026-03-05"
203        );
204        assert_eq!(format_date_in("", T, DateFields::HourMinute), "15:30");
205    }
206
207    #[test]
208    fn the_tracked_form_follows_the_current_locale() {
209        crate::set_locale("fr");
210        assert_eq!(
211            format_date(T, DateFields::MonthDay).replace('\u{a0}', " "),
212            "5 mars"
213        );
214        crate::set_locale("en");
215        assert_eq!(format_date(T, DateFields::MonthDay), "Mar 5");
216    }
217}