timewindow 0.1.4

Generic time-window generation for recurring, overlapping, and metadata-rich intervals
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
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

use chrono::{DateTime, Duration, Utc};

/// A half-open time interval `[start, end)` with associated metadata.
///
/// A `Window<M>` represents a bounded span of time in UTC together with
/// arbitrary metadata of type `M`.
///
/// # Semantics
///
/// Windows are half-open intervals:
///
/// - `start` is included
/// - `end` is excluded
///
/// A window is active at time `now` when:
///
/// `start <= now && now < end`
///
/// This convention makes adjacent windows compose cleanly without overlapping
/// at boundaries.
///
/// # Type parameter
///
/// - `M`: arbitrary metadata associated with the window
///
/// # Examples
///
/// ```rust
/// use chrono::{TimeZone, Utc};
/// use timewindow::Window;
///
/// let window = Window::new(
///     Utc.with_ymd_and_hms(2026, 3, 20, 12, 0, 0).unwrap(),
///     Utc.with_ymd_and_hms(2026, 3, 20, 14, 0, 0).unwrap(),
///     "metadata",
/// )
/// .unwrap();
///
/// assert!(window.is_active(Utc.with_ymd_and_hms(2026, 3, 20, 12, 0, 0).unwrap()));
/// assert!(window.is_active(Utc.with_ymd_and_hms(2026, 3, 20, 13, 0, 0).unwrap()));
/// assert!(!window.is_active(Utc.with_ymd_and_hms(2026, 3, 20, 14, 0, 0).unwrap()));
/// ```
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Window<M> {
    /// Inclusive start of the window.
    pub start: DateTime<Utc>,
    /// Exclusive end of the window.
    pub end: DateTime<Utc>,
    // Arbitrary metadata associated with the window.
    pub meta: M,
}

impl<M> Window<M> {
    /// Creates a new window if `start < end`.
    ///
    /// Returns `None` if the interval is empty or invalid, including:
    ///
    /// - `start == end`
    /// - `start > end`
    ///
    /// # Examples
    ///
    /// ```rust
    /// use chrono::{TimeZone, Utc};
    /// use timewindow::Window;
    ///
    /// let ok = Window::new(
    ///     Utc.with_ymd_and_hms(2026, 3, 20, 12, 0, 0).unwrap(),
    ///     Utc.with_ymd_and_hms(2026, 3, 20, 13, 0, 0).unwrap(),
    ///     (),
    /// );
    ///
    /// assert!(ok.is_some());
    ///
    /// let invalid = Window::new(
    ///     Utc.with_ymd_and_hms(2026, 3, 20, 13, 0, 0).unwrap(),
    ///     Utc.with_ymd_and_hms(2026, 3, 20, 13, 0, 0).unwrap(),
    ///     (),
    /// );
    ///
    /// assert!(invalid.is_none());
    /// ```
    pub fn new(start: DateTime<Utc>, end: DateTime<Utc>, meta: M) -> Option<Self> {
        (start < end).then_some(Self { start, end, meta })
    }

    /// Returns `true` if the window has not started yet at `now`.
    ///
    /// Equivalent to `now < self.start`.
    #[inline]
    pub fn is_upcoming(&self, now: DateTime<Utc>) -> bool {
        now < self.start
    }

    /// Returns `true` if the window is active at `now`.
    ///
    /// This uses half-open interval semantics:
    ///
    /// `self.start <= now && now < self.end`
    #[inline]
    pub fn is_active(&self, now: DateTime<Utc>) -> bool {
        self.start <= now && now < self.end
    }

    /// Returns `true` if the window has ended at or before `now`.
    ///
    /// Equivalent to `now >= self.end`.
    #[inline]
    pub fn is_expired(&self, now: DateTime<Utc>) -> bool {
        now >= self.end
    }

    /// Returns the total duration of the window.
    #[inline]
    pub fn duration(&self) -> Duration {
        self.end - self.start
    }

    /// Returns the time elapsed since the start of the window at `now`,
    /// if the window is currently active.
    ///
    /// Returns `None` if the window is not active at `now`.
    pub fn elapsed_at(&self, now: DateTime<Utc>) -> Option<Duration> {
        if self.is_active(now) {
            Some(now - self.start)
        } else {
            None
        }
    }

    /// Returns the time remaining until the end of the window at `now`,
    /// if the window is currently active.
    ///
    /// Returns `None` if the window is not active at `now`.
    pub fn remaining_at(&self, now: DateTime<Utc>) -> Option<Duration> {
        if self.is_active(now) {
            Some(self.end - now)
        } else {
            None
        }
    }
}