slice.go

// Package slicezh provides common slice operations with Chinese-named functions
// Contains filtering, finding, transforming, reversing, shuffling, deduplicating and conversion utilities
// Implements generic slice operations with intuitive naming conventions
//
// slicezh 提供常用的切片操作，使用中文命名的函数
// 包含过滤、查找、转换、翻转、乱序、去重和类型转换等工具函数
// 使用直观的命名规范实现泛型切片操作
package slicezh

import (
	"math/rand/v2"
	"slices"

	"github.com/yylego/slicezh/internal/utils"
)

// Get按条件过滤 returns elements matching the condition
// Returns a new slice containing elements where condition returns true
// The input slice remains unchanged
//
// Get按条件过滤 按条件过滤切片元素
// 返回包含满足条件的元素的新切片
// 输入切片保持不变
func Get按条件过滤[T any](slice []T, condition func(value T) bool) []T {
	res := make([]T, 0, len(slice))
	for _, v := range slice {
		if condition(v) {
			res = append(res, v)
		}
	}
	return res
}

// Get首个满足条件的 returns the first element matching the condition
// Returns the element and true if found, the zero value and false if not found
//
// Get首个满足条件的 返回第一个满足条件的元素
// 找到时返回元素和 true，未找到时返回零值和 false
func Get首个满足条件的[T any](slice []T, condition func(value T) bool) (T, bool) {
	for _, v := range slice {
		if condition(v) {
			return v, true
		}
	}
	return utils.Zero[T](), false
}

// Mut翻转自身内容 reverses the slice in place
// Modifies the input slice
//
// Mut翻转自身内容 原地翻转切片内容
// 修改输入切片
func Mut翻转自身内容[T any](slice []T) {
	slices.Reverse(slice)
}

// Get获取逆序新数组 returns a new slice with elements in reverse sequence
// The input slice remains unchanged
//
// Get获取逆序新数组 返回元素逆序排列的新切片
// 输入切片保持不变
func Get获取逆序新数组[T any](slice []T) []T {
	res := make([]T, len(slice))
	for i, v := range slice {
		res[len(res)-i-1] = v
	}
	return res
}

// Get随机取个元素 returns a random element from the slice
// Panics when slice has no elements
//
// Get随机取个元素 从切片中随机取一个元素
// 切片无元素时会 panic
func Get随机取个元素[T any](slice []T) T {
	return slice[rand.IntN(len(slice))]
}

// Mut随机乱序元素 shuffles the slice in place using random swap algorithm
// Modifies the input slice
//
// Mut随机乱序元素 使用随机交换算法原地随机打乱切片顺序
// 修改输入切片
func Mut随机乱序元素[T any](slice []T) {
	rand.Shuffle(len(slice), func(i, j int) {
		slice[i], slice[j] = slice[j], slice[i]
	})
}

// Contains checks if the slice contains the specified value
// Returns true if value exists in slice, false if not
//
// Contains 检查切片是否包含指定值
// 值存在于切片中返回 true，不存在返回 false
func Contains[T comparable](slice []T, value T) bool {
	return slices.Contains(slice, value)
}

// In checks if the value exists in the slice
// Same as Contains but with swapped parameters
//
// In 检查值是否存在于切片中
// 与 Contains 相同，但参数位置交换
func In[T comparable](value T, slice []T) bool {
	return slices.Contains(slice, value)
}

// Get映射Map converts a slice to a map using a keyFunc extraction function
// keyFunc extracts the map-key from each element
// When duplicates exist, subsequent elements replace previous ones
//
// Get映射Map 使用 keyFunc 提取函数将切片转换为 map
// keyFunc 从每个元素中提取 map 键
// 存在重复时，后续元素会替换之前的元素
func Get映射Map[K comparable, V any](slice []V, keyFunc func(value V) K) map[K]V {
	res := make(map[K]V, len(slice))
	for _, v := range slice {
		res[keyFunc(v)] = v
	}
	return res
}

// Get映射转换 transforms each element to a new type using transform function
// Returns a new slice with transformed elements
// Preserves element sequence and count
//
// Get映射转换 使用转换函数将每个元素转换为新类型
// 返回包含转换后元素的新切片
// 保持元素顺序和数量
func Get映射转换[T any, R any](slice []T, transform func(T) R) []R {
	res := make([]R, len(slice))
	for i, v := range slice {
		res[i] = transform(v)
	}
	return res
}

// Get元素去重 removes duplicate elements while preserving sequence
// Keeps the first occurrence of each element
// Uses map-based deduplication with O(n) time
//
// Get元素去重 去除重复元素，保持原始顺序
// 保留每个元素的首次出现
// 使用基于 map 的去重，时间 O(n)
func Get元素去重[T comparable](slice []T) []T {
	seen := make(map[T]struct{}, len(slice))
	res := make([]T, 0, len(slice))
	for _, v := range slice {
		if _, ok := seen[v]; !ok {
			seen[v] = struct{}{}
			res = append(res, v)
		}
	}
	return res
}