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.lookup(&[1]), None);
assert_eq!(subset_map.lookup(&[2]), Some(&2));
assert_eq!(subset_map.lookup(&[1, 2]), Some(&3));
assert_eq!(subset_map.lookup(&[]), None);
assert_eq!(subset_map.lookup(&[2, 1]), None);
assert_eq!(subset_map.lookup(&[0]), None);
assert_eq!(subset_map.lookup(&[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.lookup(&[1]), Some(&1));
assert_eq!(subset_map.lookup(&[2]), Some(&2));
assert_eq!(subset_map.lookup(&[1, 2]), Some(&3));
assert_eq!(subset_map.lookup(&[]), None);
assert_eq!(subset_map.lookup(&[2, 1]), None);
assert_eq!(subset_map.lookup(&[0]), None);
assert_eq!(subset_map.lookup(&[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.lookup(&[1]), Some(&42));
assert_eq!(subset_map.lookup(&[2]), Some(&42));
assert_eq!(subset_map.lookup(&[1, 2]), Some(&42));
assert_eq!(subset_map.lookup(&[]), None);
assert_eq!(subset_map.lookup(&[2, 1]), None);
assert_eq!(subset_map.lookup(&[0]), None);
assert_eq!(subset_map.lookup(&[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.lookup(&[1]), Some(&0));
assert_eq!(subset_map.lookup(&[2]), Some(&0));
assert_eq!(subset_map.lookup(&[1, 2]), Some(&0));
assert_eq!(subset_map.lookup(&[]), None);
assert_eq!(subset_map.lookup(&[2, 1]), None);
assert_eq!(subset_map.lookup(&[0]), None);
assert_eq!(subset_map.lookup(&[0, 1]), None);

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

Looks up a payload by the given subset.

Only "perfect" matches on subset are returned.

The function returns None regardless of wether 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.lookup(&[1]), None);
assert_eq!(subset_map.lookup(&[2]), None);
assert_eq!(subset_map.lookup(&[3]), None);
assert_eq!(subset_map.lookup(&[1, 2]), Some(&vec![1, 2]));
assert_eq!(subset_map.lookup(&[2, 3]), Some(&vec![2, 3]));
assert_eq!(subset_map.lookup(&[1, 3]), Some(&vec![1, 3]));
assert_eq!(subset_map.lookup(&[1, 2, 3]), Some(&vec![1, 2, 3]));

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

pub fn lookup_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 lookup.

pub fn find<'a>(&'a self, subset: &'a [E]) -> MatchResult<'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 no element of the input set matched None is returned. The returned MatchResult may still contain no value(None) if there was no value assigned to the resolved subset.

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.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.find(&[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.find(&[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.find(&[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 filter_payloads<F>(&mut self, predicate: F) where
    F: FnMut(&P) -> bool, 

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

pub fn is_empty(&self) -> bool

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

pub fn size(&self) -> usize

The number of subsets in this map

Trait Implementations

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

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

Formats the value using the given formatter.

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: PartialEq, P: PartialEq> PartialEq for SubsetMap<E, P>

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

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

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

This method tests for !=.

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

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

fn default() -> Self

Returns the "default value" for a type.