lib

Core libraries for Radroots
git clone https://radroots.dev/git/lib.git
Log | Files | Refs | README

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 {}