Skip to main content

arrow_buffer/
interval.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: See the NOTICE file distributed with this work for additional information regarding copyright ownership
3// SPDX-FileContributor: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements
4
5use crate::arith::derive_arith;
6use std::ops::Neg;
7
8/// Value of an IntervalMonthDayNano array
9///
10///  ## Representation
11///
12/// This type is stored as a single 128 bit integer, interpreted as three
13/// different signed integral fields:
14///
15/// 1. The number of months (32 bits)
16/// 2. The number days (32 bits)
17/// 2. The number of nanoseconds (64 bits).
18///
19/// Nanoseconds does not allow for leap seconds.
20///
21/// Each field is independent (e.g. there is no constraint that the quantity of
22/// nanoseconds represents less than a day's worth of time).
23///
24/// ```text
25/// ┌───────────────┬─────────────┬─────────────────────────────┐
26/// │     Months    │     Days    │            Nanos            │
27/// │   (32 bits)   │  (32 bits)  │          (64 bits)          │
28/// └───────────────┴─────────────┴─────────────────────────────┘
29/// 0            32             64                           128 bit offset
30/// ```
31/// Please see the [Arrow Spec](https://github.com/apache/arrow/blob/081b4022fe6f659d8765efc82b3f4787c5039e3c/format/Schema.fbs#L409-L415) for more details
32///
33///## Note on Comparing and Ordering for Calendar Types
34///
35/// Values of `IntervalMonthDayNano` are compared using their binary
36/// representation, which can lead to surprising results.
37///
38/// Spans of time measured in calendar units are not fixed in absolute size (e.g.
39/// number of seconds) which makes defining comparisons and ordering non trivial.
40/// For example `1 month` is 28 days for February but `1 month` is 31 days
41/// in December.
42///
43/// This makes the seemingly simple operation of comparing two intervals
44/// complicated in practice. For example is `1 month` more or less than `30
45/// days`? The answer depends on what month you are talking about.
46///
47/// This crate defines comparisons for calendar types using their binary
48/// representation which is fast and efficient, but leads
49/// to potentially surprising results.
50///
51/// For example a
52/// `IntervalMonthDayNano` of `1 month` will compare as **greater** than a
53/// `IntervalMonthDayNano` of `100 days` because the binary representation of `1 month`
54/// is larger than the binary representation of 100 days.
55#[derive(Debug, Default, Copy, Clone, Eq, PartialEq, Hash, Ord, PartialOrd)]
56#[repr(C)]
57pub struct IntervalMonthDayNano {
58    /// Number of months
59    pub months: i32,
60    /// Number of days
61    pub days: i32,
62    /// Number of nanoseconds
63    pub nanoseconds: i64,
64}
65
66impl IntervalMonthDayNano {
67    /// The additive identity i.e. `0`.
68    pub const ZERO: Self = Self::new(0, 0, 0);
69
70    /// The multiplicative identity, i.e. `1`.
71    pub const ONE: Self = Self::new(1, 1, 1);
72
73    /// The multiplicative inverse, i.e. `-1`.
74    pub const MINUS_ONE: Self = Self::new(-1, -1, -1);
75
76    /// The maximum value that can be represented
77    pub const MAX: Self = Self::new(i32::MAX, i32::MAX, i64::MAX);
78
79    /// The minimum value that can be represented
80    pub const MIN: Self = Self::new(i32::MIN, i32::MIN, i64::MIN);
81
82    /// Create a new [`IntervalMonthDayNano`]
83    #[inline]
84    pub const fn new(months: i32, days: i32, nanoseconds: i64) -> Self {
85        Self {
86            months,
87            days,
88            nanoseconds,
89        }
90    }
91
92    /// Computes the absolute value
93    #[inline]
94    pub fn wrapping_abs(self) -> Self {
95        Self {
96            months: self.months.wrapping_abs(),
97            days: self.days.wrapping_abs(),
98            nanoseconds: self.nanoseconds.wrapping_abs(),
99        }
100    }
101
102    /// Computes the absolute value
103    #[inline]
104    pub fn checked_abs(self) -> Option<Self> {
105        Some(Self {
106            months: self.months.checked_abs()?,
107            days: self.days.checked_abs()?,
108            nanoseconds: self.nanoseconds.checked_abs()?,
109        })
110    }
111
112    /// Negates the value
113    #[inline]
114    pub fn wrapping_neg(self) -> Self {
115        Self {
116            months: self.months.wrapping_neg(),
117            days: self.days.wrapping_neg(),
118            nanoseconds: self.nanoseconds.wrapping_neg(),
119        }
120    }
121
122    /// Negates the value
123    #[inline]
124    pub fn checked_neg(self) -> Option<Self> {
125        Some(Self {
126            months: self.months.checked_neg()?,
127            days: self.days.checked_neg()?,
128            nanoseconds: self.nanoseconds.checked_neg()?,
129        })
130    }
131
132    /// Performs wrapping addition
133    #[inline]
134    pub fn wrapping_add(self, other: Self) -> Self {
135        Self {
136            months: self.months.wrapping_add(other.months),
137            days: self.days.wrapping_add(other.days),
138            nanoseconds: self.nanoseconds.wrapping_add(other.nanoseconds),
139        }
140    }
141
142    /// Performs checked addition
143    #[inline]
144    pub fn checked_add(self, other: Self) -> Option<Self> {
145        Some(Self {
146            months: self.months.checked_add(other.months)?,
147            days: self.days.checked_add(other.days)?,
148            nanoseconds: self.nanoseconds.checked_add(other.nanoseconds)?,
149        })
150    }
151
152    /// Performs wrapping subtraction
153    #[inline]
154    pub fn wrapping_sub(self, other: Self) -> Self {
155        Self {
156            months: self.months.wrapping_sub(other.months),
157            days: self.days.wrapping_sub(other.days),
158            nanoseconds: self.nanoseconds.wrapping_sub(other.nanoseconds),
159        }
160    }
161
162    /// Performs checked subtraction
163    #[inline]
164    pub fn checked_sub(self, other: Self) -> Option<Self> {
165        Some(Self {
166            months: self.months.checked_sub(other.months)?,
167            days: self.days.checked_sub(other.days)?,
168            nanoseconds: self.nanoseconds.checked_sub(other.nanoseconds)?,
169        })
170    }
171
172    /// Performs wrapping multiplication
173    #[inline]
174    pub fn wrapping_mul(self, other: Self) -> Self {
175        Self {
176            months: self.months.wrapping_mul(other.months),
177            days: self.days.wrapping_mul(other.days),
178            nanoseconds: self.nanoseconds.wrapping_mul(other.nanoseconds),
179        }
180    }
181
182    /// Performs checked multiplication
183    pub fn checked_mul(self, other: Self) -> Option<Self> {
184        Some(Self {
185            months: self.months.checked_mul(other.months)?,
186            days: self.days.checked_mul(other.days)?,
187            nanoseconds: self.nanoseconds.checked_mul(other.nanoseconds)?,
188        })
189    }
190
191    /// Performs wrapping division
192    #[inline]
193    pub fn wrapping_div(self, other: Self) -> Self {
194        Self {
195            months: self.months.wrapping_div(other.months),
196            days: self.days.wrapping_div(other.days),
197            nanoseconds: self.nanoseconds.wrapping_div(other.nanoseconds),
198        }
199    }
200
201    /// Performs checked division
202    pub fn checked_div(self, other: Self) -> Option<Self> {
203        Some(Self {
204            months: self.months.checked_div(other.months)?,
205            days: self.days.checked_div(other.days)?,
206            nanoseconds: self.nanoseconds.checked_div(other.nanoseconds)?,
207        })
208    }
209
210    /// Performs wrapping remainder
211    #[inline]
212    pub fn wrapping_rem(self, other: Self) -> Self {
213        Self {
214            months: self.months.wrapping_rem(other.months),
215            days: self.days.wrapping_rem(other.days),
216            nanoseconds: self.nanoseconds.wrapping_rem(other.nanoseconds),
217        }
218    }
219
220    /// Performs checked remainder
221    pub fn checked_rem(self, other: Self) -> Option<Self> {
222        Some(Self {
223            months: self.months.checked_rem(other.months)?,
224            days: self.days.checked_rem(other.days)?,
225            nanoseconds: self.nanoseconds.checked_rem(other.nanoseconds)?,
226        })
227    }
228
229    /// Performs wrapping exponentiation
230    #[inline]
231    pub fn wrapping_pow(self, exp: u32) -> Self {
232        Self {
233            months: self.months.wrapping_pow(exp),
234            days: self.days.wrapping_pow(exp),
235            nanoseconds: self.nanoseconds.wrapping_pow(exp),
236        }
237    }
238
239    /// Performs checked exponentiation
240    #[inline]
241    pub fn checked_pow(self, exp: u32) -> Option<Self> {
242        Some(Self {
243            months: self.months.checked_pow(exp)?,
244            days: self.days.checked_pow(exp)?,
245            nanoseconds: self.nanoseconds.checked_pow(exp)?,
246        })
247    }
248}
249
250impl Neg for IntervalMonthDayNano {
251    type Output = Self;
252
253    #[cfg(debug_assertions)]
254    fn neg(self) -> Self::Output {
255        self.checked_neg().expect("IntervalMonthDayNano overflow")
256    }
257
258    #[cfg(not(debug_assertions))]
259    fn neg(self) -> Self::Output {
260        self.wrapping_neg()
261    }
262}
263
264derive_arith!(
265    IntervalMonthDayNano,
266    Add,
267    AddAssign,
268    add,
269    add_assign,
270    wrapping_add,
271    checked_add
272);
273derive_arith!(
274    IntervalMonthDayNano,
275    Sub,
276    SubAssign,
277    sub,
278    sub_assign,
279    wrapping_sub,
280    checked_sub
281);
282derive_arith!(
283    IntervalMonthDayNano,
284    Mul,
285    MulAssign,
286    mul,
287    mul_assign,
288    wrapping_mul,
289    checked_mul
290);
291derive_arith!(
292    IntervalMonthDayNano,
293    Div,
294    DivAssign,
295    div,
296    div_assign,
297    wrapping_div,
298    checked_div
299);
300derive_arith!(
301    IntervalMonthDayNano,
302    Rem,
303    RemAssign,
304    rem,
305    rem_assign,
306    wrapping_rem,
307    checked_rem
308);
309
310/// Value of an IntervalDayTime array
311///
312/// ## Representation
313///
314/// This type is stored as a single 64 bit integer, interpreted as two i32
315/// fields:
316///
317/// 1. the number of elapsed days
318/// 2. The number of milliseconds (no leap seconds),
319///
320/// ```text
321/// ┌──────────────┬──────────────┐
322/// │     Days     │ Milliseconds │
323/// │  (32 bits)   │  (32 bits)   │
324/// └──────────────┴──────────────┘
325/// 0              31            63 bit offset
326/// ```
327///
328/// Please see the [Arrow Spec](https://github.com/apache/arrow/blob/081b4022fe6f659d8765efc82b3f4787c5039e3c/format/Schema.fbs#L406-L408) for more details
329///
330/// ## Note on Comparing and Ordering for Calendar Types
331///
332/// Values of `IntervalDayTime` are compared using their binary representation,
333/// which can lead to surprising results. Please see the description of ordering on
334/// [`IntervalMonthDayNano`] for more details
335#[derive(Debug, Default, Copy, Clone, Eq, PartialEq, Hash, Ord, PartialOrd)]
336#[repr(C)]
337pub struct IntervalDayTime {
338    /// Number of days
339    pub days: i32,
340    /// Number of milliseconds
341    pub milliseconds: i32,
342}
343
344impl IntervalDayTime {
345    /// The additive identity i.e. `0`.
346    pub const ZERO: Self = Self::new(0, 0);
347
348    /// The multiplicative identity, i.e. `1`.
349    pub const ONE: Self = Self::new(1, 1);
350
351    /// The multiplicative inverse, i.e. `-1`.
352    pub const MINUS_ONE: Self = Self::new(-1, -1);
353
354    /// The maximum value that can be represented
355    pub const MAX: Self = Self::new(i32::MAX, i32::MAX);
356
357    /// The minimum value that can be represented
358    pub const MIN: Self = Self::new(i32::MIN, i32::MIN);
359
360    /// Create a new [`IntervalDayTime`]
361    #[inline]
362    pub const fn new(days: i32, milliseconds: i32) -> Self {
363        Self { days, milliseconds }
364    }
365
366    /// Computes the absolute value
367    #[inline]
368    pub fn wrapping_abs(self) -> Self {
369        Self {
370            days: self.days.wrapping_abs(),
371            milliseconds: self.milliseconds.wrapping_abs(),
372        }
373    }
374
375    /// Computes the absolute value
376    #[inline]
377    pub fn checked_abs(self) -> Option<Self> {
378        Some(Self {
379            days: self.days.checked_abs()?,
380            milliseconds: self.milliseconds.checked_abs()?,
381        })
382    }
383
384    /// Negates the value
385    #[inline]
386    pub fn wrapping_neg(self) -> Self {
387        Self {
388            days: self.days.wrapping_neg(),
389            milliseconds: self.milliseconds.wrapping_neg(),
390        }
391    }
392
393    /// Negates the value
394    #[inline]
395    pub fn checked_neg(self) -> Option<Self> {
396        Some(Self {
397            days: self.days.checked_neg()?,
398            milliseconds: self.milliseconds.checked_neg()?,
399        })
400    }
401
402    /// Performs wrapping addition
403    #[inline]
404    pub fn wrapping_add(self, other: Self) -> Self {
405        Self {
406            days: self.days.wrapping_add(other.days),
407            milliseconds: self.milliseconds.wrapping_add(other.milliseconds),
408        }
409    }
410
411    /// Performs checked addition
412    #[inline]
413    pub fn checked_add(self, other: Self) -> Option<Self> {
414        Some(Self {
415            days: self.days.checked_add(other.days)?,
416            milliseconds: self.milliseconds.checked_add(other.milliseconds)?,
417        })
418    }
419
420    /// Performs wrapping subtraction
421    #[inline]
422    pub fn wrapping_sub(self, other: Self) -> Self {
423        Self {
424            days: self.days.wrapping_sub(other.days),
425            milliseconds: self.milliseconds.wrapping_sub(other.milliseconds),
426        }
427    }
428
429    /// Performs checked subtraction
430    #[inline]
431    pub fn checked_sub(self, other: Self) -> Option<Self> {
432        Some(Self {
433            days: self.days.checked_sub(other.days)?,
434            milliseconds: self.milliseconds.checked_sub(other.milliseconds)?,
435        })
436    }
437
438    /// Performs wrapping multiplication
439    #[inline]
440    pub fn wrapping_mul(self, other: Self) -> Self {
441        Self {
442            days: self.days.wrapping_mul(other.days),
443            milliseconds: self.milliseconds.wrapping_mul(other.milliseconds),
444        }
445    }
446
447    /// Performs checked multiplication
448    pub fn checked_mul(self, other: Self) -> Option<Self> {
449        Some(Self {
450            days: self.days.checked_mul(other.days)?,
451            milliseconds: self.milliseconds.checked_mul(other.milliseconds)?,
452        })
453    }
454
455    /// Performs wrapping division
456    #[inline]
457    pub fn wrapping_div(self, other: Self) -> Self {
458        Self {
459            days: self.days.wrapping_div(other.days),
460            milliseconds: self.milliseconds.wrapping_div(other.milliseconds),
461        }
462    }
463
464    /// Performs checked division
465    pub fn checked_div(self, other: Self) -> Option<Self> {
466        Some(Self {
467            days: self.days.checked_div(other.days)?,
468            milliseconds: self.milliseconds.checked_div(other.milliseconds)?,
469        })
470    }
471
472    /// Performs wrapping remainder
473    #[inline]
474    pub fn wrapping_rem(self, other: Self) -> Self {
475        Self {
476            days: self.days.wrapping_rem(other.days),
477            milliseconds: self.milliseconds.wrapping_rem(other.milliseconds),
478        }
479    }
480
481    /// Performs checked remainder
482    pub fn checked_rem(self, other: Self) -> Option<Self> {
483        Some(Self {
484            days: self.days.checked_rem(other.days)?,
485            milliseconds: self.milliseconds.checked_rem(other.milliseconds)?,
486        })
487    }
488
489    /// Performs wrapping exponentiation
490    #[inline]
491    pub fn wrapping_pow(self, exp: u32) -> Self {
492        Self {
493            days: self.days.wrapping_pow(exp),
494            milliseconds: self.milliseconds.wrapping_pow(exp),
495        }
496    }
497
498    /// Performs checked exponentiation
499    #[inline]
500    pub fn checked_pow(self, exp: u32) -> Option<Self> {
501        Some(Self {
502            days: self.days.checked_pow(exp)?,
503            milliseconds: self.milliseconds.checked_pow(exp)?,
504        })
505    }
506}
507
508impl Neg for IntervalDayTime {
509    type Output = Self;
510
511    #[cfg(debug_assertions)]
512    fn neg(self) -> Self::Output {
513        self.checked_neg().expect("IntervalDayMillisecond overflow")
514    }
515
516    #[cfg(not(debug_assertions))]
517    fn neg(self) -> Self::Output {
518        self.wrapping_neg()
519    }
520}
521
522derive_arith!(
523    IntervalDayTime,
524    Add,
525    AddAssign,
526    add,
527    add_assign,
528    wrapping_add,
529    checked_add
530);
531derive_arith!(
532    IntervalDayTime,
533    Sub,
534    SubAssign,
535    sub,
536    sub_assign,
537    wrapping_sub,
538    checked_sub
539);
540derive_arith!(
541    IntervalDayTime,
542    Mul,
543    MulAssign,
544    mul,
545    mul_assign,
546    wrapping_mul,
547    checked_mul
548);
549derive_arith!(
550    IntervalDayTime,
551    Div,
552    DivAssign,
553    div,
554    div_assign,
555    wrapping_div,
556    checked_div
557);
558derive_arith!(
559    IntervalDayTime,
560    Rem,
561    RemAssign,
562    rem,
563    rem_assign,
564    wrapping_rem,
565    checked_rem
566);