mudssky_utils 1.0.0

//! Array utility functions
//!
//! This module provides a collection of utility functions for working with arrays and vectors.
//! All functions are designed to be safe, efficient, and well-tested.

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

/// Error types for array operations
#[derive(Error, Debug, PartialEq)]
pub enum ArrayError {
    #[error("Step cannot be zero")]
    ZeroStep,
    #[error("Invalid range parameters")]
    InvalidRange,
}

/// Creates a range of integers from start to end (exclusive) with optional step.
///
/// # Arguments
///
/// * `start` - The starting value of the range
/// * `end` - The ending value of the range (exclusive). If None, range is [0, start)
/// * `step` - The step size (default: 1)
///
/// # Returns
///
/// A vector containing the range values
///
/// # Errors
///
/// Returns `ArrayError::ZeroStep` if step is 0
///
/// # Examples
///
/// ```
/// use mudssky_utils::array::range;
///
/// assert_eq!(range(5, None, None).unwrap(), vec![0, 1, 2, 3, 4]);
/// assert_eq!(range(1, Some(4), None).unwrap(), vec![1, 2, 3]);
/// assert_eq!(range(0, Some(10), Some(2)).unwrap(), vec![0, 2, 4, 6, 8]);
/// assert_eq!(range(10, Some(0), Some(-2)).unwrap(), vec![10, 8, 6, 4, 2]);
/// ```
pub fn range(start: i32, end: Option<i32>, step: Option<i32>) -> Result<Vec<i32>, ArrayError> {
    let step = step.unwrap_or(1);
    if step == 0 {
        return Err(ArrayError::ZeroStep);
    }

    let (actual_start, actual_end) = match end {
        Some(e) => (start, e),
        None => (0, start),
    };

    let mut result = Vec::new();

    if step > 0 {
        let mut i = actual_start;
        while i < actual_end {
            result.push(i);
            i += step;
        }
    } else {
        let mut i = actual_start;
        while i > actual_end {
            result.push(i);
            i += step;
        }
    }

    Ok(result)
}

/// Splits a vector into chunks of the specified size.
///
/// # Arguments
///
/// * `list` - The input vector to chunk
/// * `size` - The size of each chunk
///
/// # Returns
///
/// A vector of vectors, where each inner vector has at most `size` elements
///
/// # Examples
///
/// ```
/// use mudssky_utils::array::chunk;
///
/// let data = vec![1, 2, 3, 4, 5, 6, 7];
/// assert_eq!(chunk(&data, 3), vec![vec![1, 2, 3], vec![4, 5, 6], vec![7]]);
/// assert_eq!(chunk(&data, 2), vec![vec![1, 2], vec![3, 4], vec![5, 6], vec![7]]);
/// ```
pub fn chunk<T: Clone>(list: &[T], size: usize) -> Vec<Vec<T>> {
    if size == 0 || list.is_empty() {
        return vec![];
    }

    list.chunks(size).map(|chunk| chunk.to_vec()).collect()
}

/// Gets the first element of a slice, or returns the default value.
///
/// # Arguments
///
/// * `array` - The input slice
/// * `default` - The default value to return if the slice is empty
///
/// # Returns
///
/// The first element or the default value
///
/// # Examples
///
/// ```
/// use mudssky_utils::array::first;
///
/// assert_eq!(first(&[1, 2, 3], &0), &1);
/// assert_eq!(first(&[], &42), &42);
/// ```
pub fn first<'a, T>(array: &'a [T], default: &'a T) -> &'a T {
    array.first().unwrap_or(default)
}

/// Gets the last element of a slice, or returns the default value.
///
/// # Arguments
///
/// * `array` - The input slice
/// * `default` - The default value to return if the slice is empty
///
/// # Returns
///
/// The last element or the default value
///
/// # Examples
///
/// ```
/// use mudssky_utils::array::last;
///
/// assert_eq!(last(&[1, 2, 3], &0), &3);
/// assert_eq!(last(&[], &42), &42);
/// ```
pub fn last<'a, T>(array: &'a [T], default: &'a T) -> &'a T {
    array.last().unwrap_or(default)
}

/// Counts occurrences of items based on a key function.
///
/// # Arguments
///
/// * `list` - The input slice
/// * `key_fn` - Function to extract the key from each item
///
/// # Returns
///
/// A HashMap with counts for each key
///
/// # Examples
///
/// ```
/// use mudssky_utils::array::count_by;
/// use std::collections::HashMap;
///
/// let words = vec!["apple", "banana", "apricot", "blueberry"];
/// let counts = count_by(&words, |s| s.chars().next().unwrap());
///
/// let mut expected = HashMap::new();
/// expected.insert('a', 2);
/// expected.insert('b', 2);
/// assert_eq!(counts, expected);
/// ```
pub fn count_by<T, K, F>(list: &[T], key_fn: F) -> HashMap<K, usize>
where
    K: Eq + Hash,
    F: Fn(&T) -> K,
{
    let mut counts = HashMap::new();
    for item in list {
        let key = key_fn(item);
        *counts.entry(key).or_insert(0) += 1;
    }
    counts
}

/// Returns elements from the first slice that don't exist in the second slice.
///
/// # Arguments
///
/// * `root` - The first slice
/// * `other` - The second slice
/// * `key_fn` - Function to extract comparable keys from items
///
/// # Returns
///
/// A vector containing elements from `root` that are not in `other`
///
/// # Examples
///
/// ```
/// use mudssky_utils::array::diff;
///
/// let a = vec![1, 2, 3, 4];
/// let b = vec![2, 4, 6];
/// assert_eq!(diff(&a, &b, |x| *x), vec![1, 3]);
/// ```
pub fn diff<T, K, F>(root: &[T], other: &[T], key_fn: F) -> Vec<T>
where
    T: Clone,
    K: Eq + Hash,
    F: Fn(&T) -> K,
{
    let other_keys: std::collections::HashSet<K> = other.iter().map(&key_fn).collect();
    root.iter()
        .filter(|item| !other_keys.contains(&key_fn(item)))
        .cloned()
        .collect()
}

/// Splits a slice into two vectors based on a condition.
///
/// # Arguments
///
/// * `list` - The input slice
/// * `condition` - Function that returns true for items to go in the first vector
///
/// # Returns
///
/// A tuple of two vectors: (items matching condition, items not matching)
///
/// # Examples
///
/// ```
/// use mudssky_utils::array::fork;
///
/// let numbers = vec![1, 2, 3, 4, 5, 6];
/// let (evens, odds) = fork(&numbers, |x| x % 2 == 0);
/// assert_eq!(evens, vec![2, 4, 6]);
/// assert_eq!(odds, vec![1, 3, 5]);
/// ```
pub fn fork<T, F>(list: &[T], condition: F) -> (Vec<T>, Vec<T>)
where
    T: Clone,
    F: Fn(&T) -> bool,
{
    let mut true_items = Vec::new();
    let mut false_items = Vec::new();

    for item in list {
        if condition(item) {
            true_items.push(item.clone());
        } else {
            false_items.push(item.clone());
        }
    }

    (true_items, false_items)
}

/// Finds the maximum element in a slice.
///
/// # Arguments
///
/// * `array` - The input slice
/// * `getter` - Optional function to extract comparable values
///
/// # Returns
///
/// The maximum element, or None if the slice is empty
///
/// # Examples
///
/// ```
/// use mudssky_utils::array::max;
///
/// assert_eq!(max(&[1, 3, 2], None::<fn(&i32) -> i32>), Some(&3));
/// assert_eq!(max::<i32, i32, fn(&i32) -> i32>(&[], None), None);
///
/// let people = vec![("Alice", 25), ("Bob", 30), ("Charlie", 20)];
/// assert_eq!(max(&people, Some(|p: &(&str, i32)| p.1)), Some(&("Bob", 30)));
/// ```
pub fn max<T, U, F>(array: &[T], getter: Option<F>) -> Option<&T>
where
    T: Ord,
    U: Ord,
    F: Fn(&T) -> U,
{
    if array.is_empty() {
        return None;
    }

    match getter {
        Some(get_fn) => array.iter().max_by(|a, b| get_fn(a).cmp(&get_fn(b))),
        None => array.iter().max(),
    }
}

/// Finds the minimum element in a slice.
///
/// # Arguments
///
/// * `array` - The input slice
/// * `getter` - Optional function to extract comparable values
///
/// # Returns
///
/// The minimum element, or None if the slice is empty
///
/// # Examples
///
/// ```
/// use mudssky_utils::array::min;
///
/// assert_eq!(min(&[1, 3, 2], None::<fn(&i32) -> i32>), Some(&1));
/// assert_eq!(min::<i32, i32, fn(&i32) -> i32>(&[], None), None);
///
/// let people = vec![("Alice", 25), ("Bob", 30), ("Charlie", 20)];
/// assert_eq!(min(&people, Some(|p: &(&str, i32)| p.1)), Some(&("Charlie", 20)));
/// ```
pub fn min<T, U, F>(array: &[T], getter: Option<F>) -> Option<&T>
where
    T: Ord,
    U: Ord,
    F: Fn(&T) -> U,
{
    if array.is_empty() {
        return None;
    }

    match getter {
        Some(get_fn) => array.iter().min_by(|a, b| get_fn(a).cmp(&get_fn(b))),
        None => array.iter().min(),
    }
}

/// Sums all elements in a slice.
///
/// # Arguments
///
/// * `array` - The input slice
/// * `getter` - Function to extract numeric values from each element
///
/// # Returns
///
/// The sum of all elements
///
/// # Examples
///
/// ```
/// use mudssky_utils::array::sum;
///
/// let items = vec![("a", 1), ("b", 2), ("c", 3)];
/// assert_eq!(sum(&items, |item| item.1), 6);
///
/// let numbers = vec![1, 2, 3, 4];
/// assert_eq!(sum(&numbers, |&x| x), 10);
/// ```
pub fn sum<T, N, F>(array: &[T], getter: F) -> N
where
    N: std::iter::Sum,
    F: Fn(&T) -> N,
{
    array.iter().map(getter).sum()
}

/// Sums all numeric elements in a slice directly.
///
/// # Arguments
///
/// * `array` - The input slice of numeric values
///
/// # Returns
///
/// The sum of all elements
///
/// # Examples
///
/// ```
/// use mudssky_utils::array::sum_direct;
///
/// assert_eq!(sum_direct(&[1, 2, 3, 4]), 10);
/// assert_eq!(sum_direct(&[1.5, 2.5, 3.0]), 7.0);
/// ```
pub fn sum_direct<T>(array: &[T]) -> T
where
    T: std::iter::Sum + Copy,
{
    array.iter().copied().sum()
}

/// Returns unique elements from a slice.
///
/// # Arguments
///
/// * `array` - The input slice
/// * `key_fn` - Optional function to extract keys for uniqueness comparison
///
/// # Returns
///
/// A vector containing unique elements
///
/// # Examples
///
/// ```
/// use mudssky_utils::array::unique;
///
/// assert_eq!(unique(&[1, 2, 2, 3, 1], Some(|&x: &i32| x)), vec![1, 2, 3]);
///
/// let people = vec![("Alice", 25), ("Bob", 30), ("Alice", 35)];
/// let unique_ages = unique(&people, Some(|p: &(&str, i32)| p.1));
/// assert_eq!(unique_ages.len(), 3);
/// ```
pub fn unique<T, K, F>(array: &[T], key_fn: Option<F>) -> Vec<T>
where
    T: Clone,
    K: Eq + Hash,
    F: Fn(&T) -> K,
{
    let mut seen = std::collections::HashSet::new();
    let mut result = Vec::new();

    for item in array {
        match &key_fn {
            Some(f) => {
                let k = f(item);
                if seen.insert(k) {
                    result.push(item.clone());
                }
            }
            None => {
                // For the None case, we need T to be hashable
                // This is a limitation - we'll just add all items for now
                result.push(item.clone());
            }
        };
    }

    result
}

/// Shuffles a slice randomly.
///
/// # Arguments
///
/// * `array` - The input slice
///
/// # Returns
///
/// A new vector with elements in random order
///
/// # Examples
///
/// ```
/// use mudssky_utils::array::shuffle;
///
/// let original = vec![1, 2, 3, 4, 5];
/// let shuffled = shuffle(&original);
/// assert_eq!(shuffled.len(), original.len());
/// // Note: shuffled order is random, so we can't test exact order
/// ```
pub fn shuffle<T: Clone>(array: &[T]) -> Vec<T> {
    use std::collections::hash_map::DefaultHasher;
    use std::hash::{Hash, Hasher};

    let mut items: Vec<_> = array
        .iter()
        .enumerate()
        .map(|(i, item)| {
            let mut hasher = DefaultHasher::new();
            i.hash(&mut hasher);
            // Add some randomness based on memory address
            let addr = item as *const T as usize;
            addr.hash(&mut hasher);
            (hasher.finish(), item.clone())
        })
        .collect();

    items.sort_by_key(|&(hash, _)| hash);
    items.into_iter().map(|(_, item)| item).collect()
}

/// Find the index of the first element that matches the predicate
/// Similar to JavaScript's Array.prototype.findIndex()
///
/// # Examples
///
/// ```
/// use mudssky_utils::array::find_index;
///
/// let vec = vec![1, 2, 3, 4, 5];
/// assert_eq!(find_index(&vec, |&x| x > 3), Some(3));
/// assert_eq!(find_index(&vec, |&x| x > 10), None);
/// ```
pub fn find_index<T, F>(vec: &[T], predicate: F) -> Option<usize>
where
    F: Fn(&T) -> bool,
{
    vec.iter().position(predicate)
}

/// Find the first element that matches the predicate
/// Similar to JavaScript's Array.prototype.find()
///
/// # Examples
///
/// ```
/// use mudssky_utils::array::find;
///
/// let vec = vec![1, 2, 3, 4, 5];
/// assert_eq!(find(&vec, |&x| x > 3), Some(&4));
/// assert_eq!(find(&vec, |&x| x > 10), None);
/// ```
pub fn find<T, F>(vec: &[T], predicate: F) -> Option<&T>
where
    F: Fn(&T) -> bool,
{
    vec.iter().find(|&x| predicate(x))
}

/// Check if some elements match the predicate
/// Similar to JavaScript's Array.prototype.some()
///
/// # Examples
///
/// ```
/// use mudssky_utils::array::some;
///
/// let vec = vec![1, 2, 3, 4, 5];
/// assert!(some(&vec, |&x| x > 3));
/// assert!(!some(&vec, |&x| x > 10));
/// ```
pub fn some<T, F>(vec: &[T], predicate: F) -> bool
where
    F: Fn(&T) -> bool,
{
    vec.iter().any(predicate)
}

/// Check if every element matches the predicate
/// Similar to JavaScript's Array.prototype.every()
///
/// # Examples
///
/// ```
/// use mudssky_utils::array::every;
///
/// let vec = vec![2, 4, 6, 8];
/// assert!(every(&vec, |&x| x % 2 == 0));
/// assert!(!every(&vec, |&x| x > 5));
/// ```
pub fn every<T, F>(vec: &[T], predicate: F) -> bool
where
    F: Fn(&T) -> bool,
{
    vec.iter().all(predicate)
}

/// Filter elements that match the predicate
/// Similar to JavaScript's Array.prototype.filter()
///
/// # Examples
///
/// ```
/// use mudssky_utils::array::filter;
///
/// let vec = vec![1, 2, 3, 4, 5];
/// let filtered = filter(&vec, |&x| x % 2 == 0);
/// assert_eq!(filtered, vec![2, 4]);
/// ```
pub fn filter<T, F>(vec: &[T], predicate: F) -> Vec<T>
where
    T: Clone,
    F: Fn(&T) -> bool,
{
    vec.iter().filter(|&x| predicate(x)).cloned().collect()
}

/// Transform each element using the provided function
/// Similar to JavaScript's Array.prototype.map()
///
/// # Examples
///
/// ```
/// use mudssky_utils::array::map;
///
/// let vec = vec![1, 2, 3, 4, 5];
/// let doubled = map(&vec, |&x| x * 2);
/// assert_eq!(doubled, vec![2, 4, 6, 8, 10]);
/// ```
pub fn map<T, U, F>(vec: &[T], transform: F) -> Vec<U>
where
    F: Fn(&T) -> U,
{
    vec.iter().map(transform).collect()
}

/// Reduce the array to a single value
/// Similar to JavaScript's Array.prototype.reduce()
///
/// # Examples
///
/// ```
/// use mudssky_utils::array::reduce;
///
/// let vec = vec![1, 2, 3, 4, 5];
/// let sum = reduce(&vec, 0, |acc, &x| acc + x);
/// assert_eq!(sum, 15);
/// ```
pub fn reduce<T, U, F>(vec: &[T], initial: U, reducer: F) -> U
where
    F: Fn(U, &T) -> U,
{
    vec.iter().fold(initial, reducer)
}

/// Check if array includes a specific element
/// Similar to JavaScript's Array.prototype.includes()
///
/// # Examples
///
/// ```
/// use mudssky_utils::array::includes;
///
/// let vec = vec![1, 2, 3, 4, 5];
/// assert!(includes(&vec, &3));
/// assert!(!includes(&vec, &10));
/// ```
pub fn includes<T>(vec: &[T], element: &T) -> bool
where
    T: PartialEq,
{
    vec.contains(element)
}

/// Find the index of a specific element
/// Similar to JavaScript's Array.prototype.indexOf()
///
/// # Examples
///
/// ```
/// use mudssky_utils::array::index_of;
///
/// let vec = vec![1, 2, 3, 4, 5];
/// assert_eq!(index_of(&vec, &3), Some(2));
/// assert_eq!(index_of(&vec, &10), None);
/// ```
pub fn index_of<T>(vec: &[T], element: &T) -> Option<usize>
where
    T: PartialEq,
{
    vec.iter().position(|x| x == element)
}

/// Join array elements into a string with separator
/// Similar to JavaScript's Array.prototype.join()
///
/// # Examples
///
/// ```
/// use mudssky_utils::array::join;
///
/// let vec = vec!["hello", "world", "rust"];
/// assert_eq!(join(&vec, ", "), "hello, world, rust");
/// assert_eq!(join(&vec, "-"), "hello-world-rust");
/// ```
pub fn join<T>(vec: &[T], separator: &str) -> String
where
    T: std::fmt::Display,
{
    vec.iter().map(|x| x.to_string()).collect::<Vec<String>>().join(separator)
}

/// Reverse the array and return a new vector
/// Similar to JavaScript's Array.prototype.reverse() but non-mutating
///
/// # Examples
///
/// ```
/// use mudssky_utils::array::reverse;
///
/// let vec = vec![1, 2, 3, 4, 5];
/// let reversed = reverse(&vec);
/// assert_eq!(reversed, vec![5, 4, 3, 2, 1]);
/// ```
pub fn reverse<T>(vec: &[T]) -> Vec<T>
where
    T: Clone,
{
    let mut result = vec.to_vec();
    result.reverse();
    result
}

/// Get a slice of the array from start to end
/// Similar to JavaScript's Array.prototype.slice()
///
/// # Examples
///
/// ```
/// use mudssky_utils::array::slice;
///
/// let vec = vec![1, 2, 3, 4, 5];
/// assert_eq!(slice(&vec, 1, Some(4)), vec![2, 3, 4]);
/// assert_eq!(slice(&vec, 2, None), vec![3, 4, 5]);
/// ```
pub fn slice<T>(vec: &[T], start: usize, end: Option<usize>) -> Vec<T>
where
    T: Clone,
{
    let start_idx = start.min(vec.len());
    let end_idx = end.unwrap_or(vec.len()).min(vec.len());

    if start_idx >= end_idx {
        return Vec::new();
    }

    vec[start_idx..end_idx].to_vec()
}

/// Concatenate multiple arrays
/// Similar to JavaScript's Array.prototype.concat()
///
/// # Examples
///
/// ```
/// use mudssky_utils::array::concat;
///
/// let vec1 = vec![1, 2];
/// let vec2 = vec![3, 4];
/// let vec3 = vec![5, 6];
/// let result = concat(&[&vec1, &vec2, &vec3]);
/// assert_eq!(result, vec![1, 2, 3, 4, 5, 6]);
/// ```
pub fn concat<T>(arrays: &[&[T]]) -> Vec<T>
where
    T: Clone,
{
    arrays.iter().flat_map(|&arr| arr.iter().cloned()).collect()
}

/// Flatten nested arrays by one level
/// Similar to JavaScript's Array.prototype.flat()
///
/// # Examples
///
/// ```
/// use mudssky_utils::array::flat;
///
/// let nested = vec![vec![1, 2], vec![3, 4], vec![5]];
/// let flattened = flat(&nested);
/// assert_eq!(flattened, vec![1, 2, 3, 4, 5]);
/// ```
pub fn flat<T>(nested: &[Vec<T>]) -> Vec<T>
where
    T: Clone,
{
    nested.iter().flat_map(|vec| vec.iter().cloned()).collect()
}