Struct subset_map::SubsetMap

pub struct SubsetMap<E, P> { /* fields omitted */ }

A map like data structure where the keys are subsets made of combinations of the original sets.

Methods

impl<E, P> SubsetMap<E, P> where
    E: Clone, 

pub fn new<F>(elements: &[E], init: F) -> SubsetMap<E, P> where
    F: FnMut(&[E]) -> Option<P>, 

Creates a new instance where the payloads are initialized with a closure that is passed the current subset of elements.

This function assigns values to those combinations where the given closure init returns Some.

Example

use subset_map::*;

let subset_map = SubsetMap::new(&[1, 2], |x| {
    let sum = x.iter().sum::<i32>();
    if sum == 1 {
        None
    } else {
        Some(sum)
    }
});

assert_eq!(subset_map.get(&[1]), None);
assert_eq!(subset_map.get(&[2]), Some(&2));
assert_eq!(subset_map.get(&[1, 2]), Some(&3));
assert_eq!(subset_map.get(&[]), None);
assert_eq!(subset_map.get(&[2, 1]), None);
assert_eq!(subset_map.get(&[0]), None);
assert_eq!(subset_map.get(&[0, 1]), None);

pub fn fill<F>(elements: &[E], init: F) -> SubsetMap<E, P> where
    F: FnMut(&[E]) -> P, 

Creates a new instance where the payloads are initialized with a closure that is passed the current subset of elements.

This fuction will assign an element to each subset.

Example

use subset_map::*;

let subset_map = SubsetMap::fill(&[1, 2], |x| x.iter().sum::<i32>());
assert_eq!(subset_map.get(&[1]), Some(&1));
assert_eq!(subset_map.get(&[2]), Some(&2));
assert_eq!(subset_map.get(&[1, 2]), Some(&3));
assert_eq!(subset_map.get(&[]), None);
assert_eq!(subset_map.get(&[2, 1]), None);
assert_eq!(subset_map.get(&[0]), None);
assert_eq!(subset_map.get(&[0, 1]), None);

pub fn init<F, X>(elements: &[E], init: F) -> Result<SubsetMap<E, P>, X> where
    F: FnMut(&[E]) -> Result<Option<P>, X>, 

Initializes the SubsetMap with a closure that can fail. This function initializes all those subsets with the returned payloads where the init closure returned an Result::Ok(Option::Some) given that all calls on the closure returned Result::Ok.

Failure of the init closure will result in a failure of the whole initialization process.

Example

The whole initialization process fails.

use subset_map::*;

let subset_map = SubsetMap::init(&[1, 2], |x| {
    let sum = x.iter().sum::<i32>();
    if sum == 1 {
        Ok(Some(sum))
    } else if sum == 2 {
        Ok(None)
    } else {
        Err("bang!")
    }
});

assert_eq!(subset_map, Err("bang!"));

pub fn init_filled<F, X>(elements: &[E], init: F) -> Result<SubsetMap<E, P>, X> where
    F: FnMut(&[E]) -> Result<P, X>, 

Initializes the SubsetMap with a closure that can fail. This function initializes all subsets with the returned payloads given that all calls on the closure returned Result::Ok.

Failure of the init closure will result in a failure of the whole initialization process.

Example

use subset_map::*;

let subset_map = SubsetMap::init_filled(&[1, 2], |x| {
    let sum = x.iter().sum::<i32>();
    if sum != 3 {
        Ok(sum)
    } else {
        Err("bang!")
    }
});

assert_eq!(subset_map, Err("bang!"));

pub fn with_value<F>(elements: &[E], init: F) -> SubsetMap<E, P> where
    F: FnMut() -> P, 

Creates a new instance where the payloads are all initialized with the same value.

Example

use subset_map::*;

let subset_map = SubsetMap::with_value(&[1, 2], || 42);
assert_eq!(subset_map.get(&[1]), Some(&42));
assert_eq!(subset_map.get(&[2]), Some(&42));
assert_eq!(subset_map.get(&[1, 2]), Some(&42));
assert_eq!(subset_map.get(&[]), None);
assert_eq!(subset_map.get(&[2, 1]), None);
assert_eq!(subset_map.get(&[0]), None);
assert_eq!(subset_map.get(&[0, 1]), None);

pub fn with_default(elements: &[E]) -> SubsetMap<E, P> where
    P: Default, 

Creates a new instance where the payloads are all initialized with the Default::default() value of the payload type. Creates a new instance where the payloads are all initialized with the same value.

Example

use subset_map::*;

let subset_map = SubsetMap::with_default(&[1, 2]);
assert_eq!(subset_map.get(&[1]), Some(&0));
assert_eq!(subset_map.get(&[2]), Some(&0));
assert_eq!(subset_map.get(&[1, 2]), Some(&0));
assert_eq!(subset_map.get(&[]), None);
assert_eq!(subset_map.get(&[2, 1]), None);
assert_eq!(subset_map.get(&[0]), None);
assert_eq!(subset_map.get(&[0, 1]), None);

pub fn get<'a>(&'a self, subset: &[E]) -> Option<&'a P> where
    E: Eq, 

Gets a payload by the given subset.

Only "perfect" matches on subset are returned.

The function returns None regardless of whether subset was part of the map or there was no payload assigned to the given subset.

use subset_map::*;

let subset_map = SubsetMap::new(&[1, 2, 3], |x| {
    let payload = x.iter().cloned().collect::<Vec<_>>();
    if payload.len() == 1 {
        None
    } else {
        Some(payload)
    }
});
assert_eq!(subset_map.get(&[1]), None);
assert_eq!(subset_map.get(&[2]), None);
assert_eq!(subset_map.get(&[3]), None);
assert_eq!(subset_map.get(&[1, 2]), Some(&vec![1, 2]));
assert_eq!(subset_map.get(&[2, 3]), Some(&vec![2, 3]));
assert_eq!(subset_map.get(&[1, 3]), Some(&vec![1, 3]));
assert_eq!(subset_map.get(&[1, 2, 3]), Some(&vec![1, 2, 3]));

assert_eq!(subset_map.get(&[]), None);
assert_eq!(subset_map.get(&[7]), None);
assert_eq!(subset_map.get(&[3, 2, 1]), None);
assert_eq!(subset_map.get(&[1, 3, 2]), None);
assert_eq!(subset_map.get(&[3, 2, 1]), None);
assert_eq!(subset_map.get(&[2, 1]), None);

pub fn get_owned(&self, subset: &[E]) -> Option<P::Owned> where
    E: Eq,
    P: ToOwned, 

Looks up a payload by the given subset and returns the corresponding owned value.

The function returns None regardless of wether subset was part of the map or there was no payload assigned to the given subset.

Only perfect matches on subset are returned. See get.

pub fn lookup<'a>(&'a self, subset: &[E]) -> LookupResult<'a, E, P> where
    E: Eq, 

Looks up a subset and maybe returns the assigned payload.

Elements in subset that are not part of the initial set are skipped.

The returned LookupResult may still contain an optional payload. None indicates that the subset was matched but there was no payload for the given subset.

Use this method if you are interested whether there was a matching subset and then process the maybe present payload. Otherwise use find or lookup.

Example

use subset_map::*;

let subset_map = SubsetMap::new(&[1u32, 2, 3], |x| {
    if x == &[2] {
        None
    } else {
        let payload = x.iter().cloned().collect::<Vec<_>>();
        Some(payload)
    }
});

let empty: &[u32] = &[];

// A perfect match with a payload:
let match_result = subset_map.lookup(&[1]);
assert_eq!(match_result.payload(), Some(&vec![1]));
assert_eq!(match_result.excluded_elements(), empty);
assert_eq!(match_result.is_match(), true);
assert_eq!(match_result.is_perfect(), true);
assert_eq!(match_result.is_excluded(), false);

// A perfect match that has no payload:
let match_result = subset_map.lookup(&[2]);
assert_eq!(match_result.payload(), None);
assert_eq!(match_result.excluded_elements(), empty);
assert_eq!(match_result.is_match(), true);
assert_eq!(match_result.is_perfect(), true);
assert_eq!(match_result.is_excluded(), false);

// There is no answer at all:
let match_result = subset_map.lookup(&[42]);
assert_eq!(match_result.is_no_match(), true);
assert_eq!(match_result.is_perfect(), false);
assert_eq!(match_result.is_excluded(), false);
assert_eq!(match_result.excluded_elements(), empty);

// A nearby match but that has a payload:
let match_result = subset_map.lookup(&[3,1]);
assert_eq!(match_result.payload(), Some(&vec![3]));
assert_eq!(match_result.excluded_elements(), &[1]);
assert_eq!(match_result.is_perfect(), false);
assert_eq!(match_result.is_excluded(), true);
assert_eq!(match_result.is_match(), true);

pub fn find<'a>(&'a self, subset: &[E]) -> FindResult<'a, E, P> where
    E: Eq, 

Finds a payload by the given subset.

Elements in subset that are not part of the initial set are skipped.

If there was no match or no payload for the given subset FindResult::NotFound is returned.

Use this function if you are mostly interested in payloads and how they were matched. Otherwise use lookup or get

Example

use subset_map::*;

let subset_map = SubsetMap::new(&[1u32, 2, 3], |x| {
    if x == &[2] {
        None
    } else {
        let payload = x.iter().cloned().collect::<Vec<_>>();
        Some(payload)
    }
});

let empty: &[u32] = &[];

// A perfect match with a payload:
let match_result = subset_map.find(&[1]);

assert_eq!(match_result.payload(), Some(&vec![1]));
assert_eq!(match_result.is_found(), true);
assert_eq!(match_result.is_found_and_perfect(), true);
assert_eq!(match_result.is_found_and_excluded(), false);
assert_eq!(match_result.excluded_elements(), empty);

// A perfect match that has no payload:
let match_result = subset_map.find(&[2]);

assert_eq!(match_result.payload(), None);
assert_eq!(match_result.is_found(), false);
assert_eq!(match_result.is_found_and_perfect(), false);
assert_eq!(match_result.is_found_and_excluded(), false);
assert_eq!(match_result.excluded_elements(), empty);

// There is no answer at all:
let match_result = subset_map.find(&[42]);

assert_eq!(match_result.payload(), None);
assert_eq!(match_result.is_not_found(), true);
assert_eq!(match_result.is_found_and_perfect(), false);
assert_eq!(match_result.is_found_and_excluded(), false);
assert_eq!(match_result.excluded_elements(), empty);

// A nearby match but that has a payload:
let match_result = subset_map.find(&[3,1]);

assert_eq!(match_result.is_found_and_perfect(), false);
assert_eq!(match_result.is_found_and_excluded(), true);
assert_eq!(match_result.is_found(), true);
assert_eq!(match_result.payload(), Some(&vec![3]));
assert_eq!(match_result.excluded_elements(), &[1]);

pub fn filter_values<F>(&mut self, predicate: F) where
    F: FnMut(&P) -> bool, 

Sets the payload of all subsets to None where the given payload does not fulfill the predicate

pub fn walk_values<F>(&self, f: F) where
    F: FnMut(&P), 

Executes the given mutable closure f on the value of each node.

pub fn walk_values_until<F>(&self, f: F) where
    F: FnMut(&P) -> bool, 

Executes the given mutable closure f on the value of each node until the first closure returns false.

pub fn walk_payloads<F>(&self, f: F) where
    F: FnMut(Option<&P>), 

Executes the given mutable closure f on the payload of each node

pub fn walk_payloads_until<F>(&self, f: F) where
    F: FnMut(Option<&P>) -> bool, 

Executes the given mutable closure f on the payload of each node until the first closure returns false.

pub fn walk<F>(&self, f: F) where
    F: FnMut(&[&E], Option<&P>), 

Walk all elements with their payloads

pub fn for_each_value<F>(&self, f: F) where
    F: FnMut(&P), 

Executes the given mutable closure f on the payload of each node

pub fn for_each_payload<F>(&self, f: F) where
    F: FnMut(Option<&P>), 

Executes the given mutable closure f on the payload of each node

pub fn all_subsets_have_values(&self) -> bool

Returns true if there are nodes and all of these have a payload set.

pub fn no_subset_with_value(&self) -> bool

Returns true if there are no subsets or all of these have no payload set.

Example

An empty map has no values:

use subset_map::*;

let subset_map = SubsetMap::<u8, u8>::with_default(&[]);

assert_eq!(subset_map.no_subset_with_value(), true);

An map with a set entry has values:

use subset_map::*;

let subset_map = SubsetMap::<u8, u8>::with_default(&[1]);

assert_eq!(subset_map.no_subset_with_value(), false);

An non empty map where at least one subset has a value:

use subset_map::*;

let mut subset_map = SubsetMap::fill(&[1, 2], |c| c.len());

subset_map.filter_values(|p| *p == 2);

assert_eq!(subset_map.no_subset_with_value(), false);

An non empty map where no subset has a value:

use subset_map::*;

let mut subset_map = SubsetMap::<u8, u8>::with_default(&[1, 2]);

// Set all payloads to `None`
subset_map.filter_values(|p| false);

assert_eq!(subset_map.no_subset_with_value(), true);

pub fn is_empty(&self) -> bool

Returns true if the map is empty and contains no subsets.

pub fn size(&self) -> usize

The number of subsets in this map

Trait Implementations

impl<E: Clone, P: Clone> Clone for SubsetMap<E, P>

fn clone(&self) -> SubsetMap<E, P>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<E: Debug, P: Debug> Debug for SubsetMap<E, P>

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

Formats the value using the given formatter.

impl<E, P> Default for SubsetMap<E, P>

fn default() -> Self

Returns the "default value" for a type.

impl<E: Eq, P: Eq> Eq for SubsetMap<E, P>

impl<E: PartialEq, P: PartialEq> PartialEq<SubsetMap<E, P>> for SubsetMap<E, P>

fn eq(&self, other: &SubsetMap<E, P>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &SubsetMap<E, P>) -> bool

This method tests for !=.

impl<E, P> StructuralEq for SubsetMap<E, P>

impl<E, P> StructuralPartialEq for SubsetMap<E, P>