API Reference - zhoudm1743/go-util GitHub Wiki

欢迎来到 Go-Util 完整的 API 参考文档。本文档提供了所有公开 API 的详细说明、使用示例和最佳实践。

📖 文档导航

🔗 快速导航

📚 文档约定

参数说明

  • T - 泛型类型参数
  • K - 键类型 (通常用于 map)
  • V - 值类型 (通常用于 map)
  • []T - 切片类型
  • map[K]V - 映射类型
  • chan T - 通道类型

返回值约定

  • 大多数方法返回指向自身的指针以支持链式调用
  • 转换方法（如 String(), ToSlice()）返回最终值
  • 查询方法（如 Contains(), IsEmpty()）返回布尔值
  • 可能失败的操作返回 (result, error) 元组

错误处理

  • nil 输入通常返回空值或默认值
  • 索引越界返回零值和错误
  • 类型转换失败返回零值和描述性错误

XStr 字符串工具

XStr 提供了强大的字符串处理功能，支持链式调用、Unicode 处理、格式验证等。

创建和基础操作

Str(s string) *XStr

创建一个新的 XStr 实例。

str := util.Str("hello world")

参数:

  • s string - 输入字符串

返回值:

  • *XStr - XStr 实例

String() string

获取字符串的最终值。

result := util.Str("HELLO").Lower().String()
// 结果: "hello"

返回值:

  • string - 最终字符串值

大小写操作

Upper() *XStr

将字符串转换为大写。

result := util.Str("hello").Upper().String()
// 结果: "HELLO"

特性:

  • 支持 Unicode 字符
  • 保持原实例不变
  • 返回新的 XStr 实例

Lower() *XStr

将字符串转换为小写。

result := util.Str("HELLO").Lower().String()
// 结果: "hello"

Title() *XStr

将字符串转换为标题格式（每个单词首字母大写）。

result := util.Str("hello world").Title().String()
// 结果: "Hello World"

FirstUpper() *XStr

将字符串首字母转换为大写。

result := util.Str("hello").FirstUpper().String()
// 结果: "Hello"

FirstLower() *XStr

将字符串首字母转换为小写。

result := util.Str("Hello").FirstLower().String()
// 结果: "hello"

命名风格转换

CamelCase() *XStr

转换为驼峰命名风格。

result := util.Str("hello_world").CamelCase().String()
// 结果: "helloWorld"

PascalCase() *XStr

转换为帕斯卡命名风格。

result := util.Str("hello_world").PascalCase().String()
// 结果: "HelloWorld"

SnakeCase() *XStr

转换为蛇形命名风格。

result := util.Str("HelloWorld").SnakeCase().String()
// 结果: "hello_world"

KebabCase() *XStr

转换为烤串命名风格。

result := util.Str("HelloWorld").KebabCase().String()
// 结果: "hello-world"

空白处理

Trim() *XStr

去除字符串首尾的空白字符。

result := util.Str("  hello  ").Trim().String()
// 结果: "hello"

TrimLeft() *XStr

去除字符串左侧的空白字符。

result := util.Str("  hello  ").TrimLeft().String()
// 结果: "hello  "

TrimRight() *XStr

去除字符串右侧的空白字符。

result := util.Str("  hello  ").TrimRight().String()
// 结果: "  hello"

TrimPrefix(prefix string) *XStr

去除字符串的指定前缀。

result := util.Str("hello_world").TrimPrefix("hello_").String()
// 结果: "world"

参数:

  • prefix string - 要移除的前缀

TrimSuffix(suffix string) *XStr

去除字符串的指定后缀。

result := util.Str("hello_world").TrimSuffix("_world").String()
// 结果: "hello"

参数:

  • suffix string - 要移除的后缀

XArray 数组工具

XArray 提供了功能丰富的数组操作，支持泛型、函数式编程和链式调用。

创建和基础操作

Arrays[T](items ...T) *XArray[T]

创建一个新的 XArray 实例。

arr := util.Arrays(1, 2, 3, 4, 5)
// 或者
arr := util.Arrays("a", "b", "c")

参数:

  • items ...T - 可变参数，数组元素

返回值:

  • *XArray[T] - XArray 实例

ArraysFromSlice[T](slice []T) *XArray[T]

从切片创建 XArray 实例。

slice := []int{1, 2, 3, 4, 5}
arr := util.ArraysFromSlice(slice)

参数:

  • slice []T - 输入切片

返回值:

  • *XArray[T] - XArray 实例

ToSlice() []T

将 XArray 转换为普通切片。

slice := util.Arrays(1, 2, 3).ToSlice()
// 结果: []int{1, 2, 3}

返回值:

  • []T - 切片

元素操作

Append(items ...T) *XArray[T]

向数组末尾添加元素。

result := util.Arrays(1, 2).Append(3, 4, 5).ToSlice()
// 结果: [1, 2, 3, 4, 5]

参数:

  • items ...T - 要添加的元素

Prepend(items ...T) *XArray[T]

向数组开头添加元素。

result := util.Arrays(3, 4).Prepend(1, 2).ToSlice()
// 结果: [1, 2, 3, 4]

参数:

  • items ...T - 要添加的元素

Insert(index int, items ...T) *XArray[T]

在指定位置插入元素。

result := util.Arrays(1, 3).Insert(1, 2).ToSlice()
// 结果: [1, 2, 3]

参数:

  • index int - 插入位置
  • items ...T - 要插入的元素

查询操作

Get(index int) T

获取指定索引的元素。

value := util.Arrays(1, 2, 3).Get(1)
// 结果: 2

参数:

  • index int - 元素索引

返回值:

  • T - 元素值（越界返回零值）

SafeGet(index int) (T, bool)

安全获取指定索引的元素。

value, ok := util.Arrays(1, 2, 3).SafeGet(1)
// value: 2, ok: true

value, ok := util.Arrays(1, 2, 3).SafeGet(10)
// value: 0, ok: false

参数:

  • index int - 元素索引

返回值:

  • T - 元素值
  • bool - 是否获取成功

📝 使用示例

复杂链式操作示例

// 字符串处理示例
result := util.Str("  Hello_WORLD  ").
    Trim().                      // "Hello_WORLD"
    Lower().                     // "hello_world"
    Snake2Camel().              // "helloWorld"
    FirstUpper().               // "HelloWorld"
    String()

// 数组处理示例
numbers := []int{1, 2, 3, 4, 5, 6, 7, 8, 9, 10}
result := util.ArraysFromSlice(numbers).
    Filter(func(n int) bool { return n%2 == 0 }).  // [2, 4, 6, 8, 10]
    Map(func(n int) int { return n * 2 }).         // [4, 8, 12, 16, 20]
    Take(3).                                       // [4, 8, 12]
    ToSlice()

📋 待完成部分

本 API Reference 正在逐步完善中，以下部分将陆续添加：

  • XStr 完整 API（格式验证、正则操作、编码等）
  • XArray 完整 API（函数式操作、排序、分组等）
  • XMap 完整 API
  • XTime 完整 API
  • JSONx 完整 API
  • JWT 完整 API
  • XEnum 完整 API
  • XFile 完整 API
  • XHttp 完整 API

🔍 API 搜索

使用 Ctrl+F 快速搜索特定的 API 方法。常用搜索关键词：

  • 字符串操作: Upper, Lower, Trim, Replace, Split
  • 格式验证: IsEmail, IsURL, IsNumeric, IsJSON
  • 数组操作: Filter, Map, Reduce, Sort, Group
  • 时间操作: Format, Parse, Add, Sub, Between
  • JSON操作: Get, Set, Delete, Parse, Stringify

💬 获取帮助

如果您在使用 API 时遇到问题：

📖 本文档持续更新中，敬请关注最新版本！