Skip to main content

astrs_data/array/
temporal.rs

1//! [`TimestampArray`] and [`DurationArray`] โ€” the two nanosecond temporal
2//! columns.
3//!
4//! Both are `i64` columns with their own [`DataType`]. Blueprint ยง6.1 pins the
5//! unit to nanoseconds and drops the timezone, because AstRS timestamps come
6//! from the HLC in `astrs-time`, which is nanosecond-resolution and UTC by
7//! construction. That leaves the two types distinguished only by *meaning*:
8//!
9//! * `Timestamp` โ€” nanoseconds **since the Unix epoch**, an instant.
10//! * `Duration` โ€” a nanosecond **count**, an interval.
11//!
12//! Keeping them as separate Rust types (rather than aliases for
13//! `PrimitiveArray<i64>`) is what lets the graph's type checker reject an edge
14//! that feeds a duration into an instant port. Internally each wraps a
15//! [`PrimitiveArray<i64>`] built through
16//! [`PrimitiveArray::try_new_with_type`], so the buffer layout is byte-for-byte
17//! the Arrow `Timestamp(NANOSECOND, None)` / `Duration(NANOSECOND)` layout.
18//!
19//! ```
20//! use astrs_data::array::{Array, DurationArray, TimestampArray};
21//!
22//! let stamps = TimestampArray::from_nanos([1_000_000_000, 1_500_000_000]);
23//! assert_eq!(stamps.get(0), Some(1_000_000_000));
24//! assert_eq!(stamps.value_as_secs_f64(1), Some(1.5));
25//!
26//! let gaps = DurationArray::from_nanos([500_000_000]);
27//! assert_eq!(gaps.value_as_secs_f64(0), Some(0.5));
28//! assert_eq!(gaps.value_as_duration(0), Some(std::time::Duration::from_millis(500)));
29//! ```
30
31use 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
43/// Nanoseconds in one second.
44const NANOS_PER_SEC: f64 = 1_000_000_000.0;
45
46/// Generates the shared body of [`TimestampArray`] and [`DurationArray`].
47///
48/// The two types are identical apart from their `DataType`, their name and the
49/// documentation of what the number means, so the implementation is written
50/// once and instantiated twice. Writing it out twice by hand would be 400
51/// lines of duplicated logic with two places for a bug to hide.
52macro_rules! temporal_array {
53    ($name:ident, $data_type:expr, $static_type:ident, $doc:literal, $unit_doc:literal) => {
54        #[doc = $doc]
55        ///
56        /// A nanosecond `i64` column; see the [module documentation](self).
57        #[derive(Clone)]
58        pub struct $name {
59            /// The `i64` values, carrying this type's `DataType`.
60            inner: Int64Array,
61        }
62
63        impl $name {
64            /// Builds an array from a values buffer and an optional validity
65            /// bitmap.
66            ///
67            /// # Errors
68            ///
69            /// [`ValidityLengthMismatch`](crate::DataError::ValidityLengthMismatch)
70            /// when the bitmap does not cover exactly one bit per value.
71            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            /// An all-null array of `len` slots.
107            #[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            /// The raw nanosecond values, including the placeholder in every
120            /// null slot.
121            #[inline]
122            #[must_use]
123            pub fn values(&self) -> &[i64] {
124                self.inner.values()
125            }
126
127            /// The values buffer.
128            #[inline]
129            #[must_use]
130            pub const fn values_buffer(&self) -> &ScalarBuffer<i64> {
131                self.inner.values_buffer()
132            }
133
134            /// The raw slot value at `index`, ignoring validity.
135            ///
136            /// Returns `None` only when `index` is out of range.
137            #[inline]
138            #[must_use]
139            pub fn value(&self, index: usize) -> Option<i64> {
140                self.inner.value(index)
141            }
142
143            /// The logical value at `index`: `None` when the slot is null or
144            /// out of range.
145            #[inline]
146            #[must_use]
147            pub fn get(&self, index: usize) -> Option<i64> {
148                self.inner.get(index)
149            }
150
151            /// The value at `index` in seconds, as a float.
152            ///
153            /// Lossy beyond 2^53 nanoseconds (about 104 days); use
154            /// [`Self::get`] when exactness matters.
155            #[must_use]
156            pub fn value_as_secs_f64(&self, index: usize) -> Option<f64> {
157                // The precision loss past 2^53 ns is the documented contract of
158                // this accessor, not an oversight: callers who need exactness
159                // are pointed at `get`, which returns the raw integer.
160                #[allow(clippy::cast_precision_loss)]
161                self.get(index).map(|nanos| nanos as f64 / NANOS_PER_SEC)
162            }
163
164            /// The value at `index` as a [`std::time::Duration`].
165            ///
166            /// Returns `None` for a negative value, which `Duration` cannot
167            /// represent.
168            #[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            /// Iterates over the logical values, `None` for nulls.
177            #[inline]
178            pub fn iter(&self) -> ArrayIter<&Self> {
179                ArrayIter::new(self)
180            }
181
182            /// A zero-copy sub-range, clamped to the array (the crate-wide
183            /// slicing convention).
184            #[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            /// Checked [`Self::slice`].
192            ///
193            /// # Errors
194            ///
195            /// [`SliceOutOfBounds`](crate::DataError::SliceOutOfBounds) when
196            /// the window leaves the array.
197            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            /// Returns a copy with a different validity bitmap.
204            ///
205            /// # Errors
206            ///
207            /// [`ValidityLengthMismatch`](crate::DataError::ValidityLengthMismatch)
208            /// when the bitmap length is wrong.
209            pub fn with_validity(&self, validity: Option<Bitmap>) -> Result<Self> {
210                Ok(Self {
211                    inner: self.inner.with_validity(validity)?,
212                })
213            }
214
215            /// The underlying `i64` column, keeping this type's `DataType`.
216            #[inline]
217            #[must_use]
218            pub const fn as_primitive(&self) -> &Int64Array {
219                &self.inner
220            }
221
222            /// Reinterprets a plain `Int64` column as this temporal type.
223            ///
224            /// Free: the two share a buffer layout.
225            ///
226            /// # Errors
227            ///
228            /// [`TypeMismatch`](crate::DataError::TypeMismatch) when the
229            /// source is not an `Int64`, `Timestamp` or `Duration` column.
230            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}