This is an automated email from the ASF dual-hosted git repository. github-merge-queue[bot] pushed a commit to branch gh-readonly-queue/main/pr-11535-786ba611bc1fe796d9d047a5dd9f474afc8f5589 in repository https://gitbox.apache.org/repos/asf/arrow-rs.git
commit dd240116c75a15a2a048a041c808d67f3f32a375 Author: Martin Hilton <[email protected]> AuthorDate: Thu Oct 15 12:51:12 2026 +0000 feat: add GapInfo to timezone (#11535) # Which issue does this PR close? <!-- It is not necessary to raise an issue, but it is encouraged if it is a non-trivial enhancement/bug. If this PR relates to an existing issue, but does not fully resolve it, please change the wording below from "Closes #NNN" to "Relates to #NNN" or "Part of #NNN" to avoid false closing an issue. --> - Closes #11472 # Rationale for this change <!-- Why are you proposing this change? If this is already explained clearly in the issue then this section is not needed. Explaining clearly why changes are proposed helps reviewers understand your changes and offer better suggestions for fixes. Please try to explain the problem you are trying to solve in terms of the user-visible behavior, rather than the implementation. --> Currently when converting from local time to UTC within a timezone if the local time represents a time within a discontinuity it is not possible to find the parameters of that discontinuity. This allows clients to find details of the gap in order to make decisions about how conversions should be performed. # What changes are included in this PR? <!-- There is no need to duplicate the description in the issue here but it is sometimes worth providing a summary of the individual changes in this PR. --> Add a GapInfo struct to the arrow::timezone module to publish information about gaps in local time for a timezone. This is a direct copy of the GapInfo type from chrono-tz with the types changed to be appropriate for this module. # Are these changes tested? <!-- We typically require tests for all PRs in order to: 1. Prevent the code from being accidentally broken by subsequent changes 2. Serve as another way to document the expected behavior of the code If tests are not included in your PR, please explain why (for example, are they covered by existing tests, if so identify these tests)? If this PR claims a performance improvement, please include evidence such as benchmark results. DO NOT simply paste a list of commands ran to verify the code; this is what our CI is for and it pollutes the PR. ONLY explain if testing was included with this PR, or why it wasn't. --> Yes, new unit tests # Are there any significant user-facing changes? <!-- Significant user-facing changes include: - Breaking public API change - Significant change to existing functionality (e.g. function returns something different) These need to be explicitly called out to ensure we have proper documentation if required and to ensure we follow proper semantic versioning. DO NOT restate the changes of this PR; if a bug was fixed and already explained above, we don't need this to be restated as a user-facing change. --> The new `GapInfo` types represents a new interface. There are no changes to any existing interface. --- arrow-array/Cargo.toml | 2 +- arrow-array/src/timezone.rs | 217 +++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 217 insertions(+), 2 deletions(-) diff --git a/arrow-array/Cargo.toml b/arrow-array/Cargo.toml index c9ade8ef24..6503f7b8dd 100644 --- a/arrow-array/Cargo.toml +++ b/arrow-array/Cargo.toml @@ -54,7 +54,7 @@ arrow-buffer = { workspace = true } arrow-schema = { workspace = true } arrow-data = { workspace = true } chrono = { workspace = true } -chrono-tz = { version = "0.10", optional = true } +chrono-tz = { version = "0.10.3", optional = true } futures = { version = "0.3", optional = true } num-complex = { version = "0.4.6", default-features = false, features = ["std"] } num-integer = { version = "0.1.46", default-features = false, features = ["std"] } diff --git a/arrow-array/src/timezone.rs b/arrow-array/src/timezone.rs index bcf5821521..73053229de 100644 --- a/arrow-array/src/timezone.rs +++ b/arrow-array/src/timezone.rs @@ -18,7 +18,7 @@ //! Timezone for timestamp arrays use arrow_schema::ArrowError; -use chrono::FixedOffset; +use chrono::{DateTime, FixedOffset, NaiveDateTime}; pub use private::{Tz, TzOffset}; /// Parses a fixed offset of the form "+09:00", "-09" or "+0930" @@ -160,6 +160,25 @@ mod private { } } + #[inline] + pub(super) fn new_gap_info(local: &NaiveDateTime, tz: &Tz) -> Option<GapInfo> { + let TzInner::Timezone(ctz) = &tz.0 else { + return None; + }; + chrono_tz::GapInfo::new(local, ctz).map(|gi| GapInfo { + begin: gi.begin.map(|(ndt, ctz)| { + ( + ndt, + TzOffset { + tz: *tz, + offset: ctz.fix(), + }, + ) + }), + end: gi.end.map(|dt| dt.with_timezone(tz)), + }) + } + #[cfg(test)] mod tests { use super::*; @@ -239,6 +258,95 @@ mod private { ); } + fn naive(y: i32, mo: u32, d: u32, h: u32, mi: u32) -> NaiveDateTime { + NaiveDate::from_ymd_opt(y, mo, d) + .unwrap() + .and_hms_opt(h, mi, 0) + .unwrap() + } + + fn utc(y: i32, mo: u32, d: u32, h: u32, mi: u32) -> chrono::DateTime<Utc> { + Utc.with_ymd_and_hms(y, mo, d, h, mi, 0).unwrap() + } + + #[test] + fn test_gap_info_not_in_gap() { + let tz: Tz = "America/New_York".parse().unwrap(); + // Just before and at the end of the 2021 spring forward gap + assert!(GapInfo::new(&naive(2021, 3, 14, 1, 59), &tz).is_none()); + assert!(GapInfo::new(&naive(2021, 3, 14, 3, 0), &tz).is_none()); + // Ambiguous time during the 2021 fall back overlap is not a gap + assert!(GapInfo::new(&naive(2021, 11, 7, 1, 30), &tz).is_none()); + } + + #[test] + fn test_gap_info_america_new_york() { + // Clocks went forward from 2021-03-14T02:00:00-05:00 to 2021-03-14T03:00:00-04:00 + let tz: Tz = "America/New_York".parse().unwrap(); + for local in [ + naive(2021, 3, 14, 2, 0), + naive(2021, 3, 14, 2, 30), + naive(2021, 3, 14, 2, 59), + ] { + assert!(tz.from_local_datetime(&local).single().is_none()); + + let gap = GapInfo::new(&local, &tz).unwrap(); + let (begin, begin_offset) = gap.begin.unwrap(); + assert_eq!(begin, naive(2021, 3, 14, 2, 0)); + assert_eq!( + begin_offset.fix(), + FixedOffset::west_opt(5 * 60 * 60).unwrap() + ); + + let end = gap.end.unwrap(); + assert_eq!(end.naive_local(), naive(2021, 3, 14, 3, 0)); + assert_eq!( + end.offset().fix(), + FixedOffset::west_opt(4 * 60 * 60).unwrap() + ); + assert_eq!(end, utc(2021, 3, 14, 7, 0)); + assert_eq!(end.timezone().to_string(), "America/New_York"); + } + } + + #[test] + fn test_gap_info_europe_london() { + // Clocks went forward from 2021-03-28T01:00:00+00:00 to 2021-03-28T02:00:00+01:00 + let tz: Tz = "Europe/London".parse().unwrap(); + let gap = GapInfo::new(&naive(2021, 3, 28, 1, 30), &tz).unwrap(); + + let (begin, begin_offset) = gap.begin.unwrap(); + assert_eq!(begin, naive(2021, 3, 28, 1, 0)); + assert_eq!(begin_offset.fix(), FixedOffset::east_opt(0).unwrap()); + + let end = gap.end.unwrap(); + assert_eq!(end.naive_local(), naive(2021, 3, 28, 2, 0)); + assert_eq!(end.offset().fix(), FixedOffset::east_opt(60 * 60).unwrap()); + assert_eq!(end, utc(2021, 3, 28, 1, 0)); + } + + #[test] + fn test_gap_info_australia_sydney() { + // Clocks went forward from 2021-10-03T02:00:00+10:00 to 2021-10-03T03:00:00+11:00 + let tz: Tz = "Australia/Sydney".parse().unwrap(); + let gap = GapInfo::new(&naive(2021, 10, 3, 2, 30), &tz).unwrap(); + + let (begin, begin_offset) = gap.begin.unwrap(); + assert_eq!(begin, naive(2021, 10, 3, 2, 0)); + assert_eq!( + begin_offset.fix(), + FixedOffset::east_opt(10 * 60 * 60).unwrap() + ); + + let end = gap.end.unwrap(); + assert_eq!(end.naive_local(), naive(2021, 10, 3, 3, 0)); + assert_eq!( + end.offset().fix(), + FixedOffset::east_opt(11 * 60 * 60).unwrap() + ); + assert_eq!(end, utc(2021, 10, 2, 16, 0)); + } + #[test] fn test_timezone_display() { let test_cases = ["UTC", "America/Los_Angeles", "-08:00", "+05:30"]; @@ -313,6 +421,87 @@ mod private { TzOffset(self.0.offset_from_utc_datetime(utc).fix()) } } + + #[inline] + pub(super) fn new_gap_info(_local: &NaiveDateTime, _tz: &Tz) -> Option<GapInfo> { + // Fixed offsets never contain gaps + None + } +} + +/// Represents the information of a gap. +/// +/// This returns useful information that can be used when converting a local [`NaiveDateTime`] +/// to a timezone-aware [`DateTime`] with [`chrono::TimeZone::from_local_datetime`] and a gap +/// ([`chrono::LocalResult::None`]) is found. +/// +/// # Examples +/// +/// In the `America/New_York` timezone the clocks went forward one hour at `2026-03-08T02:00:00`. +/// The local time `2026-03-08T01:30:00` exists, but `2026-03-08T02:30:00` falls in the gap and +/// does not. +/// +/// ``` +/// # #[cfg(feature = "chrono-tz")] +/// # { +/// use arrow_array::timezone::{GapInfo, Tz}; +/// use chrono::{DateTime, FixedOffset, LocalResult, NaiveDateTime, Offset, TimeZone}; +/// +/// let tz: Tz = "America/New_York".parse().unwrap(); +/// let expect_offset: FixedOffset = "-0500".parse().unwrap(); +/// +/// // A local time before the gap has a single offset, and is not in a gap. +/// let exists: NaiveDateTime = "2026-03-08T01:30:00".parse().unwrap(); +/// let offset = tz.offset_from_local_datetime(&exists).single().unwrap(); +/// assert_eq!(offset.fix(), expect_offset); +/// assert!(GapInfo::new(&exists, &tz).is_none()); +/// +/// // A local time inside the gap has no offset... +/// let not_exist: NaiveDateTime = "2026-03-08T02:30:00".parse().unwrap(); +/// let offset = tz.offset_from_local_datetime(¬_exist); +/// assert!(matches!(offset, LocalResult::None)); +/// +/// // ...but `GapInfo` describes the gap it falls in. +/// let GapInfo { begin, end } = GapInfo::new(¬_exist, &tz).unwrap(); +/// +/// // The gap begins at 02:00 local time. The offset is the one in effect before the gap. +/// let (begin_datetime, begin_offset) = begin.unwrap(); +/// let expect_begin: NaiveDateTime = "2026-03-08T02:00:00".parse().unwrap(); +/// assert_eq!(begin_datetime, expect_begin); +/// assert_eq!(begin_offset.fix(), expect_offset); +/// +/// // The gap ends at 03:00 local time, with the offset in effect after the gap. +/// let expect_end: DateTime<FixedOffset> = "2026-03-08T03:00:00-0400".parse().unwrap(); +/// assert_eq!(end.unwrap(), expect_end.with_timezone(&tz)); +/// # } +/// ``` +#[derive(Debug, Clone, Copy)] +pub struct GapInfo { + /// When available it contains information about the beginning of the gap. + /// + /// The time represents the first instant in which the gap starts. + /// This means that it is the first instant that when used with + /// [`chrono::TimeZone::from_local_datetime`] it will return + /// [`chrono::LocalResult::None`]. + /// + /// The offset represents the offset of the first instant before the gap. + pub begin: Option<(NaiveDateTime, TzOffset)>, + + /// When available it contains the first instant after the gap. + pub end: Option<DateTime<Tz>>, +} + +impl GapInfo { + /// Return information about a gap. + /// + /// It returns `None` if `local` is not in a gap for the current timezone. Timezones + /// that represent fixed offsets contain no gaps and therefore always return `None`. + /// + /// If `local` is at the limits of the known timestamps the fields `begin` or `end` in + /// [`GapInfo`] will be `None`. + pub fn new(local: &NaiveDateTime, tz: &Tz) -> Option<Self> { + private::new_gap_info(local, tz) + } } #[cfg(test)] @@ -355,4 +544,30 @@ mod tests { let err = "+9:00".parse::<Tz>().unwrap_err().to_string(); assert!(err.contains("Invalid timezone"), "{}", err); } + + #[test] + fn test_gap_info_fixed_offset() { + let times = [ + NaiveDate::from_ymd_opt(2000, 1, 1) + .unwrap() + .and_hms_opt(0, 0, 0) + .unwrap(), + // Times that are in a DST gap for some named timezones + NaiveDate::from_ymd_opt(2021, 3, 14) + .unwrap() + .and_hms_opt(2, 30, 0) + .unwrap(), + NaiveDate::from_ymd_opt(2021, 3, 28) + .unwrap() + .and_hms_opt(1, 30, 0) + .unwrap(), + ]; + + for tz in ["+00:00", "-05:00", "+01:00", "+09:30"] { + let tz: Tz = tz.parse().unwrap(); + for t in × { + assert!(GapInfo::new(t, &tz).is_none(), "{tz:?} {t}"); + } + } + } }
