Skip to main content

wordval_utils/
collection.rs

1//! 集合工具:分组、去重、分块、查找
2
3use std::collections::HashMap;
4use std::hash::Hash;
5
6/// 集合扩展工具
7pub struct CollectionExt;
8
9impl CollectionExt {
10    /// 按指定键分组(类似 SQL GROUP BY)
11    ///
12    /// # 示例
13    ///
14    /// ```
15    /// use wordval_utils::collection::CollectionExt;
16    ///
17    /// let items = vec![
18    ///     ("apple", 1),
19    ///     ("banana", 2),
20    ///     ("apple", 3),
21    /// ];
22    /// let grouped = CollectionExt::group_by(&items, |item| item.0);
23    /// assert_eq!(grouped.get("apple").unwrap().len(), 2);
24    /// ```
25    pub fn group_by<T, K, F>(items: &[T], key_fn: F) -> HashMap<K, Vec<&T>>
26    where
27        K: Eq + Hash,
28        F: Fn(&T) -> K,
29    {
30        let mut map: HashMap<K, Vec<&T>> = HashMap::new();
31        for item in items {
32            let key = key_fn(item);
33            map.entry(key).or_default().push(item);
34        }
35        map
36    }
37
38    /// 去重并保持原始顺序
39    ///
40    /// # 示例
41    ///
42    /// ```
43    /// use wordval_utils::collection::CollectionExt;
44    ///
45    /// let v = vec![3, 1, 2, 1, 3, 4];
46    /// assert_eq!(CollectionExt::dedup(v), vec![3, 1, 2, 4]);
47    /// ```
48    pub fn dedup<T>(items: Vec<T>) -> Vec<T>
49    where
50        T: Eq + Hash + Clone,
51    {
52        let mut seen = std::collections::HashSet::with_capacity(items.len());
53        let mut result = Vec::with_capacity(items.len());
54        for item in items {
55            if seen.insert(item.clone()) {
56                result.push(item);
57            }
58        }
59        result
60    }
61
62    /// 将大列表切成固定大小的块
63    ///
64    /// # 示例
65    ///
66    /// ```
67    /// use wordval_utils::collection::CollectionExt;
68    ///
69    /// let v = vec![1, 2, 3, 4, 5];
70    /// let chunks = CollectionExt::chunks(v, 2);
71    /// assert_eq!(chunks, vec![vec![1, 2], vec![3, 4], vec![5]]);
72    /// ```
73    pub fn chunks<T>(items: Vec<T>, size: usize) -> Vec<Vec<T>> {
74        assert!(size > 0, "chunk size must be greater than 0");
75        // 消费型切分:直接移动元素,无需 Clone
76        let n = items.len().div_ceil(size);
77        let mut out = Vec::with_capacity(n);
78        let mut iter = items.into_iter();
79        for _ in 0..n {
80            out.push(iter.by_ref().take(size).collect());
81        }
82        out
83    }
84
85    /// 查找第一个满足条件的元素
86    ///
87    /// # 示例
88    ///
89    /// ```
90    /// use wordval_utils::collection::CollectionExt;
91    ///
92    /// let items = vec![1, 2, 3, 4, 5];
93    /// assert_eq!(CollectionExt::find_first(&items, |x| *x > 3), Some(&4));
94    /// ```
95    pub fn find_first<T, F>(items: &[T], predicate: F) -> Option<&T>
96    where
97        F: Fn(&T) -> bool,
98    {
99        items.iter().find(|item| predicate(item))
100    }
101
102    /// 查找最后一个满足条件的元素
103    ///
104    /// # 示例
105    ///
106    /// ```
107    /// use wordval_utils::collection::CollectionExt;
108    ///
109    /// let items = vec![1, 2, 3, 4, 5];
110    /// assert_eq!(CollectionExt::find_last(&items, |x| *x < 4), Some(&3));
111    /// ```
112    pub fn find_last<T, F>(items: &[T], predicate: F) -> Option<&T>
113    where
114        F: Fn(&T) -> bool,
115    {
116        items.iter().rev().find(|item| predicate(item))
117    }
118
119    /// 查找所有满足条件的元素
120    ///
121    /// # 示例
122    ///
123    /// ```
124    /// use wordval_utils::collection::CollectionExt;
125    ///
126    /// let items = vec![1, 2, 3, 4, 5];
127    /// assert_eq!(CollectionExt::find_all(&items, |x| *x % 2 == 0), vec![&2, &4]);
128    /// ```
129    pub fn find_all<T, F>(items: &[T], predicate: F) -> Vec<&T>
130    where
131        F: Fn(&T) -> bool,
132    {
133        items.iter().filter(|item| predicate(item)).collect()
134    }
135}
136
137#[cfg(test)]
138mod tests {
139    use super::*;
140
141    #[test]
142    fn test_group_by() {
143        let items = vec![
144            ("apple", 1),
145            ("banana", 2),
146            ("apple", 3),
147            ("cherry", 4),
148            ("banana", 5),
149        ];
150        let grouped = CollectionExt::group_by(&items, |item| item.0);
151        assert_eq!(grouped.get("apple").unwrap().len(), 2);
152        assert_eq!(grouped.get("banana").unwrap().len(), 2);
153        assert_eq!(grouped.get("cherry").unwrap().len(), 1);
154    }
155
156    #[test]
157    fn test_group_by_empty() {
158        let items: Vec<(&str, i32)> = vec![];
159        let grouped = CollectionExt::group_by(&items, |item| item.0);
160        assert!(grouped.is_empty());
161    }
162
163    #[test]
164    fn test_dedup() {
165        let v = vec![3, 1, 2, 1, 3, 4, 2, 5];
166        assert_eq!(CollectionExt::dedup(v), vec![3, 1, 2, 4, 5]);
167    }
168
169    #[test]
170    fn test_dedup_empty() {
171        let v: Vec<i32> = vec![];
172        assert_eq!(CollectionExt::dedup(v), Vec::<i32>::new());
173    }
174
175    #[test]
176    fn test_dedup_no_duplicates() {
177        let v = vec![1, 2, 3, 4, 5];
178        assert_eq!(CollectionExt::dedup(v), vec![1, 2, 3, 4, 5]);
179    }
180
181    #[test]
182    fn test_chunks() {
183        let v = vec![1, 2, 3, 4, 5, 6, 7];
184        assert_eq!(
185            CollectionExt::chunks(v, 3),
186            vec![vec![1, 2, 3], vec![4, 5, 6], vec![7]]
187        );
188    }
189
190    #[test]
191    fn test_chunks_exact() {
192        let v = vec![1, 2, 3, 4, 5, 6];
193        assert_eq!(
194            CollectionExt::chunks(v, 2),
195            vec![vec![1, 2], vec![3, 4], vec![5, 6]]
196        );
197    }
198
199    #[test]
200    fn test_chunks_empty() {
201        let v: Vec<i32> = vec![];
202        let result: Vec<Vec<i32>> = CollectionExt::chunks(v, 3);
203        assert!(result.is_empty());
204    }
205
206    #[test]
207    #[should_panic(expected = "chunk size must be greater than 0")]
208    fn test_chunks_zero_size() {
209        let v = vec![1, 2, 3];
210        CollectionExt::chunks(v, 0);
211    }
212
213    #[test]
214    fn test_find_first() {
215        let items = vec![1, 2, 3, 4, 5];
216        assert_eq!(CollectionExt::find_first(&items, |x| *x > 3), Some(&4));
217        assert_eq!(CollectionExt::find_first(&items, |x| *x > 10), None);
218    }
219
220    #[test]
221    fn test_find_last() {
222        let items = vec![1, 2, 3, 4, 5];
223        assert_eq!(CollectionExt::find_last(&items, |x| *x < 4), Some(&3));
224        assert_eq!(CollectionExt::find_last(&items, |x| *x > 10), None);
225    }
226
227    #[test]
228    fn test_find_all() {
229        let items = vec![1, 2, 3, 4, 5, 6];
230        let evens = CollectionExt::find_all(&items, |x| *x % 2 == 0);
231        assert_eq!(evens, vec![&2, &4, &6]);
232    }
233
234    #[test]
235    fn test_find_all_none() {
236        let items = vec![1, 3, 5, 7];
237        let evens = CollectionExt::find_all(&items, |x| *x % 2 == 0);
238        assert!(evens.is_empty());
239    }
240}