deep_time/tz/
mod.rs

1//! Time zone name helpers.
2//!
3//! This module exposes [`UTC_ALIASES`] and [`tz_names`], used internally by the
4//! parser and formatter to recognize IANA time zone identifiers in input strings
5//! and to enumerate available zones at runtime.
6//!
7//! ## Behavior by feature
8//!
9//! | Configuration | [`tz_names`] yields |
10//! |---------------|---------------------|
11//! | `jiff-tz` or `jiff-tz-bundle` (with `alloc`) | All IANA identifiers from the bundled Jiff TZ database |
12//! | `alloc` without `jiff-tz` | [`UTC_ALIASES`] only |
13//! | `no_alloc` | [`UTC_ALIASES`] only (no heap) |
14//!
15//! Time zone–aware formatting and calendar math ([`Dt::to_str_in_tz`](../struct.Dt.html#method.to_str_in_tz),
16//! [`Dt::add_hr_tz`](../struct.Dt.html#method.add_hr_tz), etc.) require the `jiff-tz` feature.
17//! [`tz_names`] is independent of those APIs but uses the same database when `jiff-tz` is enabled.
18//!
19//! ## Examples
20//!
21//! Iterate over IANA time zone names when `jiff-tz` is enabled:
22//!
23//! ```rust
24//! # #[cfg(feature = "jiff-tz")]
25//! # {
26//! use deep_time::tz::tz_names;
27//!
28//! let mut found_london = false;
29//! for name in tz_names() {
30//!     if name.as_str() == "Europe/London" {
31//!         found_london = true;
32//!         break;
33//!     }
34//! }
35//! assert!(found_london);
36//! # }
37//! ```
38//!
39//! Without `jiff-tz`, only UTC aliases are returned:
40//!
41//! ```rust
42//! # #[cfg(not(any(feature = "jiff-tz-bundle", feature = "jiff-tz")))]
43//! # {
44//! use deep_time::tz::{tz_names, UTC_ALIASES};
45//!
46//! let count = tz_names().count();
47//! assert_eq!(count, UTC_ALIASES.len());
48//! assert!(tz_names().any(|n| n.as_str() == "UTC"));
49//! # }
50//! ```
51
52use crate::LiteStr;
53
54/// Well-known aliases for UTC accepted in parsed date/time strings.
55pub static UTC_ALIASES: &[&str] = &[
56    "Etc/UCT",
57    "Etc/UTC",
58    "Etc/Universal",
59    "Etc/Zulu",
60    "UCT",
61    "UTC",
62    "Universal",
63    "Zulu",
64];
65
66/// Returns an iterator over known time zone names as [`LiteStr<49>`](../struct.LiteStr.html).
67///
68/// With `jiff-tz` or `jiff-tz-bundle`, yields every IANA identifier from the Jiff
69/// time zone database. Otherwise yields only [`UTC_ALIASES`].
70pub fn tz_names() -> impl Iterator<Item = LiteStr<49>> {
71    #[cfg(feature = "alloc")]
72    {
73        tz_names_alloc()
74    }
75    #[cfg(not(feature = "alloc"))]
76    {
77        tz_names_no_alloc()
78    }
79}
80
81// alloc version (uses Jiff when available)
82#[cfg(feature = "alloc")]
83fn tz_names_alloc() -> impl Iterator<Item = LiteStr<49>> {
84    #[cfg(any(feature = "jiff-tz-bundle", feature = "jiff-tz"))]
85    {
86        jiff::tz::db()
87            .available()
88            .map(|s| LiteStr::new(&s.to_string()))
89    }
90    #[cfg(not(any(feature = "jiff-tz-bundle", feature = "jiff-tz")))]
91    {
92        UTC_ALIASES.iter().copied().map(LiteStr::new)
93    }
94}
95
96// no-alloc version (only UTC aliases)
97#[cfg(not(feature = "alloc"))]
98fn tz_names_no_alloc() -> impl Iterator<Item = LiteStr<49>> {
99    UTC_ALIASES.iter().copied().map(LiteStr::new)
100}
deep_time/tz/mod.rs

deep_time/tz/
mod.rs
