vortex_array/extension/datetime/
time.rs1use 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#[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 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 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
52pub enum TimeValue {
54 Seconds(i32),
56 Milliseconds(i32),
58 Microseconds(i64),
60 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 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 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 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 assert!(vtable.deserialize_metadata(&[0xFF]).is_err());
227 }
228}