use chrono::{DateTime, NaiveDateTime, Offset, TimeZone};
use chrono_tz::Tz;
use crate::{Error, Result, Value};
use super::{map_temporal, Temporal};
#[derive(Clone, Copy)]
pub(super) enum ZoneSpec<'a> {
Iana(&'a str),
Utc,
Fixed(&'a str),
Prefixed(&'a str),
Other(&'a str),
}
pub(super) fn strip_zone_prefix(z: &str) -> Option<&str> {
let (prefix, rest) = z.split_at_checked(3)?;
(prefix.eq_ignore_ascii_case("GMT") || prefix.eq_ignore_ascii_case("UTC")).then_some(rest)
}
fn is_prefixed_fixed_offset(z: &str) -> bool {
strip_zone_prefix(z)
.is_some_and(|rest| rest.is_empty() || rest.starts_with('+') || rest.starts_with('-'))
}
pub(super) fn zone_kind(z: &str) -> ZoneSpec<'_> {
if z.contains('/') {
ZoneSpec::Iana(z)
} else if z.eq_ignore_ascii_case("Z") {
ZoneSpec::Utc
} else if z.starts_with('+') || z.starts_with('-') {
ZoneSpec::Fixed(z)
} else if is_prefixed_fixed_offset(z) {
ZoneSpec::Prefixed(z)
} else {
ZoneSpec::Other(z)
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ZoneError {
UnknownZone,
NonexistentWallTime,
}
pub(super) enum LocalResolution {
Unique(DateTime<Tz>),
Ambiguous {
earlier: DateTime<Tz>,
later: DateTime<Tz>,
},
None,
}
impl LocalResolution {
pub(super) fn earliest(self) -> Option<DateTime<Tz>> {
match self {
LocalResolution::Unique(dt) => Some(dt),
LocalResolution::Ambiguous { earlier, .. } => Some(earlier),
LocalResolution::None => None,
}
}
}
pub(super) fn resolve_local(tz: Tz, local: NaiveDateTime) -> LocalResolution {
match tz.from_local_datetime(&local) {
chrono::LocalResult::Single(dt) => LocalResolution::Unique(dt),
chrono::LocalResult::Ambiguous(earlier, later) => {
LocalResolution::Ambiguous { earlier, later }
}
chrono::LocalResult::None => LocalResolution::None,
}
}
pub fn zone_offset_at(zone: &str, local: NaiveDateTime) -> std::result::Result<i32, ZoneError> {
let tz: Tz = zone.parse().map_err(|_| ZoneError::UnknownZone)?;
let dt = resolve_local(tz, local)
.earliest()
.ok_or(ZoneError::NonexistentWallTime)?;
Ok(dt.offset().fix().local_minus_utc())
}
enum WallClock {
Unique { offset: i32 },
Ambiguous { earlier: i32, later: i32 },
Gap { before: i32, after: i32 },
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(super) enum OverlapPolicy {
Earliest,
Prefer(i32),
Require(i32),
Reject,
}
impl OverlapPolicy {
pub(super) fn admits_unique(self, offset: i32) -> bool {
match self {
Self::Require(want) => want == offset,
Self::Earliest | Self::Prefer(_) | Self::Reject => true,
}
}
pub(super) fn shifts_gap(self) -> bool {
!matches!(self, Self::Require(_))
}
pub(super) fn pick(self, earlier: i32, later: i32) -> Option<i32> {
match self {
Self::Earliest => Some(earlier),
Self::Prefer(want) if want == later => Some(later),
Self::Prefer(_) => Some(earlier),
Self::Require(want) if want == earlier || want == later => Some(want),
Self::Require(_) | Self::Reject => None,
}
}
}
fn offset_at_utc(tz: Tz, utc: NaiveDateTime) -> i32 {
tz.from_utc_datetime(&utc).offset().fix().local_minus_utc()
}
fn wall_clock(zone: &str, local: NaiveDateTime) -> Result<WallClock> {
let tz: Tz = zone.parse().map_err(|_| unknown_zone_err(zone))?;
Ok(match resolve_local(tz, local) {
LocalResolution::Unique(dt) => WallClock::Unique {
offset: dt.offset().fix().local_minus_utc(),
},
LocalResolution::Ambiguous { earlier, later } => WallClock::Ambiguous {
earlier: earlier.offset().fix().local_minus_utc(),
later: later.offset().fix().local_minus_utc(),
},
LocalResolution::None => {
let before = local
.checked_sub_signed(chrono::Duration::hours(15))
.map(|probe| offset_at_utc(tz, probe))
.ok_or_else(super::range_err)?;
let after = local
.checked_add_signed(chrono::Duration::hours(15))
.map(|probe| offset_at_utc(tz, probe))
.ok_or_else(super::range_err)?;
WallClock::Gap { before, after }
}
})
}
pub(super) fn zone_offset_mismatch(zone: &str) -> Error {
Error::ty(format!("Timezone and offset do not match: {zone}"))
}
pub(super) fn resolve_wall_forward(
zone: &str,
local: NaiveDateTime,
overlap: OverlapPolicy,
) -> Result<(NaiveDateTime, i32)> {
match wall_clock(zone, local)? {
WallClock::Unique { offset } if overlap.admits_unique(offset) => Ok((local, offset)),
WallClock::Unique { .. } => Err(zone_offset_mismatch(zone)),
WallClock::Ambiguous { earlier, later } => {
let offset = overlap
.pick(earlier, later)
.ok_or_else(ambiguous_datetime_err)?;
Ok((local, offset))
}
WallClock::Gap { .. } if !overlap.shifts_gap() => Err(ambiguous_datetime_err()),
WallClock::Gap { before, after } => {
let shift = after - before;
if shift <= 0 {
return Err(ambiguous_datetime_err());
}
let shifted = local
.checked_add_signed(chrono::Duration::seconds(i64::from(shift)))
.ok_or_else(super::range_err)?;
match wall_clock(zone, shifted)? {
WallClock::Unique { offset } if offset == after => Ok((shifted, offset)),
_ => Err(ambiguous_datetime_err()),
}
}
}
}
pub fn zone_offset_at_utc(zone: &str, utc: NaiveDateTime) -> std::result::Result<i32, ZoneError> {
let tz: Tz = zone.parse().map_err(|_| ZoneError::UnknownZone)?;
Ok(tz.from_utc_datetime(&utc).offset().fix().local_minus_utc())
}
pub(super) fn zone_from_short_name(name: &str) -> Option<&'static str> {
ZONE_NAMES
.iter()
.find(|row| row.short_names.iter().any(|n| n.eq_ignore_ascii_case(name)))
.map(|row| row.zone)
}
pub(super) struct ZoneDisplay {
pub(super) short_summer: &'static str,
pub(super) short_generic: &'static str,
pub(super) long_summer: &'static str,
pub(super) long_generic: &'static str,
}
struct ZoneNameRow {
short_names: &'static [&'static str],
zone: &'static str,
display: Option<ZoneDisplay>,
}
const ZONE_NAMES: [ZoneNameRow; 5] = [
ZoneNameRow {
short_names: &["CET", "CEST"],
zone: "Europe/Paris",
display: Some(ZoneDisplay {
short_summer: "CEST",
short_generic: "CET",
long_summer: "Central European Summer Time",
long_generic: "Central European Time",
}),
},
ZoneNameRow {
short_names: &["UTC"],
zone: "UTC",
display: None,
},
ZoneNameRow {
short_names: &["EST", "EDT"],
zone: "America/New_York",
display: None,
},
ZoneNameRow {
short_names: &["PST", "PDT"],
zone: "America/Los_Angeles",
display: None,
},
ZoneNameRow {
short_names: &["JST"],
zone: "Asia/Tokyo",
display: None,
},
];
pub(super) fn zone_display(zone: &str) -> Option<&'static ZoneDisplay> {
ZONE_NAMES
.iter()
.find(|row| row.zone == zone)
.and_then(|row| row.display.as_ref())
}
pub fn zone_region(zone: Option<&str>) -> Option<&str> {
match zone.map(zone_kind) {
Some(ZoneSpec::Iana(name)) => Some(name),
_ => None,
}
}
pub(super) enum IanaAt {
Local(NaiveDateTime),
Utc(NaiveDateTime),
}
pub(super) fn ambiguous_datetime_err() -> Error {
Error::ty("ambiguous datetime")
}
pub(super) fn unknown_zone_err(zone: &str) -> Error {
Error::ty(format!("unknown timezone '{zone}'"))
}
fn iana_offset_at(zone: &str, at: IanaAt) -> Result<i32> {
let resolved = match at {
IanaAt::Local(local) => zone_offset_at(zone, local),
IanaAt::Utc(utc) => zone_offset_at_utc(zone, utc),
};
resolved.map_err(|e| match e {
ZoneError::UnknownZone => unknown_zone_err(zone),
ZoneError::NonexistentWallTime => ambiguous_datetime_err(),
})
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub(super) struct ResolvedZone {
pub(super) offset: i32,
pub(super) zone: Option<String>,
}
impl ResolvedZone {
pub(super) fn utc() -> Self {
Self {
offset: 0,
zone: Some("Z".into()),
}
}
}
pub const MAX_OFFSET_SECONDS: i64 = 18 * 3600;
fn invalid_offset(s: &str) -> Error {
Error::argument_error(format!("invalid timezone offset '{s}'"))
}
pub(super) fn parse_offset(s: &str) -> Result<i32> {
if s == "Z" || s == "z" {
return Ok(0);
}
let numeric = strip_zone_prefix(s).unwrap_or(s);
if numeric.is_empty() {
return Ok(0);
}
let sign: i64 = if numeric.starts_with('-') { -1 } else { 1 };
let rest = numeric.strip_prefix(['+', '-']).unwrap_or(numeric);
if !rest.chars().all(|c| c.is_ascii_digit() || c == ':') {
return Err(invalid_offset(s));
}
let field = |value: &str| -> Result<i64> { value.parse().map_err(|_| invalid_offset(s)) };
let (h, m, sec): (i64, i64, i64) = if rest.contains(':') {
match rest.split(':').collect::<Vec<_>>().as_slice() {
[h] => (field(h)?, 0, 0),
[h, m] => (field(h)?, field(m)?, 0),
[h, m, sec] => (field(h)?, field(m)?, field(sec)?),
_ => return Err(invalid_offset(s)),
}
} else {
match rest.len() {
0..=2 => (field(rest)?, 0, 0),
4 => (field(&rest[..2])?, field(&rest[2..])?, 0),
6 => (field(&rest[..2])?, field(&rest[2..4])?, field(&rest[4..])?),
_ => return Err(invalid_offset(s)),
}
};
let total = sign
* h.saturating_mul(3600)
.saturating_add(m.saturating_mul(60))
.saturating_add(sec);
if total.unsigned_abs() > MAX_OFFSET_SECONDS as u64 {
return Err(invalid_offset(s));
}
i32::try_from(total).map_err(|_| invalid_offset(s))
}
fn resolved_zone(spec: ZoneSpec<'_>, spelling: &str, at: IanaAt) -> Result<ResolvedZone> {
Ok(match spec {
ZoneSpec::Iana(name) | ZoneSpec::Other(name) => ResolvedZone {
offset: iana_offset_at(name, at)?,
zone: Some(String::from(spelling)),
},
ZoneSpec::Utc => ResolvedZone::utc(),
ZoneSpec::Fixed(s) | ZoneSpec::Prefixed(s) => ResolvedZone {
offset: parse_offset(s)?,
zone: Some(String::from(spelling)),
},
})
}
pub(super) fn offset_for_zone(z: &str, at: IanaAt) -> Result<ResolvedZone> {
resolved_zone(zone_kind(z), z, at)
}
pub(super) fn offset_from_map(
m: &std::collections::BTreeMap<String, Value>,
at: IanaAt,
) -> Result<ResolvedZone> {
match m.get("timezone") {
None => Ok(ResolvedZone::utc()),
Some(Value::String(z)) => offset_for_zone(z, at),
Some(_) => Err(Error::argument_error("timezone must be STRING")),
}
}
struct SourceZone {
zone: ResolvedZone,
overlap: OverlapPolicy,
}
fn source_offset_zone(m: &std::collections::BTreeMap<String, Value>) -> Option<SourceZone> {
for k in ["time", "datetime"] {
if let Some(t) = map_temporal(m, k) {
let (offset, zone, overlap) = match (k, t) {
(_, Temporal::Time { offset, .. }) => (*offset, None, OverlapPolicy::Earliest),
("datetime", Temporal::DateTime { offset, zone, .. }) => {
(*offset, zone.clone(), OverlapPolicy::Prefer(*offset))
}
(_, Temporal::DateTime { offset, zone, .. }) => {
(*offset, zone.clone(), OverlapPolicy::Earliest)
}
_ => continue,
};
return Some(SourceZone {
zone: ResolvedZone { offset, zone },
overlap,
});
}
}
None
}
pub(super) fn add_offset(utc: NaiveDateTime, offset: i32) -> Result<NaiveDateTime> {
utc.checked_add_signed(chrono::Duration::seconds(i64::from(offset)))
.ok_or_else(super::range_err)
}
pub(super) fn sub_offset(local: NaiveDateTime, offset: i32) -> Result<NaiveDateTime> {
local
.checked_sub_signed(chrono::Duration::seconds(i64::from(offset)))
.ok_or_else(super::range_err)
}
pub(super) fn apply_timezone(
local: NaiveDateTime,
m: &std::collections::BTreeMap<String, Value>,
) -> Result<(NaiveDateTime, ResolvedZone)> {
match source_offset_zone(m) {
Some(src) => {
let (local, offset) = source_wall(&src, local)?;
let utc = sub_offset(local, offset)?;
if m.contains_key("timezone") {
return Ok((utc, offset_from_map(m, IanaAt::Utc(utc))?));
}
Ok((
utc,
ResolvedZone {
offset,
zone: src.zone.zone,
},
))
}
None => {
let (local, resolved) = offset_from_map_local(m, local)?;
Ok((sub_offset(local, resolved.offset)?, resolved))
}
}
}
fn source_wall(source: &SourceZone, local: NaiveDateTime) -> Result<(NaiveDateTime, i32)> {
match source.zone.zone.as_deref().map(zone_kind) {
Some(ZoneSpec::Iana(name)) => resolve_wall_forward(name, local, source.overlap),
_ => Ok((local, source.zone.offset)),
}
}
pub(super) fn offset_from_map_local(
m: &std::collections::BTreeMap<String, Value>,
local: NaiveDateTime,
) -> Result<(NaiveDateTime, ResolvedZone)> {
match m.get("timezone") {
None => Ok((local, ResolvedZone::utc())),
Some(Value::String(z)) => {
let spec = zone_kind(z);
Ok(match spec {
ZoneSpec::Iana(name) => {
let (local, offset) =
resolve_wall_forward(name, local, OverlapPolicy::Earliest)?;
(
local,
ResolvedZone {
offset,
zone: Some(z.to_string()),
},
)
}
_ => (local, resolved_zone(spec, z, IanaAt::Local(local))?),
})
}
Some(_) => Err(Error::argument_error("timezone must be STRING")),
}
}
#[cfg(test)]
mod tests {
use chrono::NaiveDate;
use super::*;
#[test]
fn overlap_policy_picks_the_occurrence_it_names() {
let (earlier, later) = (7200, 3600);
assert_eq!(OverlapPolicy::Earliest.pick(earlier, later), Some(earlier));
assert_eq!(
OverlapPolicy::Prefer(later).pick(earlier, later),
Some(later)
);
assert_eq!(OverlapPolicy::Prefer(0).pick(earlier, later), Some(earlier));
assert_eq!(
OverlapPolicy::Require(later).pick(earlier, later),
Some(later)
);
assert_eq!(OverlapPolicy::Require(0).pick(earlier, later), None);
assert_eq!(OverlapPolicy::Reject.pick(earlier, later), None);
}
#[test]
fn resolve_wall_forward_requires_a_supplied_offset() {
let at = |m, d, h| {
NaiveDate::from_ymd_opt(2020, m, d)
.unwrap()
.and_hms_opt(h, 30, 0)
.unwrap()
};
let zone = "Europe/Stockholm";
let summer = at(7, 1, 12);
assert_eq!(
resolve_wall_forward(zone, summer, OverlapPolicy::Require(7200)).unwrap(),
(summer, 7200)
);
assert_eq!(
resolve_wall_forward(zone, summer, OverlapPolicy::Require(3600))
.unwrap_err()
.to_string(),
zone_offset_mismatch(zone).to_string()
);
let overlap = at(10, 25, 2);
assert_eq!(
resolve_wall_forward(zone, overlap, OverlapPolicy::Require(3600))
.unwrap()
.1,
3600
);
assert!(resolve_wall_forward(zone, overlap, OverlapPolicy::Reject).is_err());
let gap = at(3, 29, 2);
assert!(resolve_wall_forward(zone, gap, OverlapPolicy::Require(3600)).is_err());
assert_eq!(
resolve_wall_forward(zone, gap, OverlapPolicy::Reject).unwrap(),
(at(3, 29, 3), 7200)
);
}
#[test]
fn zone_offset_at_utc_is_typed_and_unambiguous() {
let at =
|s: &str| NaiveDateTime::parse_from_str(s, "%Y-%m-%dT%H:%M").expect("test instant");
assert_eq!(
zone_offset_at_utc("Europe/Stockholm", at("2021-10-31T00:30")),
Ok(7200)
);
assert_eq!(
zone_offset_at_utc("Europe/Stockholm", at("2021-10-31T01:30")),
Ok(3600)
);
assert_eq!(
zone_offset_at_utc("Mars/Base", at("2021-10-31T01:30")),
Err(ZoneError::UnknownZone)
);
let gap = NaiveDate::from_ymd_opt(2021, 3, 28)
.unwrap()
.and_hms_opt(2, 30, 0)
.unwrap();
assert_eq!(
zone_offset_at("Europe/Stockholm", gap),
Err(ZoneError::NonexistentWallTime)
);
let before_transition = NaiveDate::from_ymd_opt(2021, 3, 28)
.unwrap()
.and_hms_opt(0, 30, 0)
.unwrap();
assert_eq!(
zone_offset_at_utc("Europe/Stockholm", before_transition),
Ok(3600)
);
}
#[test]
fn offset_from_map_distinguishes_missing_from_malformed_timezone() {
let at = || {
IanaAt::Local(
NaiveDate::from_ymd_opt(2021, 1, 1)
.unwrap()
.and_hms_opt(0, 0, 0)
.unwrap(),
)
};
let missing = std::collections::BTreeMap::new();
assert_eq!(
offset_from_map(&missing, at()),
Ok(ResolvedZone {
offset: 0,
zone: Some("Z".into()),
})
);
let malformed = [("timezone".into(), Value::Int(42))]
.into_iter()
.collect::<std::collections::BTreeMap<_, _>>();
assert_eq!(
offset_from_map(&malformed, at()),
Err(Error::argument_error("timezone must be STRING"))
);
}
#[test]
fn parse_offset_carries_at_most_one_leading_sign() {
assert_eq!(parse_offset("+01:00"), Ok(3600));
assert_eq!(parse_offset("-01:00"), Ok(-3600));
assert_eq!(parse_offset("-0130"), Ok(-5400));
assert_eq!(parse_offset("-05"), Ok(-18000));
assert_eq!(parse_offset("Z"), Ok(0));
assert_eq!(parse_offset("UTC"), Ok(0));
assert_eq!(parse_offset("GMT+03:00"), Ok(10800));
for s in [
"--01:00",
"+-01:00",
"++01:00",
"-+01:00",
"UTC+-01:00",
"GMT--05:00",
] {
assert_eq!(parse_offset(s), Err(invalid_offset(s)), "{s}");
}
}
#[test]
fn iana_offset_at_renders_one_unknown_zone_message() {
let local = NaiveDate::from_ymd_opt(2021, 3, 28)
.unwrap()
.and_hms_opt(12, 0, 0)
.unwrap();
let expected = Error::ty("unknown timezone 'Not/AZone'");
assert_eq!(
iana_offset_at("Not/AZone", IanaAt::Local(local)),
Err(expected.clone())
);
assert_eq!(
iana_offset_at("Not/AZone", IanaAt::Utc(local)),
Err(expected)
);
}
}