Struct UnaryRelation 

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

Finite unary relation type. A finite unary relation.

UnaryRelation<T> remains the exact unary relation surface. Current carrier-sensitive exact APIs still accept UnaryRelation<T> arguments for compatibility, but G7 introduces crate::FiniteCarrier as the explicit carrier boundary when a declared domain should stay distinct from support inferred from stored tuples.

The starter implementation uses BTreeSet so iteration order is deterministic.

Examples

use relmath::{FiniteRelation, UnaryRelation};

let mut xs = UnaryRelation::new();
assert!(xs.is_empty());

xs.insert(3);
xs.insert(1);
xs.insert(2);
xs.insert(2);

let ys = UnaryRelation::singleton(3);
let zs = UnaryRelation::from_values([2, 3, 4]);

assert!(xs.contains(&1));
assert_eq!(xs.iter().copied().collect::<Vec<_>>(), vec![1, 2, 3]);
assert_eq!(xs.union(&ys).to_vec(), vec![1, 2, 3]);
assert_eq!(xs.intersection(&zs).to_vec(), vec![2, 3]);
assert_eq!(xs.difference(&zs).to_vec(), vec![1]);
assert!(ys.is_subset(&xs));

Implementations

impl<T: Ord> UnaryRelation<T>

pub fn new() -> Self

Creates an empty unary relation.

pub fn from_values<I>(values: I) -> Self

where I: IntoIterator<Item = T>,

Creates a unary relation from the provided values.

Duplicate values are coalesced into a single stored element.

Examples found in repository

examples/workflow.rs (line 13)

fn main() {
    let step = BinaryRelation::from_pairs([
        ("Draft", "Review"),
        ("Review", "Approved"),
        ("Review", "Rejected"),
    ]);

    let states =
        UnaryRelation::from_values(["Draft", "Review", "Approved", "Rejected", "Archived"]);
    let reachable = step.reflexive_transitive_closure(&states);
    let draft = UnaryRelation::singleton("Draft");

    assert!(reachable.contains(&"Archived", &"Archived"));
    assert!(reachable.contains(&"Draft", &"Approved"));

    println!(
        "reachable from Draft: {:?}",
        reachable.image(&draft).to_vec()
    );
}

examples/family.rs (line 14)

fn main() {
    let parent = BinaryRelation::from_pairs([
        ("Ada", "Bob"),
        ("Ada", "Cara"),
        ("Bob", "Dana"),
        ("Cara", "Eli"),
        ("Dana", "Finn"),
    ]);

    let people = UnaryRelation::from_values(["Ada", "Bob", "Cara", "Dana", "Eli", "Finn"]);
    let grandparent = parent.compose(&parent);
    let ancestor = parent.reflexive_transitive_closure(&people);

    let ada = UnaryRelation::singleton("Ada");
    let reachable_from_ada = ancestor.image(&ada);

    assert!(grandparent.contains(&"Ada", &"Dana"));
    assert!(grandparent.contains(&"Ada", &"Eli"));
    assert!(reachable_from_ada.contains(&"Finn"));

    println!("grandparent pairs: {:?}", grandparent.to_vec());
    println!(
        "people reachable from Ada: {:?}",
        reachable_from_ada.to_vec()
    );
}

examples/relation_view.rs (line 10)

fn main() -> Result<(), relmath::NaryRelationError> {
    let people = UnaryRelation::from_values(["Ada", "Bob"]);
    let parent = BinaryRelation::from_pairs([("Ada", "Bob"), ("Bob", "Cara")]);
    let enrollments =
        NaryRelation::from_rows(["student", "course"], [["Ada", "Math"], ["Bob", "Physics"]])?;

    assert_eq!(tuple_count(&people), 2);
    assert_eq!(tuple_count(&parent), 2);
    assert_eq!(tuple_count(&enrollments), 2);

    assert_eq!(
        people.tuples().copied().collect::<Vec<_>>(),
        vec!["Ada", "Bob"]
    );
    assert_eq!(
        parent.tuples().copied().collect::<Vec<_>>(),
        vec![("Ada", "Bob"), ("Bob", "Cara")]
    );
    assert_eq!(
        enrollments
            .tuples()
            .map(|row| row.to_vec())
            .collect::<Vec<_>>(),
        vec![vec!["Ada", "Math"], vec!["Bob", "Physics"]]
    );

    println!("people: {:?}", people.tuples().copied().collect::<Vec<_>>());
    println!("parent: {:?}", parent.tuples().copied().collect::<Vec<_>>());
    println!(
        "enrollments: {:?}",
        enrollments
            .tuples()
            .map(|row| row.to_vec())
            .collect::<Vec<_>>()
    );

    Ok(())
}

pub fn singleton(value: T) -> Self

Creates a unary relation containing exactly one value.

Examples found in repository

examples/workflow.rs (line 15)

fn main() {
    let step = BinaryRelation::from_pairs([
        ("Draft", "Review"),
        ("Review", "Approved"),
        ("Review", "Rejected"),
    ]);

    let states =
        UnaryRelation::from_values(["Draft", "Review", "Approved", "Rejected", "Archived"]);
    let reachable = step.reflexive_transitive_closure(&states);
    let draft = UnaryRelation::singleton("Draft");

    assert!(reachable.contains(&"Archived", &"Archived"));
    assert!(reachable.contains(&"Draft", &"Approved"));

    println!(
        "reachable from Draft: {:?}",
        reachable.image(&draft).to_vec()
    );
}

examples/family.rs (line 18)

fn main() {
    let parent = BinaryRelation::from_pairs([
        ("Ada", "Bob"),
        ("Ada", "Cara"),
        ("Bob", "Dana"),
        ("Cara", "Eli"),
        ("Dana", "Finn"),
    ]);

    let people = UnaryRelation::from_values(["Ada", "Bob", "Cara", "Dana", "Eli", "Finn"]);
    let grandparent = parent.compose(&parent);
    let ancestor = parent.reflexive_transitive_closure(&people);

    let ada = UnaryRelation::singleton("Ada");
    let reachable_from_ada = ancestor.image(&ada);

    assert!(grandparent.contains(&"Ada", &"Dana"));
    assert!(grandparent.contains(&"Ada", &"Eli"));
    assert!(reachable_from_ada.contains(&"Finn"));

    println!("grandparent pairs: {:?}", grandparent.to_vec());
    println!(
        "people reachable from Ada: {:?}",
        reachable_from_ada.to_vec()
    );
}

examples/access_control.rs (line 23)

fn main() {
    let user_role = BinaryRelation::from_pairs([
        ("ann", "admin"),
        ("bob", "analyst"),
        ("bob", "reviewer"),
        ("cara", "guest"),
    ]);

    let role_permission = BinaryRelation::from_pairs([
        ("admin", "read"),
        ("admin", "write"),
        ("admin", "deploy"),
        ("analyst", "read"),
        ("reviewer", "approve"),
        ("guest", "read"),
    ]);

    let effective_permission = user_role.compose(&role_permission);
    let bob = UnaryRelation::singleton("bob");
    let bob_permissions = effective_permission.image(&bob);

    assert!(effective_permission.contains(&"ann", &"deploy"));
    assert!(bob_permissions.contains(&"approve"));
    assert!(bob_permissions.contains(&"read"));

    println!(
        "effective permissions for bob: {:?}",
        bob_permissions.to_vec()
    );
}

examples/annotated.rs (line 38)

fn main() {
    let confirmations = AnnotatedRelation::from_facts([
        (("Alice", "Math"), SupportCount(1)),
        (("Alice", "Math"), SupportCount(1)),
        (("Bob", "Physics"), SupportCount(1)),
        (("Cara", "Logic"), SupportCount::zero()),
    ]);

    let exact_completed = confirmations.to_binary_relation();
    let alice = UnaryRelation::singleton("Alice");

    assert_eq!(
        confirmations.annotation_of(&("Alice", "Math")),
        Some(&SupportCount(2))
    );
    assert_eq!(exact_completed.image(&alice).to_vec(), vec!["Math"]);
    assert!(!confirmations.contains_fact(&("Cara", "Logic")));
    assert_eq!(
        confirmations
            .iter()
            .map(|(fact, count)| (*fact, count.0))
            .collect::<Vec<_>>(),
        vec![(("Alice", "Math"), 2), (("Bob", "Physics"), 1)]
    );

    println!(
        "stored support counts: {:?}",
        confirmations
            .iter()
            .map(|(fact, count)| (*fact, count.0))
            .collect::<Vec<_>>()
    );
}

examples/provenance.rs (line 19)

fn main() {
    let gene_disease = ProvenanceRelation::from_facts([
        (("BRCA1", "BreastCancer"), "curated_panel"),
        (("BRCA1", "BreastCancer"), "paper_12"),
        (("TP53", "BreastCancer"), "paper_77"),
    ]);

    let disease_drug = relmath::BinaryRelation::from_pairs([
        ("BreastCancer", "Olaparib"),
        ("BreastCancer", "Tamoxifen"),
    ]);

    let supported_gene_disease = gene_disease.to_binary_relation();
    let gene_drug = supported_gene_disease.compose(&disease_drug);
    let brca1 = UnaryRelation::singleton("BRCA1");
    let brca1_witness = gene_disease
        .why(&("BRCA1", "BreastCancer"))
        .expect("expected explanation");

    assert_eq!(
        gene_drug.image(&brca1).to_vec(),
        vec!["Olaparib", "Tamoxifen"]
    );
    assert_eq!(brca1_witness.to_vec(), vec!["curated_panel", "paper_12"]);
    assert!(brca1_witness.contains_token(&"paper_12"));
    assert_eq!(
        gene_disease
            .provenance_of(&("BRCA1", "BreastCancer"))
            .expect("expected explanation")
            .to_vec(),
        brca1_witness.to_vec()
    );
    assert_eq!(
        gene_disease.support().to_vec(),
        vec![("BRCA1", "BreastCancer"), ("TP53", "BreastCancer")]
    );
    assert!(gene_disease.why(&("BRCA1", "Olaparib")).is_none());

    println!(
        "why BRCA1 links to BreastCancer in the base evidence: {:?}",
        brca1_witness.to_vec()
    );
}

examples/valid_time.rs (line 24)

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 insert(&mut self, value: T) -> bool

Inserts a value into the unary relation.

Returns true when the value was not already present.

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

Returns true when the unary relation contains the given value.

Examples found in repository

examples/family.rs (line 23)

fn main() {
    let parent = BinaryRelation::from_pairs([
        ("Ada", "Bob"),
        ("Ada", "Cara"),
        ("Bob", "Dana"),
        ("Cara", "Eli"),
        ("Dana", "Finn"),
    ]);

    let people = UnaryRelation::from_values(["Ada", "Bob", "Cara", "Dana", "Eli", "Finn"]);
    let grandparent = parent.compose(&parent);
    let ancestor = parent.reflexive_transitive_closure(&people);

    let ada = UnaryRelation::singleton("Ada");
    let reachable_from_ada = ancestor.image(&ada);

    assert!(grandparent.contains(&"Ada", &"Dana"));
    assert!(grandparent.contains(&"Ada", &"Eli"));
    assert!(reachable_from_ada.contains(&"Finn"));

    println!("grandparent pairs: {:?}", grandparent.to_vec());
    println!(
        "people reachable from Ada: {:?}",
        reachable_from_ada.to_vec()
    );
}

examples/access_control.rs (line 27)

fn main() {
    let user_role = BinaryRelation::from_pairs([
        ("ann", "admin"),
        ("bob", "analyst"),
        ("bob", "reviewer"),
        ("cara", "guest"),
    ]);

    let role_permission = BinaryRelation::from_pairs([
        ("admin", "read"),
        ("admin", "write"),
        ("admin", "deploy"),
        ("analyst", "read"),
        ("reviewer", "approve"),
        ("guest", "read"),
    ]);

    let effective_permission = user_role.compose(&role_permission);
    let bob = UnaryRelation::singleton("bob");
    let bob_permissions = effective_permission.image(&bob);

    assert!(effective_permission.contains(&"ann", &"deploy"));
    assert!(bob_permissions.contains(&"approve"));
    assert!(bob_permissions.contains(&"read"));

    println!(
        "effective permissions for bob: {:?}",
        bob_permissions.to_vec()
    );
}

pub fn iter(&self) -> impl Iterator<Item = &T>

Returns an iterator over the values in deterministic order.

Iteration order follows T: Ord.

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

where T: Clone,

Returns the union of self and other.

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

where T: Clone,

Returns the intersection of self and other.

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

where T: Clone,

Returns the set difference self \ other.

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

Returns true when every element of self also appears in other.

pub fn to_vec(&self) -> Vec<T>

where T: Clone,

Converts the unary relation into a sorted vector.

Examples found in repository

examples/capability_boundaries.rs (line 16)

fn exact_pairs<R>(relation: &R) -> BinaryRelation<&'static str, &'static str>
where
    R: ExactSupport<(&'static str, &'static str)>
        + ToExactBinaryRelation<&'static str, &'static str>,
{
    assert_eq!(
        relation.exact_support().to_vec(),
        relation.to_binary_relation().to_vec()
    );
    relation.to_binary_relation()
}

examples/workflow.rs (line 22)

fn main() {
    let step = BinaryRelation::from_pairs([
        ("Draft", "Review"),
        ("Review", "Approved"),
        ("Review", "Rejected"),
    ]);

    let states =
        UnaryRelation::from_values(["Draft", "Review", "Approved", "Rejected", "Archived"]);
    let reachable = step.reflexive_transitive_closure(&states);
    let draft = UnaryRelation::singleton("Draft");

    assert!(reachable.contains(&"Archived", &"Archived"));
    assert!(reachable.contains(&"Draft", &"Approved"));

    println!(
        "reachable from Draft: {:?}",
        reachable.image(&draft).to_vec()
    );
}

examples/family.rs (line 28)

fn main() {
    let parent = BinaryRelation::from_pairs([
        ("Ada", "Bob"),
        ("Ada", "Cara"),
        ("Bob", "Dana"),
        ("Cara", "Eli"),
        ("Dana", "Finn"),
    ]);

    let people = UnaryRelation::from_values(["Ada", "Bob", "Cara", "Dana", "Eli", "Finn"]);
    let grandparent = parent.compose(&parent);
    let ancestor = parent.reflexive_transitive_closure(&people);

    let ada = UnaryRelation::singleton("Ada");
    let reachable_from_ada = ancestor.image(&ada);

    assert!(grandparent.contains(&"Ada", &"Dana"));
    assert!(grandparent.contains(&"Ada", &"Eli"));
    assert!(reachable_from_ada.contains(&"Finn"));

    println!("grandparent pairs: {:?}", grandparent.to_vec());
    println!(
        "people reachable from Ada: {:?}",
        reachable_from_ada.to_vec()
    );
}

examples/access_control.rs (line 32)

fn main() {
    let user_role = BinaryRelation::from_pairs([
        ("ann", "admin"),
        ("bob", "analyst"),
        ("bob", "reviewer"),
        ("cara", "guest"),
    ]);

    let role_permission = BinaryRelation::from_pairs([
        ("admin", "read"),
        ("admin", "write"),
        ("admin", "deploy"),
        ("analyst", "read"),
        ("reviewer", "approve"),
        ("guest", "read"),
    ]);

    let effective_permission = user_role.compose(&role_permission);
    let bob = UnaryRelation::singleton("bob");
    let bob_permissions = effective_permission.image(&bob);

    assert!(effective_permission.contains(&"ann", &"deploy"));
    assert!(bob_permissions.contains(&"approve"));
    assert!(bob_permissions.contains(&"read"));

    println!(
        "effective permissions for bob: {:?}",
        bob_permissions.to_vec()
    );
}

examples/annotated.rs (line 44)

fn main() {
    let confirmations = AnnotatedRelation::from_facts([
        (("Alice", "Math"), SupportCount(1)),
        (("Alice", "Math"), SupportCount(1)),
        (("Bob", "Physics"), SupportCount(1)),
        (("Cara", "Logic"), SupportCount::zero()),
    ]);

    let exact_completed = confirmations.to_binary_relation();
    let alice = UnaryRelation::singleton("Alice");

    assert_eq!(
        confirmations.annotation_of(&("Alice", "Math")),
        Some(&SupportCount(2))
    );
    assert_eq!(exact_completed.image(&alice).to_vec(), vec!["Math"]);
    assert!(!confirmations.contains_fact(&("Cara", "Logic")));
    assert_eq!(
        confirmations
            .iter()
            .map(|(fact, count)| (*fact, count.0))
            .collect::<Vec<_>>(),
        vec![(("Alice", "Math"), 2), (("Bob", "Physics"), 1)]
    );

    println!(
        "stored support counts: {:?}",
        confirmations
            .iter()
            .map(|(fact, count)| (*fact, count.0))
            .collect::<Vec<_>>()
    );
}

examples/provenance.rs (line 25)

fn main() {
    let gene_disease = ProvenanceRelation::from_facts([
        (("BRCA1", "BreastCancer"), "curated_panel"),
        (("BRCA1", "BreastCancer"), "paper_12"),
        (("TP53", "BreastCancer"), "paper_77"),
    ]);

    let disease_drug = relmath::BinaryRelation::from_pairs([
        ("BreastCancer", "Olaparib"),
        ("BreastCancer", "Tamoxifen"),
    ]);

    let supported_gene_disease = gene_disease.to_binary_relation();
    let gene_drug = supported_gene_disease.compose(&disease_drug);
    let brca1 = UnaryRelation::singleton("BRCA1");
    let brca1_witness = gene_disease
        .why(&("BRCA1", "BreastCancer"))
        .expect("expected explanation");

    assert_eq!(
        gene_drug.image(&brca1).to_vec(),
        vec!["Olaparib", "Tamoxifen"]
    );
    assert_eq!(brca1_witness.to_vec(), vec!["curated_panel", "paper_12"]);
    assert!(brca1_witness.contains_token(&"paper_12"));
    assert_eq!(
        gene_disease
            .provenance_of(&("BRCA1", "BreastCancer"))
            .expect("expected explanation")
            .to_vec(),
        brca1_witness.to_vec()
    );
    assert_eq!(
        gene_disease.support().to_vec(),
        vec![("BRCA1", "BreastCancer"), ("TP53", "BreastCancer")]
    );
    assert!(gene_disease.why(&("BRCA1", "Olaparib")).is_none());

    println!(
        "why BRCA1 links to BreastCancer in the base evidence: {:?}",
        brca1_witness.to_vec()
    );
}

Additional examples can be found in:

• examples/carrier.rs
• examples/valid_time.rs

Trait Implementations

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

fn clone(&self) -> UnaryRelation<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 UnaryRelation<T>

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

Formats the value using the given formatter.

impl<T: Ord> Default for UnaryRelation<T>

fn default() -> Self

Returns the “default value” for a type.

impl<T: Ord> Extend<T> for UnaryRelation<T>

fn extend<I: IntoIterator<Item = 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> FiniteRelation for UnaryRelation<T>

fn len(&self) -> usize

Returns the number of stored tuples in the relation.

fn is_empty(&self) -> bool

Returns true when the relation contains no tuples.

impl<T: Ord> FromIterator<T> for UnaryRelation<T>

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

Creates a value from an iterator.

impl<'a, T: Ord> IntoIterator for &'a UnaryRelation<T>

type Item = &'a T

The type of the elements being iterated over.

type IntoIter = Iter<'a, T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T: Ord> IntoIterator for UnaryRelation<T>

type Item = T

The type of the elements being iterated over.

type IntoIter = IntoIter<T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

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

fn eq(&self, other: &UnaryRelation<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: Ord> RelationView for UnaryRelation<T>

type Tuple<'a> = &'a T where Self: 'a

Borrowed tuple item yielded by Self::tuples.

fn tuples(&self) -> impl Iterator<Item = Self::Tuple<'_>>

Returns the stored tuples in deterministic order.

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

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