date_differencer/
lib.rs

1/*!
2# Date Differencer
3
4Calculate the time interval between two `DateTime` instances 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## Usage
7
8```rust
9use chrono::prelude::*;
10
11use date_differencer::{date_diff, date_time_diff, add_date_time_diff};
12
13let a = Local.with_ymd_and_hms(2022, 4, 6, 0, 0, 0).unwrap();
14let b = Local.with_ymd_and_hms(2023, 6, 9, 1, 0, 0).unwrap();
15
16println!("{:?}", date_diff(a, b));
17/*
18{
19    "years": 1,
20    "months": 2,
21    "days": 3
22}
23*/
24
25println!("{:?}", date_time_diff(a, b));
26/*
27{
28    "years": 1,
29    "months": 2,
30    "days": 3,
31    "hours": 1,
32    "minutes": 0,
33    "seconds": 0,
34    "nanoseconds": 0
35}
36*/
37
38println!("{}", add_date_time_diff(a, &date_time_diff(a, b)).unwrap()); // the same as b
39```
40
41This 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.
42
43```rust
44use chrono::prelude::*;
45
46use date_differencer::date_diff;
47
48let a = Local.with_ymd_and_hms(2020, 2, 27, 0, 0, 0).unwrap();
49let b = Local.with_ymd_and_hms(2021, 3, 1, 0, 0, 0).unwrap();
50
51println!("{:?}", date_diff(a, b));
52/*
53{
54    "years": 1,
55    "months": 0,
56    "days": 2
57}
58
59Explanation:
60    1. 2020-02-27 + 1 year -> 2021-02-27
61    2. 2021-02-27 + 2 days -> 2021-03-01 (2021-02 has 28 days)
62*/
63
64println!("{:?}", date_diff(b, a));
65/*
66{
67    "years": -1,
68    "months": 0,
69    "days": -3
70}
71
72Explanation:
73    1. 2021-03-01 - 1 year -> 2020-03-01
74    2. 2020-03-01 - 3 days -> 2020-02-27 (2020-02 has 29 days)
75*/
76```
77*/
78
79#![no_std]
80
81mod constants;
82
83mod add_diff;
84mod diff;
85
86pub use add_diff::*;
87pub use diff::*;