time.rs (3527B)
1 use crate::UnixSeconds; 2 use core::fmt; 3 4 /// Pinned IANA data identity shared with the retained calendar source. 5 pub const TIME_ZONE_DATABASE_VERSION: &str = "2026c"; 6 7 /// Exact canonical IANA identifier, without ambient clock or conversion effects. 8 #[derive(Clone, Copy, Eq, PartialEq, Ord, PartialOrd, Hash)] 9 #[cfg_attr(feature = "serde", derive(serde::Serialize))] 10 #[cfg_attr(feature = "serde", serde(transparent))] 11 pub struct TimeZoneId(&'static str); 12 impl TimeZoneId { 13 /// Admits a bounded exact name from the pinned dataset. Case, whitespace and 14 /// unknown names are never normalized or replaced with a guessed zone. 15 pub fn from_name(value: &str) -> Result<Self, TimeError> { 16 if jiff_tzdb::VERSION != Some(TIME_ZONE_DATABASE_VERSION) { 17 return Err(TimeError::UnsupportedDatabase); 18 } 19 if value.is_empty() || value.len() > 80 { 20 return Err(TimeError::InvalidTimeZone); 21 } 22 let (canonical, _) = jiff_tzdb::get(value).ok_or(TimeError::InvalidTimeZone)?; 23 if canonical != value { 24 return Err(TimeError::InvalidTimeZone); 25 } 26 Ok(Self(canonical)) 27 } 28 /// Returns the exact validated name, not a claim about an ambient zone. 29 pub const fn name(self) -> &'static str { 30 self.0 31 } 32 } 33 impl fmt::Debug for TimeZoneId { 34 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 35 f.write_str("TimeZoneId(<redacted>)") 36 } 37 } 38 39 /// Ordered absolute instants and an explicit display zone. No local wall-time 40 /// ambiguity, fold or offset is guessed; civil conversion is a separate job. 41 #[derive(Clone, Copy, Eq, PartialEq)] 42 #[cfg_attr(feature = "serde", derive(serde::Serialize))] 43 pub struct Window { 44 start: UnixSeconds, 45 end: UnixSeconds, 46 timezone: TimeZoneId, 47 } 48 impl Window { 49 /// Requires a strictly later end, preserving the existing calendar rule. 50 pub fn new( 51 start: UnixSeconds, 52 end: UnixSeconds, 53 timezone: TimeZoneId, 54 ) -> Result<Self, TimeError> { 55 if end <= start { 56 return Err(TimeError::InvalidWindow); 57 } 58 Ok(Self { 59 start, 60 end, 61 timezone, 62 }) 63 } 64 /// Returns the exact absolute start without observing current time. 65 pub const fn start(self) -> UnixSeconds { 66 self.start 67 } 68 /// Returns the exact strictly later end. 69 pub const fn end(self) -> UnixSeconds { 70 self.end 71 } 72 /// Returns the explicit validated display-zone identity. 73 pub const fn timezone(self) -> TimeZoneId { 74 self.timezone 75 } 76 } 77 impl fmt::Debug for Window { 78 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 79 f.write_str("Window(<redacted>)") 80 } 81 } 82 83 /// Input-free shared time-value failure, with no ambient fallback. 84 #[derive(Clone, Copy, Debug, Eq, PartialEq)] 85 #[non_exhaustive] 86 pub enum TimeError { 87 /// An unknown, noncanonical or excessive IANA name was supplied. 88 InvalidTimeZone, 89 /// End is not strictly after start. 90 InvalidWindow, 91 /// Compiled data does not match the explicitly pinned version. 92 UnsupportedDatabase, 93 } 94 impl fmt::Display for TimeError { 95 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 96 f.write_str(match self { 97 Self::InvalidTimeZone => "invalid time zone", 98 Self::InvalidWindow => "invalid absolute window", 99 Self::UnsupportedDatabase => "unsupported time zone database", 100 }) 101 } 102 } 103 impl core::error::Error for TimeError {}