relative_duration/
lib.rs

1/// # Relative Duration
2///
3/// A duration (the std style) that can retain negative values. Shipped with the standard set of
4/// operators for basic math.
5/// ```
6/// use relative_duration::RelativeDuration;
7///
8/// let a = RelativeDuration::from_millis(10);
9/// let b = RelativeDuration::from_millis(20);
10/// let c = a - b;
11///
12/// assert_eq!(c, RelativeDuration::from_millis(-10));
13/// ```
14///
15/// ## Reason
16///
17/// The existence of this (rather simple) crate is for calculus purposes only. Sometimes, when you
18/// work with offsets of timed events, you need to go backwards in time (shifting an event to the
19/// "left" for exemple).
20///
21/// when you try to do it on std durations, you get a panic.
22/// ```
23/// use std::panic::catch_unwind;
24/// use std::time::Duration;
25///
26/// let a = Duration::from_millis(10);
27/// let b = Duration::from_millis(20);
28///
29/// let res = catch_unwind(|| {
30///     let c = a - b;
31/// });
32///
33/// assert!(res.is_err()); // The thing has panicked... we lost :'(
34/// ```
35///
36/// That's because durations in the std library are meant to represent a delta between two instants,
37/// and instants are guaranteed to not go backwards.
38///
39/// The typical use case of this crate is when you want to do calculus with durations that can be
40/// negative without using formatting oriented types as with chrono, or resort to using bare numerical
41/// representations that take away the flexibility of the Duration type.
42///
43/// ## Features
44/// ### Comparison
45/// Relative duration objects can be compared like standard durations
46/// ```
47/// use relative_duration::RelativeDuration;
48///
49/// let a = RelativeDuration::from_secs(-10);
50/// let b = RelativeDuration::from_secs(20);
51///
52/// assert!(b > a);
53/// ```
54///
55/// ### Basic operations
56/// As this crate is really meant for calculus, basic operations are handled
57/// ```
58/// use relative_duration::RelativeDuration;
59///
60/// let a = RelativeDuration::from_millis(10);
61/// let b = RelativeDuration::from_millis(20);
62/// let c = a + b;
63/// let d = c - RelativeDuration::from_millis(-50);
64///
65/// assert_eq!(c, RelativeDuration::from_millis(30));
66/// assert_eq!(d, RelativeDuration::from_millis(80));
67/// ```
68///
69/// as well as divisions and multiplication by an unsigned integer scalar
70///
71/// ```
72/// use relative_duration::RelativeDuration;
73///
74/// let a = 2u32 * RelativeDuration::from_millis(10);
75/// assert_eq!(a, RelativeDuration::from_millis(20));
76///
77/// let b = RelativeDuration::from_millis(30) / 2;
78/// assert_eq!(b, RelativeDuration::from_millis(15));
79/// ```
80///
81/// and methods that mirror those of std duration.
82///
83/// ### Duration division
84///
85/// It is possible to divide durations by other durations
86/// ```
87/// use relative_duration::RelativeDuration;
88/// let f1 = RelativeDuration::from_millis(100).div_duration_f32(RelativeDuration::from_millis(10));
89///
90/// assert_eq!(f1, 10.0);
91/// ```
92///
93/// ### Handy things
94/// This crate has a trait called Suffix. It helps create relative durations from a bunch of primitives
95/// (kotlin style)
96/// ```
97/// use relative_duration::RelativeDuration;
98/// use relative_duration::suffix::Suffix;
99///
100/// let d = 10.microseconds();
101///
102/// assert_eq!(d, RelativeDuration::from_micros(10));
103/// ```
104///
105/// exists for nanoseconds, microseconds, milliseconds and seconds.
106pub mod cmp;
107pub mod disp;
108pub mod ops;
109pub mod relative_duration;
110pub mod utils;
111pub mod suffix;
112
113pub use relative_duration::RelativeDuration;
relative_duration/lib.rs

relative_duration/
lib.rs
