mbutrovich commented on code in PR #11482:
URL: https://github.com/apache/arrow-rs/pull/11482#discussion_r4630434144
##########
arrow-array/src/timezone.rs:
##########
@@ -35,7 +77,648 @@ fn parse_fixed_offset(tz: &str) -> Option<FixedOffset> {
}
}
-#[cfg(feature = "chrono-tz")]
+#[cfg(feature = "jiff")]
+mod private {
+ use super::*;
+ use chrono::offset::TimeZone;
+ use chrono::{Datelike, LocalResult, NaiveDate, NaiveDateTime, NaiveTime,
Offset, Timelike};
+ use jiff::Timestamp;
+ use jiff::civil::DateTime as JiffDateTime;
+ use jiff::tz::{AmbiguousOffset, TimeZone as JiffTimeZone};
+ use std::collections::HashMap;
+ use std::fmt::Display;
+ use std::str::FromStr;
+ use std::sync::OnceLock;
+
+ /// An [`Offset`] for [`Tz`]
+ #[derive(Debug, Copy, Clone)]
+ pub struct TzOffset {
+ tz: Tz,
+ offset: FixedOffset,
+ }
+
+ impl std::fmt::Display for TzOffset {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ self.offset.fmt(f)
+ }
+ }
+
+ impl Offset for TzOffset {
+ fn fix(&self) -> FixedOffset {
+ self.offset
+ }
+ }
+
+ /// A named timezone resolved by jiff, together with its name.
+ struct NamedTz {
+ name: &'static str,
+ tz: JiffTimeZone,
+ }
+
+ /// Prints only the name, so that `Debug` output matches the `chrono-tz`
feature.
+ impl std::fmt::Debug for NamedTz {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ f.write_str(self.name)
+ }
+ }
+
+ /// Builds a timezone from jiff-tzdb. `jiff::tz::db()` would read the
host's zoneinfo files
+ /// instead if any crate in the build enabled jiff's `tzdb-zoneinfo`
feature.
+ fn bundled_tz(name: &str) -> Option<JiffTimeZone> {
+ // As jiff's own bundled database does, so that UTC is not backed by
TZif data
+ if name == "UTC" {
+ return Some(JiffTimeZone::UTC);
+ }
+ let (canonical_name, tzif) = jiff_tzdb::get(name)?;
+ JiffTimeZone::tzif(canonical_name, tzif).ok()
+ }
+
+ /// Resolves a name in the bundled database. As with chrono-tz, and unlike
jiff, names are case
+ /// sensitive.
+ ///
+ /// [`Tz`] is `Copy` but [`JiffTimeZone`] is reference counted, so `Tz`
holds a `'static`
+ /// reference into a table with one slot per bundled name, each resolved
on first use.
+ fn named_tz(name: &str) -> Result<&'static NamedTz, ArrowError> {
+ type Slots = HashMap<&'static str, OnceLock<Option<NamedTz>>,
ahash::RandomState>;
+ static SLOTS: OnceLock<Slots> = OnceLock::new();
+ let slots = SLOTS.get_or_init(|| {
+ jiff_tzdb::available()
+ // A placeholder for an unknown local timezone, which
chrono-tz does not accept
+ .filter(|name| *name != "Factory")
+ .map(|name| (name, OnceLock::new()))
+ .collect()
+ });
+ slots
+ .get_key_value(name)
+ .and_then(|(name, slot)| {
+ slot.get_or_init(|| {
+ let tz = bundled_tz(name)?;
+ Some(NamedTz { name, tz })
+ })
+ .as_ref()
+ })
+ // The same message as with chrono-tz
+ .ok_or_else(|| {
+ ArrowError::ParseError(format!(
+ "Invalid timezone \"{name}\": failed to parse timezone"
+ ))
+ })
+ }
+
+ /// An Arrow [`TimeZone`]
+ #[derive(Debug, Copy, Clone)]
+ pub struct Tz(TzInner);
+
+ #[derive(Debug, Copy, Clone)]
+ enum TzInner {
+ Timezone(&'static NamedTz),
+ Offset(FixedOffset),
+ }
+
+ // These are copied per value by chrono, so catch any accidental growth
+ #[cfg(target_pointer_width = "64")]
+ const _: () = {
+ assert!(std::mem::size_of::<Tz>() == 16);
+ assert!(std::mem::size_of::<TzOffset>() == 24);
+ };
+
+ impl FromStr for Tz {
+ type Err = ArrowError;
+
+ fn from_str(tz: &str) -> Result<Self, Self::Err> {
+ match parse_fixed_offset(tz) {
+ Some(offset) => Ok(Self(TzInner::Offset(offset))),
+ None => Ok(Self(TzInner::Timezone(named_tz(tz)?))),
+ }
+ }
+ }
+
+ impl Display for Tz {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ match self.0 {
+ TzInner::Timezone(tz) => f.write_str(tz.name),
+ TzInner::Offset(offset) => offset.fmt(f),
+ }
+ }
+ }
+
+ fn fixed_offset(offset: jiff::tz::Offset) -> FixedOffset {
+ // The bundled database never holds an offset of a day or more, so
this cannot fail
+ FixedOffset::east_opt(offset.seconds()).expect("timezone offset within
a day")
+ }
+
+ /// The instant jiff should consult for a UTC datetime. jiff covers years
-9999 to 9999;
+ /// anything outside that range takes the offset in force at the nearest
covered instant.
+ fn jiff_timestamp(utc: &NaiveDateTime) -> Timestamp {
+ let seconds = utc.and_utc().timestamp();
+ Timestamp::from_second(seconds).unwrap_or(if seconds < 0 {
+ Timestamp::MIN
+ } else {
+ Timestamp::MAX
+ })
+ }
+
+ /// The civil datetime jiff should resolve for a local datetime, or `None`
when the year is
+ /// outside jiff's range. Sub-second precision is irrelevant to the offset
in force.
+ fn jiff_civil(local: &NaiveDateTime) -> Option<JiffDateTime> {
+ JiffDateTime::new(
+ i16::try_from(local.year()).ok()?,
+ local.month() as i8,
+ local.day() as i8,
+ local.hour() as i8,
+ local.minute() as i8,
+ local.second() as i8,
+ 0,
+ )
+ .ok()
+ }
+
+ impl Tz {
+ fn offset(&self, offset: FixedOffset) -> TzOffset {
+ TzOffset { tz: *self, offset }
+ }
+ }
+
+ impl TimeZone for Tz {
+ type Offset = TzOffset;
+
+ fn from_offset(offset: &Self::Offset) -> Self {
+ offset.tz
+ }
+
+ fn offset_from_local_date(&self, local: &NaiveDate) ->
LocalResult<Self::Offset> {
+ match self.0 {
+ TzInner::Offset(tz) => tz
+ .offset_from_local_date(local)
+ .map(|x| self.offset(x.fix())),
+ TzInner::Timezone(_) => {
+ // As chrono-tz does, take an offset in force at the start
or end of the day,
+ // so that a day with a transition still resolves
+ let earliest =
self.offset_from_local_datetime(&local.and_time(NaiveTime::MIN));
+ let latest =
+ self.offset_from_local_datetime(&local.and_hms_opt(23,
59, 59).unwrap());
+ match (earliest, latest) {
+ (result @ LocalResult::Single(_), _) => result,
+ (_, result @ LocalResult::Single(_)) => result,
+ (LocalResult::Ambiguous(offset, _), _) =>
LocalResult::Single(offset),
+ (_, LocalResult::Ambiguous(offset, _)) =>
LocalResult::Single(offset),
+ (LocalResult::None, LocalResult::None) =>
LocalResult::None,
+ }
+ }
+ }
+ }
+
+ fn offset_from_local_datetime(&self, local: &NaiveDateTime) ->
LocalResult<Self::Offset> {
+ match self.0 {
+ TzInner::Offset(tz) => tz
+ .offset_from_local_datetime(local)
+ .map(|x| self.offset(x.fix())),
+ TzInner::Timezone(tz) => match jiff_civil(local) {
+ // Outside jiff's range, treat the local datetime as if it
were UTC. Either
+ // way it takes the offset in force at the nearest covered
instant.
+ None =>
LocalResult::Single(self.offset_from_utc_datetime(local)),
+ Some(dt) => match
tz.tz.to_ambiguous_timestamp(dt).offset() {
+ AmbiguousOffset::Unambiguous { offset } => {
+
LocalResult::Single(self.offset(fixed_offset(offset)))
+ }
+ AmbiguousOffset::Gap { .. } => LocalResult::None,
+ AmbiguousOffset::Fold { before, after } =>
LocalResult::Ambiguous(
+ self.offset(fixed_offset(before)),
+ self.offset(fixed_offset(after)),
+ ),
+ },
+ },
+ }
+ }
+
+ fn offset_from_utc_date(&self, utc: &NaiveDate) -> Self::Offset {
+ self.offset_from_utc_datetime(&utc.and_time(NaiveTime::MIN))
+ }
+
+ fn offset_from_utc_datetime(&self, utc: &NaiveDateTime) ->
Self::Offset {
+ match self.0 {
+ TzInner::Offset(tz) =>
self.offset(tz.offset_from_utc_datetime(utc).fix()),
+ TzInner::Timezone(tz) => {
+
self.offset(fixed_offset(tz.tz.to_offset(jiff_timestamp(utc))))
+ }
+ }
+ }
+ }
+
+ pub(super) fn new_gap_info(local: &NaiveDateTime, tz: &Tz) ->
Option<GapInfo> {
+ let TzInner::Timezone(named) = tz.0 else {
+ return None;
+ };
+ // A local datetime outside jiff's range resolves to a single offset,
so it is not in a gap
+ let civil = jiff_civil(local)?;
+ let AmbiguousOffset::Gap { before, after } =
+ named.tz.to_ambiguous_timestamp(civil).offset()
+ else {
+ return None;
+ };
+ // Reading a local datetime in the gap with the later offset gives an
instant before the
+ // transition, so the next transition is the one that opened the gap
+ let from = after.to_timestamp(civil).ok()?;
+ let transition = named.tz.following(from).next()?;
+ let end = DateTime::from_timestamp(transition.timestamp().as_second(),
0)?;
+ let begin = end.naive_utc() +
chrono::TimeDelta::seconds(before.seconds().into());
+ Some(GapInfo {
+ begin: Some((begin, tz.offset(fixed_offset(before)))),
+ end: Some(end.with_timezone(tz)),
+ })
+ }
+
+ #[cfg(test)]
+ mod tests {
+ use super::*;
+ use chrono::{Timelike, Utc};
+
+ #[test]
+ fn test_with_timezone() {
+ let vals = [
+ Utc.timestamp_millis_opt(37800000).unwrap(),
+ Utc.timestamp_millis_opt(86339000).unwrap(),
+ ];
+
+ assert_eq!(10, vals[0].hour());
+ assert_eq!(23, vals[1].hour());
+
+ let tz: Tz = "America/Los_Angeles".parse().unwrap();
+
+ assert_eq!(2, vals[0].with_timezone(&tz).hour());
+ assert_eq!(15, vals[1].with_timezone(&tz).hour());
+ }
+
+ #[test]
+ fn test_dst_transitions_from_utc() {
+ let tz: Tz = "Australia/Sydney".parse().unwrap();
+ let standard = FixedOffset::east_opt(10 * 60 * 60).unwrap();
+ let daylight = FixedOffset::east_opt(11 * 60 * 60).unwrap();
+ let at = |y, m, d, h, min| {
+ NaiveDate::from_ymd_opt(y, m, d)
+ .unwrap()
+ .and_hms_opt(h, min, 0)
+ .unwrap()
+ };
+ // Daylight time ended 2021-04-04T03:00+11:00, which is
2021-04-03T16:00Z
+ assert_eq!(
+ tz.offset_from_utc_datetime(&at(2021, 4, 3, 15, 30)).fix(),
+ daylight
+ );
+ assert_eq!(
+ tz.offset_from_utc_datetime(&at(2021, 4, 3, 16, 30)).fix(),
+ standard
+ );
+ // Daylight time started 2021-10-03T02:00+10:00, which is
2021-10-02T16:00Z
+ assert_eq!(
+ tz.offset_from_utc_datetime(&at(2021, 10, 2, 15, 30)).fix(),
+ standard
+ );
+ assert_eq!(
+ tz.offset_from_utc_datetime(&at(2021, 10, 2, 16, 30)).fix(),
+ daylight
+ );
+ }
+
+ #[test]
+ fn test_dst_transitions_from_local() {
+ let tz: Tz = "America/New_York".parse().unwrap();
+ let eastern_standard = FixedOffset::west_opt(5 * 60 * 60).unwrap();
+ let eastern_daylight = FixedOffset::west_opt(4 * 60 * 60).unwrap();
+ let at = |m, d, h, min| {
+ NaiveDate::from_ymd_opt(2024, m, d)
+ .unwrap()
+ .and_hms_opt(h, min, 0)
+ .unwrap()
+ };
+ match tz.offset_from_local_datetime(&at(1, 15, 12, 0)) {
+ LocalResult::Single(offset) => assert_eq!(offset.fix(),
eastern_standard),
+ other => panic!("expected a single offset, got {other:?}"),
+ }
+ // 02:30 on 2024-03-10 was skipped when clocks went forward
+ assert!(matches!(
+ tz.offset_from_local_datetime(&at(3, 10, 2, 30)),
+ LocalResult::None
+ ));
+ // 01:30 on 2024-11-03 happened twice; the daylight reading comes
first
+ match tz.offset_from_local_datetime(&at(11, 3, 1, 30)) {
+ LocalResult::Ambiguous(first, second) => {
+ assert_eq!(first.fix(), eastern_daylight);
+ assert_eq!(second.fix(), eastern_standard);
+ }
+ other => panic!("expected an ambiguous offset, got {other:?}"),
+ }
+ // A date on a transition day still resolves to an offset in force
that day
+ assert!(matches!(
+ tz.offset_from_local_date(&NaiveDate::from_ymd_opt(2024, 3,
10).unwrap()),
+ LocalResult::Single(_)
+ ));
+ }
+
+ /// chrono-tz keeps its last offset after 2099, while jiff keeps
applying daylight saving
+ #[test]
+ fn test_dst_applies_after_2099() {
Review Comment:
This test checks offsets at noon on January 1 and July 1, and the comparison
with chrono-tz [stops at
2099](https://github.com/apache/arrow-rs/blob/dc062fdb109b86e055f57891257396d987d50e70/arrow-array/src/timezone.rs#L652-L654).
So nothing checks gaps, folds, or `GapInfo` after 2099, which is where this
feature's results are new. That's also the path a per-zone transition table
from Phase 2 on #9183 would replace, so a test here would guard that change
too. Could you add something like this?
```rust
/// After 2099 only jiff applies daylight saving, so the comparison with
chrono-tz
/// cannot check gaps and folds there
#[test]
fn test_gaps_and_folds_after_2099() {
let tz: Tz = "America/Los_Angeles".parse().unwrap();
let pacific_standard = FixedOffset::west_opt(8 * 60 * 60).unwrap();
let pacific_daylight = FixedOffset::west_opt(7 * 60 * 60).unwrap();
let at = |y, m, d, h, min| {
NaiveDate::from_ymd_opt(y, m, d)
.unwrap()
.and_hms_opt(h, min, 0)
.unwrap()
};
// The second Sunday in March and the first Sunday in November of each
year
for (year, spring, fall) in [(2100, 14, 7), (2300, 11, 4), (9998, 8, 1)]
{
let skipped = at(year, 3, spring, 2, 30);
assert!(matches!(
tz.offset_from_local_datetime(&skipped),
LocalResult::None
));
let gap = GapInfo::new(&skipped, &tz).unwrap();
let (begin, begin_offset) = gap.begin.unwrap();
assert_eq!(begin, at(year, 3, spring, 2, 0));
assert_eq!(begin_offset.fix(), pacific_standard);
let end = gap.end.unwrap();
assert_eq!(end.naive_local(), at(year, 3, spring, 3, 0));
assert_eq!(end.offset().fix(), pacific_daylight);
match tz.offset_from_local_datetime(&at(year, 11, fall, 1, 30)) {
LocalResult::Ambiguous(first, second) => {
assert_eq!(first.fix(), pacific_daylight);
assert_eq!(second.fix(), pacific_standard);
}
other => panic!("expected an ambiguous offset in {year}, got
{other:?}"),
}
}
}
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]