rlg/
datetime.rs

1// datetime.rs
2// Copyright © 2024-2026 RustLogs (RLG). All rights reserved.
3// SPDX-License-Identifier: Apache-2.0
4// SPDX-License-Identifier: MIT
5
6//! Minimal ISO 8601 timestamp generation and validation.
7//!
8//! Uses only `std::time` — no external date crates. Replaces the historical
9//! `dtt` dependency (which transitively pulled the unmaintained `paste`
10//! crate, RUSTSEC-2024-0436).
11
12use crate::error::{RlgError, RlgResult};
13use std::time::{SystemTime, UNIX_EPOCH};
14
15/// Return the current UTC timestamp in RFC 3339 / ISO 8601 form with
16/// nanosecond precision: `YYYY-MM-DDTHH:MM:SS.fffffffffZ`.
17///
18/// Falls back to `1970-01-01T00:00:00.000000000Z` if the system clock
19/// is set before `UNIX_EPOCH`.
20#[must_use]
21pub fn now_iso8601() -> String {
22    let dur = SystemTime::now()
23        .duration_since(UNIX_EPOCH)
24        .unwrap_or_default();
25    format_epoch(dur.as_secs(), dur.subsec_nanos())
26}
27
28/// Validate `s` as an RFC 3339 / ISO 8601 timestamp.
29///
30/// Accepts the subset this crate emits: `YYYY-MM-DDTHH:MM:SS[.fff…]Z`
31/// or `YYYY-MM-DDTHH:MM:SS[.fff…][+HH:MM|-HH:MM]`. Returns the original
32/// input on success.
33///
34/// # Errors
35/// Returns [`RlgError::DateTimeParseError`] when the string does not
36/// match the supported grammar or contains out-of-range components.
37pub fn parse_iso8601(s: &str) -> RlgResult<String> {
38    validate(s).map(|()| s.to_string()).map_err(|why| {
39        RlgError::DateTimeParseError(format!("{s:?}: {why}"))
40    })
41}
42
43fn validate(s: &str) -> Result<(), &'static str> {
44    let bytes = s.as_bytes();
45    if bytes.len() < 20 {
46        return Err("too short");
47    }
48    if !is_ymd(&bytes[..10]) {
49        return Err("invalid date");
50    }
51    if bytes[10] != b'T' {
52        return Err("missing 'T' separator");
53    }
54    if !is_hms(&bytes[11..19]) {
55        return Err("invalid time");
56    }
57    // Optional fractional seconds, then mandatory zone designator.
58    let mut i = 19usize;
59    if bytes.get(i) == Some(&b'.') {
60        i += 1;
61        let start = i;
62        while bytes.get(i).is_some_and(u8::is_ascii_digit) {
63            i += 1;
64        }
65        if i == start {
66            return Err("empty fractional seconds");
67        }
68    }
69    match bytes.get(i) {
70        Some(&b'Z') if i + 1 == bytes.len() => Ok(()),
71        Some(&b'+' | &b'-') if bytes.len() - i == 6 => {
72            if is_offset(&bytes[i + 1..]) {
73                Ok(())
74            } else {
75                Err("invalid timezone offset")
76            }
77        }
78        _ => Err("missing timezone designator"),
79    }
80}
81
82fn is_ymd(b: &[u8]) -> bool {
83    b.len() == 10
84        && b[..4].iter().all(u8::is_ascii_digit)
85        && b[4] == b'-'
86        && b[5..7].iter().all(u8::is_ascii_digit)
87        && b[7] == b'-'
88        && b[8..10].iter().all(u8::is_ascii_digit)
89        && in_range(&b[5..7], 1, 12)
90        && in_range(&b[8..10], 1, 31)
91}
92
93fn is_hms(b: &[u8]) -> bool {
94    b.len() == 8
95        && b[..2].iter().all(u8::is_ascii_digit)
96        && b[2] == b':'
97        && b[3..5].iter().all(u8::is_ascii_digit)
98        && b[5] == b':'
99        && b[6..8].iter().all(u8::is_ascii_digit)
100        && in_range(&b[..2], 0, 23)
101        && in_range(&b[3..5], 0, 59)
102        && in_range(&b[6..8], 0, 60) // leap second tolerated
103}
104
105fn is_offset(b: &[u8]) -> bool {
106    b.len() == 5
107        && b[..2].iter().all(u8::is_ascii_digit)
108        && b[2] == b':'
109        && b[3..5].iter().all(u8::is_ascii_digit)
110        && in_range(&b[..2], 0, 23)
111        && in_range(&b[3..5], 0, 59)
112}
113
114fn in_range(b: &[u8], lo: u32, hi: u32) -> bool {
115    std::str::from_utf8(b)
116        .ok()
117        .and_then(|s| s.parse::<u32>().ok())
118        .is_some_and(|n| (lo..=hi).contains(&n))
119}
120
121/// Convert `seconds` since `UNIX_EPOCH` (+ `nanos`) into an RFC 3339 string.
122///
123/// Uses Howard Hinnant's `civil_from_days` algorithm — branch-free, no
124/// allocation beyond the final `String`.
125fn format_epoch(seconds: u64, nanos: u32) -> String {
126    let days = i64::try_from(seconds / 86_400).unwrap_or(0);
127    let sod = seconds % 86_400;
128    let hour = (sod / 3600) as u32;
129    let minute = ((sod % 3600) / 60) as u32;
130    let second = (sod % 60) as u32;
131    let (year, month, day) = civil_from_days(days);
132    format!(
133        "{year:04}-{month:02}-{day:02}T{hour:02}:{minute:02}:{second:02}.{nanos:09}Z"
134    )
135}
136
137/// Days since 1970-01-01 (UTC) → (year, month [1..=12], day [1..=31]).
138///
139/// Algorithm from <http://howardhinnant.github.io/date_algorithms.html>.
140#[allow(
141    clippy::cast_possible_truncation,
142    clippy::cast_possible_wrap,
143    clippy::cast_sign_loss
144)]
145const fn civil_from_days(days: i64) -> (i32, u32, u32) {
146    let z = days + 719_468;
147    let era = if z >= 0 { z } else { z - 146_096 } / 146_097;
148    let doe = (z - era * 146_097) as u64;
149    let yoe = (doe - doe / 1460 + doe / 36_524 - doe / 146_096) / 365;
150    let y = yoe as i64 + era * 400;
151    let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
152    let mp = (5 * doy + 2) / 153;
153    let d = (doy - (153 * mp + 2) / 5 + 1) as u32;
154    let m = if mp < 10 { mp + 3 } else { mp - 9 } as u32;
155    let year_offset: i64 = if m <= 2 { 1 } else { 0 };
156    ((y + year_offset) as i32, m, d)
157}
158
159#[cfg(test)]
160mod tests {
161    use super::*;
162
163    #[test]
164    fn now_iso8601_shape() {
165        let s = now_iso8601();
166        assert_eq!(s.len(), 30, "{s}"); // YYYY-MM-DDTHH:MM:SS.fffffffffZ
167        assert!(s.ends_with('Z'));
168        assert_eq!(&s[4..5], "-");
169        assert_eq!(&s[10..11], "T");
170        assert!(parse_iso8601(&s).is_ok(), "roundtrip failed for {s}");
171    }
172
173    #[test]
174    fn parses_canonical_utc() {
175        assert!(parse_iso8601("2024-08-29T12:00:00Z").is_ok());
176        assert!(
177            parse_iso8601("1970-01-01T00:00:00.000000000Z").is_ok()
178        );
179        assert!(parse_iso8601("2099-12-31T23:59:59.123Z").is_ok());
180    }
181
182    #[test]
183    fn parses_offset_zones() {
184        assert!(parse_iso8601("2024-08-29T12:00:00+02:00").is_ok());
185        assert!(parse_iso8601("2024-08-29T12:00:00.5-05:30").is_ok());
186    }
187
188    #[test]
189    fn rejects_garbage() {
190        assert!(parse_iso8601("").is_err());
191        assert!(parse_iso8601("not a date").is_err());
192        assert!(parse_iso8601("2024-13-29T12:00:00Z").is_err()); // bad month
193        assert!(parse_iso8601("2024-08-32T12:00:00Z").is_err()); // bad day
194        assert!(parse_iso8601("2024-08-29T24:00:00Z").is_err()); // bad hour
195        assert!(parse_iso8601("2024-08-29T12:00:00").is_err()); // missing zone
196        assert!(parse_iso8601("2024-08-29 12:00:00Z").is_err()); // missing T
197    }
198
199    #[test]
200    fn known_epoch_values() {
201        assert_eq!(
202            format_epoch(0, 0),
203            "1970-01-01T00:00:00.000000000Z"
204        );
205        // 1700000000 = 2023-11-14T22:13:20Z
206        assert_eq!(
207            format_epoch(1_700_000_000, 0),
208            "2023-11-14T22:13:20.000000000Z"
209        );
210    }
211
212    #[test]
213    fn rejects_dangling_fractional_dot() {
214        // Hits the `empty fractional seconds` branch.
215        let r = parse_iso8601("2024-08-29T12:00:00.Z");
216        let msg = r.unwrap_err().to_string();
217        assert!(msg.contains("empty fractional seconds"), "got: {msg}");
218    }
219
220    #[test]
221    fn rejects_invalid_timezone_offset() {
222        // Hits the `invalid timezone offset` branch (right length, bad digits).
223        let r = parse_iso8601("2024-08-29T12:00:00+99:99");
224        let msg = r.unwrap_err().to_string();
225        assert!(msg.contains("invalid timezone offset"), "got: {msg}");
226    }
227
228    #[test]
229    fn rejects_missing_timezone_designator() {
230        // Hits the `_` (catch-all) arm in the match — neither Z nor +/-.
231        let r = parse_iso8601("2024-08-29T12:00:00X");
232        let msg = r.unwrap_err().to_string();
233        assert!(
234            msg.contains("missing timezone designator"),
235            "got: {msg}"
236        );
237    }
238
239    #[test]
240    fn civil_from_days_handles_pre_epoch() {
241        // Exercises the negative-`z` branch in civil_from_days.
242        // The algorithm anchors at days = -719_468 → 0000-03-01, so
243        // -719_469 lands on 0000-02-29 (year 0 is a leap year in
244        // proleptic Gregorian). What matters here is hitting the
245        // `z < 0` arm in `civil_from_days`, not the exact value.
246        let (y, m, d) = civil_from_days(-719_469);
247        assert_eq!((y, m, d), (0, 2, 29));
248
249        // Also exercise a deeply negative input so era != 0.
250        let (y2, _, _) = civil_from_days(-1_000_000);
251        assert!(y2 < 0);
252    }
253}
rlg/datetime.rs

rlg/
datetime.rs
