mathx

func Abs ¶

func Abs[T types.Numerical](x T) T

Abs 返回数值的绝对值 - 使用 cmp.Compare 判断正负 支持所有数值类型的泛型版本

func AddUniqueSlice ¶

func AddUniqueSlice[T comparable](slice []T, items ...T) ([]T, bool)

AddUniqueSlice 向切片中添加元素（如果不存在） 返回新切片和是否实际添加了元素

func AllSlice ¶

func AllSlice[T any](slice []T, predicate func(T) bool) bool

AllSlice 检查是否所有元素都满足条件

func AnySlice ¶

func AnySlice[T any](slice []T, predicate func(T) bool) bool

AnySlice 检查是否有任何元素满足条件

func AtLeast ¶

func AtLeast[T types.Numerical](x, lower T) T

AtLeast 返回 x 和 lower 中的最小值 参数: x - 要比较的第一个数值 lower - 要比较的第二个数值（下限） 返回值: 返回 x 和 lower 中的最小值

func AtMost ¶

func AtMost[T types.Numerical](x, upper T) T

AtMost 返回 x 和 upper 中的最大值 参数: x - 要比较的第一个数值 upper - 要比较的第二个数值（上限） 返回值: 返回 x 和 upper 中的最大值

func Between ¶

func Between[T types.Numerical](x, lower, upper T) T

Between 将 x 的值限制在 [lower, upper] 范围内 如果 x 小于 lower，则返回 lower； 如果 x 大于 upper，则返回 upper； 否则，返回 x 本身 参数: x - 要限制的数值 lower - 范围的下限 upper - 范围的上限 返回值: 返回 x 被限制在 [lower, upper] 范围内的值

func Bit64ToArray ¶

func Bit64ToArray(bit uint64) []uint

Bit64ToArray 将掩码中所有被置1的位索引提取为数组

func BitToArrayBig ¶

func BitToArrayBig(bits *big.Int) []uint

BitToArrayBig 将big.Int掩码中所有被置1的位索引提取为数组

func BubbleSort ¶

func BubbleSort(arr []int)

BubbleSort 实现冒泡排序算法

func CalcEntropy ¶

func CalcEntropy(m map[interface{}]int) float64

CalcEntropy 计算给定概率分布（map）的熵值 熵值表示信息的不确定性或随机性

func Clone ¶

func Clone(value interface{}, seen map[uintptr]interface{}) interface{}

Clone 深拷贝任意类型的值

func CompactSlice ¶

func CompactSlice[T comparable](slice []T) []T

CompactSlice 移除切片中的零值元素

func ContainsAllSlice ¶

func ContainsAllSlice[T comparable](slice []T, items ...T) bool

ContainsAllSlice 检查切片是否包含所有指定元素

func ContainsAnySlice ¶

func ContainsAnySlice[T comparable](slice []T, items ...T) bool

ContainsAnySlice 检查切片是否包含任意一个指定元素

func ConvertMapKeysToString ¶

func ConvertMapKeysToString(data interface{}) interface{}

ConvertMapKeysToString 递归地将 map 的所有键转换为字符串 支持嵌套的 map 和 slice

func CountPathSegments ¶

func CountPathSegments(path string, prefixes ...string) int

CountPathSegments 计算路径中指定前缀的参数数量，默认为 ":" 和 "*"

func Decimals ¶

func Decimals[T types.Numerical](num T, digit int) string

Decimals 转换为包含小数点后指定位数的字符串

func DedupeValues ¶

func DedupeValues[T any, K comparable](items []T, key func(T) (K, bool)) []K

DedupeValues 从切片中按键提取去重后的值列表 key 函数返回 (值, 是否包含)；ok=false 时跳过该项（常用于过滤零值）

func DeepMergeMap ¶

func DeepMergeMap(target, source map[string]interface{}, options *MapMergeOptions) (map[string]interface{}, error)

DeepMergeMap 深度合并两个 map[string]interface{} target: 目标map（会被修改） source: 源map options: 合并选项，nil则使用默认选项 返回合并后的 map 和可能的错误

func DefaultIfNilPtr ¶

func DefaultIfNilPtr[T any](param *T, defaultValue T) *T

DefaultIfNilPtr 如果参数为 nil，返回指向默认值的指针；否则返回原参数 适用于需要保持指针类型的场景，如分页参数、配置对象等

示例：

基础类型示例
var count *int
count = mathx.DefaultIfNilPtr(count, 10)
fmt.Println(*count) // 输出: 10

字符串示例
var name *string
name = mathx.DefaultIfNilPtr(name, "default")
fmt.Println(*name) // 输出: default

结构体示例（分页参数）
var page *PageReq
page = mathx.DefaultIfNilPtr(page, PageReq{Page: 1, PageSize: 10})
page 现在指向默认值

已存在的指针保持原值
existing := &PageReq{Page: 2, PageSize: 20}
result := mathx.DefaultIfNilPtr(existing, PageReq{Page: 1, PageSize: 10})
result == existing (保持原值，Page=2, PageSize=20)

func EqualSlices ¶

func EqualSlices[T comparable](a, b []T) bool

EqualSlices 比较两个切片是否相等，支持任意类型

func FilterSlice ¶

func FilterSlice[T any](slice []T, predicate func(T) bool) []T

FilterSlice 过滤切片，保留满足条件的元素 与 SliceRemove 的区别：FilterSlice 保留满足条件的，SliceRemove 也是保留满足条件的 这个函数提供更直观的命名

func FilterSliceByFunc ¶

func FilterSliceByFunc[T any](slice []T, predicate func(T) bool) []T

FilterSliceByFunc 是一个通用的切片过滤函数。 它接收一个切片 slice 和一个判断函数 predicate， 返回一个新的切片，包含所有满足 predicate 条件的元素。

泛型参数说明：

T 表示切片元素的类型，可以是任意类型。

参数说明：

slice - 输入的切片，类型为 []T。
predicate - 一个函数，接收一个 T 类型元素，返回 bool，表示该元素是否满足条件。

返回值说明：

返回一个新的切片，包含所有满足 predicate 条件的元素，顺序与原切片一致。

示例：

results := []ABC{...}
frontFaces := FilterSliceByFunc(results, func(d ABC) bool {
    return d.key == "123"
})

func FindLastSlice ¶

func FindLastSlice[T any](slice []T, predicate func(T) bool) (T, bool)

FindLastSlice 查找最后一个满足条件的元素

func FindSlice ¶

func FindSlice[T any](slice []T, predicate func(T) bool) (T, bool)

FindSlice 查找第一个满足条件的元素

func FlattenMap ¶

func FlattenMap(m map[string]interface{}, separator string) map[string]interface{}

FlattenMap 扁平化嵌套的 map，使用点号分隔键 例如: {"a": {"b": {"c": 1}}} => {"a.b.c": 1}

func FlattenSlice ¶

func FlattenSlice[T any](slices [][]T) []T

FlattenSlice 扁平化嵌套切片

func FormatPercentage ¶

func FormatPercentage(part, total uint64, precision int) string

FormatPercentage 格式化百分比

func FormatRatio ¶

func FormatRatio(ratio float64, precision int) string

FormatRatio 将 [0,1] 区间的比率格式化为百分比字符串（不带 % 后缀） precision 为小数位数，如 0.855 + precision=2 → "85.50" 内部先乘 100 再格式化，避免外部重复 *100 造成精度损失

func FormatRatioFromCount ¶

func FormatRatioFromCount(part, total uint64, precision int) string

FormatRatioFromCount 从 count 直接计算并格式化百分比字符串（不带 % 后缀） 等价于 FormatRatio(Ratio(part, total), precision)，但减少一次中间赋值 part 为分子（如 success_count），total 为分母（如 终态订单数），precision 为小数位数

func GetBit64 ¶

func GetBit64(min, max, step uint) uint64

GetBit64 返回范围 [min, max] 内，步长为 step 的所有位掩码

func GetBitBig ¶

func GetBitBig(min, max, step uint) *big.Int

GetBitBig 返回范围 [min, max] 内，步长为 step 的所有位掩码，使用big.Int支持大位数

func GetNestedMapValue ¶

func GetNestedMapValue[T any](m map[string]interface{}, keys ...string) (T, bool)

GetNestedMapValue 从嵌套的 map 中获取值，支持路径访问 例如: GetNestedMapValue[string](data, "user", "profile", "name")

func GroupSliceBy ¶

func GroupSliceBy[T any, K comparable](slice []T, keyFunc func(T) K) map[K][]T

GroupSliceBy 按照键函数对切片元素分组

func IF ¶

func IF[T any](condition bool, trueVal, falseVal T) T

IF 实现三元运算，使用泛型 T 根据布尔条件 condition 返回 trueVal 或 falseVal 作用类似于三元表达式 condition ? trueVal : falseVal

func IfAll ¶

func IfAll[T any](conditions []bool, trueVal, falseVal T) T

IfAll 所有条件满足的三元运算 如果 conditions 中所有条件都为 true，返回 trueVal；否则返回 falseVal

func IfAllEmpty ¶

func IfAllEmpty[T any](values []interface{}, trueVal, falseVal T) T

IfAllEmpty 所有值为空检查三元运算 检查提供的所有值是否都为空 如果全部为空，返回 trueVal；否则返回 falseVal

示例：

result := mathx.IfAllEmpty([]interface{}{"", 0, []int{}}, "all empty", "has value")  // "all empty"
result := mathx.IfAllEmpty([]interface{}{"", 0, "x"}, "all empty", "has value")      // "has value"

func IfAllowedField ¶

func IfAllowedField[T any](field string, allowedFields []string, trueVal, falseVal T) T

IfAllowedField 字段白名单检查三元运算 使用 validator.IsAllowedField 检查字段是否在白名单中 如果允许，返回 trueVal；否则返回 falseVal

示例：

allowed := []string{"id", "name", "email"}
result := mathx.IfAllowedField("name", allowed, "ok", "forbidden")     // "ok"
result := mathx.IfAllowedField("password", allowed, "ok", "forbidden") // "forbidden"

func IfAny ¶

func IfAny[T any](conditions []bool, trueVal, falseVal T) T

IfAny 任意条件满足的三元运算 如果 conditions 中任意一个为 true，返回 trueVal；否则返回 falseVal

func IfBetween ¶

func IfBetween[T types.Numerical](val, min, max T, trueVal, falseVal T) T

IfBetween 区间检查三元运算（支持数值类型） 检查 val 是否在 [min, max] 区间内

func IfCEmpty ¶

func IfCEmpty[T comparable, R any](val T, trueVal, falseVal R) R

IfCEmpty 可比较类型零值检查三元运算 使用 validator.IsCEmpty 检查可比较类型是否为零值 如果为零值，返回 trueVal；否则返回 falseVal

示例：

result := mathx.IfCEmpty(0, "is zero", "not zero")           // "is zero"
result := mathx.IfCEmpty("", "is empty", "not empty")        // "is empty"
result := mathx.IfCEmpty(false, "is false", "is true")       // "is false"

func IfCall ¶

func IfCall[T any](condition bool, result T, err error, callbacks ...func(T, error))

IfCall 根据布尔条件 condition，选择性调用对应的回调函数

Params

• condition: 判断条件，true 时调用 onTrue，false 时调用 onFalse
• result: 泛型参数，传递给回调函数的结果值
• err: 错误信息，传递给回调函数
• callbacks: 可变参数，可以传 0-2 个回调函数
• callbacks[0]: onTrue - 条件为 true 时调用
• callbacks[1]: onFalse - 条件为 false 时调用

函数逻辑：

1. 根据 condition 选择要调用的回调函数
2. 如果回调不为 nil，则调用它
3. 支持省略任意回调函数

示例：

完整版本（两个回调）
mathx.IfCall(err != nil, result, err,
    func(r T, e error) { onSuccess(r) },
    func(r T, e error) { onError(e) },
)

只需要 true 分支
mathx.IfCall(success, data, nil,
    func(r T, e error) { log.Info("成功: %v", r) },
)

只需要 false 分支
mathx.IfCall(err != nil, nil, err,
    nil,
    func(r T, e error) { log.Error("错误: %v", e) },
)

func IfCast ¶

func IfCast[R any](val any, defaultVal R) R

IfCast 类型转换三元运算 尝试将 val 断言为 R 类型 如果断言成功，返回转换后的值；否则返回 defaultVal

func IfChain ¶

func IfChain[T any](pairs []ConditionValue[T], defaultVal T) T

IfChain 根据传入的 ConditionValue 切片，依次判断每个条件 返回第一个条件为 true 的对应值；如果所有条件均为 false，返回默认值 defaultVal 实现类似 if-else if-else 的多条件链判断，且支持任意泛型类型

示例：

pairs := []ConditionValue[int]{
    {Cond: x > 0, Value: 1},
    {Cond: x == 0, Value: 0},
    {Cond: x < 0, Value: -1},
}
result := IfChain(pairs, 999) // 若都不满足，返回 999

func IfClamp ¶

func IfClamp[T types.Numerical](val, min, max T) T

IfClamp 将值限制在 [min, max] 范围内 如果 val < min，返回 min；如果 val > max，返回 max；否则返回 val

示例：

result := mathx.IfClamp(150, 0, 100)  // 返回 100
result := mathx.IfClamp(-10, 0, 100)  // 返回 0
result := mathx.IfClamp(50, 0, 100)   // 返回 50

func IfContains ¶

func IfContains[T comparable](slice []T, target T, trueVal, falseVal T) T

IfContains 包含检查三元运算 检查 slice 是否包含 target 如果包含，返回 trueVal；否则返回 falseVal

func IfContainsChinese ¶

func IfContainsChinese[T any](str string, trueVal, falseVal T) T

IfContainsChinese 中文字符检查三元运算 使用 validator.ContainsChinese 检查字符串是否包含中文 如果包含，返回 trueVal；否则返回 falseVal

示例：

result := mathx.IfContainsChinese("你好world", "has chinese", "no chinese")  // "has chinese"
result := mathx.IfContainsChinese("hello", "has chinese", "no chinese")      // "no chinese"

func IfCount ¶

func IfCount[T any](conditions []bool, threshold int, trueVal, falseVal T) T

IfCount 计数条件三元运算 统计 conditions 中为 true 的条件数量 如果满足条件的数量 >= threshold，返回 trueVal；否则返回 falseVal

func IfCountGt ¶

func IfCountGt[R any](count, threshold int64, trueVal, falseVal R) R

IfCountGt 计数大于检查 检查计数是否大于阈值

func IfDefaultAndClamp ¶

func IfDefaultAndClamp[T types.Numerical](val, defaultVal, min, max T) T

IfDefaultAndClamp 先应用默认值，再做范围限制 适用于分页等场景，先判断 <=0 用默认值，再限制在[min,max]区间

示例：

pageSize = mathx.IfDefaultAndClamp(pageSize, 10, 1, 100)

func IfDo ¶

func IfDo[T any](condition bool, do DoFunc[T], defaultVal T) T

IfDo 根据条件 condition 决定是否执行函数 do 并返回结果 如果 condition 为 true，执行 do() 并返回其结果；否则返回默认值 defaultVal

func IfDoAF ¶

func IfDoAF[T any](condition bool, do DoFunc[T], defaultFunc DoFunc[T]) T

IfDoAF 根据条件 condition 决定执行 do 或 defaultFunc 函数并返回结果 如果 condition 为 true，执行 do()；否则执行 defaultFunc()

func IfDoAsync ¶

func IfDoAsync[T any](condition bool, do DoFunc[T], defaultVal ...T) <-chan T

IfDoAsync 支持异步执行延迟函数 do，返回结果的通道 根据条件 condition 决定是否执行 do()，否则返回默认值 defaultVal（可选） 结果通过带缓冲的通道返回，避免阻塞

示例：

提供默认值
ch := mathx.IfDoAsync(needFetch,
    func() Data { return fetchData() },
    defaultData,
)

不提供默认值（返回零值）
ch := mathx.IfDoAsync(needFetch,
    func() Data { return fetchData() },
)

func IfDoAsyncWithTimeout ¶

func IfDoAsyncWithTimeout[T any](condition bool, do DoFunc[T], timeoutMs int, defaultVal ...T) <-chan T

IfDoAsyncWithTimeout 异步执行延迟函数 do，支持超时控制 condition 为 true 时执行 do()，否则返回默认值 defaultVal（可选） timeoutMs 指定超时时间（毫秒），超时则返回类型 T 的零值 返回一个通道，异步获取结果

func IfDoWithError ¶

func IfDoWithError[T any](condition bool, do DoFuncWithError[T], defaultVal T) (T, error)

IfDoWithError 根据条件 condition 执行带错误返回的函数 do 如果 condition 为 true，执行 do() 并返回结果与错误；否则返回默认值 defaultVal 和 nil 错误

func IfDoWithErrorAsync ¶

func IfDoWithErrorAsync[T any](condition bool, do DoFuncWithError[T], defaultVal T) <-chan ResultWithError[T]

IfDoWithErrorAsync 支持异步执行带错误返回的函数 do 根据条件 condition 决定是否执行 do()，否则返回默认值 defaultVal 和 nil 错误 返回一个通道，通道元素是 ResultWithError[T] 类型

func IfDoWithErrorDefault ¶

func IfDoWithErrorDefault[T any](condition bool, do DoFuncWithError[T], defaultVal T) T

IfDoWithErrorDefault 根据条件 condition 执行带错误返回的函数 do 如果 condition 为 false 或 do 返回错误，则返回 defaultVal

func IfElse ¶

func IfElse[T any](conditions []bool, values []T, defaultVal T) T

IfElse 实现多条件链式判断，安全泛型版本IfE conditions 和 values 长度必须相等，依次判断 conditions 中的条件 返回第一个为 true 的对应 values 元素；如果没有满足条件，返回 defaultVal 适合实现类似 if ... else if ... else 的多分支逻辑

func IfEmpty ¶

func IfEmpty[T any](val T, defaultVal T) T

IfEmpty 空值检查三元运算 使用 validator.IsEmptyValue 检查值是否为空 如果为空，返回 defaultVal；否则返回 val

示例：

result := mathx.IfEmpty("", "default")        // "default"
result := mathx.IfEmpty("hello", "default")   // "hello"
result := mathx.IfEmpty([]int{}, []int{1,2})  // []int{1,2}
result := mathx.IfEmpty(0, 100)               // 100

func IfEmptyDo ¶

func IfEmptyDo[T any](val T, do DoFunc[T]) T

IfEmptyDo 空值检查执行函数 如果值为空，执行 do 函数；否则返回 val

示例：

result := mathx.IfEmptyDo("", func() string { return generateDefaultName() })
result := mathx.IfEmptyDo([]int{}, func() []int { return loadDefaultData() })

func IfEmptySlice ¶

func IfEmptySlice[T any, R any](slice []T, trueVal, falseVal R) R

IfEmptySlice 空切片检查三元运算 如果切片为空，返回 trueVal；否则返回 falseVal

func IfEq ¶

func IfEq[T comparable, R any](a, b T, trueVal, falseVal R) R

IfEq 等于比较三元运算 如果 a == b，返回 trueVal；否则返回 falseVal

示例：

result := mathx.IfEq(5, 5, "equal", "not equal")  // "equal"
result := mathx.IfEq(5, 3, "equal", "not equal")  // "not equal"

func IfErrOrNil ¶

func IfErrOrNil[T comparable, R any](val T, err error, trueVal, falseVal R) R

IfErrOrNil 错误或空值检查 如果 err != nil 或 val 为零值，返回 trueVal；否则返回 falseVal

func IfExec ¶

func IfExec(condition bool, action func())

IfExec 根据条件执行副作用操作（无返回值） 适用于只需要执行代码块，不需要返回值的场景

Params

• condition: 判断条件，true 时执行 action
• action: 条件为 true 时执行的函数

示例：

mathx.IfExec(user != nil, func() {
    log.Printf("User: %s", user.Name)
})

func IfExecElse ¶

func IfExecElse(condition bool, onTrue func(), onFalse ...func())

IfExecElse 根据条件执行不同的副作用操作 类似三元运算符，但用于执行代码块而非返回值

Params

• condition: 判断条件
• onTrue: 条件为 true 时执行的函数
• onFalse: 条件为 false 时执行的函数（可选，可以省略或传 nil）

示例：

两个分支都需要

mathx.IfExecElse(err == nil,
    func() { log.Info("Success") },
    func() { log.Error("Failed: " + err.Error()) },
)

只需要 false 分支（true 分支传 nil）
mathx.IfExecElse(err == nil, nil, func() { log.Error("Failed") })

或者使用可变参数版本，省略第二个参数
mathx.IfExecElse(err == nil, func() { log.Info("Success") })

func IfFilter ¶

func IfFilter[T any](useFilter bool, slice []T, predicate func(T) bool) []T

IfFilter 过滤三元运算 根据 predicate 函数过滤 slice 如果 useFilter 为 true，返回过滤后的结果；否则返回原始 slice

func IfGe ¶

func IfGe[T types.Numerical, R any](a, b T, trueVal, falseVal R) R

IfGe 大于等于比较三元运算 如果 a >= b，返回 trueVal；否则返回 falseVal

示例：

result := mathx.IfGe(10, 10, "yes", "no")  // "yes"
result := mathx.IfGe(9, 10, "yes", "no")   // "no"

func IfGeZero ¶

func IfGeZero[T types.Numerical](val, defaultVal T) T

IfGeZero 大于等于零时使用默认值 如果 val >= 0，返回 defaultVal；否则返回 val

示例：

config.ErrorCode = mathx.IfGeZero(config.ErrorCode, -1)

func IfGt ¶

func IfGt[T types.Numerical, R any](a, b T, trueVal, falseVal R) R

IfGt 大于比较三元运算 如果 a > b，返回 trueVal；否则返回 falseVal

示例：

result := mathx.IfGt(10, 5, "greater", "not greater")  // "greater"
result := mathx.IfGt(3, 5, "greater", "not greater")   // "not greater"

func IfGtZero ¶

func IfGtZero[T types.Numerical](val, defaultVal T) T

IfGtZero 大于零时使用默认值 如果 val > 0，返回 defaultVal；否则返回 val

示例：

config.MaxSize = mathx.IfGtZero(config.MaxSize, 100)

func IfHasEmpty ¶

func IfHasEmpty[T any](values []interface{}, trueVal, falseVal T) T

IfHasEmpty 包含空值检查三元运算 检查提供的值中是否有空值 如果有空值，返回 trueVal；否则返回 falseVal

示例：

result := mathx.IfHasEmpty([]interface{}{"hello", "", "world"}, "has empty", "all filled")  // "has empty"
result := mathx.IfHasEmpty([]interface{}{"a", "b", "c"}, "has empty", "all filled")         // "all filled"

func IfIPAllowed ¶

func IfIPAllowed[T any](ip string, cidrList []string, trueVal, falseVal T) T

IfIPAllowed IP白名单检查三元运算 使用 validator.IsIPAllowed 检查 IP 是否在白名单中 如果允许，返回 trueVal；否则返回 falseVal

示例：

allowList := []string{"192.168.1.0/24", "10.0.0.1"}
result := mathx.IfIPAllowed("192.168.1.100", allowList, "allowed", "denied")  // "allowed"
result := mathx.IfIPAllowed("8.8.8.8", allowList, "allowed", "denied")        // "denied"

func IfLe ¶

func IfLe[T types.Numerical, R any](a, b T, trueVal, falseVal R) R

IfLe 小于等于比较三元运算 如果 a <= b，返回 trueVal；否则返回 falseVal

示例：

result := mathx.IfLe(5, 5, "yes", "no")  // "yes"
result := mathx.IfLe(6, 5, "yes", "no")  // "no"

func IfLeZero ¶

func IfLeZero[T types.Numerical](val, defaultVal T) T

IfLeZero 小于等于零时使用默认值 如果 val <= 0，返回 defaultVal；否则返回 val 适用于配置参数、超时时间等场景

示例：

config.CleanupInterval = mathx.IfLeZero(config.CleanupInterval, time.Minute*10)
config.PageSize = mathx.IfLeZero(config.PageSize, 10)
config.Timeout = mathx.IfLeZero(config.Timeout, 30*time.Second)

func IfLenEq ¶

func IfLenEq[T any, R any](slice []T, length int, trueVal, falseVal R) R

IfLenEq 长度等于检查

func IfLenGt ¶

func IfLenGt[T any, R any](slice []T, threshold int, trueVal, falseVal R) R

IfLenGt 长度检查三元运算 检查切片长度是否大于指定值

示例：

message := mathx.IfLenGt(availableAgents, 0,
    "ABC",
    "DEF",
)

func IfLt ¶

func IfLt[T types.Numerical, R any](a, b T, trueVal, falseVal R) R

IfLt 小于比较三元运算 如果 a < b，返回 trueVal；否则返回 falseVal

示例：

result := mathx.IfLt(3, 5, "less", "not less")  // "less"
result := mathx.IfLt(7, 5, "less", "not less")  // "not less"

func IfLtZero ¶

func IfLtZero[T types.Numerical](val, defaultVal T) T

IfLtZero 小于零时使用默认值 如果 val < 0，返回 defaultVal；否则返回 val

示例：

config.MinValue = mathx.IfLtZero(config.MinValue, 10)
config.Offset = mathx.IfLtZero(config.Offset, 0)

func IfMap ¶

func IfMap[T, R any](condition bool, val T, mapper func(T) R, defaultVal R) R

IfMap 映射转换三元运算 根据条件决定是否对值进行转换 如果 condition 为 true，对 val 执行 mapper 函数；否则返回 defaultVal

func IfMapElse ¶

func IfMapElse[T, R any](condition bool, val T, trueMapper func(T) R, falseMapper ...func(T) R) R

IfMapElse 双向映射三元运算 根据条件选择不同的映射函数 如果 condition 为 true，执行 trueMapper；否则执行 falseMapper（可选） 如果不提供 falseMapper，则 condition=false 时返回 R 类型的零值

示例：

完整版本
output := mathx.IfMapElse(isJSON, data,
    func(d Data) string { return d.ToJSON() },
    func(d Data) string { return d.ToXML() },
)

简化版本（false 时返回零值）
output := mathx.IfMapElse(needFormat, data,
    func(d Data) string { return d.Format() },
)

func IfMemoized ¶

func IfMemoized[T any](condition bool, key string, cache map[string]T, computeFn func() T, defaultVal T) T

IfMemoized 带缓存的三元运算 缓存函数执行结果，避免重复计算 cache 用于存储计算结果

func IfMulti ¶

func IfMulti[T comparable, R any](target T, values []T, trueVal, falseVal R) R

IfMulti 多值比较三元运算 检查 target 是否等于 values 中的任意一个 如果匹配，返回 trueVal；否则返回 falseVal

func IfNe ¶

func IfNe[T comparable, R any](a, b T, trueVal, falseVal R) R

IfNe 不等于比较三元运算 如果 a != b，返回 trueVal；否则返回 falseVal

示例：

result := mathx.IfNe(5, 3, "different", "same")  // "different"
result := mathx.IfNe(5, 5, "different", "same")  // "same"

func IfNil ¶

func IfNil[T any](val interface{}, trueVal, falseVal T) T

IfNil Nil检查三元运算 使用 validator.IsNil 检查值是否为 nil 如果为 nil，返回 trueVal；否则返回 falseVal

示例：

var ptr *string
result := mathx.IfNil(ptr, "is nil", "not nil")              // "is nil"
result := mathx.IfNil(&value, "is nil", "not nil")           // "not nil"
result := mathx.IfNil([]int(nil), "is nil", "not nil")       // "is nil"

func IfNotCEmpty ¶

func IfNotCEmpty[T comparable, R any](val T, trueVal, falseVal R) R

IfNotCEmpty 可比较类型非零值检查三元运算 使用 validator.IsCEmpty 检查可比较类型是否非零值 如果非零值，返回 trueVal；否则返回 falseVal

示例：

result := mathx.IfNotCEmpty("hello", "has text", "empty")    // "has text"
result := mathx.IfNotCEmpty(0, "has value", "zero")          // "zero"

func IfNotEmpty ¶

func IfNotEmpty(str string, defaultVal string) string

IfNotEmpty 空字符串检查三元运算 如果字符串非空，返回原字符串；否则返回默认值

func IfNotEmptyValue ¶

func IfNotEmptyValue[T any](val T, defaultVal T) T

IfNotEmptyValue 非空值检查三元运算 使用 validator.IsEmptyValue 检查值是否非空 如果非空，返回 val；否则返回 defaultVal

示例：

result := mathx.IfNotEmptyValue("hello", "default")  // "hello"
result := mathx.IfNotEmptyValue("", "default")       // "default"
result := mathx.IfNotEmptyValue([]int{1}, []int{})   // []int{1}

func IfNotNil ¶

func IfNotNil[T any](val *T, defaultVal T) T

IfNotNil 空值检查三元运算 如果 val 不为 nil，返回 val；否则返回 defaultVal 适用于指针类型的空值检查

func IfNotNilValue ¶

func IfNotNilValue[T any](val interface{}, trueVal, falseVal T) T

IfNotNilValue 非Nil检查三元运算 使用 validator.IsNil 检查值是否非 nil 如果非 nil，返回 trueVal；否则返回 falseVal

示例：

result := mathx.IfNotNilValue(&value, "has value", "no value")  // "has value"
result := mathx.IfNotNilValue(nil, "has value", "no value")     // "no value"

func IfNotZero ¶

func IfNotZero[T comparable](val T, defaultVal T) T

IfNotZero 零值检查三元运算 如果值不为类型零值，返回原值；否则返回默认值 支持任意可比较类型

func IfNull ¶

func IfNull[T any](str string, trueVal, falseVal T) T

IfNull "null"字符串检查三元运算 使用 validator.IsNull 检查字符串是否为 "null" 如果是，返回 trueVal；否则返回 falseVal

示例：

result := mathx.IfNull("null", "is null", "not null")  // "is null"
result := mathx.IfNull("undefined", "is null", "not null") // "not null"

func IfNullOrUndefined ¶

func IfNullOrUndefined[T any](str string, trueVal, falseVal T) T

IfNullOrUndefined "null"或"undefined"字符串检查三元运算 同时支持 "null" 和 "undefined" 字符串 如果是其中之一，返回 trueVal；否则返回 falseVal

示例：

result := mathx.IfNullOrUndefined("null", "empty", "not empty")        // "empty"
result := mathx.IfNullOrUndefined("undefined", "empty", "not empty")   // "empty"
result := mathx.IfNullOrUndefined("hello", "empty", "not empty")       // "not empty"

func IfPipeline ¶

func IfPipeline[T any](condition bool, input T, funcs []func(T) T, defaultVal T) T

IfPipeline 管道式三元运算 如果 condition 为 true，依次执行 funcs 中的函数 每个函数的输出作为下一个函数的输入 如果 condition 为 false，返回 defaultVal

func IfSafeFieldName ¶

func IfSafeFieldName[T any](field string, trueVal, falseVal T) T

IfSafeFieldName 字段名安全检查三元运算 使用 validator.IsSafeFieldName 检查字段名是否安全 如果安全，返回 trueVal；否则返回 falseVal

示例：

result := mathx.IfSafeFieldName("user_name", "safe", "unsafe")       // "safe"
result := mathx.IfSafeFieldName("user'; DROP TABLE", "safe", "unsafe") // "unsafe"

func IfSafeIndex ¶

func IfSafeIndex[T any](slice []T, index int, defaultVal T) T

IfSafeIndex 安全索引访问三元运算 安全地访问 slice 的指定索引 如果索引有效，返回对应元素；否则返回 defaultVal

func IfSafeKey ¶

func IfSafeKey[K comparable, V any](m map[K]V, key K, defaultVal V) V

IfSafeKey 安全键访问三元运算 安全地访问 map 的指定键 如果键存在，返回对应值；否则返回 defaultVal

func IfStrFmt ¶

func IfStrFmt(condition bool, trueFormat string, trueArgs []any, falseFormat string, falseArgs []any) (string, []any)

IfStrFmt 条件格式化字符串选择 根据条件选择不同的格式化字符串和参数

示例：

format, args := mathx.IfStrFmt(err != nil,
    "  - %s: 获取负载失败 (%v)", []any{agentID, err},
    "  - %s: %d 个工单", []any{agentID, workload},
)
logger.InfoContext(ctx, format, args...)

func IfSwitch ¶

func IfSwitch[K comparable, V any](key K, cases map[K]V, defaultVal V) V

IfSwitch 开关式三元运算 根据 key 从 cases 映射中查找对应值 如果找到，返回对应值；否则返回 defaultVal

func IfTryParse ¶

func IfTryParse[T, R any](input T, parser func(T) (R, error), defaultVal R) R

IfTryParse 尝试解析三元运算 使用 parser 函数尝试解析 input 如果解析成功（无错误），返回解析结果；否则返回 defaultVal

func IfUndefined ¶

func IfUndefined[T any](str string, trueVal, falseVal T) T

IfUndefined "undefined"字符串检查三元运算 使用 validator.IsUndefined 检查字符串是否为 "undefined" 如果是，返回 trueVal；否则返回 falseVal

示例：

result := mathx.IfUndefined("undefined", "is undef", "defined")  // "is undef"
result := mathx.IfUndefined("null", "is undef", "defined")       // "defined"

func IfValidate ¶

func IfValidate[T, R any](val T, validator func(T) bool, validVal, invalidVal R) R

IfValidate 验证三元运算 使用验证函数检查值，根据验证结果返回不同值 如果验证通过，返回 validVal；否则返回 invalidVal

func IndexOfSlice ¶

func IndexOfSlice[T comparable](slice []T, item T) int

IndexOfSlice 返回元素在切片中的索引，不存在返回 -1

func InsertionSort ¶

func InsertionSort(arr []int)

InsertionSort 对小规模数组使用插入排序

func LastIndexOfSlice ¶

func LastIndexOfSlice[T comparable](slice []T, item T) int

LastIndexOfSlice 返回元素在切片中最后一次出现的索引，不存在返回 -1

func LongestCommonPrefix ¶

func LongestCommonPrefix(a, b string) int

LongestCommonPrefix 返回两个字符串的最长公共前缀的长度 参数: a - 第一个字符串 b - 第二个字符串 返回值: 返回两个字符串的最长公共前缀的长度

func MapAssign ¶

func MapAssign[K comparable, V any, M ~map[K]V](maps ...M) M

MapAssign 从左到右合并多个 map，后者覆盖前者 与 ShallowMergeMap 区别：ShallowMergeMap 接收可变参数 map[K]V， MapAssign 接收自定义 map 类型 M（~map[K]V）保持类型

func MapClone ¶

func MapClone[K comparable, V any](m map[K]V) map[K]V

MapClone 浅拷贝 map 的键值对（不递归复制值引用的对象） 与 CloneMap 功能等价，命名遵循 MapXxx 风格

func MapFilterKeys ¶

func MapFilterKeys[K comparable, V any](in map[K]V, predicate func(key K, value V) bool) []K

MapFilterKeys 按 predicate 过滤，返回满足条件的键切片（Filter + Keys 组合）

func MapFilterToSlice ¶

func MapFilterToSlice[K comparable, V any, R any](in map[K]V, iteratee func(key K, value V) (R, bool)) []R

MapFilterToSlice 过滤+转换 map 到切片 iteratee 返回 (结果, 是否保留)，仅保留的元素进入切片

func MapFilterValues ¶

func MapFilterValues[K comparable, V any](in map[K]V, predicate func(key K, value V) bool) []V

MapFilterValues 按 predicate 过滤，返回满足条件的值切片（Filter + Values 组合）

func MapFromEntries ¶

func MapFromEntries[K comparable, V any](entries []MapEntry[K, V]) map[K]V

MapFromEntries 将键值对切片转为 map（同 key 后者覆盖前者）

func MapHasKey ¶

func MapHasKey[K comparable, V any](in map[K]V, key K) bool

MapHasKey 检查键是否存在

func MapInvert ¶

func MapInvert[K, V comparable](in map[K]V) map[V]K

MapInvert 反转 map 的键和值（V 必须可比较） 若有重复值，后者覆盖前者

func MapKeys ¶

func MapKeys[K comparable, V any](in ...map[K]V) []K

MapKeys 提取一个或多个 map 的所有键，返回切片 支持多个 map，键来自所有 map 的并集（不去重，见 MapUniqKeys 去重版本）

func MapMapEntries ¶

func MapMapEntries[K1 comparable, V1 any, K2 comparable, V2 any](in map[K1]V1, iteratee func(key K1, value V1) (K2, V2)) map[K2]V2

MapMapEntries 同时转换 key 和 value，返回新类型的 map

func MapMapKeys ¶

func MapMapKeys[K comparable, V any, R comparable](in map[K]V, iteratee func(value V, key K) R) map[R]V

MapMapKeys 转换所有键，返回新 map（值类型不变）

func MapMapValues ¶

func MapMapValues[K comparable, V any, R any](in map[K]V, iteratee func(value V, key K) R) map[K]R

MapMapValues 转换所有值，返回新 map（键类型不变） 与 TransformMapValues 区别：TransformMapValues 只接收 value，本方法接收 (value, key)

func MapOmitBy ¶

func MapOmitBy[K comparable, V any, M ~map[K]V](in M, predicate func(key K, value V) bool) M

MapOmitBy 按 predicate 过滤，移除满足条件的键值对（与 PickBy 相反）

func MapOmitByKeys ¶

func MapOmitByKeys[K comparable, V any, M ~map[K]V](in M, keys []K) M

MapOmitByKeys 按键列表过滤，移除 keys 中存在的键

func MapOmitByValues ¶

func MapOmitByValues[K, V comparable, M ~map[K]V](in M, values []V) M

MapOmitByValues 按值列表过滤，移除 values 中存在的值（V 必须可比较）

func MapPickBy ¶

func MapPickBy[K comparable, V any, M ~map[K]V](in M, predicate func(key K, value V) bool) M

MapPickBy 按 predicate 过滤，保留满足条件的键值对，返回同类型 map

func MapPickByKeys ¶

func MapPickByKeys[K comparable, V any, M ~map[K]V](in M, keys []K) M

MapPickByKeys 按键列表过滤，仅保留 keys 中存在的键

func MapPickByValues ¶

func MapPickByValues[K, V comparable, M ~map[K]V](in M, values []V) M

MapPickByValues 按值列表过滤，仅保留 values 中存在的值（V 必须可比较）

func MapSliceByKey ¶

func MapSliceByKey[T any, K comparable](slice []T, keyFunc func(T) K) map[K]T

MapSliceByKey 将一个切片 slice 转换为一个 map， 键由 keyFunc 从切片元素中提取，值为对应的切片元素。

泛型参数说明：

T - 切片元素的类型，支持任意类型。
K - map 的键类型，必须是可比较类型（comparable），
    这是 Go map 键的要求。

参数说明：

slice - 输入的切片，类型为 []T。
keyFunc - 函数，接收一个 T 类型元素，返回对应的键 K。

返回值说明：

返回一个 map[K]T，键是 keyFunc 生成的键，值是对应的切片元素。
如果 slice 中有重复的键，后出现的元素会覆盖前面的。

例子：

users := []User{{ID:1, Name:"A"}, {ID:2, Name:"B"}}
userMap := MapSliceByKey(users, func(u User) int { return u.ID })
userMap[1] == User{ID:1, Name:"A"}

func MapToSlice ¶

func MapToSlice[K comparable, V any, R any](in map[K]V, iteratee func(key K, value V) R) []R

MapToSlice 将 map 转为切片，iteratee 接收 (key, value) 返回结果元素

func MapUniqKeys ¶

func MapUniqKeys[K comparable, V any](in ...map[K]V) []K

MapUniqKeys 提取一个或多个 map 的所有去重键

func MapUniqValues ¶

func MapUniqValues[K, V comparable](in ...map[K]V) []V

MapUniqValues 提取一个或多个 map 的所有去重值（V 必须可比较）

func MapValueOr ¶

func MapValueOr[K comparable, V any](in map[K]V, key K, fallback V) V

MapValueOr 返回键对应的值或 fallback

func MapValues ¶

func MapValues[K comparable, V any](in ...map[K]V) []V

MapValues 提取一个或多个 map 的所有值，返回切片

func MarshalJSONOrDefault ¶

func MarshalJSONOrDefault(value any, defaultVal string) string

MarshalJSONOrDefault 将任意值序列化为 JSON 字符串，失败或空值时返回默认值 适用于需要确保 JSON 字段不为空的场景（如 MySQL JSON 列）

参数：

• value: 待序列化的值（可以是 map、struct、slice 等任意类型）
• defaultVal: 序列化失败或值为空时返回的默认值（通常为 "{}" 或 "[]"）

返回：

• JSON 字符串或默认值

示例：

map[string]string 序列化
extra := map[string]string{"key": "value"}
json := mathx.MarshalJSONOrDefault(extra, "{}") // 返回 {"key":"value"}

空 map 返回默认值
empty := map[string]string{}
json := mathx.MarshalJSONOrDefault(empty, "{}") // 返回 {}

nil 值返回默认值
json := mathx.MarshalJSONOrDefault(nil, "{}") // 返回 {}

序列化失败返回默认值
invalid := make(chan int) // channel 不能序列化
json := mathx.MarshalJSONOrDefault(invalid, "{}") // 返回 {}

func Max ¶

func Max[T types.Numerical](values ...T) T

Max 返回多个数值中的最大值 - 使用 cmp.Compare 进行泛型比较

func Mean ¶

func Mean(values []float64) float64

Mean 计算平均值

func MergeLayeredKeyValues ¶

func MergeLayeredKeyValues[T any, KV any](
	layers []*T,
	fieldGetter func(*T) []KV,
	keyFieldName string,
	valueFieldName string,
) []KV

MergeLayeredKeyValues 多层级键值对合并工具（支持传入任意数量的配置层级）

参数：

• layers: 配置层级切片，从低到高优先级（越靠后优先级越高，后面的会覆盖前面的）
• fieldGetter: 从配置对象中提取键值对切片的函数
• keyFieldName: 键值对结构中 key 字段的名称（如 "Key"）
• valueFieldName: 键值对结构中 value 字段的名称（如 "Value"）

返回：合并后的键值对切片，保持 key 首次出现的顺序

特性：

• 支持任意层级的链式合并
• 自动跳过 nil 层级
• 自动跳过空值（值为空字符串的项不会覆盖已有值）
• 保持 key 的首次出现顺序
• 使用反射自动提取字段，支持任意结构体

示例：

type LocalizedText struct {
    Key   string
    Value string
}

type Config struct {
    Messages []LocalizedText
}

result := MergeLayeredKeyValues(
    []*Config{hardcodedDefault, ownerConfig, agentConfig},
    func(c *Config) []LocalizedText { return c.Messages },
    "Key",
    "Value",
)

func MergeLayeredScalar ¶

func MergeLayeredScalar[T any, V types.Numerical](layers []*T, fieldGetter func(*T) V) V

MergeLayeredScalar 多层级标量字段合并，从高优先级层取第一个非零值

参数：

• layers: 配置层级切片，从低到高优先级（越靠后优先级越高）
• fieldGetter: 从配置对象中提取标量值的函数

返回：第一个非零值，若全为零值则返回零值

示例：

timeout := MergeLayeredScalar(layers, func(c *Config) int32 { return c.Timeout })
ratio := MergeLayeredScalar(layers, func(c *Config) float64 { return c.Ratio })

func Min ¶

func Min[T types.Numerical](values ...T) T

Min 返回多个数值中的最小值 - 使用 cmp.Compare 进行泛型比较

func MinSlice ¶

func MinSlice(values []float64) float64

MinSlice 返回切片中的最小值 Deprecated: 使用 SliceMinOrdered 替代，支持所有 Ordered 类型（int/float/string 等）

func NoneSlice ¶

func NoneSlice[T any](slice []T, predicate func(T) bool) bool

NoneSlice 检查是否没有元素满足条件

func ParseInt64 ¶

func ParseInt64(s string) (int64, error)

ParseInt64 将字符串解析为int64 支持常见的字符串到int64的转换，解析失败时返回错误

func PartitionSlice ¶

func PartitionSlice[T any](slice []T, predicate func(T) bool) (truthy, falsy []T)

PartitionSlice 将切片分为两部分：满足条件的和不满足条件的

func Percentage ¶

func Percentage(part, total uint64) float64

Percentage 计算百分比

func Percentile ¶

func Percentile(values []float64, p float64) float64

Percentile 计算百分位数（支持50, 90, 95, 99）

func Percentiles ¶

func Percentiles(values []float64, percentiles ...float64) map[float64]float64

Percentiles 批量计算多个百分位数

func QuickSort ¶

func QuickSort(arr []int, low, high int)

QuickSort 实现快速排序算法

func Ratio ¶

func Ratio(part, total uint64) float64

Ratio 计算比率，返回 [0,1] 区间的小数 part 为分子，total 为分母；total 为 0 时返回 0（避免除零） 与 Percentage 的区别：Percentage 返回 [0,100]，Ratio 返回 [0,1] 适用于"终态订单数 = success+failed+cancelled"作为分母的率计算

func RatioFloat ¶

func RatioFloat(part, total float64) float64

RatioFloat 浮点版本，用于分子分母已是 float64 的场景

func RatioRound ¶

func RatioRound(part, total int64, precision int) float64

RatioRound 计算比率并四舍五入保留 precision 位小数，分母为 0 时返回 0 适用于金额/计数等 int64 指标的安全占比计算，避免结果带浮点尾差

func ReduceSlice ¶

func ReduceSlice[T any, R any](slice []T, initial R, accumulator func(R, T) R) R

ReduceSlice 将切片归约为单个值

func RemoveSliceAt ¶

func RemoveSliceAt[T any](slice []T, index int) []T

RemoveSliceAt 移除指定索引的元素

func RepeatField ¶

func RepeatField[T any](field T, count int) []T

RepeatField 返回一个长度为 count 的切片， 切片中的每个元素都是传入的 field 值的副本

func ReturnIfErr ¶

func ReturnIfErr[T any](val T, err error) (T, error)

ReturnIfErr 简化错误检查和返回 如果 err 不为 nil，返回 T 类型的零值和 err；否则返回 val 和 nil

func ReverseSlice ¶

func ReverseSlice[T any](slice []T) []T

ReverseSlice 反转切片（返回新切片）

func ReverseSliceInPlace ¶

func ReverseSliceInPlace[T any](slice []T)

ReverseSliceInPlace 原地反转切片

func SafeGetIndexOrDefault ¶

func SafeGetIndexOrDefault[T any](slice []T, index int, defaultVal T) (val T)

SafeGetIndexOrDefault 安全获取切片指定索引元素，索引越界时返回指定默认值

func SafeGetIndexOrDefaultNoSpace ¶

func SafeGetIndexOrDefaultNoSpace(slice []string, index int, defaultVal string) string

SafeGetIndexOrDefaultNoSpace 安全获取字符串切片指定索引元素，索引越界时返回默认值，且结果去除所有空格

func SafeGetIndexWithErr ¶

func SafeGetIndexWithErr[T any](slice []T, index int) (zero T, err error)

SafeGetIndexWithErr 安全获取切片指定索引的元素 支持任意类型切片，避免索引越界导致 panic 如果索引合法，返回对应元素和 nil 错误；否则返回类型零值和错误

参数:

slice - 目标切片，支持任意类型 []T
index - 需要获取的元素索引，0-based

返回:

T     - 索引对应的元素，索引越界时返回类型零值
error - 发生错误时返回详细错误信息，否则为 nil

示例:

val, _ := SafeGetIndexWithErr([]string{"a", "b", "c"}, 1)
fmt.Println(val) // 输出: b

func SetNestedMapValue ¶

func SetNestedMapValue(m map[string]interface{}, value interface{}, keys ...string)

SetNestedMapValue 在嵌套的 map 中设置值，如果路径不存在则创建 例如: SetNestedMapValue(data, "John", "user", "profile", "name")

func SkipLastSlice ¶

func SkipLastSlice[T any](slice []T, n int) []T

SkipLastSlice 跳过后 n 个元素

func SkipSlice ¶

func SkipSlice[T any](slice []T, n int) []T

SkipSlice 跳过前 n 个元素

func SliceChunk ¶

func SliceChunk[T any](slice []T, size int) [][]T

SliceChunk 将一个切片分割成多个子切片 size 参数指定每个子切片的大小 返回一个包含子切片的切片

func SliceContainsComparable ¶

func SliceContainsComparable[T comparable](slice []T, element T) bool

SliceContainsComparable 检查切片中是否包含某个元素（支持 comparable 类型） 适用于枚举、字符串、结构体等任意 comparable 类型

一律线性查找，零分配

原先按长度分流：超过 1000 条就先把整个切片灌进 map 再查一次 那条分支在任何情况下都更慢，包括它本想优化的最坏情况（元素不存在或在末尾）—— 线性扫描是 n 次比较，建 map 是 n 次插入，后者单次成本高出一个量级， 而「O(1) 查找」只省下最后那一次比较 实测（Apple M4，元素不存在）：

规模      线性              哈希
1000      232.7 ns / 0 B    7141 ns / 36 KB / 5 allocs
20000     4546 ns / 0 B     182821 ns / 591 KB / 65 allocs
200000    45520 ns / 0 B    2096300 ns / 4.7 MB / 513 allocs

map 只在同一切片上反复查找时才划算，而本函数每次调用都要重建它， 调用方若要多次查找，应当自己建一次集合复用

[EN] Always a linear scan, with no allocation. The length-based split that loaded slices over 1000 elements into a map first was slower in every case, including the worst case it meant to improve: a linear scan is n comparisons while building the map is n insertions, each an order of magnitude dearer, and the O(1) lookup only saves the final comparison. A map pays off only across repeated lookups on the same slice, which this function cannot do since it rebuilds one per call; callers needing many lookups should build a set once themselves

func SliceCountBy ¶

func SliceCountBy[T any](collection []T, predicate func(item T) bool) int

SliceCountBy 按条件计数

func SliceCountValues ¶

func SliceCountValues[T comparable](collection []T) map[T]int

SliceCountValues 按值计数，返回 map[值]出现次数

func SliceCountValuesBy ¶

func SliceCountValuesBy[T any, U comparable](collection []T, mapper func(item T) U) map[U]int

SliceCountValuesBy 按键计数，等价于 Map + CountValues

func SliceCut ¶

func SliceCut[T comparable, Slice ~[]T](collection, separator Slice) (before, after Slice, found bool)

SliceCut 围绕第一个 separator 切割，返回前/后两段及是否找到 separator 为空时返回 (空, collection, true)

func SliceDiffSetSorted ¶

func SliceDiffSetSorted[T types.Ordered](arr1, arr2 []T) []T

SliceDiffSetSorted 计算两个已排序数组的对称差集（symmetric difference） 返回仅在其中一个数组中出现的元素（保持有序，自动去重）

算法：双指针一次遍历，O(n+m) 时间复杂度

• arr1[i] < arr2[j]: arr1[i] 仅在 arr1 中，加入结果，i++
• arr1[i] > arr2[j]: arr2[j] 仅在 arr2 中，加入结果，j++
• 相等: 同时出现在两边，跳过，i++, j++
• 自动跳过各自数组内的重复元素（set 语义）

注意：输入必须已排序，否则结果不正确

func SliceDifference ¶

func SliceDifference[T comparable, Slice ~[]T](list1, list2 Slice) (Slice, Slice)

SliceDifference 双向差集，返回 (list1有而list2无, list2有而list1无)

func SliceDropRightWhile ¶

func SliceDropRightWhile[T any, Slice ~[]T](collection Slice, predicate func(item T) bool) Slice

SliceDropRightWhile 从末尾丢弃满足条件的元素，直到遇到第一个不满足的

func SliceDropWhile ¶

func SliceDropWhile[T any, Slice ~[]T](collection Slice, predicate func(item T) bool) Slice

SliceDropWhile 从开头丢弃满足条件的元素，直到遇到第一个不满足的

func SliceElementsMatch ¶

func SliceElementsMatch[T comparable](list1, list2 []T) bool

SliceElementsMatch 检查两切片是否包含相同元素集合（忽略顺序，含重复计数）

func SliceEqual ¶

func SliceEqual[T comparable](a, b []T) bool

SliceEqual 比较两个切片是否相等，支持任何类型

func SliceFilterMap ¶

func SliceFilterMap[T, R any](collection []T, callback func(item T, index int) (R, bool)) []R

SliceFilterMap 过滤+映射组合 回调返回 (映射值, 是否保留)，与 TransformAndFilterSlice 等价但参数顺序更直观

func SliceFilterToMap ¶

func SliceFilterToMap[T any, K comparable, V any](collection []T, transform func(item T, index int) (K, V, bool)) map[K]V

SliceFilterToMap 过滤后转 map 回调返回 (key, value, 是否保留)，仅保留的元素进入 map

func SliceFindDuplicates ¶

func SliceFindDuplicates[T comparable, Slice ~[]T](collection Slice) Slice

SliceFindDuplicates 返回每个重复元素的首次出现（保持原顺序）

func SliceFindDuplicatesBy ¶

func SliceFindDuplicatesBy[T any, U comparable, Slice ~[]T](collection Slice, iteratee func(item T) U) Slice

SliceFindDuplicatesBy 按键函数返回每个重复元素的首次出现

func SliceFindUniques ¶

func SliceFindUniques[T comparable, Slice ~[]T](collection Slice) Slice

SliceFindUniques 返回只出现一次的元素（保持原顺序）

func SliceFindUniquesBy ¶

func SliceFindUniquesBy[T any, U comparable, Slice ~[]T](collection Slice, iteratee func(item T) U) Slice

SliceFindUniquesBy 按键函数返回只出现一次的元素

func SliceFirst ¶

func SliceFirst[T any](collection []T) (T, bool)

SliceFirst 返回首个元素及是否存在

func SliceFirstOr ¶

func SliceFirstOr[T any](collection []T, fallback T) T

SliceFirstOr 返回首个元素或 fallback

func SliceFisherYates ¶

func SliceFisherYates[T comparable](slice []T, maxRetries int) error

SliceFisherYates 洗牌算法打乱数组

func SliceFlatMap ¶

func SliceFlatMap[T, R any](collection []T, iteratee func(item T, index int) []R) []R

SliceFlatMap 映射并展平，一次遍历完成 Map+Flatten iteratee 返回切片，所有返回切片被展平到一个结果切片

func SliceForEachWhile ¶

func SliceForEachWhile[T any](collection []T, iteratee func(item T, index int) bool)

SliceForEachWhile 可中断遍历 iteratee 返回 false 时中断遍历（类似 do-while）

func SliceGroupByMap ¶

func SliceGroupByMap[T any, K comparable, V any](collection []T, iteratee func(item T) (K, V)) map[K][]V

SliceGroupByMap 按键函数分组，返回 map[key][]value 与 GroupSliceBy 区别：value 类型可与原元素不同（iteratee 同时提取 key 和 value）

func SliceHasDuplicates ¶

func SliceHasDuplicates[T comparable](slice []T) bool

SliceHasDuplicates 检查切片中是否存在重复元素

算法：单次遍历 + map 记录已见元素，O(n) 时间 O(n) 空间

• map 查找/插入平均 O(1)，比 goroutine + mutex 方案更快（无锁竞争、无 goroutine 启动开销）
• 发现第一个重复立即返回，避免完整遍历

修复说明：原实现用 goroutine 分块处理，存在三个问题：

1. 跨 chunk 的重复检测不到（每个 goroutine 只检查自己 chunk 内的重复）
2. 共享 map 写入有 race（len(m) 读取未加锁）
3. 小切片 goroutine 启动开销远大于直接计算

预分配到整个切片长度是刻意的，不要「顺手改掉」

看上去它抵消了提前退出的收益——重复出现在第 101 个元素时，仍为两万个槽位 付了钱实测过三种写法（Apple M4，两万个 int）：

形状            预分配              不给提示            上限 1024
第101个重复      44669 ns / 591 KB   2301 ns / 4.4 KB    3217 ns / 37 KB
最后一个重复     244265 ns / 591 KB  601343 ns / 1183 KB 576321 ns / 1145 KB
无重复          243984 ns / 591 KB  598450 ns / 1183 KB 578225 ns / 1145 KB

没有普遍更优的选择：提前退出的场景不给提示快 19 倍，而要扫完全程的场景 预分配快 2.5 倍且内存只要一半（后者的代价是 map 从小长到两万要反复 rehash） 本函数的典型用途是校验输入「有重复就拒绝」，合法数据里没有重复， 因此扫完全程才是常态，按它来取舍 调用方若明知多半有重复且只关心有无，自己用不给提示的 map 更划算

[EN] Pre-sizing to the full length is deliberate. It looks as though it cancels the early exit, and three variants were measured: with no size hint an early duplicate is 19x faster, but a full scan is 2.5x slower and uses twice the memory, since the map has to rehash its way up from nothing. This function is typically used to validate input and reject duplicates, so valid data has none and the full scan is the common case; the trade follows that

func SliceHasPrefix ¶

func SliceHasPrefix[T comparable](collection, prefix []T) bool

SliceHasPrefix 检查切片是否以 prefix 开头

func SliceHasSuffix ¶

func SliceHasSuffix[T comparable](collection, suffix []T) bool

SliceHasSuffix 检查切片是否以 suffix 结尾

func SliceInterleave ¶

func SliceInterleave[T any, Slice ~[]T](collections ...Slice) Slice

SliceInterleave 交替合并多个切片 round-robin 交替从每个切片取元素，依次追加到结果 例：[1,2,3], [4,5], [6,7,8,9] => [1,4,6,2,5,7,3,8,9]

func SliceIntersect ¶

func SliceIntersect[T ~[]E, E comparable](list1 T, list2 T) T

SliceIntersect 返回两个集合的交集

func SliceIsSorted ¶

func SliceIsSorted[T types.Ordered](collection []T) bool

SliceIsSorted 检查切片是否按升序排列

func SliceIsSortedByKey ¶

func SliceIsSortedByKey[T any, K types.Ordered](collection []T, iteratee func(item T) K) bool

SliceIsSortedByKey 检查切片是否按键函数升序排列

func SliceLast ¶

func SliceLast[T any](collection []T) (T, bool)

SliceLast 返回末尾元素及是否存在

func SliceLastOr ¶

func SliceLastOr[T any](collection []T, fallback T) T

SliceLastOr 返回末尾元素或 fallback

func SliceMaxBy ¶

func SliceMaxBy[T any](collection []T, comparison func(a, b T) bool) T

SliceMaxBy 自定义比较的最大值，comparison(a,b) 返回 true 表示 a>b

func SliceMaxIndexBy ¶

func SliceMaxIndexBy[T any](collection []T, comparison func(a, b T) bool) (T, int)

SliceMaxIndexBy 自定义比较的最大值及其索引

func SliceMaxOrdered ¶

func SliceMaxOrdered[T types.Ordered](collection []T) T

SliceMaxOrdered 返回 Ordered 类型切片的最大值（空切片返回零值）

func SliceMinBy ¶

func SliceMinBy[T any](collection []T, comparison func(a, b T) bool) T

SliceMinBy 自定义比较的最小值，comparison(a,b) 返回 true 表示 a<b

func SliceMinIndexBy ¶

func SliceMinIndexBy[T any](collection []T, comparison func(a, b T) bool) (T, int)

SliceMinIndexBy 自定义比较的最小值及其索引

func SliceMinMax ¶

func SliceMinMax[T types.Numerical](list []T, f types.MinMaxFunc[T]) (T, error)

SliceMinMax 计算列表中元素的最小值或最大值 接收一个切片和一个 MinMaxFunc 类型的函数， 根据提供的函数决定是计算最小值还是最大值 如果列表为空，则返回错误

func SliceMinOrdered ¶

func SliceMinOrdered[T types.Ordered](collection []T) T

SliceMinOrdered 返回 Ordered 类型切片的最小值（空切片返回零值）

func SliceNth ¶

func SliceNth[T any](collection []T, nth int) (T, error)

SliceNth 返回第 nth 个元素，nth 为负表示从末尾倒数 越界返回错误

func SliceNthOr ¶

func SliceNthOr[T any](collection []T, nth int, fallback T) T

SliceNthOr 返回第 nth 个元素或 fallback（越界不报错）

func SlicePartitionBy ¶

func SlicePartitionBy[T any, K comparable, Slice ~[]T](collection Slice, iteratee func(item T) K) []Slice

SlicePartitionBy 按键函数分区，返回各分区切片（保持首次出现顺序） 与 PartitionSlice 区别：PartitionBy 返回 []Slice，键由 iteratee 决定

func SliceReject ¶

func SliceReject[T any, Slice ~[]T](collection Slice, predicate func(item T, index int) bool) Slice

SliceReject 反向过滤，保留不满足条件的元素（与 FilterSlice 相反）

func SliceRemoveEmpty ¶

func SliceRemoveEmpty[T any](slice []T) []T

SliceRemoveEmpty 移除切片中的"空"元素（零值或 nil）

适用于元素类型不可比较（如含 slice/map 字段的结构体）的场景 对于 comparable 类型，优先使用 CompactSlice（用 == 比较零值，无反射开销）

性能：使用 reflect.ValueOf(v).IsZero() 直接判断，比 validator.IsEmptyValue 少一层封装

func SliceReplace ¶

func SliceReplace[T comparable, Slice ~[]T](collection Slice, old, nEw T, n int) Slice

SliceReplace 返回副本，将前 n 个 old 替换为 nEw（n<0 表示全部替换）

func SliceReplaceAll ¶

func SliceReplaceAll[T comparable, Slice ~[]T](collection Slice, old, nEw T) Slice

SliceReplaceAll 返回副本，将所有 old 替换为 nEw

func SliceSubset ¶

func SliceSubset[T any, Slice ~[]T](collection Slice, offset int, length uint) Slice

SliceSubset 返回从 offset 开始最多 length 个元素的子切片 offset 为负表示从末尾倒数；不 panic，越界返回空切片

func SliceTimes ¶

func SliceTimes[T any](count int, iteratee func(index int) T) []T

SliceTimes 生成 N 个元素 调用 iteratee n 次，返回结果切片（iteratee 接收索引作为参数）

func SliceToMap ¶

func SliceToMap[T any, K comparable](collection []T, iteratee func(item T) K) map[K]T

SliceToMap 切片转 map（KeyBy） iteratee 返回 key，value 为原元素；同 key 后者覆盖前者

func SliceUnionMulti ¶

func SliceUnionMulti[T comparable, Slice ~[]T](lists ...Slice) Slice

SliceUnionMulti 多个切片的并集（去重，保持首次出现顺序） 与 SliceUnion 区别：支持变参多个切片

func SliceUniq ¶

func SliceUniq[T ~[]E, E comparable](list T) T

SliceUniq 集合去重

func SliceUniqMap ¶

func SliceUniqMap[T any, R comparable](collection []T, iteratee func(item T, index int) R) []R

SliceUniqMap 转换并去重，一次遍历完成 Map+Uniq 相比分别调用 TransformSlice + SliceRemoveDuplicates 减少一次中间切片分配

func SliceWithout ¶

func SliceWithout[T ~[]E, E comparable](list T, exclude ...E) T

SliceWithout 返回不包括所有给定值的切片

func SliceWithoutBy ¶

func SliceWithoutBy[T any, K comparable, Slice ~[]T](collection Slice, iteratee func(item T) K, exclude ...K) Slice

SliceWithoutBy 按键排除元素 排除 iteratee(item) 结果在 exclude 列表中的元素

func SortByCount ¶

func SortByCount[T any](items []T, getCount func(T) uint64)

SortByCount 按计数排序统计数据（降序）

func SortByKey ¶

func SortByKey[T any, K cmp.Ordered](items []T, getKey func(T) K)

SortByKey 按键排序统计数据（升序）- 支持任意可比较类型

func SortByKeyDesc ¶

func SortByKeyDesc[T any, K cmp.Ordered](items []T, getKey func(T) K)

SortByKeyDesc 按键排序统计数据（降序）- 支持任意可比较类型

func SortByKeyDescUnique ¶

func SortByKeyDescUnique[T any, K cmp.Ordered, ID comparable](items []T, getKey func(T) K, getID func(T) ID) []T

SortByKeyDescUnique 按键排序统计数据（降序）并去重 去重规则：保留每个唯一标识的第一个元素（即排序后权重最大的） getKey: 用于排序的键提取函数 getID: 用于去重的唯一标识提取函数

func StdDev ¶

func StdDev(values []float64) float64

StdDev 计算标准差

func TakeLastSlice ¶

func TakeLastSlice[T any](slice []T, n int) []T

TakeLastSlice 获取后 n 个元素

func TakeSlice ¶

func TakeSlice[T any](slice []T, n int) []T

TakeSlice 获取前 n 个元素

func TransformAndCompactSlice ¶

func TransformAndCompactSlice[T any, R comparable](slice []T, transform func(T) R) []R

TransformAndCompactSlice 转换切片并移除零值 这是常见的模式：转换后过滤掉零值元素

参数:

• slice: 输入切片
• transform: 转换函数

返回:

• 转换后移除零值的切片

示例:

clients := []*Client{...}
ips := TransformAndCompactSlice(clients, func(c *Client) string { return getIP(c) })

func TransformSlice ¶

func TransformSlice[T any, R any](slice []T, transform func(T) R) []R

TransformSlice 将切片的每个元素通过函数转换为新类型 使用泛型支持任意类型转换，如 []int -> []string

func UnflattenMap ¶

func UnflattenMap(m map[string]interface{}, separator string) map[string]interface{}

UnflattenMap 将扁平化的 map 还原为嵌套结构 例如: {"a.b.c": 1} => {"a": {"b": {"c": 1}}}

func UniqueSliceBy ¶

func UniqueSliceBy[T any, K comparable](slice []T, keyFunc func(T) K) []T

UniqueSliceBy 使用自定义键函数去重 keyFunc 用于提取每个元素的唯一标识

func ZeroValue ¶

func ZeroValue[T any]() T

ZeroValue 返回类型 T 的零值