readme/
readme.rs

1use deep_time::{Dt, DtErr, Lang, LiteStr, ParseCfg, Scale, YmdHms};
2
3fn main() -> Result<(), DtErr> {
4    // ============================================
5    // Parsing
6    // ============================================
7
8    // Smart auto-parsing (multi-language + timezone)
9    let cfg = ParseCfg {
10        lang: Lang::Fr,
11        ..Default::default()
12    };
13    let dt = Dt::from_str_parse("15 août 2024 à 14:30 [Europe/Paris]", &cfg)?;
14    let s = dt.to_str_rfc9557("Europe/Paris")?;
15    assert_eq!("2024-08-15T14:30:00+02:00[Europe/Paris]", s);
16
17    // or with .parse
18    let dt: Dt = "1 jan 2000 07:00 [America/New_York] TAI".parse()?; // noon
19    assert_eq!(Dt::ZERO, dt);
20
21    // Relative dates are also supported
22    let ref_time = Dt::from_ymd(2026, 6, 16, Scale::UTC, 12, 0, 0, 0);
23    let en_cfg = ParseCfg {
24        ref_time: Some(ref_time),
25        ..Default::default()
26    };
27
28    let dt = Dt::from_str_parse("2 days from now at 9am", &en_cfg)?;
29    assert_eq!(dt, Dt::from_ymd(2026, 6, 18, Scale::UTC, 9, 0, 0, 0));
30
31    let dt = Dt::from_str_parse("next Monday at 14:00", &en_cfg)?;
32    assert_eq!(dt, Dt::from_ymd(2026, 6, 22, Scale::UTC, 14, 0, 0, 0));
33
34    // Relative dates use Dt::now if the `std` feature is enabled and no
35    // ref_time is provided in the ParseCfg
36    let _ = Dt::from_str_parse("next Monday at 14:00", &ParseCfg::DEFAULT)?;
37
38    // Fast ISO parsing with time scale and no alloc output
39    let dt = Dt::from_str_iso("2000-01-01T12:00:00 TAI")?;
40    let lite_str: LiteStr<512> = dt.to_str_lite_iso8601()?;
41    assert_eq!("2000-01-01T12:00:00+00:00", lite_str.as_str());
42
43    // ============================================
44    // Formatting
45    // ============================================
46
47    let s = dt.to_str_in_tz("%A, %d %B %Y %I:%M%P", "America/New_York", Lang::En)?;
48    assert_eq!("Saturday, 01 January 2000 07:00am", s);
49
50    let s = dt.to_str_in_tz("%A, %-d de %B de %Y %H:%M", "America/New_York", Lang::Es)?;
51    assert_eq!("Sábado, 1 de enero de 2000 07:00", s);
52
53    // ============================================
54    // Duration parsing
55    // ============================================
56
57    let span: Dt = Dt::from_str_duration("3 days 12 hours", Lang::En)?;
58    let dur = span.to_str_lite_media_duration();
59    assert_eq!("3:12:00:00", dur.to_string());
60
61    // ============================================
62    // Time scale conversions + round-tripping
63    // ============================================
64
65    let dt = Dt::from_ymd(2000, 1, 1, Scale::TAI, 0, 0, 0, 123456789);
66    let tt = dt.to(Scale::TT);
67    let tdb = tt.to(Scale::TDB);
68    let ltc = tdb.to(Scale::LTC);
69    let utc = ltc.to(Scale::UTC);
70    let tcl = utc.to(Scale::TCL);
71    let tcg = tcl.to(Scale::TCG);
72    let tai = tcg.to_tai();
73
74    // round trips work for pretty much everything except UTCHist
75    assert_eq!(dt, tai);
76    let ymd: YmdHms = tai.to_ymd();
77    assert_eq!(ymd.attos(), 123456789);
78
79    // ============================================
80    // Other conversions
81    // ============================================
82
83    // unix
84    let dt = Dt::from_ymd(1970, 1, 1, Scale::UTC, 0, 0, 0, 0);
85    let unix = dt.to_unix().to_sec_f();
86    assert_eq!(unix, 0.0);
87
88    // or to milliseconds
89    let unix: i128 = dt.add_ms(1000).to_unix().to_ms();
90    assert_eq!(unix, 1000);
91
92    // to and from jd
93    let jd = Dt::ZERO.to_jd_f();
94    assert_eq!(2451545.0, jd);
95    let dt = Dt::from_jd_f(jd, Scale::TAI);
96    assert_eq!(0, dt.attos);
97
98    // ============================================
99    // Calendar math
100    // ============================================
101
102    // calendar math and negative year
103    let dt = Dt::from_ymd(-2000, 1, 31, Scale::TAI, 12, 0, 0, 0);
104    let ymd = dt.add_mo(1).to_ymd();
105    assert_eq!(ymd.day(), 29);
106
107    // Timezone-aware calendar math (respects DST transitions, requires jiff-tz feature)
108    let dt = Dt::from_str_iso("2025-03-30T00:30:00Z")?; // Just before London DST start
109
110    // Normal (naive) addition — ignores DST rules
111    let normal = dt.add_hr(1);
112
113    // Timezone-aware addition — correctly handles the transition
114    let aware = dt.add_hr_tz(1, "Europe/London")?;
115
116    println!("Normal: {}", normal.to_str_rfc9557("Europe/London")?);
117    println!("Aware:  {}", aware.to_str_rfc9557("Europe/London")?);
118
119    // ============================================
120    // Leap seconds
121    // ============================================
122
123    // genuine leap second input round trips
124    let dt: Dt = "2015-06-30T23:59:60".parse()?;
125    let s = dt.to_str_iso8601();
126    assert_eq!("2015-06-30T23:59:60+00:00", s);
127
128    Ok(())
129}
readme/readme.rs

readme/
readme.rs
