deep_time/dt/
formatting.rs

1use crate::{Dt, DtErr, Scale};
2use alloc::string::String;
3
4impl Dt {
5    /// Returns this instant as an **RFC 3339** / ISO 8601 timestamp in **UTC**
6    /// with the `Z` suffix.
7    ///
8    /// - Always uses UTC (`Z` = Zulu = UTC).
9    /// - Default = 9 digits (nanoseconds) but **automatically trims trailing zeros**.
10    /// - If fractional part is zero → no decimal point at all (e.g. `...45Z`).
11    /// - Example: `"2024-03-14T15:30:45.123Z"`
12    #[inline]
13    pub fn to_str_rfc3339(&self, current: Scale) -> Result<String, DtErr> {
14        self.to_str_rfc3339_nf(current, 9)
15    }
16
17    /// Same as [`to_str_rfc3339`] but with a configurable maximum number of fractional digits
18    /// (0–18). Trailing zeros are always trimmed.
19    pub fn to_str_rfc3339_nf(&self, current: Scale, max_precision: usize) -> Result<String, DtErr> {
20        let prec = max_precision.min(18);
21        // Uses the formatter with the `~` "trim trailing zeros" flag.
22        // The formatter already handles:
23        //   - correct 4-digit years (with sign) for |yr| < 10000
24        //   - full-width years otherwise
25        //   - suppressing the decimal point entirely when the trimmed fraction is zero
26        let fmt = alloc::format!("%Y-%m-%dT%H:%M:%S%.{}~fZ", prec);
27        self.to_str_with_offset(current, &fmt, 0)
28    }
29
30    /// **ISO 8601 / RFC 3339** with **actual offset** (modern `+00:00` style).
31    ///
32    /// - Uses colon-separated offset (`%:z`) instead of forcing `Z`.
33    /// - Still trims trailing zeros in the fractional part.
34    /// - Example: `"2025-04-16T14:30:45.123+00:00"`
35    #[inline]
36    pub fn to_str_iso8601(&self, current: Scale) -> Result<String, DtErr> {
37        self.to_str_with_offset(current, "%Y-%m-%dT%H:%M:%S%.~f%:z", 0)
38    }
39
40    /// **Compact ISO 8601 basic format** (no separators).
41    ///
42    /// - Useful for filenames, URLs, database keys, etc.
43    /// - Example: `"20250416T143045.123456789Z"`
44    #[inline]
45    pub fn to_str_iso8601_basic(&self, current: Scale) -> Result<String, DtErr> {
46        self.to_str_with_offset(current, "%Y%m%dT%H%M%S%.~fZ", 0)
47    }
48
49    /// **HTTP-date** format (RFC 7231 / RFC 1123) — **always in GMT**.
50    ///
51    /// This is the format used in `Date`, `Expires`, `Last-Modified` headers.
52    /// Example: `"Wed, 16 Apr 2025 14:30:45 GMT"`
53    #[inline]
54    pub fn to_str_http(&self, current: Scale) -> Result<String, DtErr> {
55        self.to_str_with_offset(current, "%a, %d %b %Y %H:%M:%S GMT", 0)
56    }
57
58    /// **RFC 2822** date format (used in email `Date` headers).
59    ///
60    /// Example: `"Wed, 16 Apr 2025 14:30:45 +0000"`
61    #[inline]
62    pub fn to_str_rfc2822(&self, current: Scale) -> Result<String, DtErr> {
63        self.to_str_with_offset(current, "%a, %d %b %Y %H:%M:%S %z", 0)
64    }
65
66    /// **ISO 8601 week date**.
67    ///
68    /// Example: `"2025-W16-3"` (year-week-day)
69    #[inline]
70    pub fn to_str_iso_week_date(&self, current: Scale) -> Result<String, DtErr> {
71        self.to_str_with_offset(current, "%G-W%V-%u", 0)
72    }
73
74    /// Just the **ISO date** part (no time).
75    ///
76    /// Example: `"2025-04-16"`
77    #[inline]
78    pub fn to_str_iso_date(&self, current: Scale) -> Result<String, DtErr> {
79        self.to_str_with_offset(current, "%Y-%m-%d", 0)
80    }
81
82    /// Just the **time** part with fractional seconds (trimmed).
83    ///
84    /// Example: `"14:30:45.123456789"`
85    #[inline]
86    pub fn to_str_iso_time(&self, current: Scale) -> Result<String, DtErr> {
87        self.to_str_with_offset(current, "%H:%M:%S%.~f", 0)
88    }
89}
deep_time/dt/formatting.rs

deep_time/dt/
formatting.rs
