Go uniseg 分段函数的 state 为什么需要传回下一次调用

如果你用 github.com/rivo/uniseg 的 StepString 连续拆分文本，state 不是字符下标，也不是可有可无的临时变量。第一次调用传入 -1，之后把上一次返回的 newState 原样传回，才能让分段规则跨调用保持连续。

它的核心循环只有三件事：把当前剩余字符串交给函数，把返回的 rest 作为下一轮输入，再把返回的 newState 作为下一轮状态。只更新字符串而丢掉状态，遇到组合字符、区域指示符或跨边界的 Unicode 规则时，就可能得到不一致的结果。

state 解决的是“这一轮之前发生了什么”

Go 的字符串是 UTF-8 字节序列，rune 是 Unicode code point，而用户看到的一个字符还可能由多个 code point 组成。例如带组合标记的字母、国旗和带修饰符的表情，都不适合简单按字节或单个 rune 切开。

uniseg 按 Unicode 文本分段规则处理这些关系。一个分段函数在寻找下一个边界时，需要知道当前输入前面已经匹配到的属性和规则状态。这个上下文不会体现在 rest 的字符串内容里，所以库用整数 state 把它带到下一次调用。

第一次传 -1，后续传回 newState

官方文档对连续调用的约定很明确：不知道当前状态时传 -1；连续调用时，把上一次返回的状态和剩余片段一起传回。下面的写法适用于只需要逐个取得用户感知字符、同时希望少分配一个迭代器对象的场景。

package main

import (
    "fmt"

    "github.com/rivo/uniseg"
)

func main() {
    rest := "Ä🇩🇪🏳️‍🌈"
    state := -1 // 第一次调用不知道前置分段状态，使用 -1 初始化

    for len(rest) > 0 {
        var boundaries int
        var cluster string

        // 同时接收当前片段、剩余字符串、边界信息和下一轮状态
        cluster, rest, boundaries, state = uniseg.StepString(rest, state)
        fmt.Printf("%q width=%d\\n", cluster, boundaries>>uniseg.ShiftWidth)
    }
}

这里的重点不是变量名，而是四个返回值的配对关系：cluster 是本次识别出的 grapheme cluster，rest 已经移到下一个未处理位置，boundaries 描述当前片段后的边界，state 则携带下一轮需要的上下文。

为什么不能每一轮都重新传 -1

把循环写成 StepString(rest, -1) 看起来仍然能不断返回字符串片段，但它等价于每次都告诉分段器“这是一个新输入的开头”。这样会丢掉跨调用的规则上下文，特别是在输入被切成多个片段、或者边界判断依赖前面字符属性时，结果就不再是同一段文本的连续解析。

还要注意，state 不应该被当成字节偏移量保存或加减。偏移推进由返回的 rest 负责；状态推进由返回的 newState 负责。两者分别描述“还剩哪些输入”和“解析器记住了什么”，缺一不可。

可以把两条返回链记成一组不变量：

StepString 返回的 boundaries 也有状态含义之外的信息

StepString 不只做 grapheme cluster 分段，它还把词边界、句子边界、换行建议和等宽显示宽度打包到 boundaries 中。这个整数不是另一个游标，而是可以用常量和位运算读取的组合信息。

func boundarySummary(boundaries int) (word, sentence bool, line, width int) {
    // 用官方常量读取不同类型的边界信息
    word = boundaries&uniseg.MaskWord != 0
    sentence = boundaries&uniseg.MaskSentence != 0
    line = boundaries & uniseg.MaskLine
    // 宽度位从 ShiftWidth 开始，表示大多数等宽字体的单元格数
    width = boundaries >> uniseg.ShiftWidth
    return
}

如果业务只关心 grapheme cluster，可以选择更专门的 FirstGraphemeClusterInString；如果还需要词、句和换行信息，StepString 才有价值。专门函数的返回值更简单，但仍然遵循同样的 -1 → newState 续接约定。

什么时候改用 Graphemes 迭代器

StepString 适合热路径、低分配或需要同时读取边界信息的代码，但它把多个返回值和状态管理暴露给调用方。若代码主要目的是可读地遍历用户感知字符，可以使用 uniseg.NewGraphemes。

gr := uniseg.NewGraphemes("👍🏼!")
for gr.Next() {
    // 迭代器内部维护 state，调用方只读取当前 cluster
    fmt.Println(gr.Str(), gr.Width())
}

官方文档说明，Graphemes 本质上包装了 StepString，提供更方便的访问方式。如果你需要访问原字符串中的字节位置、词边界、句边界或换行状态，迭代器也有对应方法；如果只需要一个结果并且不想保留迭代器，专门的 First... 函数通常更直接。

排查 state 使用错误的四个检查点

1. 首轮是否是 -1：只有确定自己拥有同一分段上下文时，才把已有状态传入；新的一段独立文本从 -1 开始。
2. 循环条件是否使用 rest：每轮都应消费返回的剩余字符串，不能用原始字符串作为下一轮输入。
3. 赋值是否同时覆盖 state：多返回值接收时，要把第四个返回值写回状态变量。
4. 是否混淆了宽度和分段数量：ShiftWidth 得到的是等宽显示单元格数，不是字节数、rune 数或 grapheme cluster 数。

如果只是想统计用户感知字符数量，直接使用 GraphemeClusterCount 会比手写状态循环更清晰；如果要逐个处理字符串，就保留 rest 和 state 的双链路。

结语

state 之所以要传回下一次调用，是因为 Unicode 分段不是只看当前字节的无状态函数。rest 让输入位置向前推进，newState 让规则上下文保持连续；首次用 -1 初始化，之后原样传回，是 StepString 循环的最小正确模式。

相关问题

StepString 和 Graphemes 该选哪个？

需要少分配并同时处理边界位时选 StepString；更看重遍历代码可读性时选 Graphemes。

state 可以跨两段完全无关的文本复用吗？

不建议。每段独立文本都应从 -1 开始，只有同一段输入被 rest 连续切分时才传回 newState。

为什么不直接按 rune 遍历？

rune 只表示 code point，不一定等于用户感知字符。组合标记、旗帜和表情序列可能需要多个 code point 作为一个 grapheme cluster。