anytime 0.2.0

Ergonomic astronomical timescales in rust
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
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
use crate::{scales::TAI, Time};
use chrono::TimeDelta;

/// A collection of time values associated with a specific time scale.
///
/// Values retain the order in which they were supplied. Use [`Self::duration`]
/// to measure the physical span between the earliest and latest values,
/// regardless of their stored order.
///
/// # Examples
///
/// ```
/// use anytime::{Time, TimeSeries, scales::TAI};
/// use chrono::TimeDelta;
///
/// let series = TimeSeries::from_range(
///     Time::<TAI>::from_jd(2_451_545.0),
///     Time::<TAI>::from_jd(2_451_548.0),
///     TimeDelta::days(1),
/// );
/// assert_eq!(series.len(), 3);
/// ```
#[derive(Debug)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(bound = ""))]
pub struct TimeSeries<S> {
    times: Vec<Time<S>>,
}

/// A lazily generated range of times with an exclusive end bound.
///
/// Create one with [`TimeSeries::range_iter`]. The iterator yields the start
/// value when it is on the correct side of the end value, then advances by its
/// step until the exclusive bound is reached.
#[derive(Debug)]
pub struct TimeSeriesRange<S> {
    next: Option<Time<S>>,
    end: Time<S>,
    step: TimeDelta,
}

impl<S> TimeSeries<S> {
    /// Creates a series from time values in their supplied order.
    ///
    /// # Examples
    ///
    /// ```
    /// use anytime::{Time, TimeSeries, scales::TAI};
    ///
    /// let series = TimeSeries::new(vec![
    ///     Time::<TAI>::from_jd(2_451_545.0),
    ///     Time::<TAI>::from_jd(2_451_546.0),
    /// ]);
    /// assert_eq!(series.len(), 2);
    /// ```
    pub fn new(times: Vec<Time<S>>) -> Self {
        Self { times }
    }

    /// Returns the number of time values in the series.
    pub fn len(&self) -> usize {
        self.times.len()
    }

    /// Returns whether the series contains no time values.
    pub fn is_empty(&self) -> bool {
        self.times.is_empty()
    }

    /// Returns the first time in the series.
    pub fn first(&self) -> Option<&Time<S>> {
        self.times.first()
    }

    /// Returns the final time in the series.
    pub fn last(&self) -> Option<&Time<S>> {
        self.times.last()
    }

    /// Returns a mutable reference to the time at `index`.
    pub fn get_mut(&mut self, index: usize) -> Option<&mut Time<S>> {
        self.times.get_mut(index)
    }

    /// Appends a time to the end of the series.
    pub fn push(&mut self, time: Time<S>) {
        self.times.push(time);
    }

    /// Sorts the series in ascending physical order.
    pub fn sort(&mut self) {
        self.times.sort();
    }

    /// Reverses the stored order of the series.
    pub fn reverse(&mut self) {
        self.times.reverse();
    }

    /// Consumes the series and returns its time values in stored order.
    pub fn into_vec(self) -> Vec<Time<S>> {
        self.times
    }

    /// Returns the time at `index`, or `None` when the index is out of bounds.
    pub fn get(&self, index: usize) -> Option<&Time<S>> {
        self.times.get(index)
    }

    /// Returns the earliest physical time in the series.
    ///
    /// Stored order is ignored. When the earliest time occurs more than once,
    /// the first occurrence is returned.
    pub fn earliest(&self) -> Option<&Time<S>> {
        self.times.iter().min()
    }

    /// Returns the latest physical time in the series.
    ///
    /// Stored order is ignored. When the latest time occurs more than once,
    /// the first occurrence is returned.
    pub fn latest(&self) -> Option<&Time<S>> {
        self.times
            .iter()
            .reduce(|latest, time| if time > latest { time } else { latest })
    }

    /// Returns whether the series contains the same physical instant as `time`.
    pub fn contains<T>(&self, time: &Time<T>) -> bool
    where
        Time<T>: Into<Time<S>>,
    {
        self.times.iter().any(|candidate| candidate == time)
    }

    /// Returns whether the times are in ascending physical order.
    pub fn is_sorted(&self) -> bool {
        self.times.windows(2).all(|pair| pair[0] <= pair[1])
    }

    /// Returns the stored time nearest to `time` as a physical instant.
    ///
    /// When two values are equally near, the first one in stored order is
    /// returned.
    pub fn nearest<T>(&self, time: &Time<T>) -> Option<&Time<S>>
    where
        Time<S>: Into<Time<TAI>>,
        Time<T>: Into<Time<TAI>>,
    {
        let time: Time<TAI> = time.clone().into();
        self.times.iter().min_by_key(|candidate| {
            let candidate: Time<TAI> = (*candidate).clone().into();
            (candidate.value - time.value).abs()
        })
    }

    /// Iterates over times within the inclusive physical interval.
    ///
    /// Values are yielded in stored order and duplicates are preserved. The
    /// iterator is empty when `start` is later than `end`.
    pub fn within<T, U>(
        &self,
        start: &Time<T>,
        end: &Time<U>,
    ) -> impl Iterator<Item = &Time<S>> + '_
    where
        Time<T>: Into<Time<S>>,
        Time<U>: Into<Time<S>>,
    {
        let start: Time<S> = start.clone().into();
        let end: Time<S> = end.clone().into();
        self.times
            .iter()
            .filter(move |time| *time >= &start && *time <= &end)
    }

    /// Returns the time values in their stored order.
    pub fn as_slice(&self) -> &[Time<S>] {
        &self.times
    }

    /// Iterates over the time values in their stored order.
    pub fn iter(&self) -> std::slice::Iter<'_, Time<S>> {
        self.times.iter()
    }

    /// Iterates over signed physical intervals between adjacent stored times.
    ///
    /// A series with fewer than two values yields no intervals. Intervals can
    /// be negative when the stored times are not in ascending order.
    pub fn intervals(&self) -> impl Iterator<Item = TimeDelta> + '_
    where
        Time<S>: Into<Time<TAI>>,
    {
        self.times
            .windows(2)
            .map(|pair| pair[1].clone() - pair[0].clone())
    }

    /// Returns the elapsed physical duration from the earliest to latest time.
    ///
    /// Empty and singleton series have zero duration.
    pub fn duration(&self) -> TimeDelta
    where
        Time<S>: Into<Time<TAI>>,
    {
        let Some(first) = self.times.first() else {
            return TimeDelta::zero();
        };

        let (earliest, latest) =
            self.times
                .iter()
                .skip(1)
                .fold((first, first), |(earliest, latest), time| {
                    (
                        if time < earliest { time } else { earliest },
                        if time > latest { time } else { latest },
                    )
                });

        latest.clone() - earliest.clone()
    }
}

impl<S, T> From<Vec<Time<S>>> for TimeSeries<T>
where
    Time<S>: Into<Time<T>>,
{
    fn from(times: Vec<Time<S>>) -> Self {
        Self::new(times.into_iter().map(|time| time.into()).collect())
    }
}

impl<S> From<Vec<crate::AnyTime>> for TimeSeries<S>
where
    Time<S>: From<crate::AnyTime>,
{
    fn from(times: Vec<crate::AnyTime>) -> Self {
        Self::new(times.into_iter().map(Into::into).collect())
    }
}

impl<S> IntoIterator for TimeSeries<S> {
    type Item = Time<S>;
    type IntoIter = std::vec::IntoIter<Time<S>>;

    fn into_iter(self) -> Self::IntoIter {
        self.times.into_iter()
    }
}

impl<S: crate::Scale> Iterator for TimeSeriesRange<S> {
    type Item = Time<S>;

    fn next(&mut self) -> Option<Self::Item> {
        let current = self.next.take()?;
        self.next = current
            .value
            .checked_add(&self.step)
            .map(Time::new)
            .filter(|next| {
                if self.step > TimeDelta::zero() {
                    next < &self.end
                } else {
                    next > &self.end
                }
            });
        Some(current)
    }
}

impl<S: crate::Scale> TimeSeries<S> {
    /// Lazily generates a range with an exclusive end bound.
    ///
    /// Positive steps generate ascending ranges and negative steps generate
    /// descending ranges. A range whose step points away from its end is empty.
    ///
    /// # Panics
    ///
    /// Panics if `step` is zero.
    pub fn range_iter(start: Time<S>, end: Time<S>, step: TimeDelta) -> TimeSeriesRange<S> {
        assert_ne!(step, TimeDelta::zero(), "time series step must not be zero");

        let has_values = if step > TimeDelta::zero() {
            start < end
        } else {
            start > end
        };

        TimeSeriesRange {
            next: has_values.then_some(start),
            end,
            step,
        }
    }

    /// Creates a range with an exclusive end bound.
    ///
    /// This is the eager counterpart to [`Self::range_iter`].
    pub fn from_range(start: Time<S>, end: Time<S>, step: TimeDelta) -> Self {
        Self {
            times: Self::range_iter(start, end, step).collect(),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::scales::{TAI, UTC};

    fn tai(seconds: i64) -> Time<TAI> {
        Time::new(TimeDelta::seconds(seconds))
    }

    #[test]
    fn new_preserves_time_order() {
        let empty = TimeSeries::<TAI>::new(vec![]);
        assert!(empty.is_empty());
        assert_eq!(empty.first(), None);
        assert_eq!(empty.last(), None);
        assert_eq!(empty.duration(), TimeDelta::zero());
        let series = TimeSeries::new(vec![tai(2), tai(0), tai(1)]);

        assert_eq!(series.as_slice(), &[tai(2), tai(0), tai(1)]);
        assert_eq!(series.duration(), TimeDelta::seconds(2));
    }

    #[test]
    fn supports_collection_operations() {
        let mut series = TimeSeries::new(vec![tai(2), tai(0)]);

        series.push(tai(1));
        *series.get_mut(1).unwrap() = tai(3);
        assert_eq!(series.get_mut(3), None);
        assert_eq!(series.as_slice(), &[tai(2), tai(3), tai(1)]);

        series.sort();
        assert_eq!(series.as_slice(), &[tai(1), tai(2), tai(3)]);
        series.reverse();
        assert_eq!(series.into_vec(), vec![tai(3), tai(2), tai(1)]);
    }

    #[test]
    fn queries_stored_and_physical_order() {
        let series = TimeSeries::new(vec![tai(2), tai(0), tai(1), tai(0)]);

        assert_eq!(series.get(1), Some(&tai(0)));
        assert_eq!(series.get(4), None);
        assert_eq!(series.earliest(), Some(&tai(0)));
        assert_eq!(series.latest(), Some(&tai(2)));
        assert!(series.contains(&tai(1).utc()));
        assert!(!series.contains(&tai(3).utc()));
        assert!(!series.is_sorted());
        assert!(TimeSeries::new(vec![tai(0), tai(0), tai(1)]).is_sorted());
    }

    #[test]
    fn nearest_uses_physical_distance_and_stored_order_for_ties() {
        let series = TimeSeries::new(vec![tai(2), tai(0), tai(4)]);

        assert_eq!(series.nearest(&tai(1).utc()), Some(&tai(2)));
        assert_eq!(series.nearest(&tai(4).utc()), Some(&tai(4)));
        assert_eq!(TimeSeries::<TAI>::new(vec![]).nearest(&tai(0)), None);
    }

    #[test]
    fn within_is_inclusive_and_preserves_stored_order() {
        let series = TimeSeries::new(vec![tai(3), tai(1), tai(2), tai(1), tai(0)]);

        assert_eq!(
            series
                .within(&tai(1).utc(), &tai(2))
                .cloned()
                .collect::<Vec<_>>(),
            vec![tai(1), tai(2), tai(1)]
        );
        assert_eq!(series.within(&tai(2), &tai(1)).count(), 0);
    }

    #[test]
    fn range_is_ascending_and_has_a_duration() {
        let series = TimeSeries::from_range(tai(0), tai(3), TimeDelta::seconds(1));

        assert_eq!(series.len(), 3);
        assert_eq!(series.duration(), TimeDelta::seconds(2));
        assert_eq!(series.as_slice(), &[tai(0), tai(1), tai(2)]);
    }

    #[test]
    fn range_allows_a_single_time() {
        let series = TimeSeries::from_range(tai(0), tai(1), TimeDelta::seconds(2));

        assert_eq!(series.len(), 1);
        assert_eq!(series.duration(), TimeDelta::zero());
        assert_eq!(series.first(), Some(&tai(0)));
        assert_eq!(series.last(), Some(&tai(0)));
    }

    #[test]
    fn range_iter_generates_times_lazily() {
        let mut range = TimeSeries::range_iter(tai(0), tai(3), TimeDelta::seconds(1));

        assert_eq!(range.next(), Some(tai(0)));
        assert_eq!(range.collect::<Vec<_>>(), vec![tai(1), tai(2)]);
    }

    #[test]
    fn range_is_empty_when_step_points_away_from_end() {
        let ascending = TimeSeries::from_range(tai(1), tai(0), TimeDelta::seconds(1));
        let descending = TimeSeries::from_range(tai(0), tai(1), TimeDelta::seconds(-1));

        assert!(ascending.is_empty());
        assert!(descending.is_empty());
    }

    #[test]
    fn range_supports_negative_steps() {
        let series = TimeSeries::from_range(tai(3), tai(0), TimeDelta::seconds(-1));

        assert_eq!(series.as_slice(), &[tai(3), tai(2), tai(1)]);
        assert_eq!(series.duration(), TimeDelta::seconds(2));
    }

    #[test]
    #[should_panic(expected = "time series step must not be zero")]
    fn range_rejects_zero_step() {
        TimeSeries::range_iter(tai(0), tai(1), TimeDelta::zero());
    }

    #[test]
    fn series_converts_scales() {
        let series = TimeSeries::new(vec![tai(0), tai(1)]);
        let utc: TimeSeries<UTC> = series.into();

        assert_eq!(utc.len(), 2);
        assert_eq!(utc.duration(), TimeDelta::seconds(1));
    }

    #[test]
    fn vec_of_times_converts_to_a_series_in_the_target_scale() {
        let utc: TimeSeries<UTC> = vec![tai(0), tai(1)].into();

        assert_eq!(utc.as_slice(), &[tai(0).utc(), tai(1).utc()]);
    }

    #[test]
    fn vec_of_any_times_converts_to_a_series_in_the_target_scale() {
        let utc: TimeSeries<UTC> =
            vec![crate::AnyTime::TAI(tai(0)), crate::AnyTime::TAI(tai(1))].into();

        assert_eq!(utc.as_slice(), &[tai(0).utc(), tai(1).utc()]);
    }

    #[test]
    fn series_iterates_by_reference_and_value() {
        let series = TimeSeries::new(vec![tai(0), tai(1)]);
        assert_eq!(series.iter().count(), 2);
        assert_eq!(series.into_iter().count(), 2);
    }

    #[test]
    fn intervals_follow_stored_order() {
        let series = TimeSeries::new(vec![tai(0), tai(2), tai(1)]);

        assert_eq!(
            series.intervals().collect::<Vec<_>>(),
            vec![TimeDelta::seconds(2), TimeDelta::seconds(-1)]
        );
        assert_eq!(TimeSeries::new(vec![tai(0)]).intervals().count(), 0);
        assert_eq!(TimeSeries::<TAI>::new(vec![]).intervals().count(), 0);
    }

    #[test]
    fn intervals_measure_physical_time_across_utc_leap_seconds() {
        let start = Time::<UTC>::from_isot_str("2016-12-31T00:00:00").unwrap();
        let end = Time::<UTC>::from_isot_str("2017-01-01T00:00:00").unwrap();
        let series = TimeSeries::new(vec![start, end]);

        assert_eq!(
            series.intervals().collect::<Vec<_>>(),
            vec![TimeDelta::seconds(86_401)]
        );
    }

    #[cfg(feature = "serde")]
    #[test]
    fn serde_round_trip() {
        let series = TimeSeries::new(vec![tai(0), tai(1)]);
        let json = serde_json::to_string(&series).unwrap();
        let deserialized = serde_json::from_str::<TimeSeries<TAI>>(&json).unwrap();

        assert_eq!(deserialized.as_slice(), series.as_slice());
    }
}