Struct TimeWindow

pub struct TimeWindow { /* private fields */ }

An interval or range of time: [start,end). Debug-asserts ensure that start <= end. If compiled in release mode, the invariant of start <= end is maintained, by correcting invalid use of the API (and setting end to start).

Implementations

impl TimeWindow

pub fn new(start: Time, end: Time) -> Self

Constructs a new TimeWindow. debug_asserts that start < end. Sets end to start in release mode if start > end.

pub fn new_checked(start: Time, end: Time) -> Result<Self, TimeWindowError>

Constructs a new TimeWindow. Validates that start <= end and returns an error if not.

Examples

assert!(TimeWindow::new_checked(Time::hours(1), Time::hours(2)).is_ok());
assert_eq!(
    Err(TimeWindowError::StartAfterEnd),
    TimeWindow::new_checked(Time::hours(2), Time::hours(1))
);

pub fn epoch_to(end: Time) -> Self

Returns TimeWindow with range [Time::EPOCH, end)

pub fn from_minutes(a: i64, b: i64) -> Self

pub fn from_seconds(a: i64, b: i64) -> Self

pub fn from_length_starting_at(length: Duration, start: Time) -> Self

Creates time window from start time and length.

Negative lengths are treated as Duration::ZERO.

Examples

assert_eq!(
    TimeWindow::from_seconds(1, 3),
    TimeWindow::from_length_starting_at(Duration::seconds(2), Time::seconds(1))
);
assert_eq!(
    TimeWindow::from_seconds(1, 1),
    TimeWindow::from_length_starting_at(Duration::seconds(-2), Time::seconds(1))
);

pub fn from_length_ending_at(length: Duration, end: Time) -> Self

Creates time window from length and end time.

Negative lengths are treated as Duration::ZERO.

Examples

assert_eq!(
    TimeWindow::from_seconds(1, 3),
    TimeWindow::from_length_ending_at(Duration::seconds(2), Time::seconds(3))
);
assert_eq!(
    TimeWindow::from_seconds(3, 3),
    TimeWindow::from_length_ending_at(Duration::seconds(-2), Time::seconds(3))
);

pub const fn instant(time: Time) -> Self

pub const fn widest() -> Self

pub fn instant_seconds(seconds: i64) -> Self

pub const fn start(&self) -> Time

pub const fn end(&self) -> Time

pub fn length(&self) -> Duration

pub fn with_start(&self, new_start: Time) -> Self

Creates a new TimeWindow with start set to new_start. If new_start is greater than or equal to end the start will be set equal to end.

pub fn with_end(&self, new_end: Time) -> Self

Creates a new TimeWindow with end set to new_end. If new_end is smaller or equal to start, the end will be set to start.

pub fn prepone_start_to(&self, new_start: Time) -> Self

Creates a new TimeWindow with the start preponed to the given value. If new_start isn’t earlier than the current time window start, a copy of self is returned.

Examples

let x = TimeWindow::from_seconds(4, 5);
assert_eq!(
    TimeWindow::from_seconds(3, 5),
    x.prepone_start_to(Time::seconds(3))
);
assert_eq!(
    TimeWindow::from_seconds(4, 5),
    x.prepone_start_to(Time::seconds(6))
);

pub fn prepone_start_by(&self, duration: Duration) -> Self

Creates a new TimeWindow with the start preponed by the given duration.

Negative durations are treated as Duration::ZERO.

Examples

let tw = TimeWindow::from_seconds(8, 9);
assert_eq!(
    TimeWindow::from_seconds(5, 9),
    tw.prepone_start_by(Duration::seconds(3))
);
assert_eq!(
    TimeWindow::from_seconds(8, 9),
    tw.prepone_start_by(Duration::seconds(-3))
);

pub fn prepone_start_extend_to(&self, new_length: Duration) -> Self

Creates a new TimeWindow with the start preponed so that the new time window length matches the given value.

Returns a copy of self if the new length is smaller than Self::length().

Examples

let tw = TimeWindow::from_seconds(1, 3);
assert_eq!(
    TimeWindow::from_seconds(1, 3),
    tw.prepone_start_extend_to(Duration::seconds(-1))
);
assert_eq!(
    TimeWindow::from_seconds(1, 3),
    tw.prepone_start_extend_to(Duration::seconds(0))
);
assert_eq!(
    TimeWindow::from_seconds(-2, 3),
    tw.prepone_start_extend_to(Duration::seconds(5))
);

pub fn postpone_start_to(&self, new_start: Time) -> Self

Creates a new TimeWindow with the start postponed to the given value.

Returns a copy of self when the given value isn’t later than the current time window start. Will never postpone the start past the end of the time window.

Examples

let tw = TimeWindow::from_seconds(1, 3);
assert_eq!(
    TimeWindow::from_seconds(1, 3),
    tw.postpone_start_to(Time::EPOCH)
);
assert_eq!(
    TimeWindow::from_seconds(2, 3),
    tw.postpone_start_to(Time::seconds(2))
);
assert_eq!(
    TimeWindow::from_seconds(3, 3),
    tw.postpone_start_to(Time::seconds(3))
);

pub fn postpone_start_by(&self, duration: Duration) -> Self

Creates a new TimeWindow with the start postponed by the given duration.

Negative durations are treated as Duration::ZERO. Will not postpone start further than end.

Examples

let tw = TimeWindow::from_seconds(1, 5);
assert_eq!(
    TimeWindow::from_seconds(4, 5),
    tw.postpone_start_by(Duration::seconds(3))
);
assert_eq!(
    TimeWindow::from_seconds(5, 5),
    tw.postpone_start_by(Duration::seconds(30))
);
assert_eq!(
    TimeWindow::from_seconds(1, 5),
    tw.postpone_start_by(Duration::seconds(-3))
);

pub fn postpone_start_shrink_to(&self, new_length: Duration) -> Self

Creates a new TimeWindow with the start postponed so that the new time window length matches the given value.

Returns a copy of self if the new length is smaller than the current one. Negative length will set the resulting time window length to zero.

Examples

let tw = TimeWindow::from_seconds(1, 3);
assert_eq!(
    TimeWindow::from_seconds(3, 3),
    tw.postpone_start_shrink_to(Duration::seconds(-1))
);
assert_eq!(
    TimeWindow::from_seconds(3, 3),
    tw.postpone_start_shrink_to(Duration::seconds(0))
);
assert_eq!(
    TimeWindow::from_seconds(2, 3),
    tw.postpone_start_shrink_to(Duration::seconds(1))
);
assert_eq!(
    TimeWindow::from_seconds(1, 3),
    tw.postpone_start_shrink_to(Duration::seconds(5))
);

pub fn prepone_end_to(&self, new_end: Time) -> Self

Creates a new TimeWindow with the end preponed to the given value.

Returns a copy of self when the given value isn’t earlier than the current time window end. Will never prepone the end more than to the start of the time window.

Examples

let tw = TimeWindow::from_seconds(1, 3);
assert_eq!(
    TimeWindow::from_seconds(1, 3),
    tw.prepone_end_to(Time::seconds(4))
);
assert_eq!(
    TimeWindow::from_seconds(1, 2),
    tw.prepone_end_to(Time::seconds(2))
);
assert_eq!(
    TimeWindow::from_seconds(1, 1),
    tw.prepone_end_to(Time::EPOCH)
);

pub fn prepone_end_by(&self, duration: Duration) -> Self

Creates a new TimeWindow with the end preponed by the given duration.

Negative durations are treated as Duration::ZERO. Will not prepone end before end.

Examples

let tw = TimeWindow::from_seconds(4, 9);
assert_eq!(
    TimeWindow::from_seconds(4, 6),
    tw.prepone_end_by(Duration::seconds(3))
);
assert_eq!(
    TimeWindow::from_seconds(4, 4),
    tw.prepone_end_by(Duration::seconds(30))
);
assert_eq!(
    TimeWindow::from_seconds(4, 9),
    tw.prepone_end_by(Duration::seconds(-3))
);

pub fn prepone_end_shrink_to(&self, new_length: Duration) -> Self

Creates a new TimeWindow with the end preponed so that the new time window length matches the given value.

Returns a copy of self if the new length is smaller than the current one. Negative length will set the resulting time window length to zero.

Examples

let tw = TimeWindow::from_seconds(1, 3);
assert_eq!(
    TimeWindow::from_seconds(1, 1),
    tw.prepone_end_shrink_to(Duration::seconds(-1))
);
assert_eq!(
    TimeWindow::from_seconds(1, 1),
    tw.prepone_end_shrink_to(Duration::seconds(0))
);
assert_eq!(
    TimeWindow::from_seconds(1, 2),
    tw.prepone_end_shrink_to(Duration::seconds(1))
);
assert_eq!(
    TimeWindow::from_seconds(1, 3),
    tw.prepone_end_shrink_to(Duration::seconds(5))
);

pub fn postpone_end_to(&self, new_end: Time) -> Self

Creates a new TimeWindow with the end postponed to the given value. If new_end isn’t later than the current time window end, a copy of self is returned.

Examples

let x = TimeWindow::from_seconds(1, 2);
assert_eq!(
    TimeWindow::from_seconds(1, 3),
    x.postpone_end_to(Time::seconds(3))
);
assert_eq!(
    TimeWindow::from_seconds(1, 2),
    x.postpone_end_to(Time::EPOCH)
);

pub fn postpone_end_by(&self, duration: Duration) -> Self

Creates a new TimeWindow with the end postponed by the given duration.

Negative durations are treated as Duration::ZERO.

Examples

let tw = TimeWindow::from_seconds(1, 2);
assert_eq!(
    TimeWindow::from_seconds(1, 5),
    tw.postpone_end_by(Duration::seconds(3))
);
assert_eq!(
    TimeWindow::from_seconds(1, 2),
    tw.postpone_end_by(Duration::seconds(-3))
);

pub fn postpone_end_extend_to(&self, new_length: Duration) -> Self

Creates a new TimeWindow with the end postponed so that the new time window length matches the given value.

Returns a copy of self if the new length is smaller than Self::length().

Examples

let tw = TimeWindow::from_seconds(1, 3);
assert_eq!(
    TimeWindow::from_seconds(1, 3),
    tw.postpone_end_extend_to(Duration::seconds(-1))
);
assert_eq!(
    TimeWindow::from_seconds(1, 3),
    tw.postpone_end_extend_to(Duration::seconds(0))
);
assert_eq!(
    TimeWindow::from_seconds(1, 6),
    tw.postpone_end_extend_to(Duration::seconds(5))
);

pub fn contains(&self, that: Time) -> bool

Returns true if this time window contains the given time.

Examples

let mut x = TimeWindow::from_seconds(5, 10);
assert!(!x.contains(Time::seconds(4)));
assert!(x.contains(Time::seconds(5)));
assert!(x.contains(Time::seconds(7)));
assert!(x.contains(Time::seconds(10)));
assert!(!x.contains(Time::seconds(11)));

pub fn overlaps(&self, that: &TimeWindow) -> bool

Returns true if this time window overlaps with another one

Examples

let mut x = TimeWindow::from_seconds(5, 10);
assert!(x.overlaps(&TimeWindow::from_seconds(5, 10)));
assert!(x.overlaps(&TimeWindow::from_seconds(3, 12)));
assert!(x.overlaps(&TimeWindow::from_seconds(6, 9)));
assert!(x.overlaps(&TimeWindow::from_seconds(6, 12)));
assert!(x.overlaps(&TimeWindow::from_seconds(3, 9)));
assert!(!x.overlaps(&TimeWindow::from_seconds(1, 4)));
assert!(!x.overlaps(&TimeWindow::from_seconds(1, 5)));
assert!(!x.overlaps(&TimeWindow::from_seconds(10, 15)));
assert!(!x.overlaps(&TimeWindow::from_seconds(11, 15)));

pub fn intersect(&self, that: &TimeWindow) -> Option<TimeWindow>

Returns time window that is an intersection between this time window and another one. Returns None if time windows don’t overlap.

Examples

let x = TimeWindow::from_seconds(5, 10);
assert_eq!(
    Some(TimeWindow::from_seconds(5, 10)),
    x.intersect(&TimeWindow::from_seconds(5, 10)),
    "time windows are equal"
);
assert_eq!(
    Some(TimeWindow::from_seconds(5, 10)),
    x.intersect(&TimeWindow::from_seconds(3, 12)),
    "that contains x"
);
assert_eq!(
    Some(TimeWindow::from_seconds(6, 9)),
    x.intersect(&TimeWindow::from_seconds(6, 9)),
    "x contains that"
);
assert_eq!(
    Some(TimeWindow::from_seconds(6, 10)),
    x.intersect(&TimeWindow::from_seconds(6, 12))
);
assert_eq!(
    Some(TimeWindow::from_seconds(5, 9)),
    x.intersect(&TimeWindow::from_seconds(3, 9))
);
assert_eq!(
    None,
    x.intersect(&TimeWindow::from_seconds(1, 4)),
    "that is before x"
);
assert_eq!(
    Some(TimeWindow::from_seconds(5, 5)),
    x.intersect(&TimeWindow::from_seconds(1, 5)),
    "single-point intersection"
);
assert_eq!(
    Some(TimeWindow::from_seconds(10, 10)),
    x.intersect(&TimeWindow::from_seconds(10, 15)),
    "single-point intersection"
);
assert_eq!(
    None,
    x.intersect(&TimeWindow::from_seconds(11, 15)),
    "that is after x"
);

pub fn shift(&mut self, duration: Duration)

Shifts this time window by duration into the future. Affects both start and end equally, leaving the length untouched.

Examples

let mut tw = TimeWindow::new(Time::EPOCH, Time::minutes(15));
// shift to the future
tw.shift(Duration::minutes(30));
assert_eq!(TimeWindow::new(Time::minutes(30), Time::minutes(45)), tw);
// shift into the past
tw.shift(-Duration::minutes(15));
assert_eq!(TimeWindow::new(Time::minutes(15), Time::minutes(30)), tw);

Trait Implementations

impl Clone for TimeWindow

fn clone(&self) -> TimeWindow

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TimeWindow

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for TimeWindow

fn default() -> TimeWindow

Returns the “default value” for a type.

impl From<(Time, Time)> for TimeWindow

fn from((start, end): (Time, Time)) -> Self

Converts to this type from the input type.

impl From<TimeWindow> for (Time, Time)

fn from(tw: TimeWindow) -> Self

Converts to this type from the input type.

impl Hash for TimeWindow

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for TimeWindow

fn eq(&self, other: &TimeWindow) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for TimeWindow

impl Eq for TimeWindow

impl StructuralPartialEq for TimeWindow