date_differencer/
lib.rs

1/*!
2# Date Differencer
3
4Calculate the time interval between two supported date-time values and output the result in years plus months plus days plus hours plus minutes plus seconds plus nanoseconds (instead of representing the same duration in different units). This library is useful for lifespan check and age calculation.
5
6## Supported Date-Time Crates
7
8Date-time crate support is enabled through Cargo features. Enable only the providers your project uses.
9
10| Feature | Time-zone aware types | Naive/local date-time types |
11| --- | --- | --- |
12| `chrono` | `chrono::DateTime<Tz>` | `chrono::NaiveDateTime` |
13| `jiff` | `jiff::Zoned` | `jiff::civil::DateTime` |
14| `time` | `time::OffsetDateTime`, `time::UtcDateTime` | `time::PrimitiveDateTime` |
15
16Time-zone aware types keep a timezone or UTC offset in the value. Naive/local types store only calendar and clock fields, so the caller decides how to interpret them.
17
18## Usage
19
20```rust
21# #[cfg(feature = "chrono")]
22# {
23use chrono::prelude::*;
24
25use date_differencer::{add_date_time_diff, date_diff, date_time_diff};
26
27let a = Local.with_ymd_and_hms(2022, 4, 6, 0, 0, 0).unwrap();
28let b = Local.with_ymd_and_hms(2023, 6, 9, 1, 0, 0).unwrap();
29
30println!("{:?}", date_diff(a, b));
31/*
32{
33    "years": 1,
34    "months": 2,
35    "days": 3
36}
37*/
38
39println!("{:?}", date_time_diff(a, b));
40/*
41{
42    "years": 1,
43    "months": 2,
44    "days": 3,
45    "hours": 1,
46    "minutes": 0,
47    "seconds": 0,
48    "nanoseconds": 0
49}
50*/
51
52println!("{}", add_date_time_diff(a, &date_time_diff(a, b)).unwrap()); // the same as b
53# }
54```
55
56This library can handle leap years and odd/even number of days in a month correctly. The result of following code is a bit confusing but reasonable.
57
58```rust
59# #[cfg(feature = "chrono")]
60# {
61use chrono::prelude::*;
62
63use date_differencer::date_diff;
64
65let a = Local.with_ymd_and_hms(2020, 2, 27, 0, 0, 0).unwrap();
66let b = Local.with_ymd_and_hms(2021, 3, 1, 0, 0, 0).unwrap();
67
68println!("{:?}", date_diff(a, b));
69/*
70{
71    "years": 1,
72    "months": 0,
73    "days": 2
74}
75
76Explanation:
77    1. 2020-02-27 + 1 year -> 2021-02-27
78    2. 2021-02-27 + 2 days -> 2021-03-01 (2021-02 has 28 days)
79*/
80
81println!("{:?}", date_diff(b, a));
82/*
83{
84    "years": -1,
85    "months": 0,
86    "days": -3
87}
88
89Explanation:
90    1. 2021-03-01 - 1 year -> 2020-03-01
91    2. 2020-03-01 - 3 days -> 2020-02-27 (2020-02 has 29 days)
92*/
93# }
94```
95*/
96
97#![no_std]
98#![cfg_attr(docsrs, feature(doc_cfg))]
99
100mod constants;
101
102mod add_diff;
103mod diff;
104
105pub use add_diff::*;
106pub use diff::*;
date_differencer/lib.rs

date_differencer/
lib.rs
