Skip to main content

vortex_array/extension/datetime/
time.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright the Vortex contributors
3
4use std::fmt;
5
6use jiff::Span;
7use vortex_error::VortexExpect;
8use vortex_error::VortexResult;
9use vortex_error::vortex_bail;
10use vortex_error::vortex_ensure;
11use vortex_error::vortex_ensure_eq;
12use vortex_error::vortex_err;
13use vortex_session::registry::CachedId;
14
15use crate::dtype::DType;
16use crate::dtype::Nullability;
17use crate::dtype::PType;
18use crate::dtype::extension::ExtDType;
19use crate::dtype::extension::ExtId;
20use crate::dtype::extension::ExtVTable;
21use crate::extension::datetime::TimeUnit;
22use crate::scalar::ScalarValue;
23
24/// Time DType.
25#[derive(Clone, Debug, Default, PartialEq, Eq, Hash)]
26pub struct Time;
27
28fn time_ptype(time_unit: &TimeUnit) -> Option<PType> {
29    Some(match time_unit {
30        TimeUnit::Nanoseconds | TimeUnit::Microseconds => PType::I64,
31        TimeUnit::Milliseconds | TimeUnit::Seconds => PType::I32,
32        TimeUnit::Days => return None,
33    })
34}
35
36impl Time {
37    /// Creates a new Time extension dtype with the given time unit and nullability.
38    ///
39    /// Note that Days units are not supported for Time.
40    pub fn try_new(time_unit: TimeUnit, nullability: Nullability) -> VortexResult<ExtDType<Self>> {
41        let ptype = time_ptype(&time_unit)
42            .ok_or_else(|| vortex_err!("Time type does not support time unit {}", time_unit))?;
43        ExtDType::try_new(time_unit, DType::Primitive(ptype, nullability))
44    }
45
46    /// Creates a new Time extension dtype with the given time unit and nullability.
47    pub fn new(time_unit: TimeUnit, nullability: Nullability) -> ExtDType<Self> {
48        Self::try_new(time_unit, nullability).vortex_expect("failed to create time dtype")
49    }
50}
51
52/// Unpacked value of a [`Time`] extension scalar.
53pub enum TimeValue {
54    /// Seconds since midnight.
55    Seconds(i32),
56    /// Milliseconds since midnight.
57    Milliseconds(i32),
58    /// Microseconds since midnight.
59    Microseconds(i64),
60    /// Nanoseconds since midnight.
61    Nanoseconds(i64),
62}
63
64impl fmt::Display for TimeValue {
65    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
66        let min = jiff::civil::Time::MIN;
67
68        let time = match self {
69            TimeValue::Seconds(s) => min + Span::new().seconds(*s),
70            TimeValue::Milliseconds(ms) => min + Span::new().milliseconds(*ms),
71            TimeValue::Microseconds(us) => min + Span::new().microseconds(*us),
72            TimeValue::Nanoseconds(ns) => min + Span::new().nanoseconds(*ns),
73        };
74
75        write!(f, "{}", time)
76    }
77}
78
79impl ExtVTable for Time {
80    type Metadata = TimeUnit;
81
82    type NativeValue<'a> = TimeValue;
83
84    fn id(&self) -> ExtId {
85        static ID: CachedId = CachedId::new("vortex.time");
86        *ID
87    }
88
89    fn serialize_metadata(&self, metadata: &Self::Metadata) -> VortexResult<Vec<u8>> {
90        Ok(vec![u8::from(*metadata)])
91    }
92
93    fn deserialize_metadata(&self, data: &[u8]) -> VortexResult<Self::Metadata> {
94        vortex_ensure!(!data.is_empty(), "Time metadata must not be empty");
95        let tag = data[0];
96        TimeUnit::try_from(tag)
97    }
98
99    fn validate_dtype(ext_dtype: &ExtDType<Self>) -> VortexResult<()> {
100        let metadata = ext_dtype.metadata();
101        let ptype = time_ptype(metadata)
102            .ok_or_else(|| vortex_err!("Time type does not support time unit {}", metadata))?;
103
104        let DType::Primitive(storage_ptype, _) = ext_dtype.storage_dtype() else {
105            vortex_bail!(
106                "Time storage dtype must be primitive, got {}",
107                ext_dtype.storage_dtype()
108            );
109        };
110        vortex_ensure_eq!(*storage_ptype, ptype);
111
112        Ok(())
113    }
114
115    fn unpack_native<'a>(
116        ext_dtype: &'a ExtDType<Self>,
117        storage_value: &'a ScalarValue,
118    ) -> VortexResult<Self::NativeValue<'a>> {
119        let length_of_time = storage_value.as_primitive().cast::<i64>()?;
120
121        let (span, value) = match *ext_dtype.metadata() {
122            TimeUnit::Seconds => {
123                let v = i32::try_from(length_of_time)
124                    .map_err(|e| vortex_err!("Time seconds value out of i32 range: {e}"))?;
125                (Span::new().try_seconds(v)?, TimeValue::Seconds(v))
126            }
127            TimeUnit::Milliseconds => {
128                let v = i32::try_from(length_of_time)
129                    .map_err(|e| vortex_err!("Time milliseconds value out of i32 range: {e}"))?;
130                (Span::new().try_milliseconds(v)?, TimeValue::Milliseconds(v))
131            }
132            TimeUnit::Microseconds => (
133                Span::new().try_microseconds(length_of_time)?,
134                TimeValue::Microseconds(length_of_time),
135            ),
136            TimeUnit::Nanoseconds => (
137                Span::new().try_nanoseconds(length_of_time)?,
138                TimeValue::Nanoseconds(length_of_time),
139            ),
140            d @ TimeUnit::Days => {
141                vortex_bail!("Time type does not support time unit {d}")
142            }
143        };
144
145        // Validate the storage value is within the valid range for Time.
146        jiff::civil::Time::MIN
147            .checked_add(span)
148            .map_err(|e| vortex_err!("Invalid time scalar: {}", e))?;
149
150        Ok(value)
151    }
152}
153
154#[cfg(test)]
155mod tests {
156    use rstest::rstest;
157    use vortex_error::VortexResult;
158
159    use crate::dtype::DType;
160    use crate::dtype::Nullability::Nullable;
161    use crate::dtype::extension::ExtDType;
162    use crate::extension::datetime::Time;
163    use crate::extension::datetime::TimeUnit;
164    use crate::scalar::PValue;
165    use crate::scalar::Scalar;
166    use crate::scalar::ScalarValue;
167
168    #[rstest]
169    #[case::microseconds(TimeUnit::Microseconds, i64::MAX)]
170    #[case::nanoseconds(TimeUnit::Nanoseconds, i64::MIN)]
171    fn test_reject_time_span_out_of_range(#[case] unit: TimeUnit, #[case] value: i64) {
172        let dtype = DType::Extension(Time::new(unit, Nullable).erased());
173        assert!(Scalar::try_new(dtype, Some(ScalarValue::from(value))).is_err());
174    }
175
176    #[test]
177    fn test_reject_non_primitive_storage() {
178        assert!(ExtDType::<Time>::try_new(TimeUnit::Seconds, DType::Utf8(Nullable),).is_err());
179    }
180
181    #[test]
182    fn validate_time_scalar() -> VortexResult<()> {
183        // 3661 seconds = 1 hour, 1 minute, 1 second.
184        let dtype = DType::Extension(Time::new(TimeUnit::Seconds, Nullable).erased());
185        Scalar::try_new(dtype, Some(ScalarValue::Primitive(PValue::I32(3661))))?;
186
187        Ok(())
188    }
189
190    #[test]
191    fn reject_time_out_of_range() {
192        // 86400 seconds = exactly 24 hours, which exceeds the valid `jiff::civil::Time` range.
193        let dtype = DType::Extension(Time::new(TimeUnit::Seconds, Nullable).erased());
194        let result = Scalar::try_new(dtype, Some(ScalarValue::Primitive(PValue::I32(86400))));
195        assert!(result.is_err());
196    }
197
198    #[test]
199    fn display_time_scalar() {
200        let dtype = DType::Extension(Time::new(TimeUnit::Seconds, Nullable).erased());
201
202        let scalar = Scalar::new(
203            dtype.clone(),
204            Some(ScalarValue::Primitive(PValue::I32(3661))),
205        );
206        assert_eq!(format!("{}", scalar.as_extension()), "01:01:01");
207
208        let scalar = Scalar::new(dtype, Some(ScalarValue::Primitive(PValue::I32(0))));
209        assert_eq!(format!("{}", scalar.as_extension()), "00:00:00");
210    }
211
212    #[test]
213    fn deserialize_empty_metadata_returns_error() {
214        use crate::dtype::extension::ExtVTable;
215
216        let vtable = Time;
217        assert!(vtable.deserialize_metadata(&[]).is_err());
218    }
219
220    #[test]
221    fn deserialize_invalid_tag_returns_error() {
222        use crate::dtype::extension::ExtVTable;
223
224        let vtable = Time;
225        // 0xFF is not a valid TimeUnit tag.
226        assert!(vtable.deserialize_metadata(&[0xFF]).is_err());
227    }
228}