arrow_array/
temporal_conversions.rs

Help
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/// Number of days between 0001-01-01 and 1970-01-01
41pub const EPOCH_DAYS_FROM_CE: i32 = 719_163;
42
43/// converts a `i32` representing a `date32` to [`NaiveDateTime`]
44#[inline]
45pub fn date32_to_datetime(v: i32) -> Option<NaiveDateTime> {
46    Some(DateTime::from_timestamp(v as i64 * SECONDS_IN_DAY, 0)?.naive_utc())
47}
48
49/// converts a `i64` representing a `date64` to [`NaiveDateTime`]
50#[inline]
51pub fn date64_to_datetime(v: i64) -> Option<NaiveDateTime> {
52    let (sec, milli_sec) = split_second(v, MILLISECONDS);
53
54    let datetime = DateTime::from_timestamp(
55        // extract seconds from milliseconds
56        sec,
57        // discard extracted seconds and convert milliseconds to nanoseconds
58        milli_sec * MICROSECONDS as u32,
59    )?;
60    Some(datetime.naive_utc())
61}
62
63/// converts a `i32` representing a `time32(s)` to [`NaiveDateTime`]
64#[inline]
65pub fn time32s_to_time(v: i32) -> Option<NaiveTime> {
66    NaiveTime::from_num_seconds_from_midnight_opt(v as u32, 0)
67}
68
69/// converts a `i32` representing a `time32(ms)` to [`NaiveDateTime`]
70#[inline]
71pub fn time32ms_to_time(v: i32) -> Option<NaiveTime> {
72    let v = v as i64;
73    NaiveTime::from_num_seconds_from_midnight_opt(
74        // extract seconds from milliseconds
75        (v / MILLISECONDS) as u32,
76        // discard extracted seconds and convert milliseconds to
77        // nanoseconds
78        (v % MILLISECONDS * MICROSECONDS) as u32,
79    )
80}
81
82/// converts a `i64` representing a `time64(us)` to [`NaiveDateTime`]
83#[inline]
84pub fn time64us_to_time(v: i64) -> Option<NaiveTime> {
85    NaiveTime::from_num_seconds_from_midnight_opt(
86        // extract seconds from microseconds
87        (v / MICROSECONDS) as u32,
88        // discard extracted seconds and convert microseconds to
89        // nanoseconds
90        (v % MICROSECONDS * MILLISECONDS) as u32,
91    )
92}
93
94/// converts a `i64` representing a `time64(ns)` to [`NaiveDateTime`]
95#[inline]
96pub fn time64ns_to_time(v: i64) -> Option<NaiveTime> {
97    NaiveTime::from_num_seconds_from_midnight_opt(
98        // extract seconds from nanoseconds
99        (v / NANOSECONDS) as u32,
100        // discard extracted seconds
101        (v % NANOSECONDS) as u32,
102    )
103}
104
105/// converts [`NaiveTime`] to a `i32` representing a `time32(s)`
106#[inline]
107pub fn time_to_time32s(v: NaiveTime) -> i32 {
108    v.num_seconds_from_midnight() as i32
109}
110
111/// converts [`NaiveTime`] to a `i32` representing a `time32(ms)`
112#[inline]
113pub fn time_to_time32ms(v: NaiveTime) -> i32 {
114    (v.num_seconds_from_midnight() as i64 * MILLISECONDS
115        + v.nanosecond() as i64 * MILLISECONDS / NANOSECONDS) as i32
116}
117
118/// converts [`NaiveTime`] to a `i64` representing a `time64(us)`
119#[inline]
120pub fn time_to_time64us(v: NaiveTime) -> i64 {
121    v.num_seconds_from_midnight() as i64 * MICROSECONDS
122        + v.nanosecond() as i64 * MICROSECONDS / NANOSECONDS
123}
124
125/// converts [`NaiveTime`] to a `i64` representing a `time64(ns)`
126#[inline]
127pub fn time_to_time64ns(v: NaiveTime) -> i64 {
128    v.num_seconds_from_midnight() as i64 * NANOSECONDS + v.nanosecond() as i64
129}
130
131/// converts a `i64` representing a `timestamp(s)` to [`NaiveDateTime`]
132#[inline]
133pub fn timestamp_s_to_datetime(v: i64) -> Option<NaiveDateTime> {
134    Some(DateTime::from_timestamp(v, 0)?.naive_utc())
135}
136
137/// converts a `i64` representing a `timestamp(ms)` to [`NaiveDateTime`]
138#[inline]
139pub fn timestamp_ms_to_datetime(v: i64) -> Option<NaiveDateTime> {
140    let (sec, milli_sec) = split_second(v, MILLISECONDS);
141
142    let datetime = DateTime::from_timestamp(
143        // extract seconds from milliseconds
144        sec,
145        // discard extracted seconds and convert milliseconds to nanoseconds
146        milli_sec * MICROSECONDS as u32,
147    )?;
148    Some(datetime.naive_utc())
149}
150
151/// converts a `i64` representing a `timestamp(us)` to [`NaiveDateTime`]
152#[inline]
153pub fn timestamp_us_to_datetime(v: i64) -> Option<NaiveDateTime> {
154    let (sec, micro_sec) = split_second(v, MICROSECONDS);
155
156    let datetime = DateTime::from_timestamp(
157        // extract seconds from microseconds
158        sec,
159        // discard extracted seconds and convert microseconds to nanoseconds
160        micro_sec * MILLISECONDS as u32,
161    )?;
162    Some(datetime.naive_utc())
163}
164
165/// converts a `i64` representing a `timestamp(ns)` to [`NaiveDateTime`]
166#[inline]
167pub fn timestamp_ns_to_datetime(v: i64) -> Option<NaiveDateTime> {
168    let (sec, nano_sec) = split_second(v, NANOSECONDS);
169
170    let datetime = DateTime::from_timestamp(
171        // extract seconds from nanoseconds
172        sec, // discard extracted seconds
173        nano_sec,
174    )?;
175    Some(datetime.naive_utc())
176}
177
178#[inline]
179pub(crate) fn split_second(v: i64, base: i64) -> (i64, u32) {
180    (v.div_euclid(base), v.rem_euclid(base) as u32)
181}
182
183/// converts a `i64` representing a `duration(s)` to [`Duration`]
184#[inline]
185pub fn duration_s_to_duration(v: i64) -> Duration {
186    Duration::try_seconds(v).unwrap()
187}
188
189/// converts a `i64` representing a `duration(ms)` to [`Duration`]
190#[inline]
191pub fn duration_ms_to_duration(v: i64) -> Duration {
192    Duration::try_milliseconds(v).unwrap()
193}
194
195/// converts a `i64` representing a `duration(us)` to [`Duration`]
196#[inline]
197pub fn duration_us_to_duration(v: i64) -> Duration {
198    Duration::microseconds(v)
199}
200
201/// converts a `i64` representing a `duration(ns)` to [`Duration`]
202#[inline]
203pub fn duration_ns_to_duration(v: i64) -> Duration {
204    Duration::nanoseconds(v)
205}
206
207/// Converts an [`ArrowPrimitiveType`] to [`NaiveDateTime`]
208pub fn as_datetime<T: ArrowPrimitiveType>(v: i64) -> Option<NaiveDateTime> {
209    match T::DATA_TYPE {
210        DataType::Date32 => date32_to_datetime(v as i32),
211        DataType::Date64 => date64_to_datetime(v),
212        DataType::Time32(_) | DataType::Time64(_) => None,
213        DataType::Timestamp(unit, _) => match unit {
214            TimeUnit::Second => timestamp_s_to_datetime(v),
215            TimeUnit::Millisecond => timestamp_ms_to_datetime(v),
216            TimeUnit::Microsecond => timestamp_us_to_datetime(v),
217            TimeUnit::Nanosecond => timestamp_ns_to_datetime(v),
218        },
219        // interval is not yet fully documented [ARROW-3097]
220        DataType::Interval(_) => None,
221        _ => None,
222    }
223}
224
225/// Converts an [`ArrowPrimitiveType`] to [`DateTime<Tz>`]
226pub fn as_datetime_with_timezone<T: ArrowPrimitiveType>(v: i64, tz: Tz) -> Option<DateTime<Tz>> {
227    let naive = as_datetime::<T>(v)?;
228    Some(Utc.from_utc_datetime(&naive).with_timezone(&tz))
229}
230
231/// Converts an [`ArrowPrimitiveType`] to [`NaiveDate`]
232pub fn as_date<T: ArrowPrimitiveType>(v: i64) -> Option<NaiveDate> {
233    as_datetime::<T>(v).map(|datetime| datetime.date())
234}
235
236/// Converts an [`ArrowPrimitiveType`] to [`NaiveTime`]
237pub fn as_time<T: ArrowPrimitiveType>(v: i64) -> Option<NaiveTime> {
238    match T::DATA_TYPE {
239        DataType::Time32(unit) => {
240            // safe to immediately cast to u32 as `self.value(i)` is positive i32
241            let v = v as u32;
242            match unit {
243                TimeUnit::Second => time32s_to_time(v as i32),
244                TimeUnit::Millisecond => time32ms_to_time(v as i32),
245                _ => None,
246            }
247        }
248        DataType::Time64(unit) => match unit {
249            TimeUnit::Microsecond => time64us_to_time(v),
250            TimeUnit::Nanosecond => time64ns_to_time(v),
251            _ => None,
252        },
253        DataType::Timestamp(_, _) => as_datetime::<T>(v).map(|datetime| datetime.time()),
254        DataType::Date32 | DataType::Date64 => NaiveTime::from_hms_opt(0, 0, 0),
255        DataType::Interval(_) => None,
256        _ => None,
257    }
258}
259
260/// Converts an [`ArrowPrimitiveType`] to [`Duration`]
261pub fn as_duration<T: ArrowPrimitiveType>(v: i64) -> Option<Duration> {
262    match T::DATA_TYPE {
263        DataType::Duration(unit) => match unit {
264            TimeUnit::Second => Some(duration_s_to_duration(v)),
265            TimeUnit::Millisecond => Some(duration_ms_to_duration(v)),
266            TimeUnit::Microsecond => Some(duration_us_to_duration(v)),
267            TimeUnit::Nanosecond => Some(duration_ns_to_duration(v)),
268        },
269        _ => None,
270    }
271}
272
273#[cfg(test)]
274mod tests {
275    use crate::temporal_conversions::{
276        date64_to_datetime, split_second, timestamp_ms_to_datetime, timestamp_ns_to_datetime,
277        timestamp_us_to_datetime, NANOSECONDS,
278    };
279    use chrono::DateTime;
280
281    #[test]
282    fn negative_input_timestamp_ns_to_datetime() {
283        assert_eq!(
284            timestamp_ns_to_datetime(-1),
285            DateTime::from_timestamp(-1, 999_999_999).map(|x| x.naive_utc())
286        );
287
288        assert_eq!(
289            timestamp_ns_to_datetime(-1_000_000_001),
290            DateTime::from_timestamp(-2, 999_999_999).map(|x| x.naive_utc())
291        );
292    }
293
294    #[test]
295    fn negative_input_timestamp_us_to_datetime() {
296        assert_eq!(
297            timestamp_us_to_datetime(-1),
298            DateTime::from_timestamp(-1, 999_999_000).map(|x| x.naive_utc())
299        );
300
301        assert_eq!(
302            timestamp_us_to_datetime(-1_000_001),
303            DateTime::from_timestamp(-2, 999_999_000).map(|x| x.naive_utc())
304        );
305    }
306
307    #[test]
308    fn negative_input_timestamp_ms_to_datetime() {
309        assert_eq!(
310            timestamp_ms_to_datetime(-1),
311            DateTime::from_timestamp(-1, 999_000_000).map(|x| x.naive_utc())
312        );
313
314        assert_eq!(
315            timestamp_ms_to_datetime(-1_001),
316            DateTime::from_timestamp(-2, 999_000_000).map(|x| x.naive_utc())
317        );
318    }
319
320    #[test]
321    fn negative_input_date64_to_datetime() {
322        assert_eq!(
323            date64_to_datetime(-1),
324            DateTime::from_timestamp(-1, 999_000_000).map(|x| x.naive_utc())
325        );
326
327        assert_eq!(
328            date64_to_datetime(-1_001),
329            DateTime::from_timestamp(-2, 999_000_000).map(|x| x.naive_utc())
330        );
331    }
332
333    #[test]
334    fn test_split_seconds() {
335        let (sec, nano_sec) = split_second(100, NANOSECONDS);
336        assert_eq!(sec, 0);
337        assert_eq!(nano_sec, 100);
338
339        let (sec, nano_sec) = split_second(123_000_000_456, NANOSECONDS);
340        assert_eq!(sec, 123);
341        assert_eq!(nano_sec, 456);
342
343        let (sec, nano_sec) = split_second(-1, NANOSECONDS);
344        assert_eq!(sec, -1);
345        assert_eq!(nano_sec, 999_999_999);
346
347        let (sec, nano_sec) = split_second(-123_000_000_001, NANOSECONDS);
348        assert_eq!(sec, -124);
349        assert_eq!(nano_sec, 999_999_999);
350    }
351}
arrow_array/temporal_conversions.rs

arrow_array/
temporal_conversions.rs
