arrow_array/
temporal_conversions.rs

1// Licensed to the Apache Software Foundation (ASF) under one
2// or more contributor license agreements.  See the NOTICE file
3// distributed with this work for additional information
4// regarding copyright ownership.  The ASF licenses this file
5// to you under the Apache License, Version 2.0 (the
6// "License"); you may not use this file except in compliance
7// with the License.  You may obtain a copy of the License at
8//
9//   http://www.apache.org/licenses/LICENSE-2.0
10//
11// Unless required by applicable law or agreed to in writing,
12// software distributed under the License is distributed on an
13// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14// KIND, either express or implied.  See the License for the
15// specific language governing permissions and limitations
16// under the License.
17
18//! Conversion methods for dates and times.
19
20use crate::timezone::Tz;
21use crate::ArrowPrimitiveType;
22use arrow_schema::{DataType, TimeUnit};
23use chrono::{DateTime, Duration, NaiveDate, NaiveDateTime, NaiveTime, TimeZone, Timelike, Utc};
24
25/// Number of seconds in a day
26pub const SECONDS_IN_DAY: i64 = 86_400;
27/// Number of milliseconds in a second
28pub const MILLISECONDS: i64 = 1_000;
29/// Number of microseconds in a second
30pub const MICROSECONDS: i64 = 1_000_000;
31/// Number of nanoseconds in a second
32pub const NANOSECONDS: i64 = 1_000_000_000;
33
34/// Number of milliseconds in a day
35pub const MILLISECONDS_IN_DAY: i64 = SECONDS_IN_DAY * MILLISECONDS;
36/// Number of microseconds in a day
37pub const MICROSECONDS_IN_DAY: i64 = SECONDS_IN_DAY * MICROSECONDS;
38/// Number of nanoseconds in a day
39pub const NANOSECONDS_IN_DAY: i64 = SECONDS_IN_DAY * NANOSECONDS;
40
41/// Constant from chrono crate
42///
43/// Number of days between Januari 1, 1970 and December 31, 1 BCE which we define to be day 0.
44/// 4 full leap year cycles until December 31, 1600     4 * 146097 = 584388
45/// 1 day until January 1, 1601                                           1
46/// 369 years until Januari 1, 1970                      369 * 365 = 134685
47/// of which floor(369 / 4) are leap years          floor(369 / 4) =     92
48/// except for 1700, 1800 and 1900                                       -3 +
49///                                                                  --------
50///                                                                  719163
51pub const UNIX_EPOCH_DAY: i64 = 719_163;
52
53/// converts a `i32` representing a `date32` to [`NaiveDateTime`]
54#[inline]
55pub fn date32_to_datetime(v: i32) -> Option<NaiveDateTime> {
56    Some(DateTime::from_timestamp(v as i64 * SECONDS_IN_DAY, 0)?.naive_utc())
57}
58
59/// converts a `i64` representing a `date64` to [`NaiveDateTime`]
60#[inline]
61pub fn date64_to_datetime(v: i64) -> Option<NaiveDateTime> {
62    let (sec, milli_sec) = split_second(v, MILLISECONDS);
63
64    let datetime = DateTime::from_timestamp(
65        // extract seconds from milliseconds
66        sec,
67        // discard extracted seconds and convert milliseconds to nanoseconds
68        milli_sec * MICROSECONDS as u32,
69    )?;
70    Some(datetime.naive_utc())
71}
72
73/// converts a `i32` representing a `time32(s)` to [`NaiveDateTime`]
74#[inline]
75pub fn time32s_to_time(v: i32) -> Option<NaiveTime> {
76    NaiveTime::from_num_seconds_from_midnight_opt(v as u32, 0)
77}
78
79/// converts a `i32` representing a `time32(ms)` to [`NaiveDateTime`]
80#[inline]
81pub fn time32ms_to_time(v: i32) -> Option<NaiveTime> {
82    let v = v as i64;
83    NaiveTime::from_num_seconds_from_midnight_opt(
84        // extract seconds from milliseconds
85        (v / MILLISECONDS) as u32,
86        // discard extracted seconds and convert milliseconds to
87        // nanoseconds
88        (v % MILLISECONDS * MICROSECONDS) as u32,
89    )
90}
91
92/// converts a `i64` representing a `time64(us)` to [`NaiveDateTime`]
93#[inline]
94pub fn time64us_to_time(v: i64) -> Option<NaiveTime> {
95    NaiveTime::from_num_seconds_from_midnight_opt(
96        // extract seconds from microseconds
97        (v / MICROSECONDS) as u32,
98        // discard extracted seconds and convert microseconds to
99        // nanoseconds
100        (v % MICROSECONDS * MILLISECONDS) as u32,
101    )
102}
103
104/// converts a `i64` representing a `time64(ns)` to [`NaiveDateTime`]
105#[inline]
106pub fn time64ns_to_time(v: i64) -> Option<NaiveTime> {
107    NaiveTime::from_num_seconds_from_midnight_opt(
108        // extract seconds from nanoseconds
109        (v / NANOSECONDS) as u32,
110        // discard extracted seconds
111        (v % NANOSECONDS) as u32,
112    )
113}
114
115/// converts [`NaiveTime`] to a `i32` representing a `time32(s)`
116#[inline]
117pub fn time_to_time32s(v: NaiveTime) -> i32 {
118    v.num_seconds_from_midnight() as i32
119}
120
121/// converts [`NaiveTime`] to a `i32` representing a `time32(ms)`
122#[inline]
123pub fn time_to_time32ms(v: NaiveTime) -> i32 {
124    (v.num_seconds_from_midnight() as i64 * MILLISECONDS
125        + v.nanosecond() as i64 * MILLISECONDS / NANOSECONDS) as i32
126}
127
128/// converts [`NaiveTime`] to a `i64` representing a `time64(us)`
129#[inline]
130pub fn time_to_time64us(v: NaiveTime) -> i64 {
131    v.num_seconds_from_midnight() as i64 * MICROSECONDS
132        + v.nanosecond() as i64 * MICROSECONDS / NANOSECONDS
133}
134
135/// converts [`NaiveTime`] to a `i64` representing a `time64(ns)`
136#[inline]
137pub fn time_to_time64ns(v: NaiveTime) -> i64 {
138    v.num_seconds_from_midnight() as i64 * NANOSECONDS + v.nanosecond() as i64
139}
140
141/// converts a `i64` representing a `timestamp(s)` to [`NaiveDateTime`]
142#[inline]
143pub fn timestamp_s_to_datetime(v: i64) -> Option<NaiveDateTime> {
144    Some(DateTime::from_timestamp(v, 0)?.naive_utc())
145}
146
147/// Similar to timestamp_s_to_datetime but only compute `date`
148#[inline]
149pub fn timestamp_s_to_date(secs: i64) -> Option<NaiveDateTime> {
150    let days = secs.div_euclid(86_400) + UNIX_EPOCH_DAY;
151    if days < i32::MIN as i64 || days > i32::MAX as i64 {
152        return None;
153    }
154    let date = NaiveDate::from_num_days_from_ce_opt(days as i32)?;
155    Some(date.and_time(NaiveTime::default()).and_utc().naive_utc())
156}
157
158/// Similar to timestamp_s_to_datetime but only compute `time`
159#[inline]
160pub fn timestamp_s_to_time(secs: i64) -> Option<NaiveDateTime> {
161    let secs = secs.rem_euclid(86_400);
162    let time = NaiveTime::from_num_seconds_from_midnight_opt(secs as u32, 0)?;
163    Some(
164        DateTime::<Utc>::from_naive_utc_and_offset(
165            NaiveDateTime::new(NaiveDate::default(), time),
166            Utc,
167        )
168        .naive_utc(),
169    )
170}
171
172/// converts a `i64` representing a `timestamp(ms)` to [`NaiveDateTime`]
173#[inline]
174pub fn timestamp_ms_to_datetime(v: i64) -> Option<NaiveDateTime> {
175    let (sec, milli_sec) = split_second(v, MILLISECONDS);
176
177    let datetime = DateTime::from_timestamp(
178        // extract seconds from milliseconds
179        sec,
180        // discard extracted seconds and convert milliseconds to nanoseconds
181        milli_sec * MICROSECONDS as u32,
182    )?;
183    Some(datetime.naive_utc())
184}
185
186/// converts a `i64` representing a `timestamp(us)` to [`NaiveDateTime`]
187#[inline]
188pub fn timestamp_us_to_datetime(v: i64) -> Option<NaiveDateTime> {
189    let (sec, micro_sec) = split_second(v, MICROSECONDS);
190
191    let datetime = DateTime::from_timestamp(
192        // extract seconds from microseconds
193        sec,
194        // discard extracted seconds and convert microseconds to nanoseconds
195        micro_sec * MILLISECONDS as u32,
196    )?;
197    Some(datetime.naive_utc())
198}
199
200/// converts a `i64` representing a `timestamp(ns)` to [`NaiveDateTime`]
201#[inline]
202pub fn timestamp_ns_to_datetime(v: i64) -> Option<NaiveDateTime> {
203    let (sec, nano_sec) = split_second(v, NANOSECONDS);
204
205    let datetime = DateTime::from_timestamp(
206        // extract seconds from nanoseconds
207        sec, // discard extracted seconds
208        nano_sec,
209    )?;
210    Some(datetime.naive_utc())
211}
212
213#[inline]
214pub(crate) fn split_second(v: i64, base: i64) -> (i64, u32) {
215    (v.div_euclid(base), v.rem_euclid(base) as u32)
216}
217
218/// converts a `i64` representing a `duration(s)` to [`Duration`]
219#[inline]
220pub fn duration_s_to_duration(v: i64) -> Duration {
221    Duration::try_seconds(v).unwrap()
222}
223
224/// converts a `i64` representing a `duration(ms)` to [`Duration`]
225#[inline]
226pub fn duration_ms_to_duration(v: i64) -> Duration {
227    Duration::try_milliseconds(v).unwrap()
228}
229
230/// converts a `i64` representing a `duration(us)` to [`Duration`]
231#[inline]
232pub fn duration_us_to_duration(v: i64) -> Duration {
233    Duration::microseconds(v)
234}
235
236/// converts a `i64` representing a `duration(ns)` to [`Duration`]
237#[inline]
238pub fn duration_ns_to_duration(v: i64) -> Duration {
239    Duration::nanoseconds(v)
240}
241
242/// Converts an [`ArrowPrimitiveType`] to [`NaiveDateTime`]
243pub fn as_datetime<T: ArrowPrimitiveType>(v: i64) -> Option<NaiveDateTime> {
244    match T::DATA_TYPE {
245        DataType::Date32 => date32_to_datetime(v as i32),
246        DataType::Date64 => date64_to_datetime(v),
247        DataType::Time32(_) | DataType::Time64(_) => None,
248        DataType::Timestamp(unit, _) => match unit {
249            TimeUnit::Second => timestamp_s_to_datetime(v),
250            TimeUnit::Millisecond => timestamp_ms_to_datetime(v),
251            TimeUnit::Microsecond => timestamp_us_to_datetime(v),
252            TimeUnit::Nanosecond => timestamp_ns_to_datetime(v),
253        },
254        // interval is not yet fully documented [ARROW-3097]
255        DataType::Interval(_) => None,
256        _ => None,
257    }
258}
259
260/// Converts an [`ArrowPrimitiveType`] to [`DateTime<Tz>`]
261pub fn as_datetime_with_timezone<T: ArrowPrimitiveType>(v: i64, tz: Tz) -> Option<DateTime<Tz>> {
262    let naive = as_datetime::<T>(v)?;
263    Some(Utc.from_utc_datetime(&naive).with_timezone(&tz))
264}
265
266/// Converts an [`ArrowPrimitiveType`] to [`NaiveDate`]
267pub fn as_date<T: ArrowPrimitiveType>(v: i64) -> Option<NaiveDate> {
268    as_datetime::<T>(v).map(|datetime| datetime.date())
269}
270
271/// Converts an [`ArrowPrimitiveType`] to [`NaiveTime`]
272pub fn as_time<T: ArrowPrimitiveType>(v: i64) -> Option<NaiveTime> {
273    match T::DATA_TYPE {
274        DataType::Time32(unit) => {
275            // safe to immediately cast to u32 as `self.value(i)` is positive i32
276            let v = v as u32;
277            match unit {
278                TimeUnit::Second => time32s_to_time(v as i32),
279                TimeUnit::Millisecond => time32ms_to_time(v as i32),
280                _ => None,
281            }
282        }
283        DataType::Time64(unit) => match unit {
284            TimeUnit::Microsecond => time64us_to_time(v),
285            TimeUnit::Nanosecond => time64ns_to_time(v),
286            _ => None,
287        },
288        DataType::Timestamp(_, _) => as_datetime::<T>(v).map(|datetime| datetime.time()),
289        DataType::Date32 | DataType::Date64 => NaiveTime::from_hms_opt(0, 0, 0),
290        DataType::Interval(_) => None,
291        _ => None,
292    }
293}
294
295/// Converts an [`ArrowPrimitiveType`] to [`Duration`]
296pub fn as_duration<T: ArrowPrimitiveType>(v: i64) -> Option<Duration> {
297    match T::DATA_TYPE {
298        DataType::Duration(unit) => match unit {
299            TimeUnit::Second => Some(duration_s_to_duration(v)),
300            TimeUnit::Millisecond => Some(duration_ms_to_duration(v)),
301            TimeUnit::Microsecond => Some(duration_us_to_duration(v)),
302            TimeUnit::Nanosecond => Some(duration_ns_to_duration(v)),
303        },
304        _ => None,
305    }
306}
307
308#[cfg(test)]
309mod tests {
310    use crate::temporal_conversions::{
311        date64_to_datetime, split_second, timestamp_ms_to_datetime, timestamp_ns_to_datetime,
312        timestamp_s_to_date, timestamp_s_to_datetime, timestamp_s_to_time,
313        timestamp_us_to_datetime, NANOSECONDS,
314    };
315    use chrono::DateTime;
316
317    #[test]
318    fn test_timestamp_func() {
319        let timestamp = 1234;
320        let datetime = timestamp_s_to_datetime(timestamp).unwrap();
321        let expected_date = datetime.date();
322        let expected_time = datetime.time();
323
324        assert_eq!(
325            timestamp_s_to_date(timestamp).unwrap().date(),
326            expected_date
327        );
328        assert_eq!(
329            timestamp_s_to_time(timestamp).unwrap().time(),
330            expected_time
331        );
332    }
333
334    #[test]
335    fn negative_input_timestamp_ns_to_datetime() {
336        assert_eq!(
337            timestamp_ns_to_datetime(-1),
338            DateTime::from_timestamp(-1, 999_999_999).map(|x| x.naive_utc())
339        );
340
341        assert_eq!(
342            timestamp_ns_to_datetime(-1_000_000_001),
343            DateTime::from_timestamp(-2, 999_999_999).map(|x| x.naive_utc())
344        );
345    }
346
347    #[test]
348    fn negative_input_timestamp_us_to_datetime() {
349        assert_eq!(
350            timestamp_us_to_datetime(-1),
351            DateTime::from_timestamp(-1, 999_999_000).map(|x| x.naive_utc())
352        );
353
354        assert_eq!(
355            timestamp_us_to_datetime(-1_000_001),
356            DateTime::from_timestamp(-2, 999_999_000).map(|x| x.naive_utc())
357        );
358    }
359
360    #[test]
361    fn negative_input_timestamp_ms_to_datetime() {
362        assert_eq!(
363            timestamp_ms_to_datetime(-1),
364            DateTime::from_timestamp(-1, 999_000_000).map(|x| x.naive_utc())
365        );
366
367        assert_eq!(
368            timestamp_ms_to_datetime(-1_001),
369            DateTime::from_timestamp(-2, 999_000_000).map(|x| x.naive_utc())
370        );
371    }
372
373    #[test]
374    fn negative_input_date64_to_datetime() {
375        assert_eq!(
376            date64_to_datetime(-1),
377            DateTime::from_timestamp(-1, 999_000_000).map(|x| x.naive_utc())
378        );
379
380        assert_eq!(
381            date64_to_datetime(-1_001),
382            DateTime::from_timestamp(-2, 999_000_000).map(|x| x.naive_utc())
383        );
384    }
385
386    #[test]
387    fn test_split_seconds() {
388        let (sec, nano_sec) = split_second(100, NANOSECONDS);
389        assert_eq!(sec, 0);
390        assert_eq!(nano_sec, 100);
391
392        let (sec, nano_sec) = split_second(123_000_000_456, NANOSECONDS);
393        assert_eq!(sec, 123);
394        assert_eq!(nano_sec, 456);
395
396        let (sec, nano_sec) = split_second(-1, NANOSECONDS);
397        assert_eq!(sec, -1);
398        assert_eq!(nano_sec, 999_999_999);
399
400        let (sec, nano_sec) = split_second(-123_000_000_001, NANOSECONDS);
401        assert_eq!(sec, -124);
402        assert_eq!(nano_sec, 999_999_999);
403    }
404}
arrow_array/temporal_conversions.rs

arrow_array/
temporal_conversions.rs
