recurring 0.1.5

A recurring event series implementation based on jiff
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124

use crate::pattern::Interval;
use crate::{DateTimeRange, Error, Pattern, private};
use jiff::{
    ToSpan,
    civil::{DateTime, Time},
};

/// A recurrence pattern for daily events which may also include fixed times of the day.
///
/// # Example
///
/// ```
/// use recurring::pattern::Daily;
/// use jiff::civil::time;
///
/// let every_two_days_at_twelve = Daily::new(1).at(time(12, 0, 0, 0));
/// ```
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Daily {
    interval: Interval,
    at: Option<Time>,
}

impl Daily {
    /// Creates a new `Daily` from an interval of days.
    ///
    /// The fallible version of this method is [`Daily::try_new`].
    ///
    /// # Panics
    ///
    /// Panics if `interval` is negative or zero.
    ///
    /// # Example
    ///
    /// ```
    /// use recurring::pattern::Daily;
    ///
    /// let every_two_days = Daily::new(2);
    /// ```
    pub fn new<I: ToSpan>(interval: I) -> Daily {
        Daily {
            interval: Interval::new(interval.days()),
            at: None,
        }
    }

    /// Creates a new `Daily` from an interval of days.
    ///
    /// The panicking version of this method is [`Daily::new`].
    ///
    /// # Errors
    ///
    /// Returns an `Error` if `interval` is negative or zero.
    ///
    /// # Example
    ///
    /// ```
    /// use recurring::pattern::Daily;
    ///
    /// assert!(Daily::try_new(1).is_ok());
    /// assert!(Daily::try_new(0).is_err());
    /// assert!(Daily::try_new(-1).is_err());
    /// ```
    pub fn try_new<I: ToSpan>(interval: I) -> Result<Daily, Error> {
        Ok(Daily {
            interval: Interval::try_new(interval.days())?,
            at: None,
        })
    }

    /// Sets the exact time of day for the daily recurrence.
    ///
    /// # Example
    ///
    /// ```
    /// use jiff::civil::time;
    /// use recurring::pattern::daily;
    ///
    /// let every_day_at_twelve = daily(1).at(time(12, 0, 0, 0));
    ///
    /// let every_day_at_midnight_and_twelve = every_day_at_twelve.at(time(0, 0, 0, 0));
    /// ```
    #[must_use]
    pub fn at<T: Into<Time>>(mut self, time: T) -> Daily {
        self.at = Some(time.into());
        self
    }

    fn range_adjusted<F>(&self, f: F, instant: DateTime, range: DateTimeRange) -> Option<DateTime>
    where
        F: FnOnce(&Interval, DateTime, DateTimeRange) -> Option<DateTime>,
    {
        let Some(time) = self.at else {
            return f(&self.interval, instant, range);
        };

        let start = if range.start.time() <= time {
            range.start
        } else {
            self.interval.next_after(range.start, range)?
        };

        let start = start.with().time(time).build().ok()?;
        let range = DateTimeRange::from(start..range.end);

        f(&self.interval, instant, range)
    }
}

impl Pattern for Daily {
    fn next_after(&self, instant: DateTime, range: DateTimeRange) -> Option<DateTime> {
        self.range_adjusted(Interval::next_after, instant, range)
    }

    fn previous_before(&self, instant: DateTime, range: DateTimeRange) -> Option<DateTime> {
        self.range_adjusted(Interval::previous_before, instant, range)
    }

    fn closest_to(&self, instant: DateTime, range: DateTimeRange) -> Option<DateTime> {
        self.range_adjusted(Interval::closest_to, instant, range)
    }
}

impl private::Sealed for Daily {}