minarrow/enums/
time_units.rs

1// Copyright 2025 Peter Garfield Bower
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! # **TimeUnits Module** - *Arrow Datetime Units*
16//!
17//! Defines time and interval units used by temporal arrays in Minarrow.
18//!  
19//! `TimeUnit` standardises second, millisecond, microsecond, nanosecond, and day resolution
20//! across `DatetimeArray32` and `DatetimeArray64`.  
21//! `IntervalUnit` specifies year–month, day–time, or month–day–nanosecond intervals
22//! for representing durations or periods in `DatetimeArray` values.
23//!  
24//! Both integrate with Apache Arrow’s native types for FFI compatibility.
25
26use std::fmt::{Display, Formatter, Result as FmtResult};
27
28/// # TimeUnit
29///
30/// Unified time unit enumeration.
31///
32/// ## Purpose
33/// - Combines time units for both `DatetimeArray32` and `DatetimeArray64`.
34/// - Confirm time since epoch units, or a raw duration value *(depending on the `ArrowType`
35/// that's attached to `Field` during `FieldArray` construction)*.
36/// - Avoids proliferating variants that require explicit handling throughout match statements.
37///
38/// ## Behaviour
39/// - Unit values are stored on the `DatetimeArray`, enabling variant-specific logic.
40/// - When transmitted over FFI, an `Apache Arrow`- produces compatible native format.
41#[derive(PartialEq, Eq, Hash, Clone, Copy, Debug, Default)]
42pub enum TimeUnit {
43    /// Seconds for Apache Arrow `Time32` and `Time64` units.
44    Seconds,
45    /// Milliseconds for Apache Arrow `Time32` and `Time64` units.
46    Milliseconds,
47    /// Microseconds for Apache Arrow `Time32` and `Time64` units.
48    Microseconds,
49    /// Nanoseconds for Apache Arrow `Time32` and `Time64` units.
50    Nanoseconds,
51    /// Default = days unspecified
52    ///
53    /// Apache Arrow's `Date32` and `Date64` types use days implicitly.
54    #[default]
55    Days,
56}
57
58/// # IntervalUnit
59///
60/// Inner Arrow discriminant for representing interval types
61///
62/// ## Usage
63/// Attach via `ArrowType` to `Field` when your `DatetimeArray<T>`
64/// T-integer represents an interval, rather than an epoch value.
65/// Then, it will materialise as an `Interval` *Apache Arrow* type
66/// when sent over FFI.
67#[derive(PartialEq, Eq, Hash, Clone, Debug)]
68pub enum IntervalUnit {
69    YearMonth,
70    DaysTime,
71    MonthDaysNs,
72}
73
74impl Display for TimeUnit {
75    fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult {
76        match self {
77            TimeUnit::Seconds => f.write_str("Seconds"),
78            TimeUnit::Milliseconds => f.write_str("Milliseconds"),
79            TimeUnit::Microseconds => f.write_str("Microseconds"),
80            TimeUnit::Nanoseconds => f.write_str("Nanoseconds"),
81            TimeUnit::Days => f.write_str("Days"),
82        }
83    }
84}
85
86impl Display for IntervalUnit {
87    fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult {
88        match self {
89            IntervalUnit::YearMonth => f.write_str("YearMonth"),
90            IntervalUnit::DaysTime => f.write_str("DaysTime"),
91            IntervalUnit::MonthDaysNs => f.write_str("MonthDaysNs"),
92        }
93    }
94}
minarrow/enums/time_units.rs

minarrow/enums/
time_units.rs
