risingwave_common/types/
interval.rs

1// Copyright 2025 RisingWave Labs
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
15use std::cmp::Ordering;
16use std::error::Error;
17use std::fmt::{Display, Formatter};
18use std::hash::{Hash, Hasher};
19use std::io::{Cursor, Write};
20use std::ops::{Add, Neg, Sub};
21use std::sync::LazyLock;
22
23use anyhow::Context;
24use byteorder::{BigEndian, NetworkEndian, ReadBytesExt, WriteBytesExt};
25use bytes::BytesMut;
26use num_traits::{CheckedAdd, CheckedNeg, CheckedSub, Zero};
27use postgres_types::to_sql_checked;
28use regex::Regex;
29use risingwave_pb::data::PbInterval;
30use rust_decimal::prelude::Decimal;
31
32use super::*;
33
34/// Every interval can be represented by a `Interval`.
35///
36/// Note that the difference between Interval and Instant.
37/// For example, `5 yrs 1 month 25 days 23:22:57` is a interval (Can be interpreted by Interval Unit
38/// with months = 61, days = 25, usecs = (57 + 23 * 3600 + 22 * 60) * 1000000),
39/// `1970-01-01 04:05:06` is a Instant or Timestamp
40/// One month may contain 28/31 days. One day may contain 23/25 hours.
41/// This internals is learned from PG:
42/// <https://www.postgresql.org/docs/9.1/datatype-datetime.html#:~:text=field%20is%20negative.-,Internally,-interval%20values%20are>
43#[derive(Debug, Clone, Copy, Default)]
44pub struct Interval {
45    months: i32,
46    days: i32,
47    usecs: i64,
48}
49
50impl ZeroHeapSize for Interval {}
51
52const USECS_PER_SEC: i64 = 1_000_000;
53const USECS_PER_DAY: i64 = 86400 * USECS_PER_SEC;
54const USECS_PER_MONTH: i64 = 30 * USECS_PER_DAY;
55
56impl Interval {
57    /// Smallest interval value.
58    pub const MIN: Self = Self {
59        months: i32::MIN,
60        days: i32::MIN,
61        usecs: i64::MIN,
62    };
63    pub const USECS_PER_DAY: i64 = USECS_PER_DAY;
64    pub const USECS_PER_MONTH: i64 = USECS_PER_MONTH;
65    pub const USECS_PER_SEC: i64 = USECS_PER_SEC;
66
67    /// Creates a new `Interval` from the given number of months, days, and microseconds.
68    pub fn from_month_day_usec(months: i32, days: i32, usecs: i64) -> Self {
69        Interval {
70            months,
71            days,
72            usecs,
73        }
74    }
75
76    /// Returns the total number of whole months.
77    ///
78    /// Note the difference between `months` and `months_field`.
79    ///
80    /// We have: `months = years_field * 12 + months_field`
81    ///
82    /// # Example
83    /// ```
84    /// # use risingwave_common::types::Interval;
85    /// let interval: Interval = "5 yrs 1 month".parse().unwrap();
86    /// assert_eq!(interval.months(), 61);
87    /// assert_eq!(interval.months_field(), 1);
88    /// ```
89    pub fn months(&self) -> i32 {
90        self.months
91    }
92
93    /// Returns the number of days.
94    pub fn days(&self) -> i32 {
95        self.days
96    }
97
98    /// Returns the number of microseconds.
99    ///
100    /// Note the difference between `usecs` and `seconds_in_micros`.
101    ///
102    /// We have: `usecs = (hours_field * 3600 + minutes_field * 60) * 1_000_000 +
103    /// seconds_in_micros`.
104    pub fn usecs(&self) -> i64 {
105        self.usecs
106    }
107
108    /// Calculates the remaining number of microseconds.
109    /// range: `0..86_400_000_000`
110    ///
111    /// Note the difference between `usecs` and `usecs_of_day`.
112    /// ```
113    /// # use risingwave_common::types::Interval;
114    /// let interval: Interval = "-1:00:00".parse().unwrap();
115    /// assert_eq!(interval.usecs(), -1 * 60 * 60 * 1_000_000);
116    /// assert_eq!(interval.usecs_of_day(), 23 * 60 * 60 * 1_000_000);
117    /// ```
118    pub fn usecs_of_day(&self) -> u64 {
119        self.usecs.rem_euclid(USECS_PER_DAY) as u64
120    }
121
122    /// Returns the years field. range: unlimited
123    ///
124    /// # Example
125    /// ```
126    /// # use risingwave_common::types::Interval;
127    /// let interval: Interval = "2332 yrs 12 months".parse().unwrap();
128    /// assert_eq!(interval.years_field(), 2333);
129    /// ```
130    pub fn years_field(&self) -> i32 {
131        self.months / 12
132    }
133
134    /// Returns the months field. range: `-11..=11`
135    ///
136    /// # Example
137    /// ```
138    /// # use risingwave_common::types::Interval;
139    /// let interval: Interval = "15 months".parse().unwrap();
140    /// assert_eq!(interval.months_field(), 3);
141    ///
142    /// let interval: Interval = "-15 months".parse().unwrap();
143    /// assert_eq!(interval.months_field(), -3);
144    /// ```
145    pub fn months_field(&self) -> i32 {
146        self.months % 12
147    }
148
149    /// Returns the days field. range: unlimited
150    ///
151    /// # Example
152    /// ```
153    /// # use risingwave_common::types::Interval;
154    /// let interval: Interval = "1 months 100 days 25:00:00".parse().unwrap();
155    /// assert_eq!(interval.days_field(), 100);
156    /// ```
157    pub fn days_field(&self) -> i32 {
158        self.days
159    }
160
161    /// Returns the hours field. range: unlimited
162    ///
163    /// # Example
164    /// ```
165    /// # use risingwave_common::types::Interval;
166    /// let interval: Interval = "25:00:00".parse().unwrap();
167    /// assert_eq!(interval.hours_field(), 25);
168    ///
169    /// let interval: Interval = "-25:00:00".parse().unwrap();
170    /// assert_eq!(interval.hours_field(), -25);
171    /// ```
172    pub fn hours_field(&self) -> i64 {
173        self.usecs / USECS_PER_SEC / 3600
174    }
175
176    /// Returns the minutes field. range: `-59..=-59`
177    ///
178    /// # Example
179    /// ```
180    /// # use risingwave_common::types::Interval;
181    /// let interval: Interval = "00:20:00".parse().unwrap();
182    /// assert_eq!(interval.minutes_field(), 20);
183    ///
184    /// let interval: Interval = "-00:20:00".parse().unwrap();
185    /// assert_eq!(interval.minutes_field(), -20);
186    /// ```
187    pub fn minutes_field(&self) -> i32 {
188        (self.usecs / USECS_PER_SEC / 60 % 60) as i32
189    }
190
191    /// Returns the seconds field, including fractional parts, in microseconds.
192    /// range: `-59_999_999..=59_999_999`
193    ///
194    /// # Example
195    /// ```
196    /// # use risingwave_common::types::Interval;
197    /// let interval: Interval = "01:02:03.45678".parse().unwrap();
198    /// assert_eq!(interval.seconds_in_micros(), 3_456_780);
199    ///
200    /// let interval: Interval = "-01:02:03.45678".parse().unwrap();
201    /// assert_eq!(interval.seconds_in_micros(), -3_456_780);
202    /// ```
203    pub fn seconds_in_micros(&self) -> i32 {
204        (self.usecs % (USECS_PER_SEC * 60)) as i32
205    }
206
207    /// Returns the total number of microseconds, as defined by PostgreSQL `extract`.
208    ///
209    /// Note this value is not used by interval ordering (`IntervalCmpValue`) and is not consistent
210    /// with it.
211    pub fn epoch_in_micros(&self) -> i128 {
212        // https://github.com/postgres/postgres/blob/REL_15_2/src/backend/utils/adt/timestamp.c#L5304
213
214        const DAYS_PER_YEAR_X4: i32 = 365 * 4 + 1;
215        const DAYS_PER_MONTH: i32 = 30;
216        const SECS_PER_DAY: i32 = 86400;
217        const MONTHS_PER_YEAR: i32 = 12;
218
219        // To do this calculation in integer arithmetic even though
220        // DAYS_PER_YEAR is fractional, multiply everything by 4 and then
221        // divide by 4 again at the end.  This relies on DAYS_PER_YEAR
222        // being a multiple of 0.25 and on SECS_PER_DAY being a multiple
223        // of 4.
224        let secs_from_day_month = ((DAYS_PER_YEAR_X4 as i64)
225            * (self.months / MONTHS_PER_YEAR) as i64
226            + (4 * DAYS_PER_MONTH as i64) * (self.months % MONTHS_PER_YEAR) as i64
227            + 4 * self.days as i64)
228            * (SECS_PER_DAY / 4) as i64;
229
230        secs_from_day_month as i128 * USECS_PER_SEC as i128 + self.usecs as i128
231    }
232
233    pub fn from_protobuf(cursor: &mut Cursor<&[u8]>) -> ArrayResult<Interval> {
234        let mut read = || {
235            let months = cursor.read_i32::<BigEndian>()?;
236            let days = cursor.read_i32::<BigEndian>()?;
237            let usecs = cursor.read_i64::<BigEndian>()?;
238
239            Ok::<_, std::io::Error>(Interval::from_month_day_usec(months, days, usecs))
240        };
241
242        Ok(read().context("failed to read Interval from buffer")?)
243    }
244
245    pub fn to_protobuf<T: Write>(self, output: &mut T) -> ArrayResult<usize> {
246        output.write_i32::<BigEndian>(self.months)?;
247        output.write_i32::<BigEndian>(self.days)?;
248        output.write_i64::<BigEndian>(self.usecs)?;
249        Ok(16)
250    }
251
252    /// Multiple [`Interval`] by an integer with overflow check.
253    pub fn checked_mul_int<I>(&self, rhs: I) -> Option<Self>
254    where
255        I: TryInto<i32>,
256    {
257        let rhs = rhs.try_into().ok()?;
258        let months = self.months.checked_mul(rhs)?;
259        let days = self.days.checked_mul(rhs)?;
260        let usecs = self.usecs.checked_mul(rhs as i64)?;
261
262        Some(Interval {
263            months,
264            days,
265            usecs,
266        })
267    }
268
269    /// Internal utility used by [`Self::mul_float`] and [`Self::div_float`] to adjust fractional
270    /// units. Not intended as general constructor.
271    fn from_floats(months: f64, days: f64, usecs: f64) -> Option<Self> {
272        // TSROUND in include/datatype/timestamp.h
273        // round eagerly at usecs precision because floats are imprecise
274        let months_round_usecs = |months: f64| {
275            (months * (USECS_PER_MONTH as f64)).round_ties_even() / (USECS_PER_MONTH as f64)
276        };
277
278        let days_round_usecs =
279            |days: f64| (days * (USECS_PER_DAY as f64)).round_ties_even() / (USECS_PER_DAY as f64);
280
281        let trunc_fract = |num: f64| (num.trunc(), num.fract());
282
283        // Handle months
284        let (months, months_fract) = trunc_fract(months_round_usecs(months));
285        if months.is_nan() || months < i32::MIN.into() || months > i32::MAX.into() {
286            return None;
287        }
288        let months = months as i32;
289        let (leftover_days, leftover_days_fract) =
290            trunc_fract(days_round_usecs(months_fract * 30.));
291
292        // Handle days
293        let (days, days_fract) = trunc_fract(days_round_usecs(days));
294        if days.is_nan() || days < i32::MIN.into() || days > i32::MAX.into() {
295            return None;
296        }
297        // Note that PostgreSQL split the integer part and fractional part individually before
298        // adding `leftover_days`. This makes a difference for mixed sign interval.
299        // For example in `interval '3 mons -3 days' / 2`
300        // * `leftover_days` is `15`
301        // * `days` from input is `-1.5`
302        // If we add first, we get `13.5` which is `13 days 12:00:00`;
303        // If we split first, we get `14` and `-0.5`, which ends up as `14 days -12:00:00`.
304        let (days_fract_whole, days_fract) =
305            trunc_fract(days_round_usecs(days_fract + leftover_days_fract));
306        let days = (days as i32)
307            .checked_add(leftover_days as i32)?
308            .checked_add(days_fract_whole as i32)?;
309        let leftover_usecs = days_fract * (USECS_PER_DAY as f64);
310
311        // Handle usecs
312        let result_usecs = usecs + leftover_usecs;
313        let usecs = result_usecs.round_ties_even();
314        if usecs.is_nan() || usecs < (i64::MIN as f64) || usecs > (i64::MAX as f64) {
315            return None;
316        }
317        let usecs = usecs as i64;
318
319        Some(Self {
320            months,
321            days,
322            usecs,
323        })
324    }
325
326    /// Divides [`Interval`] by an integer/float with zero check.
327    pub fn div_float<I>(&self, rhs: I) -> Option<Self>
328    where
329        I: TryInto<F64>,
330    {
331        let rhs = rhs.try_into().ok()?;
332        let rhs = rhs.0;
333
334        if rhs == 0.0 {
335            return None;
336        }
337
338        Self::from_floats(
339            self.months as f64 / rhs,
340            self.days as f64 / rhs,
341            self.usecs as f64 / rhs,
342        )
343    }
344
345    /// times [`Interval`] with an integer/float.
346    pub fn mul_float<I>(&self, rhs: I) -> Option<Self>
347    where
348        I: TryInto<F64>,
349    {
350        let rhs = rhs.try_into().ok()?;
351        let rhs = rhs.0;
352
353        Self::from_floats(
354            self.months as f64 * rhs,
355            self.days as f64 * rhs,
356            self.usecs as f64 * rhs,
357        )
358    }
359
360    /// Performs an exact division, returns [`None`] if for any unit, lhs % rhs != 0.
361    pub fn exact_div(&self, rhs: &Self) -> Option<i64> {
362        let mut res = None;
363        let mut check_unit = |l: i64, r: i64| {
364            if l == 0 && r == 0 {
365                return Some(());
366            }
367            if l != 0 && r == 0 {
368                return None;
369            }
370            if l % r != 0 {
371                return None;
372            }
373            let new_res = l / r;
374            if let Some(old_res) = res {
375                if old_res != new_res {
376                    return None;
377                }
378            } else {
379                res = Some(new_res);
380            }
381
382            Some(())
383        };
384
385        check_unit(self.months as i64, rhs.months as i64)?;
386        check_unit(self.days as i64, rhs.days as i64)?;
387        check_unit(self.usecs, rhs.usecs)?;
388
389        res
390    }
391
392    /// Checks if [`Interval`] is positive.
393    pub fn is_positive(&self) -> bool {
394        self > &Self::from_month_day_usec(0, 0, 0)
395    }
396
397    /// Checks if all fields of [`Interval`] are all non-negative.
398    pub fn is_never_negative(&self) -> bool {
399        self.months >= 0 && self.days >= 0 && self.usecs >= 0
400    }
401
402    /// Truncate the interval to the precision of milliseconds.
403    ///
404    /// # Example
405    /// ```
406    /// # use risingwave_common::types::Interval;
407    /// let interval: Interval = "5 years 1 mon 25 days 23:22:57.123".parse().unwrap();
408    /// assert_eq!(
409    ///     interval.truncate_millis().to_string(),
410    ///     "5 years 1 mon 25 days 23:22:57.123"
411    /// );
412    /// ```
413    pub const fn truncate_millis(self) -> Self {
414        Interval {
415            months: self.months,
416            days: self.days,
417            usecs: self.usecs / 1000 * 1000,
418        }
419    }
420
421    /// Truncate the interval to the precision of seconds.
422    ///
423    /// # Example
424    /// ```
425    /// # use risingwave_common::types::Interval;
426    /// let interval: Interval = "5 years 1 mon 25 days 23:22:57.123".parse().unwrap();
427    /// assert_eq!(
428    ///     interval.truncate_second().to_string(),
429    ///     "5 years 1 mon 25 days 23:22:57"
430    /// );
431    /// ```
432    pub const fn truncate_second(self) -> Self {
433        Interval {
434            months: self.months,
435            days: self.days,
436            usecs: self.usecs / USECS_PER_SEC * USECS_PER_SEC,
437        }
438    }
439
440    /// Truncate the interval to the precision of minutes.
441    ///
442    /// # Example
443    /// ```
444    /// # use risingwave_common::types::Interval;
445    /// let interval: Interval = "5 years 1 mon 25 days 23:22:57.123".parse().unwrap();
446    /// assert_eq!(
447    ///     interval.truncate_minute().to_string(),
448    ///     "5 years 1 mon 25 days 23:22:00"
449    /// );
450    /// ```
451    pub const fn truncate_minute(self) -> Self {
452        Interval {
453            months: self.months,
454            days: self.days,
455            usecs: self.usecs / USECS_PER_SEC / 60 * USECS_PER_SEC * 60,
456        }
457    }
458
459    /// Truncate the interval to the precision of hours.
460    ///
461    /// # Example
462    /// ```
463    /// # use risingwave_common::types::Interval;
464    /// let interval: Interval = "5 years 1 mon 25 days 23:22:57.123".parse().unwrap();
465    /// assert_eq!(
466    ///     interval.truncate_hour().to_string(),
467    ///     "5 years 1 mon 25 days 23:00:00"
468    /// );
469    /// ```
470    pub const fn truncate_hour(self) -> Self {
471        Interval {
472            months: self.months,
473            days: self.days,
474            usecs: self.usecs / USECS_PER_SEC / 60 / 60 * USECS_PER_SEC * 60 * 60,
475        }
476    }
477
478    /// Truncate the interval to the precision of days.
479    ///
480    /// # Example
481    /// ```
482    /// # use risingwave_common::types::Interval;
483    /// let interval: Interval = "5 years 1 mon 25 days 23:22:57.123".parse().unwrap();
484    /// assert_eq!(interval.truncate_day().to_string(), "5 years 1 mon 25 days");
485    /// ```
486    pub const fn truncate_day(self) -> Self {
487        Interval {
488            months: self.months,
489            days: self.days,
490            usecs: 0,
491        }
492    }
493
494    /// Truncate the interval to the precision of months.
495    ///
496    /// # Example
497    /// ```
498    /// # use risingwave_common::types::Interval;
499    /// let interval: Interval = "5 years 1 mon 25 days 23:22:57.123".parse().unwrap();
500    /// assert_eq!(interval.truncate_month().to_string(), "5 years 1 mon");
501    /// ```
502    pub const fn truncate_month(self) -> Self {
503        Interval {
504            months: self.months,
505            days: 0,
506            usecs: 0,
507        }
508    }
509
510    /// Truncate the interval to the precision of quarters.
511    ///
512    /// # Example
513    /// ```
514    /// # use risingwave_common::types::Interval;
515    /// let interval: Interval = "5 years 1 mon 25 days 23:22:57.123".parse().unwrap();
516    /// assert_eq!(interval.truncate_quarter().to_string(), "5 years");
517    /// ```
518    pub const fn truncate_quarter(self) -> Self {
519        Interval {
520            months: self.months / 3 * 3,
521            days: 0,
522            usecs: 0,
523        }
524    }
525
526    /// Truncate the interval to the precision of years.
527    ///
528    /// # Example
529    /// ```
530    /// # use risingwave_common::types::Interval;
531    /// let interval: Interval = "5 years 1 mon 25 days 23:22:57.123".parse().unwrap();
532    /// assert_eq!(interval.truncate_year().to_string(), "5 years");
533    /// ```
534    pub const fn truncate_year(self) -> Self {
535        Interval {
536            months: self.months / 12 * 12,
537            days: 0,
538            usecs: 0,
539        }
540    }
541
542    /// Truncate the interval to the precision of decades.
543    ///
544    /// # Example
545    /// ```
546    /// # use risingwave_common::types::Interval;
547    /// let interval: Interval = "15 years 1 mon 25 days 23:22:57.123".parse().unwrap();
548    /// assert_eq!(interval.truncate_decade().to_string(), "10 years");
549    /// ```
550    pub const fn truncate_decade(self) -> Self {
551        Interval {
552            months: self.months / 12 / 10 * 12 * 10,
553            days: 0,
554            usecs: 0,
555        }
556    }
557
558    /// Truncate the interval to the precision of centuries.
559    ///
560    /// # Example
561    /// ```
562    /// # use risingwave_common::types::Interval;
563    /// let interval: Interval = "115 years 1 mon 25 days 23:22:57.123".parse().unwrap();
564    /// assert_eq!(interval.truncate_century().to_string(), "100 years");
565    /// ```
566    pub const fn truncate_century(self) -> Self {
567        Interval {
568            months: self.months / 12 / 100 * 12 * 100,
569            days: 0,
570            usecs: 0,
571        }
572    }
573
574    /// Truncate the interval to the precision of millenniums.
575    ///
576    /// # Example
577    /// ```
578    /// # use risingwave_common::types::Interval;
579    /// let interval: Interval = "1115 years 1 mon 25 days 23:22:57.123".parse().unwrap();
580    /// assert_eq!(interval.truncate_millennium().to_string(), "1000 years");
581    /// ```
582    pub const fn truncate_millennium(self) -> Self {
583        Interval {
584            months: self.months / 12 / 1000 * 12 * 1000,
585            days: 0,
586            usecs: 0,
587        }
588    }
589
590    // Assuming 1 day = 24 hours, adjust `abs(usecs)` to be less than 24 hours, and has the same
591    // sign with `days`.
592    pub fn justify_hour(self) -> Option<Self> {
593        let whole_day = (self.usecs / USECS_PER_DAY) as i32;
594        let mut usecs = self.usecs % USECS_PER_DAY;
595        let mut days = self.days.checked_add(whole_day)?;
596        if days > 0 && usecs < 0 {
597            usecs += USECS_PER_DAY;
598            days -= 1;
599        } else if days < 0 && usecs > 0 {
600            usecs -= USECS_PER_DAY;
601            days += 1;
602        }
603        Some(Self::from_month_day_usec(self.months, days, usecs))
604    }
605}
606
607/// A separate mod so that `use types::*` or `use interval::*` does not `use IntervalTestExt` by
608/// accident.
609pub mod test_utils {
610    use super::*;
611
612    /// These constructors may panic when value out of bound. Only use in tests with known input.
613    pub trait IntervalTestExt {
614        fn from_ymd(year: i32, month: i32, days: i32) -> Self;
615        fn from_month(months: i32) -> Self;
616        fn from_days(days: i32) -> Self;
617        fn from_millis(ms: i64) -> Self;
618        fn from_minutes(minutes: i64) -> Self;
619    }
620
621    impl IntervalTestExt for Interval {
622        fn from_ymd(year: i32, month: i32, days: i32) -> Self {
623            let months = year * 12 + month;
624            let usecs = 0;
625            Interval {
626                months,
627                days,
628                usecs,
629            }
630        }
631
632        fn from_month(months: i32) -> Self {
633            Interval {
634                months,
635                ..Default::default()
636            }
637        }
638
639        fn from_days(days: i32) -> Self {
640            Self {
641                days,
642                ..Default::default()
643            }
644        }
645
646        fn from_millis(ms: i64) -> Self {
647            Self {
648                usecs: ms * 1000,
649                ..Default::default()
650            }
651        }
652
653        fn from_minutes(minutes: i64) -> Self {
654            Self {
655                usecs: USECS_PER_SEC * 60 * minutes,
656                ..Default::default()
657            }
658        }
659    }
660}
661
662/// Wrapper so that `Debug for IntervalDisplay` would use the concise format of `Display for
663/// Interval`.
664#[derive(Clone, Copy)]
665pub struct IntervalDisplay<'a> {
666    pub core: &'a Interval,
667}
668
669impl std::fmt::Display for IntervalDisplay<'_> {
670    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
671        (self as &dyn std::fmt::Debug).fmt(f)
672    }
673}
674
675impl std::fmt::Debug for IntervalDisplay<'_> {
676    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
677        write!(f, "{}", self.core)
678    }
679}
680
681/// <https://github.com/postgres/postgres/blob/REL_15_2/src/backend/utils/adt/timestamp.c#L2384>
682///
683/// Do NOT make this `pub` as the assumption of 1 month = 30 days and 1 day = 24 hours does not
684/// always hold in other places.
685///
686/// Given this equality definition in PostgreSQL, different interval values can be considered equal,
687/// forming equivalence classes. For example:
688/// * '-45 days' == '-1 months -15 days' == '1 months -75 days'
689/// * '-2147483646 months -210 days' == '-2147483648 months -150 days' == '-2075900865 months
690///   -2147483640 days'
691///
692/// To hash and memcompare them, we need to pick a representative for each equivalence class, and
693/// then map all values from the same equivalence class to the same representative. There are 3
694/// choices (may be more):
695/// (a) an `i128` of total `usecs`, with `months` and `days` transformed into `usecs`;
696/// (b) the justified interval, as defined by PostgreSQL `justify_interval`;
697/// (c) the alternate representative interval that maximizes `abs` of smaller units;
698///
699/// For simplicity we will assume there are only `months` and `days` and ignore `usecs` below.
700///
701/// The justified interval is more human friendly. It requires all units to have the same sign, and
702/// that `0 <= abs(usecs) < USECS_PER_DAY && 0 <= abs(days) < 30`. However, it may overflow. In the
703/// 2 examples above, '-1 months -15 days' is the justified interval of the first equivalence class,
704/// but there is no justified interval in the second one. It would be '-2147483653 months' but this
705/// overflows `i32`. A lot of bits are wasted in a justified interval because `days` is using
706/// `i32` for `-29..=29` only.
707///
708/// The alternate representative interval aims to avoid this overflow. It still requires all units
709/// to have the same sign, but maximizes `abs` of smaller unit rather than limit it to `29`. The
710/// alternate representative of the 2 examples above are '-45 days' and '-2075900865 months
711/// -2147483640 days'. The alternate representative interval always exists.
712///
713/// For serialize, we could use any of 3, with a workaround of using (i33, i6, i38) rather than
714/// (i32, i32, i64) to avoid overflow of the justified interval. We chose the `usecs: i128` option.
715///
716/// For deserialize, we attempt justified interval first and fallback to alternate. This could give
717/// human friendly results in common cases and still guarantee no overflow, as long as the bytes
718/// were serialized properly.
719///
720/// Note the alternate representative interval does not exist in PostgreSQL as they do not
721/// deserialize from `IntervalCmpValue`.
722#[derive(PartialEq, Eq, Hash, PartialOrd, Ord)]
723struct IntervalCmpValue(i128);
724
725impl From<Interval> for IntervalCmpValue {
726    fn from(value: Interval) -> Self {
727        let days = (value.days as i64) + 30i64 * (value.months as i64);
728        let usecs = (value.usecs as i128) + (USECS_PER_DAY as i128) * (days as i128);
729        Self(usecs)
730    }
731}
732
733impl Ord for Interval {
734    fn cmp(&self, other: &Self) -> Ordering {
735        IntervalCmpValue::from(*self).cmp(&(*other).into())
736    }
737}
738
739impl PartialOrd for Interval {
740    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
741        Some(self.cmp(other))
742    }
743}
744
745impl PartialEq for Interval {
746    fn eq(&self, other: &Self) -> bool {
747        self.cmp(other).is_eq()
748    }
749}
750
751impl Eq for Interval {}
752
753impl Hash for Interval {
754    fn hash<H: Hasher>(&self, state: &mut H) {
755        IntervalCmpValue::from(*self).hash(state);
756    }
757}
758
759/// Loss of information during the process due to `IntervalCmpValue`. Only intended for
760/// memcomparable encoding.
761impl Serialize for Interval {
762    fn serialize<S>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error>
763    where
764        S: serde::Serializer,
765    {
766        let cmp_value = IntervalCmpValue::from(*self);
767        cmp_value.0.serialize(serializer)
768    }
769}
770
771impl IntervalCmpValue {
772    /// Recover the justified interval from this equivalence class, if it exists.
773    fn as_justified(&self) -> Option<Interval> {
774        let usecs = (self.0 % (USECS_PER_DAY as i128)) as i64;
775        let remaining_days = self.0 / (USECS_PER_DAY as i128);
776        let days = (remaining_days % 30) as i32;
777        let months = (remaining_days / 30).try_into().ok()?;
778        Some(Interval::from_month_day_usec(months, days, usecs))
779    }
780
781    /// Recover the alternate representative interval from this equivalence class.
782    /// It always exists unless the encoding is invalid. See [`IntervalCmpValue`] for details.
783    fn as_alternate(&self) -> Option<Interval> {
784        match self.0.cmp(&0) {
785            Ordering::Equal => Some(Interval::from_month_day_usec(0, 0, 0)),
786            Ordering::Greater => {
787                let remaining_usecs = self.0;
788                let mut usecs = (remaining_usecs % (USECS_PER_DAY as i128)) as i64;
789                let mut remaining_days = remaining_usecs / (USECS_PER_DAY as i128);
790                // `usecs` is now smaller than `USECS_PER_DAY` but has 64 bits.
791                // How much more days (multiples of `USECS_PER_DAY`) can it hold before overflowing
792                // i64::MAX?
793                // It should also not exceed `remaining_days` to bring it from positive to negative.
794                // When `remaining_days` is larger than `i64::MAX`, just limit by `i64::MAX` (no-op)
795                let extra_days = ((i64::MAX - usecs) / USECS_PER_DAY)
796                    .min(remaining_days.try_into().unwrap_or(i64::MAX));
797                // The lhs of `min` ensures `extra_days * USECS_PER_DAY <= i64::MAX - usecs`
798                usecs += extra_days * USECS_PER_DAY;
799                // The rhs of `min` ensures `extra_days <= remaining_days`
800                remaining_days -= extra_days as i128;
801
802                // Similar above
803                let mut days = (remaining_days % 30) as i32;
804                let mut remaining_months = remaining_days / 30;
805                let extra_months =
806                    ((i32::MAX - days) / 30).min(remaining_months.try_into().unwrap_or(i32::MAX));
807                days += extra_months * 30;
808                remaining_months -= extra_months as i128;
809
810                let months = remaining_months.try_into().ok()?;
811                Some(Interval::from_month_day_usec(months, days, usecs))
812            }
813            Ordering::Less => {
814                let remaining_usecs = self.0;
815                let mut usecs = (remaining_usecs % (USECS_PER_DAY as i128)) as i64;
816                let mut remaining_days = remaining_usecs / (USECS_PER_DAY as i128);
817                // The negative case. Borrow negative `extra_days` to make `usecs` as close to
818                // `i64::MIN` as possible.
819                let extra_days = ((i64::MIN - usecs) / USECS_PER_DAY)
820                    .max(remaining_days.try_into().unwrap_or(i64::MIN));
821                usecs += extra_days * USECS_PER_DAY;
822                remaining_days -= extra_days as i128;
823
824                let mut days = (remaining_days % 30) as i32;
825                let mut remaining_months = remaining_days / 30;
826                let extra_months =
827                    ((i32::MIN - days) / 30).max(remaining_months.try_into().unwrap_or(i32::MIN));
828                days += extra_months * 30;
829                remaining_months -= extra_months as i128;
830
831                let months = remaining_months.try_into().ok()?;
832                Some(Interval::from_month_day_usec(months, days, usecs))
833            }
834        }
835    }
836}
837
838impl<'de> Deserialize<'de> for Interval {
839    fn deserialize<D>(deserializer: D) -> std::result::Result<Self, D::Error>
840    where
841        D: serde::Deserializer<'de>,
842    {
843        let cmp_value = IntervalCmpValue(i128::deserialize(deserializer)?);
844        let interval = cmp_value
845            .as_justified()
846            .or_else(|| cmp_value.as_alternate());
847        interval.ok_or_else(|| {
848            use serde::de::Error as _;
849            D::Error::custom("memcomparable deserialize interval overflow")
850        })
851    }
852}
853
854impl crate::hash::HashKeySer<'_> for Interval {
855    fn serialize_into(self, mut buf: impl BufMut) {
856        let cmp_value = IntervalCmpValue::from(self);
857        let b = cmp_value.0.to_ne_bytes();
858        buf.put_slice(&b);
859    }
860
861    fn exact_size() -> Option<usize> {
862        Some(16)
863    }
864}
865
866impl crate::hash::HashKeyDe for Interval {
867    fn deserialize(_data_type: &DataType, mut buf: impl Buf) -> Self {
868        let value = buf.get_i128_ne();
869        let cmp_value = IntervalCmpValue(value);
870        cmp_value
871            .as_justified()
872            .or_else(|| cmp_value.as_alternate())
873            .expect("HashKey deserialize interval overflow")
874    }
875}
876
877/// Duplicated logic only used by `HopWindow`. See #8452.
878#[expect(clippy::from_over_into)]
879impl Into<PbInterval> for Interval {
880    fn into(self) -> PbInterval {
881        PbInterval {
882            months: self.months,
883            days: self.days,
884            usecs: self.usecs,
885        }
886    }
887}
888
889impl From<&'_ PbInterval> for Interval {
890    fn from(p: &'_ PbInterval) -> Self {
891        Self {
892            months: p.months,
893            days: p.days,
894            usecs: p.usecs,
895        }
896    }
897}
898
899impl From<Time> for Interval {
900    fn from(time: Time) -> Self {
901        let mut usecs: i64 = (time.0.num_seconds_from_midnight() as i64) * USECS_PER_SEC;
902        usecs += (time.0.nanosecond() / 1000) as i64;
903        Self {
904            months: 0,
905            days: 0,
906            usecs,
907        }
908    }
909}
910
911impl Add for Interval {
912    type Output = Self;
913
914    fn add(self, rhs: Self) -> Self {
915        let months = self.months + rhs.months;
916        let days = self.days + rhs.days;
917        let usecs = self.usecs + rhs.usecs;
918        Interval {
919            months,
920            days,
921            usecs,
922        }
923    }
924}
925
926impl CheckedNeg for Interval {
927    fn checked_neg(&self) -> Option<Self> {
928        let months = self.months.checked_neg()?;
929        let days = self.days.checked_neg()?;
930        let usecs = self.usecs.checked_neg()?;
931        Some(Interval {
932            months,
933            days,
934            usecs,
935        })
936    }
937}
938
939impl CheckedAdd for Interval {
940    fn checked_add(&self, other: &Self) -> Option<Self> {
941        let months = self.months.checked_add(other.months)?;
942        let days = self.days.checked_add(other.days)?;
943        let usecs = self.usecs.checked_add(other.usecs)?;
944        Some(Interval {
945            months,
946            days,
947            usecs,
948        })
949    }
950}
951
952impl Sub for Interval {
953    type Output = Self;
954
955    fn sub(self, rhs: Self) -> Self {
956        let months = self.months - rhs.months;
957        let days = self.days - rhs.days;
958        let usecs = self.usecs - rhs.usecs;
959        Interval {
960            months,
961            days,
962            usecs,
963        }
964    }
965}
966
967impl CheckedSub for Interval {
968    fn checked_sub(&self, other: &Self) -> Option<Self> {
969        let months = self.months.checked_sub(other.months)?;
970        let days = self.days.checked_sub(other.days)?;
971        let usecs = self.usecs.checked_sub(other.usecs)?;
972        Some(Interval {
973            months,
974            days,
975            usecs,
976        })
977    }
978}
979
980impl Zero for Interval {
981    fn zero() -> Self {
982        Self::from_month_day_usec(0, 0, 0)
983    }
984
985    fn is_zero(&self) -> bool {
986        self.months == 0 && self.days == 0 && self.usecs == 0
987    }
988}
989
990impl Neg for Interval {
991    type Output = Self;
992
993    fn neg(self) -> Self {
994        Self {
995            months: -self.months,
996            days: -self.days,
997            usecs: -self.usecs,
998        }
999    }
1000}
1001
1002impl ToText for crate::types::Interval {
1003    fn write<W: std::fmt::Write>(&self, f: &mut W) -> std::fmt::Result {
1004        write!(f, "{self}")
1005    }
1006
1007    fn write_with_type<W: std::fmt::Write>(&self, ty: &DataType, f: &mut W) -> std::fmt::Result {
1008        match ty {
1009            DataType::Interval => self.write(f),
1010            _ => unreachable!(),
1011        }
1012    }
1013}
1014
1015/// Error type for parsing an [`Interval`].
1016#[derive(thiserror::Error, Debug, thiserror_ext::Construct)]
1017pub enum IntervalParseError {
1018    #[error("Invalid interval: {0}")]
1019    Invalid(String),
1020
1021    #[error(
1022        "Invalid interval: {0}, expected format P<years>Y<months>M<days>DT<hours>H<minutes>M<seconds>S"
1023    )]
1024    InvalidIso8601(String),
1025
1026    #[error("Invalid unit: {0}")]
1027    InvalidUnit(String),
1028
1029    #[error("{0}")]
1030    Uncategorized(String),
1031}
1032
1033type ParseResult<T> = std::result::Result<T, IntervalParseError>;
1034
1035impl Interval {
1036    pub fn as_iso_8601(&self) -> String {
1037        // ISO pattern - PnYnMnDTnHnMnS
1038        let years = self.months / 12;
1039        let months = self.months % 12;
1040        let days = self.days;
1041        let secs_fract = (self.usecs % USECS_PER_SEC).abs();
1042        let total_secs = (self.usecs / USECS_PER_SEC).abs();
1043        let hours = total_secs / 3600;
1044        let minutes = (total_secs / 60) % 60;
1045        let seconds = total_secs % 60;
1046        let mut buf = [0u8; 7];
1047        let fract_str = if secs_fract != 0 {
1048            write!(buf.as_mut_slice(), ".{:06}", secs_fract).unwrap();
1049            std::str::from_utf8(&buf).unwrap().trim_end_matches('0')
1050        } else {
1051            ""
1052        };
1053        format!("P{years}Y{months}M{days}DT{hours}H{minutes}M{seconds}{fract_str}S")
1054    }
1055
1056    /// Converts str to interval
1057    ///
1058    /// The input str must have the following format:
1059    /// `P<years>Y<months>M<days>DT<hours>H<minutes>M<seconds>S`
1060    ///
1061    /// Example
1062    /// - P1Y2M3DT4H5M6.78S
1063    pub fn from_iso_8601(s: &str) -> ParseResult<Self> {
1064        // ISO pattern - PnYnMnDTnHnMnS
1065        static ISO_8601_REGEX: LazyLock<Regex> = LazyLock::new(|| {
1066            Regex::new(r"^P([0-9]+)Y([0-9]+)M([0-9]+)DT([0-9]+)H([0-9]+)M([0-9]+(?:\.[0-9]+)?)S$")
1067                .unwrap()
1068        });
1069        // wrap into a closure to simplify error handling
1070        let f = || {
1071            let caps = ISO_8601_REGEX.captures(s)?;
1072            let years: i32 = caps[1].parse().ok()?;
1073            let months: i32 = caps[2].parse().ok()?;
1074            let days = caps[3].parse().ok()?;
1075            let hours: i64 = caps[4].parse().ok()?;
1076            let minutes: i64 = caps[5].parse().ok()?;
1077            // usecs = sec * 1000000, use decimal to be exact
1078            let usecs: i64 = (Decimal::from_str_exact(&caps[6])
1079                .ok()?
1080                .checked_mul(Decimal::from_str_exact("1000000").unwrap()))?
1081            .try_into()
1082            .ok()?;
1083            Some(Interval::from_month_day_usec(
1084                // months = years * 12 + months
1085                years.checked_mul(12)?.checked_add(months)?,
1086                days,
1087                // usecs = (hours * 3600 + minutes * 60) * 1000000 + usecs
1088                (hours
1089                    .checked_mul(3_600)?
1090                    .checked_add(minutes.checked_mul(60)?))?
1091                .checked_mul(USECS_PER_SEC)?
1092                .checked_add(usecs)?,
1093            ))
1094        };
1095        f().ok_or_else(|| IntervalParseError::invalid_iso8601(s))
1096    }
1097}
1098
1099impl Display for Interval {
1100    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
1101        let years = self.months / 12;
1102        let months = self.months % 12;
1103        let days = self.days;
1104        let mut space = false;
1105        let mut following_neg = false;
1106        let mut write_i32 = |arg: i32, unit: &str| -> std::fmt::Result {
1107            if arg == 0 {
1108                return Ok(());
1109            }
1110            if space {
1111                write!(f, " ")?;
1112            }
1113            if following_neg && arg > 0 {
1114                write!(f, "+")?;
1115            }
1116            write!(f, "{arg} {unit}")?;
1117            if arg != 1 {
1118                write!(f, "s")?;
1119            }
1120            space = true;
1121            following_neg = arg < 0;
1122            Ok(())
1123        };
1124        write_i32(years, "year")?;
1125        write_i32(months, "mon")?;
1126        write_i32(days, "day")?;
1127        if self.usecs != 0 || self.months == 0 && self.days == 0 {
1128            // `abs` on `self.usecs == i64::MIN` would overflow, so we divide first then abs
1129            let secs_fract = (self.usecs % USECS_PER_SEC).abs();
1130            let total_secs = (self.usecs / USECS_PER_SEC).abs();
1131            let hours = total_secs / 3600;
1132            let minutes = (total_secs / 60) % 60;
1133            let seconds = total_secs % 60;
1134
1135            if space {
1136                write!(f, " ")?;
1137            }
1138            if following_neg && self.usecs > 0 {
1139                write!(f, "+")?;
1140            } else if self.usecs < 0 {
1141                write!(f, "-")?;
1142            }
1143            write!(f, "{hours:0>2}:{minutes:0>2}:{seconds:0>2}")?;
1144            if secs_fract != 0 {
1145                let mut buf = [0u8; 7];
1146                write!(buf.as_mut_slice(), ".{:06}", secs_fract).unwrap();
1147                write!(
1148                    f,
1149                    "{}",
1150                    std::str::from_utf8(&buf).unwrap().trim_end_matches('0')
1151                )?;
1152            }
1153        }
1154        Ok(())
1155    }
1156}
1157
1158impl ToSql for Interval {
1159    to_sql_checked!();
1160
1161    fn to_sql(
1162        &self,
1163        _: &Type,
1164        out: &mut BytesMut,
1165    ) -> std::result::Result<IsNull, Box<dyn Error + 'static + Send + Sync>> {
1166        // refer: https://github.com/postgres/postgres/blob/517bf2d91/src/backend/utils/adt/timestamp.c#L1008
1167        out.put_i64(self.usecs);
1168        out.put_i32(self.days);
1169        out.put_i32(self.months);
1170        Ok(IsNull::No)
1171    }
1172
1173    fn accepts(ty: &Type) -> bool {
1174        matches!(*ty, Type::INTERVAL)
1175    }
1176}
1177
1178impl<'a> FromSql<'a> for Interval {
1179    fn from_sql(
1180        _: &Type,
1181        mut raw: &'a [u8],
1182    ) -> std::result::Result<Interval, Box<dyn Error + Sync + Send>> {
1183        let usecs = raw.read_i64::<NetworkEndian>()?;
1184        let days = raw.read_i32::<NetworkEndian>()?;
1185        let months = raw.read_i32::<NetworkEndian>()?;
1186        Ok(Interval::from_month_day_usec(months, days, usecs))
1187    }
1188
1189    fn accepts(ty: &Type) -> bool {
1190        matches!(*ty, Type::INTERVAL)
1191    }
1192}
1193
1194#[derive(Debug, Clone, PartialEq, Eq, Hash)]
1195pub enum DateTimeField {
1196    Year,
1197    Month,
1198    Day,
1199    Hour,
1200    Minute,
1201    Second,
1202}
1203
1204impl FromStr for DateTimeField {
1205    type Err = IntervalParseError;
1206
1207    fn from_str(s: &str) -> ParseResult<Self> {
1208        match s.to_lowercase().as_str() {
1209            "years" | "year" | "yrs" | "yr" | "y" => Ok(Self::Year),
1210            "days" | "day" | "d" => Ok(Self::Day),
1211            "hours" | "hour" | "hrs" | "hr" | "h" => Ok(Self::Hour),
1212            "minutes" | "minute" | "mins" | "min" | "m" => Ok(Self::Minute),
1213            "months" | "month" | "mons" | "mon" => Ok(Self::Month),
1214            "seconds" | "second" | "secs" | "sec" | "s" => Ok(Self::Second),
1215            _ => Err(IntervalParseError::invalid_unit(s)),
1216        }
1217    }
1218}
1219
1220#[derive(Debug, Clone, PartialEq, Eq, Hash)]
1221enum TimeStrToken {
1222    Second(F64),
1223    Num(i64),
1224    TimeUnit(DateTimeField),
1225}
1226
1227fn parse_interval(s: &str) -> ParseResult<Vec<TimeStrToken>> {
1228    let s = s.trim();
1229    let mut tokens = Vec::new();
1230    let mut num_buf = "".to_owned();
1231    let mut char_buf = "".to_owned();
1232    let mut hour_min_sec = Vec::new();
1233    for (i, c) in s.chars().enumerate() {
1234        match c {
1235            '-' | '+' => {
1236                num_buf.push(c);
1237            }
1238            '.' => {
1239                num_buf.push(c);
1240            }
1241            c if c.is_ascii_digit() => {
1242                convert_unit(&mut char_buf, &mut tokens)?;
1243                num_buf.push(c);
1244            }
1245            c if c.is_ascii_alphabetic() => {
1246                convert_digit(&mut num_buf, &mut tokens)?;
1247                char_buf.push(c);
1248            }
1249            chr if chr.is_ascii_whitespace() => {
1250                convert_unit(&mut char_buf, &mut tokens)?;
1251                convert_digit(&mut num_buf, &mut tokens)?;
1252            }
1253            ':' => {
1254                // there must be a digit before the ':'
1255                if num_buf.is_empty() {
1256                    return Err(IntervalParseError::invalid(s));
1257                }
1258                hour_min_sec.push(num_buf.clone());
1259                num_buf.clear();
1260            }
1261            _ => {
1262                return Err(IntervalParseError::uncategorized(format!(
1263                    "Invalid character at offset {} in {}: {:?}. Only support digit or alphabetic now",
1264                    i, s, c
1265                )));
1266            }
1267        };
1268    }
1269    if !hour_min_sec.is_empty() {
1270        if !num_buf.is_empty() {
1271            hour_min_sec.push(num_buf.clone());
1272            num_buf.clear();
1273        }
1274    } else {
1275        convert_digit(&mut num_buf, &mut tokens)?;
1276    }
1277    convert_unit(&mut char_buf, &mut tokens)?;
1278    convert_hms(&hour_min_sec, &mut tokens)
1279        .ok_or_else(|| IntervalParseError::invalid(format!("{hour_min_sec:?}")))?;
1280
1281    Ok(tokens)
1282}
1283
1284fn convert_digit(c: &mut String, t: &mut Vec<TimeStrToken>) -> ParseResult<()> {
1285    if !c.is_empty() {
1286        match c.parse::<i64>() {
1287            Ok(num) => {
1288                t.push(TimeStrToken::Num(num));
1289            }
1290            Err(_) => {
1291                return Err(IntervalParseError::invalid(c.clone()));
1292            }
1293        }
1294        c.clear();
1295    }
1296    Ok(())
1297}
1298
1299fn convert_unit(c: &mut String, t: &mut Vec<TimeStrToken>) -> ParseResult<()> {
1300    if !c.is_empty() {
1301        t.push(TimeStrToken::TimeUnit(c.parse()?));
1302        c.clear();
1303    }
1304    Ok(())
1305}
1306
1307/// convert `hour_min_sec` format
1308/// e.g.
1309/// c = ["1", "2", "3"], c will be convert to:
1310/// [`TimeStrToken::Num(1)`, `TimeStrToken::TimeUnit(DateTimeField::Hour)`,
1311///  `TimeStrToken::Num(2)`, `TimeStrToken::TimeUnit(DateTimeField::Minute)`,
1312///  `TimeStrToken::Second("3")`, `TimeStrToken::TimeUnit(DateTimeField::Second)`]
1313fn convert_hms(c: &Vec<String>, t: &mut Vec<TimeStrToken>) -> Option<()> {
1314    if c.len() > 3 {
1315        return None;
1316    }
1317    let mut is_neg = false;
1318    if let Some(s) = c.first() {
1319        let v = s.parse().ok()?;
1320        is_neg = s.starts_with('-');
1321        t.push(TimeStrToken::Num(v));
1322        t.push(TimeStrToken::TimeUnit(DateTimeField::Hour))
1323    }
1324    if let Some(s) = c.get(1) {
1325        let mut v: i64 = s.parse().ok()?;
1326        if !(0..60).contains(&v) {
1327            return None;
1328        }
1329        if is_neg {
1330            v = v.checked_neg()?;
1331        }
1332        t.push(TimeStrToken::Num(v));
1333        t.push(TimeStrToken::TimeUnit(DateTimeField::Minute))
1334    }
1335    if let Some(s) = c.get(2) {
1336        let mut v: f64 = s.parse().ok()?;
1337        // PostgreSQL allows '60.x' for seconds.
1338        if !(0f64..61f64).contains(&v) {
1339            return None;
1340        }
1341        if is_neg {
1342            v = -v;
1343        }
1344        t.push(TimeStrToken::Second(v.into()));
1345        t.push(TimeStrToken::TimeUnit(DateTimeField::Second))
1346    }
1347    Some(())
1348}
1349
1350impl Interval {
1351    fn parse_sql_standard(s: &str, leading_field: DateTimeField) -> ParseResult<Self> {
1352        use DateTimeField::*;
1353        let tokens = parse_interval(s)?;
1354        // Todo: support more syntax
1355        if tokens.len() > 1 {
1356            return Err(IntervalParseError::invalid(s));
1357        }
1358        let num = match tokens.first() {
1359            Some(TimeStrToken::Num(num)) => *num,
1360            _ => {
1361                return Err(IntervalParseError::invalid(s));
1362            }
1363        };
1364
1365        (|| match leading_field {
1366            Year => {
1367                let months = num.checked_mul(12)?.try_into().ok()?;
1368                Some(Interval::from_month_day_usec(months, 0, 0))
1369            }
1370            Month => Some(Interval::from_month_day_usec(num.try_into().ok()?, 0, 0)),
1371            Day => Some(Interval::from_month_day_usec(0, num.try_into().ok()?, 0)),
1372            Hour => {
1373                let usecs = num.checked_mul(3600 * USECS_PER_SEC)?;
1374                Some(Interval::from_month_day_usec(0, 0, usecs))
1375            }
1376            Minute => {
1377                let usecs = num.checked_mul(60 * USECS_PER_SEC)?;
1378                Some(Interval::from_month_day_usec(0, 0, usecs))
1379            }
1380            Second => {
1381                let usecs = num.checked_mul(USECS_PER_SEC)?;
1382                Some(Interval::from_month_day_usec(0, 0, usecs))
1383            }
1384        })()
1385        .ok_or_else(|| IntervalParseError::invalid(s))
1386    }
1387
1388    fn parse_postgres(s: &str) -> ParseResult<Self> {
1389        use DateTimeField::*;
1390        let mut tokens = parse_interval(s)?;
1391        if tokens.len() % 2 != 0
1392            && let Some(TimeStrToken::Num(_)) = tokens.last()
1393        {
1394            tokens.push(TimeStrToken::TimeUnit(DateTimeField::Second));
1395        }
1396        if tokens.len() % 2 != 0 {
1397            return Err(IntervalParseError::invalid(s));
1398        }
1399        let mut token_iter = tokens.into_iter();
1400        let mut result = Interval::from_month_day_usec(0, 0, 0);
1401        while let Some(num) = token_iter.next()
1402            && let Some(interval_unit) = token_iter.next()
1403        {
1404            match (num, interval_unit) {
1405                (TimeStrToken::Num(num), TimeStrToken::TimeUnit(interval_unit)) => {
1406                    result = (|| match interval_unit {
1407                        Year => {
1408                            let months = num.checked_mul(12)?.try_into().ok()?;
1409                            Some(Interval::from_month_day_usec(months, 0, 0))
1410                        }
1411                        Month => Some(Interval::from_month_day_usec(num.try_into().ok()?, 0, 0)),
1412                        Day => Some(Interval::from_month_day_usec(0, num.try_into().ok()?, 0)),
1413                        Hour => {
1414                            let usecs = num.checked_mul(3600 * USECS_PER_SEC)?;
1415                            Some(Interval::from_month_day_usec(0, 0, usecs))
1416                        }
1417                        Minute => {
1418                            let usecs = num.checked_mul(60 * USECS_PER_SEC)?;
1419                            Some(Interval::from_month_day_usec(0, 0, usecs))
1420                        }
1421                        Second => {
1422                            let usecs = num.checked_mul(USECS_PER_SEC)?;
1423                            Some(Interval::from_month_day_usec(0, 0, usecs))
1424                        }
1425                    })()
1426                    .and_then(|rhs| result.checked_add(&rhs))
1427                    .ok_or_else(|| IntervalParseError::invalid(s))?;
1428                }
1429                (TimeStrToken::Second(second), TimeStrToken::TimeUnit(interval_unit)) => {
1430                    result = match interval_unit {
1431                        Second => {
1432                            // If unsatisfied precision is passed as input, we should not return
1433                            // None (Error).
1434                            let usecs = (second.into_inner() * (USECS_PER_SEC as f64))
1435                                .round_ties_even() as i64;
1436                            Some(Interval::from_month_day_usec(0, 0, usecs))
1437                        }
1438                        _ => None,
1439                    }
1440                    .and_then(|rhs| result.checked_add(&rhs))
1441                    .ok_or_else(|| IntervalParseError::invalid(s))?;
1442                }
1443                _ => {
1444                    return Err(IntervalParseError::invalid(s));
1445                }
1446            }
1447        }
1448        Ok(result)
1449    }
1450
1451    pub fn parse_with_fields(s: &str, leading_field: Option<DateTimeField>) -> ParseResult<Self> {
1452        if let Some(leading_field) = leading_field {
1453            Self::parse_sql_standard(s, leading_field)
1454        } else {
1455            match s.as_bytes().get(0) {
1456                Some(b'P') => Self::from_iso_8601(s),
1457                _ => Self::parse_postgres(s),
1458            }
1459        }
1460    }
1461}
1462
1463impl FromStr for Interval {
1464    type Err = IntervalParseError;
1465
1466    fn from_str(s: &str) -> ParseResult<Self> {
1467        Self::parse_with_fields(s, None)
1468    }
1469}
1470
1471#[cfg(test)]
1472mod tests {
1473    use interval::test_utils::IntervalTestExt;
1474
1475    use super::*;
1476    use crate::types::ordered_float::OrderedFloat;
1477    use crate::util::panic::rw_catch_unwind;
1478
1479    #[test]
1480    fn test_parse() {
1481        let interval = "04:00:00".parse::<Interval>().unwrap();
1482        assert_eq!(interval, Interval::from_millis(4 * 3600 * 1000));
1483
1484        let interval = "1 year 2 months 3 days 00:00:01"
1485            .parse::<Interval>()
1486            .unwrap();
1487        assert_eq!(
1488            interval,
1489            Interval::from_month(14) + Interval::from_days(3) + Interval::from_millis(1000)
1490        );
1491
1492        let interval = "1 year 2 months 3 days 00:00:00.001"
1493            .parse::<Interval>()
1494            .unwrap();
1495        assert_eq!(
1496            interval,
1497            Interval::from_month(14) + Interval::from_days(3) + Interval::from_millis(1)
1498        );
1499
1500        let interval = "1 year 2 months 3 days 00:59:59.005"
1501            .parse::<Interval>()
1502            .unwrap();
1503        assert_eq!(
1504            interval,
1505            Interval::from_month(14)
1506                + Interval::from_days(3)
1507                + Interval::from_minutes(59)
1508                + Interval::from_millis(59000)
1509                + Interval::from_millis(5)
1510        );
1511
1512        let interval = "1 year 2 months 3 days 01".parse::<Interval>().unwrap();
1513        assert_eq!(
1514            interval,
1515            Interval::from_month(14) + Interval::from_days(3) + Interval::from_millis(1000)
1516        );
1517
1518        let interval = "1 year 2 months 3 days 1:".parse::<Interval>().unwrap();
1519        assert_eq!(
1520            interval,
1521            Interval::from_month(14) + Interval::from_days(3) + Interval::from_minutes(60)
1522        );
1523
1524        let interval = "1 year 2 months 3 days 1:2".parse::<Interval>().unwrap();
1525        assert_eq!(
1526            interval,
1527            Interval::from_month(14) + Interval::from_days(3) + Interval::from_minutes(62)
1528        );
1529
1530        let interval = "1 year 2 months 3 days 1:2:".parse::<Interval>().unwrap();
1531        assert_eq!(
1532            interval,
1533            Interval::from_month(14) + Interval::from_days(3) + Interval::from_minutes(62)
1534        );
1535
1536        let interval = "P1Y2M3DT0H5M0S".parse::<Interval>().unwrap();
1537        assert_eq!(
1538            interval,
1539            Interval::from_month(14) + Interval::from_days(3) + Interval::from_minutes(5)
1540        );
1541    }
1542
1543    #[test]
1544    fn test_to_string() {
1545        assert_eq!(
1546            Interval::from_month_day_usec(-14, 3, (11 * 3600 + 45 * 60 + 14) * USECS_PER_SEC + 233)
1547                .to_string(),
1548            "-1 years -2 mons +3 days 11:45:14.000233"
1549        );
1550        assert_eq!(
1551            Interval::from_month_day_usec(-14, 3, 0).to_string(),
1552            "-1 years -2 mons +3 days"
1553        );
1554        assert_eq!(Interval::default().to_string(), "00:00:00");
1555        assert_eq!(
1556            Interval::from_month_day_usec(
1557                -14,
1558                3,
1559                -((11 * 3600 + 45 * 60 + 14) * USECS_PER_SEC + 233)
1560            )
1561            .to_string(),
1562            "-1 years -2 mons +3 days -11:45:14.000233"
1563        );
1564    }
1565
1566    #[test]
1567    fn test_exact_div() {
1568        let cases = [
1569            ((14, 6, 6), (14, 6, 6), Some(1)),
1570            ((0, 0, 0), (0, 0, 0), None),
1571            ((0, 0, 0), (1, 0, 0), Some(0)),
1572            ((1, 1, 1), (0, 0, 0), None),
1573            ((1, 1, 1), (1, 0, 0), None),
1574            ((10, 0, 0), (1, 0, 0), Some(10)),
1575            ((10, 0, 0), (4, 0, 0), None),
1576            ((0, 24, 0), (4, 0, 0), None),
1577            ((6, 8, 9), (3, 1, 3), None),
1578            ((6, 8, 12), (3, 4, 6), Some(2)),
1579        ];
1580
1581        for (lhs, rhs, expected) in cases {
1582            let lhs = Interval::from_month_day_usec(lhs.0, lhs.1, lhs.2 as i64);
1583            let rhs = Interval::from_month_day_usec(rhs.0, rhs.1, rhs.2 as i64);
1584            let result = rw_catch_unwind(|| {
1585                let actual = lhs.exact_div(&rhs);
1586                assert_eq!(actual, expected);
1587            });
1588            if result.is_err() {
1589                println!("Failed on {}.exact_div({})", lhs, rhs);
1590                break;
1591            }
1592        }
1593    }
1594
1595    #[test]
1596    fn test_div_float() {
1597        let cases_int = [
1598            ((10, 8, 6), 2, Some((5, 4, 3))),
1599            ((1, 2, 33), 3, Some((0, 10, 57600000011i64))),
1600            ((1, 0, 11), 10, Some((0, 3, 1))),
1601            ((5, 6, 7), 0, None),
1602        ];
1603
1604        let cases_float = [
1605            ((10, 8, 6), 2.0f32, Some((5, 4, 3))),
1606            ((1, 2, 33), 3.0f32, Some((0, 10, 57600000011i64))),
1607            ((10, 15, 100), 2.5f32, Some((4, 6, 40))),
1608            ((5, 6, 7), 0.0f32, None),
1609        ];
1610
1611        for (lhs, rhs, expected) in cases_int {
1612            let lhs = Interval::from_month_day_usec(lhs.0, lhs.1, lhs.2 as i64);
1613            let expected = expected.map(|x| Interval::from_month_day_usec(x.0, x.1, x.2));
1614
1615            let actual = lhs.div_float(rhs as i16);
1616            assert_eq!(actual, expected);
1617
1618            let actual = lhs.div_float(rhs);
1619            assert_eq!(actual, expected);
1620
1621            let actual = lhs.div_float(rhs as i64);
1622            assert_eq!(actual, expected);
1623        }
1624
1625        for (lhs, rhs, expected) in cases_float {
1626            let lhs = Interval::from_month_day_usec(lhs.0, lhs.1, lhs.2 as i64);
1627            let expected = expected.map(|x| Interval::from_month_day_usec(x.0, x.1, x.2));
1628
1629            let actual = lhs.div_float(OrderedFloat::<f32>(rhs));
1630            assert_eq!(actual, expected);
1631
1632            let actual = lhs.div_float(OrderedFloat::<f64>(rhs as f64));
1633            assert_eq!(actual, expected);
1634        }
1635    }
1636
1637    #[test]
1638    fn test_serialize_deserialize() {
1639        let mut serializer = memcomparable::Serializer::new(vec![]);
1640        let a = Interval::from_month_day_usec(123, 456, 789);
1641        a.serialize(&mut serializer).unwrap();
1642        let buf = serializer.into_inner();
1643        let mut deserializer = memcomparable::Deserializer::new(&buf[..]);
1644        assert_eq!(Interval::deserialize(&mut deserializer).unwrap(), a);
1645    }
1646
1647    #[test]
1648    fn test_memcomparable() {
1649        let cases = [
1650            ((1, 2, 3), (4, 5, 6), Ordering::Less),
1651            ((0, 31, 0), (1, 0, 0), Ordering::Greater),
1652            ((1, 0, 0), (0, 0, USECS_PER_MONTH + 1), Ordering::Less),
1653            ((0, 1, 0), (0, 0, USECS_PER_DAY + 1), Ordering::Less),
1654            (
1655                (2, 3, 4),
1656                (1, 2, 4 + USECS_PER_DAY + USECS_PER_MONTH),
1657                Ordering::Equal,
1658            ),
1659        ];
1660
1661        for ((lhs_months, lhs_days, lhs_usecs), (rhs_months, rhs_days, rhs_usecs), order) in cases {
1662            let lhs = {
1663                let mut serializer = memcomparable::Serializer::new(vec![]);
1664                Interval::from_month_day_usec(lhs_months, lhs_days, lhs_usecs)
1665                    .serialize(&mut serializer)
1666                    .unwrap();
1667                serializer.into_inner()
1668            };
1669            let rhs = {
1670                let mut serializer = memcomparable::Serializer::new(vec![]);
1671                Interval::from_month_day_usec(rhs_months, rhs_days, rhs_usecs)
1672                    .serialize(&mut serializer)
1673                    .unwrap();
1674                serializer.into_inner()
1675            };
1676            assert_eq!(lhs.cmp(&rhs), order)
1677        }
1678    }
1679
1680    #[test]
1681    fn test_deserialize_justify() {
1682        let cases = [
1683            (
1684                (0, 0, USECS_PER_MONTH * 2 + USECS_PER_DAY * 3 + 4),
1685                Some((2, 3, 4i64, "2 mons 3 days 00:00:00.000004")),
1686            ),
1687            ((i32::MIN, i32::MIN, i64::MIN), None),
1688            ((i32::MAX, i32::MAX, i64::MAX), None),
1689            (
1690                (0, i32::MIN, i64::MIN),
1691                Some((
1692                    -75141187,
1693                    -29,
1694                    -14454775808,
1695                    "-6261765 years -7 mons -29 days -04:00:54.775808",
1696                )),
1697            ),
1698            (
1699                (i32::MIN, -60, i64::MAX),
1700                Some((
1701                    -2143925250,
1702                    -8,
1703                    -71945224193,
1704                    "-178660437 years -6 mons -8 days -19:59:05.224193",
1705                )),
1706            ),
1707        ];
1708        for ((lhs_months, lhs_days, lhs_usecs), rhs) in cases {
1709            let input = Interval::from_month_day_usec(lhs_months, lhs_days, lhs_usecs);
1710            let actual_deserialize = IntervalCmpValue::from(input).as_justified();
1711
1712            match rhs {
1713                None => {
1714                    assert_eq!(actual_deserialize, None);
1715                }
1716                Some((rhs_months, rhs_days, rhs_usecs, rhs_str)) => {
1717                    // We should test individual fields rather than using custom `Eq`
1718                    assert_eq!(actual_deserialize.unwrap().months(), rhs_months);
1719                    assert_eq!(actual_deserialize.unwrap().days(), rhs_days);
1720                    assert_eq!(actual_deserialize.unwrap().usecs(), rhs_usecs);
1721                    assert_eq!(actual_deserialize.unwrap().to_string(), rhs_str);
1722                }
1723            }
1724        }
1725
1726        // A false positive overflow that is buggy in PostgreSQL 15.2.
1727        let input = Interval::from_month_day_usec(i32::MIN, -30, 1);
1728        let actual_deserialize = IntervalCmpValue::from(input).as_justified();
1729        // It has a justified interval within range, and can be obtained by our deserialization.
1730        assert_eq!(actual_deserialize.unwrap().months(), i32::MIN);
1731        assert_eq!(actual_deserialize.unwrap().days(), -29);
1732        assert_eq!(actual_deserialize.unwrap().usecs(), -USECS_PER_DAY + 1);
1733    }
1734
1735    #[test]
1736    fn test_deserialize_alternate() {
1737        let cases = [
1738            (0, 0, USECS_PER_MONTH * 2 + USECS_PER_DAY * 3 + 4),
1739            (i32::MIN, i32::MIN, i64::MIN),
1740            (i32::MAX, i32::MAX, i64::MAX),
1741            (0, i32::MIN, i64::MIN),
1742            (i32::MIN, -60, i64::MAX),
1743        ];
1744        for (months, days, usecs) in cases {
1745            let input = Interval::from_month_day_usec(months, days, usecs);
1746
1747            let mut serializer = memcomparable::Serializer::new(vec![]);
1748            input.serialize(&mut serializer).unwrap();
1749            let buf = serializer.into_inner();
1750            let mut deserializer = memcomparable::Deserializer::new(&buf[..]);
1751            let actual = Interval::deserialize(&mut deserializer).unwrap();
1752
1753            // The Interval we get back can be a different one, but they should be equal.
1754            assert_eq!(actual, input);
1755        }
1756
1757        // Decoding invalid value
1758        let mut serializer = memcomparable::Serializer::new(vec![]);
1759        (i64::MAX, u64::MAX).serialize(&mut serializer).unwrap();
1760        let buf = serializer.into_inner();
1761        let mut deserializer = memcomparable::Deserializer::new(&buf[..]);
1762        assert!(Interval::deserialize(&mut deserializer).is_err());
1763
1764        let buf = i128::MIN.to_ne_bytes();
1765        rw_catch_unwind(|| {
1766            <Interval as crate::hash::HashKeyDe>::deserialize(&DataType::Interval, &mut &buf[..])
1767        })
1768        .unwrap_err();
1769    }
1770
1771    #[test]
1772    fn test_interval_estimate_size() {
1773        let interval = Interval::MIN;
1774        assert_eq!(interval.estimated_size(), 16);
1775    }
1776
1777    #[test]
1778    fn test_iso_8601() {
1779        let iso_8601_str = "P1Y2M3DT4H5M6.789123S";
1780        let lhs = Interval::from_month_day_usec(14, 3, 14706789123);
1781        let rhs = Interval::from_iso_8601(iso_8601_str).unwrap();
1782        assert_eq!(rhs.as_iso_8601().as_str(), iso_8601_str);
1783        assert_eq!(lhs, rhs);
1784    }
1785}
risingwave_common/types/interval.rs

risingwave_common/types/
interval.rs
