Struct Interval 

pub struct Interval<T: Ord> { /* private fields */ }

Deterministic half-open interval over an ordered endpoint domain.

Interval<T> represents [start, end): start is included and end is excluded. The interval is valid only when start < end.

Intervals derive Ord, so ordered collections such as BTreeSet keep them in lexicographic (start, end) order. That is the deterministic order later temporal coalescing code should use.

Examples

use std::collections::BTreeSet;

use relmath::temporal::Interval;

let windows = BTreeSet::from([
    Interval::new(3, 5).expect("expected valid interval"),
    Interval::new(1, 4).expect("expected valid interval"),
    Interval::new(1, 3).expect("expected valid interval"),
]);

assert_eq!(
    windows.into_iter().collect::<Vec<_>>(),
    vec![
        Interval::new(1, 3).expect("expected valid interval"),
        Interval::new(1, 4).expect("expected valid interval"),
        Interval::new(3, 5).expect("expected valid interval"),
    ]
);

Implementations

impl<T: Ord> Interval<T>

pub fn new(start: T, end: T) -> Result<Self, IntervalError<T>>

Creates one valid half-open interval [start, end).

Returns an explicit error when start >= end.

Examples

use relmath::temporal::{Interval, IntervalError};

let valid = Interval::new(2, 5).expect("expected valid interval");
assert_eq!(valid.start(), &2);
assert_eq!(valid.end(), &5);

assert_eq!(
    Interval::new(5, 2),
    Err(IntervalError::InvalidBounds { start: 5, end: 2 })
);

Examples found in repository

examples/intervals.rs (line 6)

fn main() {
    let draft_review = Interval::new(9, 12).expect("expected valid interval");
    let approval = Interval::new(12, 15).expect("expected valid interval");
    let audit = Interval::new(11, 13).expect("expected valid interval");

    let full_shift = draft_review
        .coalesce(&approval)
        .expect("adjacent intervals should coalesce");
    let audit_window = full_shift
        .restrict_to(&audit)
        .expect("expected non-empty overlap");

    assert!(draft_review.contains(&9));
    assert!(!draft_review.contains(&12));
    assert!(!draft_review.overlaps(&approval));
    assert!(draft_review.is_adjacent_to(&approval));
    assert_eq!(
        audit_window,
        Interval::new(11, 13).expect("expected valid interval")
    );

    println!(
        "full shift: {:?}, audit overlap: {:?}",
        full_shift, audit_window
    );
}

examples/capability_boundaries.rs (line 34)

fn main() {
    let evidence = ProvenanceRelation::from_facts([
        (("alice", "review"), "directory"),
        (("bob", "approve"), "policy"),
    ]);
    let permissions = AnnotatedRelation::from_facts([
        (("alice", "review"), BooleanSemiring::TRUE),
        (("bob", "approve"), BooleanSemiring::TRUE),
    ]);
    let schedule = ValidTimeRelation::from_facts([
        (
            ("alice", "review"),
            Interval::new(1, 3).expect("expected valid interval"),
        ),
        (
            ("bob", "approve"),
            Interval::new(2, 4).expect("expected valid interval"),
        ),
    ]);

    let exact_evidence = exact_pairs(&evidence);
    let exact_permissions = exact_pairs(&permissions);
    let exact_schedule = exact_pairs(&schedule);

    assert_eq!(
        exact_evidence.to_vec(),
        vec![("alice", "review"), ("bob", "approve")]
    );
    assert_eq!(exact_permissions.to_vec(), exact_evidence.to_vec());
    assert_eq!(exact_schedule.to_vec(), exact_evidence.to_vec());

    assert_eq!(
        evidence
            .why(&("alice", "review"))
            .expect("expected witness")
            .to_vec(),
        vec!["directory"]
    );
    assert_eq!(
        permissions.annotation_of(&("alice", "review")),
        Some(&BooleanSemiring::TRUE)
    );
    assert_eq!(
        schedule
            .valid_time_of(&("alice", "review"))
            .expect("expected interval support")
            .to_vec(),
        vec![Interval::new(1, 3).expect("expected valid interval")]
    );

    println!(
        "witness={:?}, annotation={:?}, interval_support={:?}, exact_support={:?}",
        evidence
            .why(&("alice", "review"))
            .expect("expected witness")
            .to_vec(),
        permissions.annotation_of(&("alice", "review")),
        schedule
            .valid_time_of(&("alice", "review"))
            .expect("expected interval support")
            .to_vec(),
        exact_schedule.to_vec()
    );
}

examples/valid_time.rs (line 12)

fn main() {
    let assignments = ValidTimeRelation::from_facts([
        (
            ("alice", "review"),
            Interval::new(1, 3).expect("expected valid interval"),
        ),
        (
            ("alice", "review"),
            Interval::new(3, 5).expect("expected valid interval"),
        ),
        (
            ("bob", "approve"),
            Interval::new(2, 4).expect("expected valid interval"),
        ),
    ]);

    let alice = UnaryRelation::singleton("alice");
    let fact_support = assignments.support();
    let exact_support = assignments.to_binary_relation();
    let audit_window = Interval::new(2, 4).expect("expected valid interval");
    let active_at_three = assignments.snapshot_at(&3);
    let audit_assignments = assignments.restrict_to(&audit_window);

    assert_eq!(
        assignments
            .valid_time_of(&("alice", "review"))
            .expect("expected support")
            .to_vec(),
        vec![Interval::new(1, 5).expect("expected valid interval")]
    );
    assert!(assignments.is_active_at(&("alice", "review"), &4));
    assert!(!assignments.is_active_at(&("alice", "review"), &5));
    assert_eq!(
        active_at_three.to_vec(),
        vec![("alice", "review"), ("bob", "approve")]
    );
    assert_eq!(
        fact_support.to_vec(),
        vec![("alice", "review"), ("bob", "approve")]
    );
    assert_eq!(
        audit_assignments
            .valid_time_of(&("alice", "review"))
            .expect("expected support")
            .to_vec(),
        vec![Interval::new(2, 4).expect("expected valid interval")]
    );
    assert_eq!(
        audit_assignments.to_binary_relation().to_vec(),
        vec![("alice", "review"), ("bob", "approve")]
    );
    assert_eq!(exact_support.image(&alice).to_vec(), vec!["review"]);

    println!(
        "fact support: {:?}; active at t=3: {:?}; audit restriction: {:?}",
        fact_support.to_vec(),
        active_at_three.to_vec(),
        audit_assignments
            .valid_time_of(&("alice", "review"))
            .expect("expected support")
            .to_vec()
    );
}

pub fn start(&self) -> &T

Returns the inclusive lower bound of the interval.

pub fn end(&self) -> &T

Returns the exclusive upper bound of the interval.

pub fn contains(&self, point: &T) -> bool

Returns true when point lies inside [start, end).

Examples

use relmath::temporal::Interval;

let window = Interval::new(10, 12).expect("expected valid interval");

assert!(window.contains(&10));
assert!(window.contains(&11));
assert!(!window.contains(&12));

Examples found in repository

examples/intervals.rs (line 17)

fn main() {
    let draft_review = Interval::new(9, 12).expect("expected valid interval");
    let approval = Interval::new(12, 15).expect("expected valid interval");
    let audit = Interval::new(11, 13).expect("expected valid interval");

    let full_shift = draft_review
        .coalesce(&approval)
        .expect("adjacent intervals should coalesce");
    let audit_window = full_shift
        .restrict_to(&audit)
        .expect("expected non-empty overlap");

    assert!(draft_review.contains(&9));
    assert!(!draft_review.contains(&12));
    assert!(!draft_review.overlaps(&approval));
    assert!(draft_review.is_adjacent_to(&approval));
    assert_eq!(
        audit_window,
        Interval::new(11, 13).expect("expected valid interval")
    );

    println!(
        "full shift: {:?}, audit overlap: {:?}",
        full_shift, audit_window
    );
}

pub fn overlaps(&self, other: &Self) -> bool

Returns true when the intervals overlap with non-empty intersection.

Directly adjacent intervals do not overlap under half-open semantics.

Examples

use relmath::temporal::Interval;

let left = Interval::new(1, 3).expect("expected valid interval");
let overlap = Interval::new(2, 4).expect("expected valid interval");
let adjacent = Interval::new(3, 5).expect("expected valid interval");

assert!(left.overlaps(&overlap));
assert!(!left.overlaps(&adjacent));

Examples found in repository

examples/intervals.rs (line 19)

fn main() {
    let draft_review = Interval::new(9, 12).expect("expected valid interval");
    let approval = Interval::new(12, 15).expect("expected valid interval");
    let audit = Interval::new(11, 13).expect("expected valid interval");

    let full_shift = draft_review
        .coalesce(&approval)
        .expect("adjacent intervals should coalesce");
    let audit_window = full_shift
        .restrict_to(&audit)
        .expect("expected non-empty overlap");

    assert!(draft_review.contains(&9));
    assert!(!draft_review.contains(&12));
    assert!(!draft_review.overlaps(&approval));
    assert!(draft_review.is_adjacent_to(&approval));
    assert_eq!(
        audit_window,
        Interval::new(11, 13).expect("expected valid interval")
    );

    println!(
        "full shift: {:?}, audit overlap: {:?}",
        full_shift, audit_window
    );
}

pub fn is_adjacent_to(&self, other: &Self) -> bool

Returns true when the intervals touch at exactly one boundary.

Adjacent intervals are not overlapping, but later valid-time layers may still coalesce them into one canonical support fragment.

Examples found in repository

examples/intervals.rs (line 20)

fn main() {
    let draft_review = Interval::new(9, 12).expect("expected valid interval");
    let approval = Interval::new(12, 15).expect("expected valid interval");
    let audit = Interval::new(11, 13).expect("expected valid interval");

    let full_shift = draft_review
        .coalesce(&approval)
        .expect("adjacent intervals should coalesce");
    let audit_window = full_shift
        .restrict_to(&audit)
        .expect("expected non-empty overlap");

    assert!(draft_review.contains(&9));
    assert!(!draft_review.contains(&12));
    assert!(!draft_review.overlaps(&approval));
    assert!(draft_review.is_adjacent_to(&approval));
    assert_eq!(
        audit_window,
        Interval::new(11, 13).expect("expected valid interval")
    );

    println!(
        "full shift: {:?}, audit overlap: {:?}",
        full_shift, audit_window
    );
}

pub fn can_coalesce_with(&self, other: &Self) -> bool

Returns true when the intervals can be coalesced.

This is true for overlapping or directly adjacent intervals.

impl<T: Ord + Clone> Interval<T>

pub fn intersection(&self, other: &Self) -> Option<Self>

Returns the non-empty intersection of two intervals.

When the intervals are disjoint or only touch at one boundary, this returns None.

Examples

use relmath::temporal::Interval;

let left = Interval::new(1, 4).expect("expected valid interval");
let right = Interval::new(3, 6).expect("expected valid interval");

assert_eq!(
    left.intersection(&right),
    Some(Interval::new(3, 4).expect("expected valid interval"))
);

pub fn restrict_to(&self, constraint: &Self) -> Option<Self>

Restricts this interval to the overlap with constraint.

This is an interval-level helper for later temporal restrict_to behavior on valid-time relations.

Examples found in repository

examples/intervals.rs (line 14)

fn main() {
    let draft_review = Interval::new(9, 12).expect("expected valid interval");
    let approval = Interval::new(12, 15).expect("expected valid interval");
    let audit = Interval::new(11, 13).expect("expected valid interval");

    let full_shift = draft_review
        .coalesce(&approval)
        .expect("adjacent intervals should coalesce");
    let audit_window = full_shift
        .restrict_to(&audit)
        .expect("expected non-empty overlap");

    assert!(draft_review.contains(&9));
    assert!(!draft_review.contains(&12));
    assert!(!draft_review.overlaps(&approval));
    assert!(draft_review.is_adjacent_to(&approval));
    assert_eq!(
        audit_window,
        Interval::new(11, 13).expect("expected valid interval")
    );

    println!(
        "full shift: {:?}, audit overlap: {:?}",
        full_shift, audit_window
    );
}

pub fn coalesce(&self, other: &Self) -> Option<Self>

Coalesces two overlapping or directly adjacent intervals.

Returns None when the intervals are strictly disjoint.

Examples

use relmath::temporal::Interval;

let morning = Interval::new(9, 12).expect("expected valid interval");
let afternoon = Interval::new(12, 15).expect("expected valid interval");

assert_eq!(
    morning.coalesce(&afternoon),
    Some(Interval::new(9, 15).expect("expected valid interval"))
);

Examples found in repository

examples/intervals.rs (line 11)

fn main() {
    let draft_review = Interval::new(9, 12).expect("expected valid interval");
    let approval = Interval::new(12, 15).expect("expected valid interval");
    let audit = Interval::new(11, 13).expect("expected valid interval");

    let full_shift = draft_review
        .coalesce(&approval)
        .expect("adjacent intervals should coalesce");
    let audit_window = full_shift
        .restrict_to(&audit)
        .expect("expected non-empty overlap");

    assert!(draft_review.contains(&9));
    assert!(!draft_review.contains(&12));
    assert!(!draft_review.overlaps(&approval));
    assert!(draft_review.is_adjacent_to(&approval));
    assert_eq!(
        audit_window,
        Interval::new(11, 13).expect("expected valid interval")
    );

    println!(
        "full shift: {:?}, audit overlap: {:?}",
        full_shift, audit_window
    );
}

Trait Implementations

impl<T: Clone + Ord> Clone for Interval<T>

fn clone(&self) -> Interval<T>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Debug + Ord> Debug for Interval<T>

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

Formats the value using the given formatter.

impl<T: Ord + Clone> Extend<Interval<T>> for ValidTimeSupport<T>

fn extend<I: IntoIterator<Item = Interval<T>>>(&mut self, iter: I)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<T: Ord + Clone> FromIterator<Interval<T>> for ValidTimeSupport<T>

fn from_iter<I: IntoIterator<Item = Interval<T>>>(iter: I) -> Self

Creates a value from an iterator.

impl<T: Ord + Ord> Ord for Interval<T>

fn cmp(&self, other: &Interval<T>) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<T: PartialEq + Ord> PartialEq for Interval<T>

fn eq(&self, other: &Interval<T>) -> 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<T: PartialOrd + Ord> PartialOrd for Interval<T>

fn partial_cmp(&self, other: &Interval<T>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T: Eq + Ord> Eq for Interval<T>

impl<T: Ord> StructuralPartialEq for Interval<T>