multi_containers 0.2.1

Ergonomically work with multiple values per key
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85

#![warn(missing_docs)]

//! This crate implements containers that can have duplicate values.
//! If you have ever written a `HashMap<K, HashSet<V>>`, this crate is for you.
//!
//! **This crate is unstable and its API is subject to change at any time until 1.0.0**.
//!
//! This crate is comparable in spirit to these containers in other languages:
//! - Java's `Guava` library's `Multimap` and `Multiset` (which heavily inspired this crate).
//! - Python's `collections.defaultdict(set)` and `collections.Counter`.
//! - C++'s `std::(unordered_)mutlimap` and `std::(unordered_)multiset`.
//!
//! ## Usage
//! The primary containers are `MultiMap` and `MultiSet`. See `examples.rs` for more examples.
//!
//! ### MultiMap
//! `MultiMap` is a wrapper around `Map<K, Set<V>>`.
//! You can either use the provided `HashMultiMap` or `BTreeMultiMap`, or provide your own types with `MultiMapBuilder`.
//! The API is similar to what you would expect from `HashMap<K, HashSet<V>>`, with some additional methods related to the multiple values.
//! For bookkeeping reasons, the inner sets are not exposed mutably.
//! `MultiMap` also provides ways of iterating over `(&K, &Set<V>)`, or over `(&K, &V)`.
//!
//! ```rust
//! use multi_containers::HashMultiMap;
//! let mut map = HashMultiMap::new();
//! map.insert("a".to_string(), 1);
//! map.insert("a".to_string(), 2);
//! map.insert("b".to_string(), 3);
//! assert_eq!(map.get("a").unwrap().len(), 2);
//! assert_eq!(map.get("b").unwrap().len(), 1);
//! ```
//!
//! ### MultiSet
//! `MultiSet` is a wrapper around `Map<V, usize>`. It offers the semantics of a set, but allows for duplicate values.
//! It offers iterators over unique `(&V, usize)`, and non-unique `&V`.
//!
//! ```rust
//! use multi_containers::HashMultiSet;
//! let mut set = HashMultiSet::new();
//! set.insert(1);
//! set.insert(1);
//! set.insert_some(2, 3);
//! assert_eq!(set.count(&1), 2);
//! assert_eq!(set.count(&2), 3);
//! ```

/// Defines the `MultiMap` type.
pub mod multimap;

/// Provides a convenient way to construct multi-maps.
pub mod multimap_builder;

/// Defines the `MultiSet` type.
pub mod multiset;

/// Provides a convenient way to construct multi-sets.
pub mod multiset_builder;

/// Traits for working with maps.
pub mod maps;

/// Traits for working with sets.
pub mod sets;

mod examples;
mod test_utils;

pub use crate::multimap::MultiMap;
pub use crate::multimap_builder::MultiMapBuilder;
pub use crate::multiset::MultiSet;
pub use crate::multiset_builder::MultiSetBuilder;
use std::collections::{BTreeMap, BTreeSet, HashMap, HashSet};
use std::hash::RandomState;

/// A multi-map that uses `HashMap` for the keys and `HashSet` for the values.
pub type HashMultiMap<K, V, S = RandomState> = MultiMap<HashMap<K, HashSet<V, S>, S>>;

/// A multi-set that uses `HashMap` for the keys.
pub type HashMultiSet<K, S = RandomState> = MultiSet<HashMap<K, usize, S>>;

/// A multi-map that uses `BTreeMap` for the keys and `BTreeSet` for the values.
pub type BTreeMultiMap<K, V> = MultiMap<BTreeMap<K, BTreeSet<V>>>;

/// A multi-set that uses `BTreeMap` for the keys.
pub type BTreeMultiSet<K> = MultiSet<BTreeMap<K, usize>>;