1use std::any::Any;
32use std::fmt;
33use std::sync::Arc;
34
35use crate::array::iter::{ArrayAccessor, ArrayIter};
36use crate::array::primitive::{Int64Array, PrimitiveArray};
37use crate::array::{Array, ArrayRef, DURATION_TYPE, TIMESTAMP_TYPE, debug_array};
38use crate::buffer::{Bitmap, ScalarBuffer};
39use crate::datatype::DataType;
40use crate::error::Result;
41use crate::sealed::Sealed;
42
43const NANOS_PER_SEC: f64 = 1_000_000_000.0;
45
46macro_rules! temporal_array {
53 ($name:ident, $data_type:expr, $static_type:ident, $doc:literal, $unit_doc:literal) => {
54 #[doc = $doc]
55 #[derive(Clone)]
58 pub struct $name {
59 inner: Int64Array,
61 }
62
63 impl $name {
64 pub fn try_new(values: ScalarBuffer<i64>, validity: Option<Bitmap>) -> Result<Self> {
72 Ok(Self {
73 inner: PrimitiveArray::try_new_with_type($data_type, values, validity)?,
74 })
75 }
76
77 #[doc = concat!("Builds an array with no nulls from ", $unit_doc, ".")]
78 #[must_use]
79 pub fn from_nanos(values: impl IntoIterator<Item = i64>) -> Self {
80 let values: Vec<i64> = values.into_iter().collect();
81 Self {
82 inner: PrimitiveArray::try_new_with_type(
83 $data_type,
84 ScalarBuffer::from_slice(&values),
85 None,
86 )
87 .unwrap_or_else(|_| PrimitiveArray::new_null(0)),
88 }
89 }
90
91 #[doc = concat!("Builds an array from optional ", $unit_doc, ".")]
92 #[must_use]
93 pub fn from_opt_nanos(values: impl IntoIterator<Item = Option<i64>>) -> Self {
94 let base = Int64Array::from_opt_iter(values);
95 let validity = base.validity().cloned();
96 Self {
97 inner: PrimitiveArray::try_new_with_type(
98 $data_type,
99 base.values_buffer().clone(),
100 validity,
101 )
102 .unwrap_or_else(|_| PrimitiveArray::new_null(0)),
103 }
104 }
105
106 #[must_use]
108 pub fn new_null(len: usize) -> Self {
109 Self {
110 inner: PrimitiveArray::try_new_with_type(
111 $data_type,
112 ScalarBuffer::zeroed(len),
113 Some(Bitmap::new_unset(len)),
114 )
115 .unwrap_or_else(|_| PrimitiveArray::new_null(len)),
116 }
117 }
118
119 #[inline]
122 #[must_use]
123 pub fn values(&self) -> &[i64] {
124 self.inner.values()
125 }
126
127 #[inline]
129 #[must_use]
130 pub const fn values_buffer(&self) -> &ScalarBuffer<i64> {
131 self.inner.values_buffer()
132 }
133
134 #[inline]
138 #[must_use]
139 pub fn value(&self, index: usize) -> Option<i64> {
140 self.inner.value(index)
141 }
142
143 #[inline]
146 #[must_use]
147 pub fn get(&self, index: usize) -> Option<i64> {
148 self.inner.get(index)
149 }
150
151 #[must_use]
156 pub fn value_as_secs_f64(&self, index: usize) -> Option<f64> {
157 #[allow(clippy::cast_precision_loss)]
161 self.get(index).map(|nanos| nanos as f64 / NANOS_PER_SEC)
162 }
163
164 #[must_use]
169 pub fn value_as_duration(&self, index: usize) -> Option<std::time::Duration> {
170 let nanos = self.get(index)?;
171 u64::try_from(nanos)
172 .ok()
173 .map(std::time::Duration::from_nanos)
174 }
175
176 #[inline]
178 pub fn iter(&self) -> ArrayIter<&Self> {
179 ArrayIter::new(self)
180 }
181
182 #[must_use]
185 pub fn slice(&self, offset: usize, len: usize) -> Self {
186 Self {
187 inner: self.inner.slice(offset, len),
188 }
189 }
190
191 pub fn try_slice(&self, offset: usize, len: usize) -> Result<Self> {
198 Ok(Self {
199 inner: self.inner.try_slice(offset, len)?,
200 })
201 }
202
203 pub fn with_validity(&self, validity: Option<Bitmap>) -> Result<Self> {
210 Ok(Self {
211 inner: self.inner.with_validity(validity)?,
212 })
213 }
214
215 #[inline]
217 #[must_use]
218 pub const fn as_primitive(&self) -> &Int64Array {
219 &self.inner
220 }
221
222 pub fn from_primitive(values: &Int64Array) -> Result<Self> {
231 Self::try_new(values.values_buffer().clone(), values.validity().cloned())
232 }
233 }
234
235 impl Sealed for $name {}
236
237 impl Array for $name {
238 fn as_any(&self) -> &dyn Any {
239 self
240 }
241
242 fn data_type(&self) -> &DataType {
243 &$static_type
244 }
245
246 fn len(&self) -> usize {
247 self.inner.len()
248 }
249
250 fn validity(&self) -> Option<&Bitmap> {
251 self.inner.validity()
252 }
253
254 fn slice(&self, offset: usize, len: usize) -> ArrayRef {
255 Arc::new(Self::slice(self, offset, len))
256 }
257
258 fn buffer_memory_size(&self) -> usize {
259 self.inner.buffer_memory_size()
260 }
261
262 fn equals(&self, other: &dyn Array) -> bool {
263 other
264 .as_any()
265 .downcast_ref::<Self>()
266 .is_some_and(|other| self.inner.equals(&other.inner))
267 }
268 }
269
270 impl<'a> ArrayAccessor for &'a $name {
271 type Item = i64;
272
273 #[inline]
274 fn accessor_len(&self) -> usize {
275 self.inner.len()
276 }
277
278 #[inline]
279 fn accessor_get(&self, index: usize) -> Option<i64> {
280 $name::get(self, index)
281 }
282 }
283
284 impl PartialEq for $name {
285 #[inline]
286 fn eq(&self, other: &Self) -> bool {
287 self.inner == other.inner
288 }
289 }
290
291 impl Eq for $name {}
292
293 impl FromIterator<i64> for $name {
294 fn from_iter<I: IntoIterator<Item = i64>>(iter: I) -> Self {
295 Self::from_nanos(iter)
296 }
297 }
298
299 impl FromIterator<Option<i64>> for $name {
300 fn from_iter<I: IntoIterator<Item = Option<i64>>>(iter: I) -> Self {
301 Self::from_opt_nanos(iter)
302 }
303 }
304
305 impl<'a> IntoIterator for &'a $name {
306 type Item = Option<i64>;
307 type IntoIter = ArrayIter<&'a $name>;
308
309 fn into_iter(self) -> Self::IntoIter {
310 self.iter()
311 }
312 }
313
314 impl fmt::Debug for $name {
315 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
316 debug_array(
317 f,
318 stringify!($name),
319 &$static_type,
320 self.len(),
321 self.null_count(),
322 self.iter(),
323 )
324 }
325 }
326 };
327}
328
329temporal_array!(
330 TimestampArray,
331 DataType::Timestamp,
332 TIMESTAMP_TYPE,
333 "Nanoseconds since the Unix epoch, timezone-less.",
334 "nanosecond instants"
335);
336
337temporal_array!(
338 DurationArray,
339 DataType::Duration,
340 DURATION_TYPE,
341 "A nanosecond interval count.",
342 "nanosecond intervals"
343);
344
345#[cfg(test)]
346mod tests {
347 #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
348
349 use super::*;
350 use crate::DataError;
351 use crate::array::IntoArrayRef;
352
353 #[test]
354 fn empty_arrays() {
355 let stamps = TimestampArray::from_nanos([]);
356 assert!(stamps.is_empty());
357 assert_eq!(stamps.get(0), None);
358 assert_eq!(stamps.data_type(), &DataType::Timestamp);
359
360 let gaps = DurationArray::from_nanos([]);
361 assert!(gaps.is_empty());
362 assert_eq!(gaps.data_type(), &DataType::Duration);
363 }
364
365 #[test]
366 fn no_null_arrays() {
367 let stamps = TimestampArray::from_nanos([0, 1_000_000_000, -1_000_000_000]);
368 assert_eq!(stamps.len(), 3);
369 assert_eq!(stamps.null_count(), 0);
370 assert!(stamps.validity().is_none());
371 assert_eq!(stamps.get(0), Some(0));
372 assert_eq!(stamps.get(1), Some(1_000_000_000));
373 assert_eq!(stamps.get(3), None);
374 assert_eq!(stamps.values(), &[0, 1_000_000_000, -1_000_000_000]);
375 }
376
377 #[test]
378 fn all_null_arrays() {
379 let stamps = TimestampArray::new_null(3);
380 assert_eq!(stamps.len(), 3);
381 assert_eq!(stamps.null_count(), 3);
382 for index in 0..3 {
383 assert!(stamps.is_null(index));
384 assert_eq!(stamps.get(index), None);
385 assert_eq!(stamps.value(index), Some(0));
386 }
387
388 let gaps = DurationArray::new_null(2);
389 assert_eq!(gaps.null_count(), 2);
390 assert_eq!(gaps.data_type(), &DataType::Duration);
391 }
392
393 #[test]
394 fn mixed_nulls() {
395 let stamps = TimestampArray::from_opt_nanos([Some(1), None, Some(3)]);
396 assert_eq!(stamps.len(), 3);
397 assert_eq!(stamps.null_count(), 1);
398 assert_eq!(stamps.data_type(), &DataType::Timestamp);
399 assert_eq!(
400 stamps.iter().collect::<Vec<_>>(),
401 vec![Some(1), None, Some(3)]
402 );
403 assert_eq!(stamps.value_as_secs_f64(1), None);
404 }
405
406 #[test]
407 fn seconds_and_std_duration_conversions() {
408 let gaps = DurationArray::from_nanos([1_500_000_000, 0, -1, 500_000_000]);
409 assert_eq!(gaps.value_as_secs_f64(0), Some(1.5));
410 assert_eq!(gaps.value_as_secs_f64(1), Some(0.0));
411 assert_eq!(gaps.value_as_secs_f64(2), Some(-1e-9));
412 assert_eq!(gaps.value_as_secs_f64(9), None);
413 assert_eq!(
414 gaps.value_as_duration(0),
415 Some(std::time::Duration::from_millis(1_500))
416 );
417 assert_eq!(
418 gaps.value_as_duration(3),
419 Some(std::time::Duration::from_millis(500))
420 );
421 assert_eq!(gaps.value_as_duration(2), None, "negative has no Duration");
422 assert_eq!(gaps.value_as_duration(9), None);
423 }
424
425 #[test]
426 fn slicing_preserves_the_data_type() {
427 let stamps = TimestampArray::from_opt_nanos((0..20).map(|i| (i % 4 != 0).then_some(i)));
428 let window = stamps.slice(5, 10);
429 assert_eq!(window.len(), 10);
430 assert_eq!(window.data_type(), &DataType::Timestamp);
431 for index in 0..10 {
432 assert_eq!(window.get(index), stamps.get(index + 5));
433 }
434 assert_eq!(stamps.slice(18, 99).len(), 2);
435 assert_eq!(stamps.slice(99, 1).len(), 0);
436 assert!(stamps.try_slice(19, 2).is_err());
437 assert_eq!(stamps.try_slice(1, 2).unwrap().len(), 2);
438 }
439
440 #[test]
441 fn timestamps_never_equal_durations() {
442 let stamps: ArrayRef = TimestampArray::from_nanos([1, 2]).into_array_ref();
443 let gaps: ArrayRef = DurationArray::from_nanos([1, 2]).into_array_ref();
444 let plain: ArrayRef = Int64Array::from_values([1, 2]).into_array_ref();
445 assert_ne!(stamps, gaps);
446 assert_ne!(stamps, plain);
447 assert_ne!(gaps, plain);
448 assert_eq!(stamps, TimestampArray::from_nanos([1, 2]).into_array_ref());
449 }
450
451 #[test]
452 fn primitive_conversions_are_free() {
453 let plain = Int64Array::from_opt_iter([Some(1), None, Some(3)]);
454 let stamps = TimestampArray::from_primitive(&plain).unwrap();
455 assert_eq!(stamps.data_type(), &DataType::Timestamp);
456 assert_eq!(stamps.null_count(), 1);
457 assert_eq!(stamps.get(2), Some(3));
458 assert_eq!(stamps.as_primitive().data_type(), &DataType::Timestamp);
459
460 let gaps = DurationArray::from_primitive(&plain).unwrap();
461 assert_eq!(gaps.data_type(), &DataType::Duration);
462 }
463
464 #[test]
465 fn try_new_checks_validity_length() {
466 let values = ScalarBuffer::from_slice(&[1i64, 2]);
467 assert!(TimestampArray::try_new(values.clone(), None).is_ok());
468 assert!(TimestampArray::try_new(values.clone(), Some(Bitmap::new_set(2))).is_ok());
469 assert!(matches!(
470 TimestampArray::try_new(values, Some(Bitmap::new_set(3))),
471 Err(DataError::ValidityLengthMismatch { .. })
472 ));
473 }
474
475 #[test]
476 fn with_validity_replaces_the_bitmap() {
477 let stamps = TimestampArray::from_nanos([1, 2]);
478 let masked = stamps
479 .with_validity(Some([true, false].into_iter().collect()))
480 .unwrap();
481 assert_eq!(masked.null_count(), 1);
482 assert_eq!(masked.data_type(), &DataType::Timestamp);
483 assert!(stamps.with_validity(Some(Bitmap::new_set(9))).is_err());
484 }
485
486 #[test]
487 fn collects_from_iterators() {
488 let stamps: TimestampArray = (0i64..3).collect();
489 assert_eq!(stamps.len(), 3);
490 let gaps: DurationArray = [Some(1i64), None].into_iter().collect();
491 assert_eq!(gaps.null_count(), 1);
492 assert_eq!((&stamps).into_iter().count(), 3);
493 }
494
495 #[test]
496 fn debug_output_names_the_type() {
497 let rendered = format!("{:?}", TimestampArray::from_opt_nanos([Some(1), None]));
498 assert!(rendered.contains("TimestampArray"), "{rendered}");
499 assert!(rendered.contains("Timestamp(ns)"), "{rendered}");
500 assert!(rendered.contains("nulls=1"), "{rendered}");
501 assert!(format!("{:?}", DurationArray::from_nanos([1])).contains("Duration(ns)"));
502 }
503
504 #[test]
505 fn extreme_values_round_trip() {
506 let stamps = TimestampArray::from_nanos([i64::MIN, i64::MAX, 0]);
507 assert_eq!(stamps.get(0), Some(i64::MIN));
508 assert_eq!(stamps.get(1), Some(i64::MAX));
509 assert_eq!(stamps.value_as_duration(0), None);
510 assert!(stamps.value_as_secs_f64(1).unwrap_or(0.0) > 9e9);
511 }
512
513 #[test]
514 fn buffer_memory_size_is_reported() {
515 let stamps = TimestampArray::from_nanos(0..1_000);
516 assert!(stamps.buffer_memory_size() >= 8_000);
517 }
518}