keylist/lib.rs
1//! ## Keylist
2//! Map like wrapper around a list with tuple pairs. Inspired by Elixir's Keyword lists.
3//!
4//! Because it is just a list with tuples, keys can be anything that can be put in a tuple. Also means that getting a value is not efficient.
5//!
6//! For something more usefull and quite similar take a look at: https://docs.rs/multimap
7//! ```
8//! use keylist::Keylist;
9//!
10//! let mut keylist = Keylist::from(vec![("a", 5), ("b", 2), ("a", 1)]);
11//!
12//! assert_eq!(keylist.get(&"a"), Some(&5));
13//!
14//! keylist.sort_by_value();
15//!
16//! assert_eq!(keylist.get(&"a"), Some(&1));
17//!
18//! keylist.push("z", 26);
19//!
20//! assert_eq!(keylist.get(&"z"), Some(&26));
21//!
22//! keylist.insert(1, "z", 2);
23//!
24//! assert_eq!(keylist.get(&"z"), Some(&2));
25//!
26//! assert_eq!(keylist.get_all(&"z"), vec![&2, &26]);
27//!
28//! assert_eq!(keylist.get_key_value(&"b"), Some(&("b", 2)));
29//!
30//! let mut swapped_keylist = keylist.into_swapped();
31//!
32//! assert_eq!(swapped_keylist.get(&2), Some(&"z"));
33//!
34//! assert_eq!(swapped_keylist.get_all(&2), vec![&"z", &"b"]);
35//!
36//! swapped_keylist.sort();
37//!
38//! assert_eq!(swapped_keylist.get_all(&2), vec![&"b", &"z"]);
39//!
40//! swapped_keylist.extend(vec![(3, "b"), (2, "g")]);
41//!
42//! assert_eq!(swapped_keylist.get_all(&2), vec![&"b", &"z", &"g"]);
43//!
44//! ```
45//!
46//! Convert keylist to map and back:
47//! ```
48//! use std::collections::HashMap;
49//! use std::iter::FromIterator;
50//! use keylist::Keylist;
51//!
52//! let keylist = Keylist::from(vec![("a", 5), ("b", 2), ("c", 1)]);
53//!
54//! let mut map = HashMap::new();
55//! map.extend(vec![("a", 5), ("b", 2), ("c", 1)]);
56//!
57//! let map_from_keylist = HashMap::from_iter(keylist.clone());
58//! let mut keylist_from_map = Keylist::from_iter(map.clone());
59//! keylist_from_map.sort();
60//!
61//! assert_eq!(map, map_from_keylist);
62//! assert_eq!(keylist, keylist_from_map);
63//! ```
64//!
65//! Arbitrary example:
66//! ```
67//! use keylist::Keylist;
68//!
69//! let mut keylist = Keylist::new();
70//! keylist.push(vec![3.12, 0.12], "a");
71//! keylist.push(vec![0.1235, 34.121551], "c");
72//!
73//! assert_eq!(keylist.get(&vec![0.1235, 34.121551]), Some(&"c"));
74//!
75//!
76//! ```
77//!
78//! ## HashKeylist
79//! There is also a more efficient implemetation, backend by a hashmap, therefore the keys should be hashable.
80//! ```
81//! use keylist::HashKeylist;
82//! use std::collections::HashMap;
83//! use std::iter::FromIterator;
84//!
85//! let mut map = HashMap::new();
86//! map.insert("one", 1);
87//! map.insert("two", 2);
88//! map.insert("three", 3);
89//! map.insert("four", 4);
90//!
91//! let mut keylist = HashKeylist::from_iter(map);
92//! // sorts keys alphabetically
93//! keylist.sort_by_key();
94//!
95//! keylist.push("one", 11);
96//! keylist.push("five", 5);
97//! keylist.push("five", 1);
98//!
99//! assert_eq!(
100//! vec![
101//! (&"four", &4),
102//! (&"one", &1),
103//! (&"three", &3),
104//! (&"two", &2),
105//! (&"one", &11),
106//! (&"five", &5),
107//! (&"five", &1),
108//! ],
109//! keylist.iter().collect::<Vec<_>>()
110//! );
111//!
112//! keylist.insert(2, "five", 12);
113//!
114//! assert_eq!(
115//! vec![
116//! (&"four", &4),
117//! (&"one", &1),
118//! (&"five", &12),
119//! (&"three", &3),
120//! (&"two", &2),
121//! (&"one", &11),
122//! (&"five", &5),
123//! (&"five", &1),
124//! ],
125//! keylist.iter().collect::<Vec<_>>()
126//! );
127//!
128//! assert_eq!(Some(("five", 1)), keylist.pop());
129//!
130//! assert_eq!(
131//! vec![
132//! (&"four", &4),
133//! (&"one", &1),
134//! (&"five", &12),
135//! (&"three", &3),
136//! (&"two", &2),
137//! (&"one", &11),
138//! (&"five", &5),
139//! ],
140//! keylist.iter().collect::<Vec<_>>()
141//! );
142//!
143//! assert_eq!(("two", 2), keylist.remove(4));
144//!
145//! assert_eq!(
146//! vec![
147//! (&"four", &4),
148//! (&"one", &1),
149//! (&"five", &12),
150//! (&"three", &3),
151//! (&"one", &11),
152//! (&"five", &5),
153//! ],
154//! keylist.iter().collect::<Vec<_>>()
155//! );
156//!
157//! assert_eq!(
158//! vec![&"four", &"one", &"five", &"three", &"one", &"five"],
159//! keylist.keys().collect::<Vec<_>>()
160//! );
161//!
162//! assert_eq!(
163//! vec![&4, &1, &12, &3, &11, &5],
164//! keylist.values().collect::<Vec<_>>()
165//! );
166//!
167//! assert_eq!(
168//! vec![
169//! ("four", 4),
170//! ("one", 1),
171//! ("five", 12),
172//! ("three", 3),
173//! ("one", 11),
174//! ("five", 5),
175//! ],
176//! Vec::from(keylist)
177//! )
178//! ```
179
180pub mod hash_keylist;
181pub mod vec_keylist;
182
183pub use hash_keylist::HashKeylist;
184pub use vec_keylist::VecKeylist;
185
186pub type Keylist<K, V> = VecKeylist<K, V>;