vortex_array/extension/datetime/
date.rs1use std::fmt;
5
6use vortex_error::VortexExpect;
7use vortex_error::VortexResult;
8use vortex_error::vortex_bail;
9use vortex_error::vortex_ensure;
10use vortex_error::vortex_ensure_eq;
11use vortex_error::vortex_err;
12use vortex_session::registry::CachedId;
13
14use crate::dtype::DType;
15use crate::dtype::Nullability;
16use crate::dtype::PType;
17use crate::dtype::extension::ExtDType;
18use crate::dtype::extension::ExtId;
19use crate::dtype::extension::ExtVTable;
20use crate::extension::datetime::TimeUnit;
21use crate::scalar::ScalarValue;
22
23const EPOCH: jiff::civil::Date = jiff::civil::Date::constant(1970, 1, 1);
25
26#[derive(Clone, Debug, Default, PartialEq, Eq, Hash)]
28pub struct Date;
29
30fn date_ptype(time_unit: &TimeUnit) -> Option<PType> {
31 match time_unit {
32 TimeUnit::Nanoseconds => None,
33 TimeUnit::Microseconds => None,
34 TimeUnit::Milliseconds => Some(PType::I64),
35 TimeUnit::Seconds => None,
36 TimeUnit::Days => Some(PType::I32),
37 }
38}
39
40impl Date {
41 pub fn try_new(time_unit: TimeUnit, nullability: Nullability) -> VortexResult<ExtDType<Self>> {
45 let ptype = date_ptype(&time_unit)
46 .ok_or_else(|| vortex_err!("Date type does not support time unit {}", time_unit))?;
47 ExtDType::try_new(time_unit, DType::Primitive(ptype, nullability))
48 }
49
50 pub fn new(time_unit: TimeUnit, nullability: Nullability) -> ExtDType<Self> {
56 Self::try_new(time_unit, nullability).vortex_expect("failed to create date dtype")
57 }
58}
59
60pub enum DateValue {
62 Days(i32),
64 Milliseconds(i64),
66}
67
68impl fmt::Display for DateValue {
69 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
70 let (unit, value) = match *self {
71 DateValue::Days(days) => (TimeUnit::Days, i64::from(days)),
72 DateValue::Milliseconds(ms) => (TimeUnit::Milliseconds, ms),
73 };
74
75 let Ok(date) = unit
77 .to_jiff_span(value)
78 .and_then(|span| Ok(EPOCH.checked_add(span)?))
79 else {
80 return write!(f, "{value}{unit}");
81 };
82
83 write!(f, "{date}")
84 }
85}
86
87impl ExtVTable for Date {
88 type Metadata = TimeUnit;
89 type NativeValue<'a> = DateValue;
90
91 fn id(&self) -> ExtId {
92 static ID: CachedId = CachedId::new("vortex.date");
93 *ID
94 }
95
96 fn serialize_metadata(&self, metadata: &Self::Metadata) -> VortexResult<Vec<u8>> {
97 Ok(vec![u8::from(*metadata)])
98 }
99
100 fn deserialize_metadata(&self, metadata: &[u8]) -> VortexResult<Self::Metadata> {
101 vortex_ensure!(!metadata.is_empty(), "Date metadata must not be empty");
102 let tag = metadata[0];
103 TimeUnit::try_from(tag)
104 }
105
106 fn validate_dtype(ext_dtype: &ExtDType<Self>) -> VortexResult<()> {
107 let metadata = ext_dtype.metadata();
108 let ptype = date_ptype(metadata)
109 .ok_or_else(|| vortex_err!("Date type does not support time unit {}", metadata))?;
110
111 let DType::Primitive(storage_ptype, _) = ext_dtype.storage_dtype() else {
112 vortex_bail!(
113 "Date storage dtype must be primitive, got {}",
114 ext_dtype.storage_dtype()
115 );
116 };
117 vortex_ensure_eq!(*storage_ptype, ptype);
118
119 Ok(())
120 }
121
122 fn unpack_native<'a>(
123 ext_dtype: &'a ExtDType<Self>,
124 storage_value: &'a ScalarValue,
125 ) -> VortexResult<Self::NativeValue<'a>> {
126 let metadata = ext_dtype.metadata();
127 match metadata {
128 TimeUnit::Milliseconds => Ok(DateValue::Milliseconds(
129 storage_value.as_primitive().cast::<i64>()?,
130 )),
131 TimeUnit::Days => Ok(DateValue::Days(storage_value.as_primitive().cast::<i32>()?)),
132 _ => vortex_bail!("Date type does not support time unit {}", metadata),
133 }
134 }
135}
136
137#[cfg(test)]
138mod tests {
139 use rstest::rstest;
140 use vortex_error::VortexResult;
141
142 use crate::dtype::DType;
143 use crate::dtype::Nullability::Nullable;
144 use crate::dtype::extension::ExtDType;
145 use crate::extension::datetime::Date;
146 use crate::extension::datetime::DateValue;
147 use crate::extension::datetime::TimeUnit;
148 use crate::scalar::PValue;
149 use crate::scalar::Scalar;
150 use crate::scalar::ScalarValue;
151
152 #[test]
153 fn test_reject_non_primitive_storage() {
154 assert!(ExtDType::<Date>::try_new(TimeUnit::Days, DType::Utf8(Nullable),).is_err());
155 }
156
157 #[test]
158 fn validate_date_scalar() -> VortexResult<()> {
159 let days_dtype = DType::Extension(Date::new(TimeUnit::Days, Nullable).erased());
160 Scalar::try_new(days_dtype, Some(ScalarValue::Primitive(PValue::I32(0))))?;
161
162 let ms_dtype = DType::Extension(Date::new(TimeUnit::Milliseconds, Nullable).erased());
163 Scalar::try_new(
164 ms_dtype,
165 Some(ScalarValue::Primitive(PValue::I64(86_400_000))),
166 )?;
167
168 Ok(())
169 }
170
171 #[test]
172 fn reject_date_with_overflowing_value() {
173 let dtype = DType::Extension(Date::new(TimeUnit::Days, Nullable).erased());
175 let result = Scalar::try_new(dtype, Some(ScalarValue::Primitive(PValue::I64(i64::MAX))));
176 assert!(result.is_err());
177 }
178
179 #[test]
180 fn display_date_scalar() {
181 let dtype = DType::Extension(Date::new(TimeUnit::Days, Nullable).erased());
182
183 let scalar = Scalar::new(dtype.clone(), Some(ScalarValue::Primitive(PValue::I32(0))));
184 assert_eq!(format!("{}", scalar.as_extension()), "1970-01-01");
185
186 let scalar = Scalar::new(dtype, Some(ScalarValue::Primitive(PValue::I32(365))));
187 assert_eq!(format!("{}", scalar.as_extension()), "1971-01-01");
188 }
189
190 #[rstest]
191 #[case::ordinary(DateValue::Milliseconds(86_400_000), "1970-01-02")]
192 #[case::after_year_9999(DateValue::Days(2_932_897), "2932897days")]
193 #[case::beyond_jiff_span(DateValue::Days(10_000_000), "10000000days")]
194 #[case::max_milliseconds(DateValue::Milliseconds(i64::MAX), "9223372036854775807ms")]
195 fn display_date_value(#[case] value: DateValue, #[case] expected: &str) {
196 assert_eq!(value.to_string(), expected);
197 }
198
199 #[test]
200 fn deserialize_empty_metadata_returns_error() {
201 use crate::dtype::extension::ExtVTable;
202
203 let vtable = Date;
204 assert!(vtable.deserialize_metadata(&[]).is_err());
205 }
206
207 #[test]
208 fn deserialize_invalid_tag_returns_error() {
209 use crate::dtype::extension::ExtVTable;
210
211 let vtable = Date;
212 assert!(vtable.deserialize_metadata(&[0xFF]).is_err());
214 }
215}