deep_time/alloc_parse/types.rs
1use crate::{Dt, Lang};
2use alloc::string::String;
3use alloc::vec::Vec;
4
5/// Used by [`ParseCfg`] in
6/// [`Dt::from_str_parse`](../struct.Dt.html#method.from_str_parse). Controls
7/// how ambiguous dates (e.g. `01/02/03`) are parsed.
8///
9/// The default `Smart` variant applies a practical heuristic that prefers
10/// year-first for compact formats and uses numeric plausibility checks
11/// for other cases. The other variants force a specific ordering.
12#[derive(Clone, Copy, Debug, PartialEq, Default)]
13#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
14#[cfg_attr(feature = "tsify", derive(tsify::Tsify))]
15pub enum Order {
16 /// Heuristic for **mixed data**. Uses the following rules, in this order:
17 ///
18 /// 1. **Pure-numeric compact formats** (≥ 6 digits with no separators,
19 /// e.g. `240314153045`, `20240315`, `YYMMDDHHMMSS`):
20 /// treated as **Year-first** (`%Y%m%d` / `%y%m%d`).
21 /// These are overwhelmingly used in logs, filenames, databases, APIs,
22 /// configs, and JSON for sortability.
23 ///
24 /// 2. **Delimited formats that start with a plausible 4-digit year**
25 /// (1900–2100): treated as **Year-first**.
26 ///
27 /// 3. **Numeric plausibility check** (strongest universal signal):
28 /// - First number is 13–31 → **Day-first** (international/European style).
29 /// - First number is 1–12 **and** second number is 13–31 → **Month-first**
30 /// (US style).
31 ///
32 /// 4. **Strong ISO 8601 / timestamp markers** (`T` connector, `Z`, numeric
33 /// offsets, or IANA timezone names) → **Year-first**.
34 ///
35 /// 5. **Fallback**:
36 /// - With the `locale` feature enabled: respects the system locale
37 /// preference (Day-first in most of the world).
38 /// - Without the `locale` feature: **Day-first** (global majority).
39 ///
40 /// The `/` separator is deliberately ignored in the plausibility step
41 /// because it is culturally ambiguous.
42 ///
43 /// Once the preferred ordering is determined, the parser tries that order
44 /// first, then the other two (e.g. Day → Month → Year), before any
45 /// year-first unambiguous fallback.
46 #[default]
47 Smart,
48 /// Prefer **Year-first** (YYYY/MM/DD or YY/MM/DD), then Day, then Month.
49 Year,
50 /// Prefer **Day-first** (DD/MM/YYYY), then Month, then Year.
51 Day,
52 /// Prefer **Month-first** (MM/DD/YYYY), then Day, then Year.
53 Month,
54}
55
56#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
57#[cfg_attr(feature = "tsify", derive(tsify::Tsify))]
58#[derive(Clone, Copy, Debug, Default, PartialEq)]
59/// Used by [`ParseCfg`] in
60/// [`Dt::from_str_parse`](../struct.Dt.html#method.from_str_parse). Controls how purely
61/// numeric dates are parsed.
62pub enum Mode {
63 /// **Default mode** — Smart heuristic:
64 /// - 5/7-digit pure-numeric inside `LEGACY_ORDINAL_YEAR_RANGE` → treated as business
65 /// ordinal (YYYYDDD / YYDDD)
66 /// - Outside that range or invalid ordinal → treated as MJD or JD
67 #[default]
68 Auto,
69 /// When combined with a provided Vec of formats in parse no other formats are tried.
70 Explicit,
71 /// It's some sort of unix timestamp
72 UnixTimestamp,
73 /// Business/legacy-only mode:
74 /// Only accepts ordinal dates (YYYYDDD / YYDDD). No astronomy (JD/MJD) support.
75 /// Strict and predictable for ERP/mainframe data.
76 Legacy,
77 /// Scientific / astronomy-first mode:
78 /// Prioritizes MJD (5-digit) and JD (7-digit). Ordinals are only fallback.
79 /// Use this when parsing data from astronomy tools or large numeric epochs.
80 Scientific,
81}
82
83/// Configuration options for
84/// [`Dt::from_str_parse`](../struct.Dt.html#method.from_str_parse).
85///
86/// Controls language, ambiguous date order, numeric parsing mode,
87/// explicit `strptime` formats, relative-date support, and reference time.
88///
89/// These settings will not persist between parse calls and have to be used
90/// as an arg every time you want them.
91#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
92#[cfg_attr(feature = "tsify", derive(tsify::Tsify))]
93#[derive(Clone, Debug, PartialEq)]
94pub struct ParseCfg {
95 /// Explicit list of formats to try **in the exact order given**.
96 ///
97 /// If this is provided and the vec is non-empty and the mode is Explicit
98 /// then only these formats are tried and `mode` and `order` are ignored.
99 ///
100 /// If the mode is not Explicit then after trying the formats in parse the
101 /// rest of the parser will continue as normal, using `mode` and `order`.
102 ///
103 /// Example:
104 /// ```js
105 /// parse: ["%Y-%m-%d", "%d/%m/%Y", "%m/%d/%Y", "%d.%m.%Y"]
106 /// ```
107 #[cfg_attr(feature = "serde", serde(default))]
108 pub parse: Option<Vec<String>>,
109
110 /// Controls which preset format sets are used (astronomy/scientific formats,
111 /// legacy business rules, etc.).
112 #[cfg_attr(feature = "serde", serde(default))]
113 pub mode: Mode,
114
115 /// Controls ambiguous numeric dates.
116 #[cfg_attr(feature = "serde", serde(default))]
117 pub order: Order,
118
119 /// Sets language to use for a particular parse call.
120 #[cfg_attr(feature = "serde", serde(default))]
121 pub lang: Lang,
122
123 /// Whether to lowercase the input:
124 /// ONLY set to `false` if the &str is already lowercase.
125 #[cfg_attr(feature = "serde", serde(default = "default_true"))]
126 pub to_lower: bool,
127
128 /// Whether to parse relative dates as well as normal dates.
129 #[cfg_attr(feature = "serde", serde(default = "default_true"))]
130 pub relative: bool,
131
132 /// **Reference ("current") time** used for relative expressions:
133 /// - "tomorrow", "next Friday", "in 3 days", "next week"
134 /// - If `Some`, this `Dt` is used as "now" (overrides everything).
135 /// - If `None` + `std` feature enabled: automatically uses real system time.
136 /// - If `None` + no `std`: parsing relative dates will fail with a clear error.
137 #[cfg_attr(feature = "serde", serde(default))]
138 pub ref_time: Option<Dt>,
139}
140
141#[cfg(feature = "serde")]
142fn default_true() -> bool {
143 true
144}
145
146impl ParseCfg {
147 /// Default configuration (all smart defaults).
148 ///
149 /// Pass a reference to this when you want the standard parsing behavior:
150 ///
151 /// ```rust
152 /// use deep_time::{Dt, ParseCfg};
153 ///
154 /// let dt = Dt::from_str_parse("2024-03-15 12:00", &ParseCfg::DEFAULT).unwrap();
155 /// ```
156 pub const DEFAULT: Self = Self {
157 parse: None,
158 mode: Mode::Auto,
159 order: Order::Smart,
160 lang: Lang::En,
161 to_lower: true,
162 relative: true,
163 ref_time: None,
164 };
165}
166
167impl Default for ParseCfg {
168 fn default() -> ParseCfg {
169 Self::DEFAULT
170 }
171}
172
173#[derive(Debug, Clone, Copy, PartialEq, Eq)]
174pub(crate) enum OrderFirst {
175 /// Year-Month-Day ordering (ISO 8601 style, `YYYY-MM-DD`, `20240315`, etc.)
176 Year,
177 /// Month-Day-Year ordering (US / some English locales, `MM/DD/YYYY`)
178 Month,
179 /// Day-Month-Year ordering (most of the world, `DD/MM/YYYY`, `DD.MM.YYYY`)
180 Day,
181}
182
183#[derive(Clone)]
184pub(crate) struct AmBuilder {
185 pub pieces: Vec<&'static str>,
186 pub seen_year: bool,
187 pub seen_month: bool,
188 pub seen_day: bool,
189}
190
191#[inline]
192pub(crate) fn append_to_all(builders: &mut Vec<AmBuilder>, s: &'static str) {
193 for b in builders {
194 b.pieces.push(s);
195 }
196}