wordval-utils 1.0.8

Wordval utilities: string manipulation, date handling, masking, ID generation, validation, crypto, web helpers, collection tools, retry utilities
Documentation
//! 集合工具:分组、去重、分块、查找

use std::collections::HashMap;
use std::hash::Hash;

/// 集合扩展工具
pub struct CollectionExt;

impl CollectionExt {
    /// 按指定键分组(类似 SQL GROUP BY)
    ///
    /// # 示例
    ///
    /// ```
    /// use wordval_utils::collection::CollectionExt;
    ///
    /// let items = vec![
    ///     ("apple", 1),
    ///     ("banana", 2),
    ///     ("apple", 3),
    /// ];
    /// let grouped = CollectionExt::group_by(&items, |item| item.0);
    /// assert_eq!(grouped.get("apple").unwrap().len(), 2);
    /// ```
    pub fn group_by<T, K, F>(items: &[T], key_fn: F) -> HashMap<K, Vec<&T>>
    where
        K: Eq + Hash,
        F: Fn(&T) -> K,
    {
        let mut map: HashMap<K, Vec<&T>> = HashMap::new();
        for item in items {
            let key = key_fn(item);
            map.entry(key).or_default().push(item);
        }
        map
    }

    /// 去重并保持原始顺序
    ///
    /// # 示例
    ///
    /// ```
    /// use wordval_utils::collection::CollectionExt;
    ///
    /// let v = vec![3, 1, 2, 1, 3, 4];
    /// assert_eq!(CollectionExt::dedup(v), vec![3, 1, 2, 4]);
    /// ```
    pub fn dedup<T>(items: Vec<T>) -> Vec<T>
    where
        T: Eq + Hash + Clone,
    {
        let mut seen = std::collections::HashSet::with_capacity(items.len());
        let mut result = Vec::with_capacity(items.len());
        for item in items {
            if seen.insert(item.clone()) {
                result.push(item);
            }
        }
        result
    }

    /// 将大列表切成固定大小的块
    ///
    /// # 示例
    ///
    /// ```
    /// use wordval_utils::collection::CollectionExt;
    ///
    /// let v = vec![1, 2, 3, 4, 5];
    /// let chunks = CollectionExt::chunks(v, 2);
    /// assert_eq!(chunks, vec![vec![1, 2], vec![3, 4], vec![5]]);
    /// ```
    pub fn chunks<T>(items: Vec<T>, size: usize) -> Vec<Vec<T>> {
        assert!(size > 0, "chunk size must be greater than 0");
        // 消费型切分:直接移动元素,无需 Clone
        let n = items.len().div_ceil(size);
        let mut out = Vec::with_capacity(n);
        let mut iter = items.into_iter();
        for _ in 0..n {
            out.push(iter.by_ref().take(size).collect());
        }
        out
    }

    /// 查找第一个满足条件的元素
    ///
    /// # 示例
    ///
    /// ```
    /// use wordval_utils::collection::CollectionExt;
    ///
    /// let items = vec![1, 2, 3, 4, 5];
    /// assert_eq!(CollectionExt::find_first(&items, |x| *x > 3), Some(&4));
    /// ```
    pub fn find_first<T, F>(items: &[T], predicate: F) -> Option<&T>
    where
        F: Fn(&T) -> bool,
    {
        items.iter().find(|item| predicate(item))
    }

    /// 查找最后一个满足条件的元素
    ///
    /// # 示例
    ///
    /// ```
    /// use wordval_utils::collection::CollectionExt;
    ///
    /// let items = vec![1, 2, 3, 4, 5];
    /// assert_eq!(CollectionExt::find_last(&items, |x| *x < 4), Some(&3));
    /// ```
    pub fn find_last<T, F>(items: &[T], predicate: F) -> Option<&T>
    where
        F: Fn(&T) -> bool,
    {
        items.iter().rev().find(|item| predicate(item))
    }

    /// 查找所有满足条件的元素
    ///
    /// # 示例
    ///
    /// ```
    /// use wordval_utils::collection::CollectionExt;
    ///
    /// let items = vec![1, 2, 3, 4, 5];
    /// assert_eq!(CollectionExt::find_all(&items, |x| *x % 2 == 0), vec![&2, &4]);
    /// ```
    pub fn find_all<T, F>(items: &[T], predicate: F) -> Vec<&T>
    where
        F: Fn(&T) -> bool,
    {
        items.iter().filter(|item| predicate(item)).collect()
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_group_by() {
        let items = vec![
            ("apple", 1),
            ("banana", 2),
            ("apple", 3),
            ("cherry", 4),
            ("banana", 5),
        ];
        let grouped = CollectionExt::group_by(&items, |item| item.0);
        assert_eq!(grouped.get("apple").unwrap().len(), 2);
        assert_eq!(grouped.get("banana").unwrap().len(), 2);
        assert_eq!(grouped.get("cherry").unwrap().len(), 1);
    }

    #[test]
    fn test_group_by_empty() {
        let items: Vec<(&str, i32)> = vec![];
        let grouped = CollectionExt::group_by(&items, |item| item.0);
        assert!(grouped.is_empty());
    }

    #[test]
    fn test_dedup() {
        let v = vec![3, 1, 2, 1, 3, 4, 2, 5];
        assert_eq!(CollectionExt::dedup(v), vec![3, 1, 2, 4, 5]);
    }

    #[test]
    fn test_dedup_empty() {
        let v: Vec<i32> = vec![];
        assert_eq!(CollectionExt::dedup(v), Vec::<i32>::new());
    }

    #[test]
    fn test_dedup_no_duplicates() {
        let v = vec![1, 2, 3, 4, 5];
        assert_eq!(CollectionExt::dedup(v), vec![1, 2, 3, 4, 5]);
    }

    #[test]
    fn test_chunks() {
        let v = vec![1, 2, 3, 4, 5, 6, 7];
        assert_eq!(
            CollectionExt::chunks(v, 3),
            vec![vec![1, 2, 3], vec![4, 5, 6], vec![7]]
        );
    }

    #[test]
    fn test_chunks_exact() {
        let v = vec![1, 2, 3, 4, 5, 6];
        assert_eq!(
            CollectionExt::chunks(v, 2),
            vec![vec![1, 2], vec![3, 4], vec![5, 6]]
        );
    }

    #[test]
    fn test_chunks_empty() {
        let v: Vec<i32> = vec![];
        let result: Vec<Vec<i32>> = CollectionExt::chunks(v, 3);
        assert!(result.is_empty());
    }

    #[test]
    #[should_panic(expected = "chunk size must be greater than 0")]
    fn test_chunks_zero_size() {
        let v = vec![1, 2, 3];
        CollectionExt::chunks(v, 0);
    }

    #[test]
    fn test_find_first() {
        let items = vec![1, 2, 3, 4, 5];
        assert_eq!(CollectionExt::find_first(&items, |x| *x > 3), Some(&4));
        assert_eq!(CollectionExt::find_first(&items, |x| *x > 10), None);
    }

    #[test]
    fn test_find_last() {
        let items = vec![1, 2, 3, 4, 5];
        assert_eq!(CollectionExt::find_last(&items, |x| *x < 4), Some(&3));
        assert_eq!(CollectionExt::find_last(&items, |x| *x > 10), None);
    }

    #[test]
    fn test_find_all() {
        let items = vec![1, 2, 3, 4, 5, 6];
        let evens = CollectionExt::find_all(&items, |x| *x % 2 == 0);
        assert_eq!(evens, vec![&2, &4, &6]);
    }

    #[test]
    fn test_find_all_none() {
        let items = vec![1, 3, 5, 7];
        let evens = CollectionExt::find_all(&items, |x| *x % 2 == 0);
        assert!(evens.is_empty());
    }
}