functools

Functools

Functools 是一个轻量级、类型安全的 Go 语言辅助函数库，提供丰富的切片（slice）操作工具，涵盖函数式编程范式（Map/Filter/Reduce）、集合运算（去重、并集、差集）、数学统计、分组、反转及组合等常见需求。所有函数均基于 Go 泛型实现，确保高性能与编译期类型检查。

---

安装

go get github.com/cuishu/functools

---

函数索引

基础函数式操作

• Map – 将切片元素逐一转换为新类型
• ForEach – 遍历切片执行副作用
• Filter – 按条件筛选元素
• Reduce – 归约切片为单个值

集合运算（去重、并集、差集）

• Unique / UniqueBy – 去重
• Union / UnionBy – 合并多个切片并去重
• Diff / DiffBy – 对称差集
• DiffSeparate / DiffSeparateBy – 分别获取仅存在于 A 或 B 中的元素

数学与数值工具

• Sum – 求和
• Min / Max – 比较两个数值
• Range – 生成整数序列

顺序操作

• Reverse / ReverseInPlace – 反转切片

分组与组合

• GroupBy – 按键分组
• Zip – 将两个切片按位置配对为 Pair 结构
• Pair – 二元组辅助类型

---

详细说明与示例

Map

对切片中的每个元素应用转换函数，返回新切片。

func Map[A, B any](list []A, f func(A) B) []B

示例：将整数切片转为字符串

nums := []int{1, 2, 3}
strs := functools.Map(nums, func(i int) string { return strconv.Itoa(i) })
// strs: ["1", "2", "3"]

---

ForEach

遍历切片并对每个元素执行传入的函数（常用于副作用操作）。

func ForEach[A any](list []A, f func(A))

示例：打印每个元素

functools.ForEach([]string{"a", "b"}, func(s string) { fmt.Println(s) })

---

Filter

根据谓词函数过滤元素，返回满足条件的新切片。

func Filter[A any](list []A, f func(A) bool) []A

示例：筛选偶数

evens := functools.Filter([]int{1,2,3,4}, func(x int) bool { return x%2==0 })
// evens: [2,4]

---

Reduce

使用归约函数将切片累计为单个值（需提供初始值）。

func Reduce[A any](list []A, f func(A, A) A, init A) A

示例：求和

sum := functools.Reduce([]int{1,2,3,4}, func(x, y int) int { return x+y }, 0)
// sum: 10

---

Unique / UniqueBy

去除切片中的重复元素，保持首次出现顺序。

func Unique[T comparable](list []T) []T
func UniqueBy[A any, B comparable](list []A, selector func(A) B) []A

• Unique 直接比较元素自身（需 comparable）。
• UniqueBy 通过 selector 提取比较键。

示例：

ints := []int{1,2,2,3}
uniq := functools.Unique(ints) // [1,2,3]

type User struct{ ID int; Name string }
users := []User{{1,"A"}, {2,"B"}, {1,"C"}}
uniqByID := functools.UniqueBy(users, func(u User) int { return u.ID })
// 保留首次出现的 {1,"A"} 和 {2,"B"}

---

Union / UnionBy

合并多个切片，去除重复元素（结果保持第一个切片的元素顺序）。

func Union[T comparable](collections ...[]T) []T
func UnionBy[A any, B comparable](selector func(A) B, collections ...[]A) []A

示例：

a := []int{1,2}
b := []int{2,3}
c := []int{3,4}
union := functools.Union(a, b, c) // [1,2,3,4]

// 按名称去重
type Item struct{ Name string }
items1 := []Item{{"x"},{"y"}}
items2 := []Item{{"y"},{"z"}}
unionByName := functools.UnionBy(func(it Item) string { return it.Name }, items1, items2)
// 保留第一个出现的同名元素

---

Diff / DiffBy

返回两个切片的对称差集（即只在其中一个切片中出现的元素），结果去重。

func Diff[T comparable](a, b []T) []T
func DiffBy[T any, K comparable](a, b []T, selector func(T) K) []T

示例：

a := []int{1,2,3}
b := []int{3,4,5}
diff := functools.Diff(a, b) // [1,2,4,5]（顺序不定）

---

DiffSeparate / DiffSeparateBy

分别返回 仅在 A 中 和 仅在 B 中 的元素（去重）。

func DiffSeparate[T comparable](a, b []T) (onlyA, onlyB []T)
func DiffSeparateBy[T any, K comparable](a, b []T, selector func(T) K) (onlyA, onlyB []T)

示例：

a := []int{1,2,3}
b := []int{3,4,5}
onlyA, onlyB := functools.DiffSeparate(a, b)
// onlyA: [1,2], onlyB: [4,5]

---

Sum

计算数值切片的和（支持所有整数、无符号整数及浮点数类型）。

func Sum[T Number](slice []T) T

示例：

total := functools.Sum([]int{1,2,3}) // 6

---

Min / Max

返回两个数值中的较小/较大值。

func Min[T cmp.Ordered](a T, args ...T) T
func Max[T cmp.Ordered](a T, args ...T) T

示例：

m := functools.Min(10, 20, 30) // 10
M := functools.Max(10, 20, 30) // 30

---

Range

生成从 start 到 stop（不包含）的整数序列，步长为 step。

func Range[T Int | Uint](start, stop, step T) []T

示例：

seq := functools.Range(0, 10, 2) // [0,2,4,6,8]

注意：stop 必须大于 start，且步长必须为正。

---

Reverse / ReverseInPlace

Reverse 返回反转后的新切片；ReverseInPlace 原地反转（不分配新内存）。

func Reverse[T any](list []T) []T
func ReverseInPlace[T any](list []T)

示例：

orig := []int{1,2,3}
reversed := functools.Reverse(orig)      // [3,2,1]
functools.ReverseInPlace(orig)           // orig 变为 [3,2,1]

---

GroupBy

根据选择器函数返回的键对元素进行分组，结果为一个映射（map）。

func GroupBy[A any, B comparable](list []A, selector func(A) B) map[B][]A

示例：按字符串长度分组

words := []string{"go", "rust", "java", "zig"}
groups := functools.GroupBy(words, func(s string) int { return len(s) })
// groups[2] = ["go"], groups[3] = ["zig"], groups[4] = ["rust","java"]

---

Zip

将两个切片按位置配对，返回 Pair 切片。结果长度取较短者。

func Zip[A, B any](a []A, b []B) []Pair[A, B]

示例：

names := []string{"Alice", "Bob"}
ages := []int{30, 25}
pairs := functools.Zip(names, ages)
// pairs[0] = Pair{First:"Alice", Second:30}

---

Pair 辅助类型

Pair 是一个简单的二元组结构，提供构造方法和取值方法。

type Pair[A, B any] struct { First A; Second B }
func NewPair[A, B any](a A, b B) Pair[A, B]
func (p Pair[A, B]) Values() (A, B)

---

性能与兼容性

• Go 版本：需 Go 1.18 及以上（泛型支持）。
• 内存效率：多数函数返回新切片（ReverseInPlace 除外），避免修改输入（除特殊说明）。
• 并发安全：所有函数均为纯函数，不涉及并发，但输入切片在函数外部被修改不影响函数结果（除非传递引用类型元素）。

---

贡献

欢迎提交 Issue 或 Pull Request。请确保代码通过 go test 并保持测试覆盖率。

---

许可证

MIT © cuishu