datetime/
interval.rs

1//! Elapsed time (duration) between two fixed [`DateTime`]s.
2//!
3//! A [`TimeInterval`] represents elapsed time, or "duration", and is the struct provided for doing
4//! "timestamp math".
5
6use std::ops::Add;
7use std::ops::AddAssign;
8use std::ops::Div;
9use std::ops::Mul;
10use std::ops::Sub;
11use std::ops::SubAssign;
12
13use crate::DateTime;
14
15#[cfg(feature = "macros")]
16#[doc(hidden)]
17pub mod __private_api {
18  pub use datetime_rs_macros::nanoseconds;
19}
20
21/// Construct a [`TimeInterval`] from a domain-specific language.
22///
23/// The language is approximately: `[+-]? ([0-9]+d)? ([0-9]+h)/ [0-9]+m)? ([0-9]+(\.[0-9]+)?s)?`.
24///
25/// ## Examples
26///
27/// ```
28/// use datetime::interval::TimeInterval;
29/// use datetime::time_interval;
30///
31/// assert_eq!(time_interval!(5m 30s), TimeInterval::new(330, 0));
32/// assert_eq!(time_interval!(-1h 30m), TimeInterval::new(-5_400, 0));
33/// assert_eq!(time_interval!(10.5s), TimeInterval::new(10, 500_000_000));
34/// ```
35#[macro_export]
36#[cfg(feature = "macros")]
37#[cfg_attr(docsrs, doc(cfg(feature = "macros")))]
38macro_rules! time_interval {
39  ($($interval:tt)+) => { const {
40    $crate::interval::TimeInterval::from_nanoseconds(
41      $crate::interval::__private_api::nanoseconds!($($interval)*)
42    )
43  }}
44}
45
46/// An interval or duration of time between two [`DateTime`]s.
47///
48/// The easiest way to create a [`TimeInterval`] is often with the [`time_interval`] macro, which
49/// uses a domain-specific language:
50///
51/// ## Examples
52///
53/// ```
54/// use datetime::interval::TimeInterval;
55/// use datetime::time_interval;
56///
57/// assert_eq!(time_interval!(5m 30s), TimeInterval::new(330, 0));
58/// assert_eq!(time_interval!(-1h 30m), TimeInterval::new(-5_400, 0));
59/// assert_eq!(time_interval!(10.5s), TimeInterval::new(10, 500_000_000));
60/// ```
61#[derive(Copy, Clone, Debug, Default, Eq, PartialEq, PartialOrd, Ord)]
62pub struct TimeInterval {
63  seconds: i64,
64  nanos: u32,
65}
66
67impl TimeInterval {
68  /// Create a new [`TimeInterval`] from seconds and nanoseconds.
69  pub const fn new(seconds: i64, nanos: u32) -> Self {
70    Self { seconds, nanos }
71  }
72
73  /// Create a new [`TimeInterval`] from a value in milliseconds.
74  pub const fn from_milliseconds(millis: i64) -> Self {
75    Self::new(millis.div_euclid(1_000), millis.rem_euclid(1_000) as u32 * 1_000_000)
76  }
77
78  /// Create a new [`TimeInterval`] from a value in microseconds.
79  pub const fn from_microseconds(micros: i64) -> Self {
80    Self::new(micros.div_euclid(1_000_000), micros.rem_euclid(1_000_000) as u32 * 1_000)
81  }
82
83  /// Create a new [`TimeInterval`] from a value in nanoseconds.
84  pub const fn from_nanoseconds(nanos: i128) -> Self {
85    Self::new(nanos.div_euclid(1_000_000_000) as i64, nanos.rem_euclid(1_000_000_000) as u32)
86  }
87
88  /// The number of seconds this interval represents.
89  ///
90  /// Note that the nanoseconds value is always positive, even if seconds is negative. For example,
91  /// an interval representing -2.5 seconds will be represented as -3 seconds and 500,000,000
92  /// nanos.
93  pub const fn seconds(&self) -> i64 {
94    self.seconds
95  }
96
97  /// The number of nanoseconds this interval represents.
98  ///
99  /// Note that the nanoseconds value is always positive, even if seconds is negative. For example,
100  /// an interval representing -2.5 seconds will be represented as -3 seconds and 500,000,000
101  /// nanos.
102  pub const fn nanoseconds(&self) -> u32 {
103    self.nanos
104  }
105
106  /// The number of milliseconds this interval represents.
107  pub const fn as_milliseconds(&self) -> i64 {
108    self.seconds * 1_000 + (self.nanos / 1_000_000) as i64
109  }
110
111  /// The number of microseconds this interval represents.
112  pub const fn as_microseconds(&self) -> i64 {
113    self.seconds * 1_000_000 + (self.nanos / 1_000) as i64
114  }
115
116  /// The number of nanoseconds this interval represents.
117  pub const fn as_nanoseconds(&self) -> i128 {
118    self.seconds as i128 * 1_000_000_000 + self.nanos as i128
119  }
120}
121
122impl Add<TimeInterval> for DateTime {
123  type Output = DateTime;
124
125  fn add(self, rhs: TimeInterval) -> Self::Output {
126    let seconds = self.seconds + rhs.seconds + ((self.nanos + rhs.nanos) / 1_000_000_000) as i64;
127    let nanos = (self.nanos + rhs.nanos) % 1_000_000_000;
128    Self {
129      seconds,
130      nanos,
131      #[cfg(feature = "tz")]
132      tz: self.tz,
133    }
134  }
135}
136
137impl AddAssign<TimeInterval> for DateTime {
138  fn add_assign(&mut self, rhs: TimeInterval) {
139    self.seconds += rhs.seconds;
140    self.nanos += rhs.nanos;
141    while self.nanos >= 1_000_000_000 {
142      self.seconds += 1;
143      self.nanos -= 1_000_000_000;
144    }
145  }
146}
147
148impl Sub<TimeInterval> for DateTime {
149  type Output = DateTime;
150
151  #[allow(clippy::suspicious_arithmetic_impl)]
152  fn sub(self, rhs: TimeInterval) -> Self::Output {
153    let mut seconds = self.seconds - rhs.seconds;
154    let nanos = self.nanos.checked_sub(rhs.nanos).unwrap_or_else(|| {
155      seconds -= 1;
156      self.nanos + 1_000_000_000 - rhs.nanos
157    });
158    Self {
159      seconds,
160      nanos,
161      #[cfg(feature = "tz")]
162      tz: self.tz,
163    }
164  }
165}
166
167impl SubAssign<TimeInterval> for DateTime {
168  fn sub_assign(&mut self, rhs: TimeInterval) {
169    self.seconds -= rhs.seconds;
170    match self.nanos >= rhs.nanos {
171      true => self.nanos -= rhs.nanos,
172      false => {
173        self.nanos += 1_000_000_000;
174        self.seconds -= 1;
175        self.nanos -= rhs.nanos;
176      },
177    }
178  }
179}
180
181impl Sub for DateTime {
182  type Output = TimeInterval;
183
184  #[allow(clippy::suspicious_arithmetic_impl)]
185  fn sub(self, rhs: Self) -> Self::Output {
186    let mut seconds = self.seconds - rhs.seconds;
187    let nanos = self.nanos.checked_sub(rhs.nanos).unwrap_or_else(|| {
188      seconds -= 1;
189      self.nanos + 1_000_000_000 - rhs.nanos
190    });
191    TimeInterval { seconds, nanos }
192  }
193}
194
195impl<I: Into<i128>> Mul<I> for TimeInterval {
196  type Output = Self;
197
198  fn mul(self, rhs: I) -> Self::Output {
199    Self::from_nanoseconds(self.as_nanoseconds() * rhs.into())
200  }
201}
202
203impl<I: Into<i128>> Div<I> for TimeInterval {
204  type Output = Self;
205
206  fn div(self, rhs: I) -> Self::Output {
207    Self::from_nanoseconds(self.as_nanoseconds() / rhs.into())
208  }
209}
210
211impl Div for TimeInterval {
212  type Output = f64;
213
214  fn div(self, rhs: Self) -> Self::Output {
215    self.as_nanoseconds() as f64 / rhs.as_nanoseconds() as f64
216  }
217}
218
219#[cfg(feature = "syn")]
220mod syn {
221  use datetime_rs_codegen::Delta;
222  use syn::Result;
223  use syn::parse::Parse;
224  use syn::parse::ParseStream;
225
226  use super::TimeInterval;
227
228  #[cfg_attr(docsrs, doc(cfg(feature = "syn")))]
229  impl Parse for TimeInterval {
230    fn parse(input: ParseStream) -> Result<Self> {
231      let delta = Delta::parse(input)?;
232      Ok(Self::new(delta.seconds(), delta.nanos()))
233    }
234  }
235
236  #[cfg(test)]
237  mod tests {
238    use assert2::check;
239    use quote::quote;
240
241    use super::*;
242
243    #[test]
244    fn test_parse() -> Result<()> {
245      check!(syn::parse2::<TimeInterval>(quote! { 15m 30s })? == time_interval!(15m 30s));
246      check!(syn::parse2::<TimeInterval>(quote! { -1h 15m })? == time_interval!(-1h 15m));
247      Ok(())
248    }
249  }
250}
251
252#[cfg(test)]
253mod tests {
254  use assert2::check;
255
256  use super::*;
257  use crate::DateTime;
258
259  #[test]
260  fn test_interval_macro() {
261    check!(time_interval!(1d) == TimeInterval::new(86_400, 0));
262    check!(time_interval!(2h) == TimeInterval::new(7_200, 0));
263    check!(time_interval!(1m) == TimeInterval::new(60, 0));
264    check!(time_interval!(1h30m) == TimeInterval::new(5_400, 0));
265    check!(time_interval!(1h 30m) == TimeInterval::new(5_400, 0));
266    check!(time_interval!(-1h 30m) == TimeInterval::new(-5_400, 0));
267    check!(time_interval!(1m 30s) == TimeInterval::new(90, 0));
268    check!(time_interval!(-1m 20s) == TimeInterval::new(-80, 0));
269    check!(time_interval!(-20s) == TimeInterval::new(-20, 0));
270    check!(time_interval!(-1.25s) == TimeInterval::new(-2, 750_000_000));
271    check!(time_interval!(1m 1.5s) == TimeInterval::new(61, 500_000_000));
272    check!(time_interval!(-0.5s) == TimeInterval::new(-1, 500_000_000));
273    check!(time_interval!(0.5s) == TimeInterval::new(0, 500_000_000));
274  }
275
276  #[test]
277  fn test_from_fractionals() {
278    for (millis, secs, nanos) in [(2_400, 2, 400_000_000), (-2_400, -3, 600_000_000)] {
279      let interval = TimeInterval::from_milliseconds(millis);
280      check!(interval.seconds() == secs);
281      check!(interval.nanoseconds() == nanos);
282    }
283    for (micros, secs, nanos) in [(2_400_000, 2, 400_000_000), (-2_400_000, -3, 600_000_000)] {
284      let interval = TimeInterval::from_microseconds(micros);
285      check!(interval.seconds() == secs);
286      check!(interval.nanoseconds() == nanos);
287    }
288    for (ns, s, n) in [(2_400_000_000, 2, 400_000_000), (-2_400_000_000, -3, 600_000_000)] {
289      let interval = TimeInterval::from_nanoseconds(ns);
290      check!(interval.seconds() == s);
291      check!(interval.nanoseconds() == n);
292    }
293  }
294
295  #[test]
296  fn test_add() {
297    check!(
298      datetime! { 2012-04-21 11:00:00 } + TimeInterval::new(3600, 0)
299        == datetime! { 2012-04-21 12:00:00 }
300    );
301    check!(
302      datetime! { 2012-04-21 11:00:00 } + TimeInterval::new(1800, 0)
303        == datetime! { 2012-04-21 11:30:00 }
304    );
305    check!(
306      datetime! { 2012-04-21 11:00:00 } + TimeInterval::new(0, 500_000_000)
307        == DateTime::ymd(2012, 4, 21).hms(11, 0, 0).nanos(500_000_000).build()
308    );
309    let incr = datetime! { 2012-04-21 11:00:00 }
310      + TimeInterval::new(0, 500_000_000)
311      + TimeInterval::new(0, 500_000_000);
312    check!(incr.seconds % 10 == 1);
313    check!(incr.nanos == 0);
314  }
315
316  #[test]
317  fn test_add_assign() {
318    let mut dt = datetime! { 2012-04-21 11:00:00 };
319    dt += TimeInterval::new(3600, 0);
320    check!(dt == datetime! { 2012-04-21 12:00:00 });
321    dt += TimeInterval::new(0, 750_000_000);
322    dt += TimeInterval::new(0, 250_000_000);
323    check!(dt == datetime! { 2012-04-21 12:00:01 });
324  }
325
326  #[test]
327  fn test_sub() {
328    check!(
329      datetime! { 2012-04-21 11:00:00 } - TimeInterval::new(3600, 0)
330        == datetime! { 2012-04-21 10:00:00 }
331    );
332    check!(
333      datetime! { 2012-04-21 11:00:00 } - TimeInterval::new(0, 500_000_000)
334        == DateTime::ymd(2012, 4, 21).hms(10, 59, 59).nanos(500_000_000).build()
335    );
336  }
337
338  #[test]
339  fn test_sub_assign() {
340    let mut dt = datetime! { 2012-04-21 11:00:00 };
341    dt -= TimeInterval::new(3600, 0);
342    check!(dt == datetime! { 2012-04-21 10:00:00 });
343    dt -= TimeInterval::new(0, 750_000_000);
344    dt -= TimeInterval::new(0, 350_000_000);
345    dt -= TimeInterval::new(0, 900_000_000);
346    check!(dt == datetime! { 2012-04-21 09:59:58 });
347  }
348
349  #[test]
350  fn test_sub_dt() {
351    check!(
352      datetime! { 2012-04-21 11:00:00 } - datetime! { 2012-04-21 10:00:00 }
353        == TimeInterval::new(3600, 0)
354    );
355    check!(
356      datetime! { 2012-04-21 11:00:00 } - datetime! { 2012-04-21 12:00:00 }
357        == TimeInterval::new(-3600, 0)
358    );
359  }
360
361  #[test]
362  fn test_mul_int() {
363    let interval = TimeInterval::new(3, 500_000_000) * 3;
364    check!(interval.seconds() == 10);
365    check!(interval.nanoseconds() == 500_000_000);
366  }
367
368  #[test]
369  fn test_div_int() {
370    let interval = TimeInterval::new(4, 500_000_000) / 3;
371    check!(interval.seconds() == 1);
372    check!(interval.nanoseconds() == 500_000_000);
373  }
374
375  #[test]
376  fn test_div() {
377    check!(TimeInterval::new(3600, 0) / TimeInterval::new(1800, 0) == 2.0);
378    check!(TimeInterval::new(-1800, 0) / TimeInterval::new(-3600, 0) == 0.5);
379    check!(TimeInterval::new(-1800, 0) / TimeInterval::new(3600, 0) == -0.5);
380    check!(TimeInterval::new(0, 3600) / TimeInterval::new(0, 1800) == 2.0);
381  }
382
383  #[test]
384  fn test_as() {
385    let dur = TimeInterval::new(5, 0);
386    check!(dur.as_milliseconds() == 5_000);
387    check!(dur.as_microseconds() == 5_000_000);
388    check!(dur.as_nanoseconds() == 5_000_000_000);
389  }
390}
datetime/interval.rs

datetime/
interval.rs
