Ruby StringScanner 源码解析掌握pos字节定位与pointer别名的完整语义【免费下载链接】rubyThe Ruby Programming Language项目地址: https://gitcode.com/GitHub_Trending/ru/rubyStringScannerstrscan是 Ruby 标准库中基于流式游标cursor处理字符串的扫描器而pos是其中唯一一个允许直接改写扫描位置的方法它同时设定字节位置并联动调整字符位置为回溯、跳跃式解析提供了基础能力。本文以doc/strscan/methods/set_pos.md文档为主体结合ext/strscan/strscan.c的 C 实现与test/strscan/test_stringscanner.rb测试系统讲解pos的参数语义、负值换算规则、越界行为、别名方法以及底层实现原理帮助你精确控制扫描器的位置状态。方法签名与核心作用pos的完整定义如下源码文档入口C 层实现在 ext/strscan/strscan.c#L584-L606pos n - n pointer n - n # 别名该方法做两件事设定字节位置byte position为n同步调整字符位置character position即charpos的返回值。同时它返回赋值参数n注意非负时原样返回负值时返回的是换算后的正值详见下文并且不会影响匹配值match values——即matched、pre_match、post_match、captures等最近一次匹配结果保持不变参考文档原文 Does not affect [match values][9]。StringScanner对象的全部位置操作可归纳为下表源自 doc/strscan/strscan.md方法作用#reset两个位置归零回到存储字符串开头#terminate两个位置移动到存储字符串末尾#pos(new_byte_position)设定字节位置并联动调整字符位置基本用法非负n直接定位当n非负时位置被直接设定为n零基字节下标。原文档示例scanner StringScanner.new(HIRAGANA_TEXT) scanner.string # こんにちは scanner.pos 3 # 3 scanner.rest # んにちは scanner.charpos # 1这里HIRAGANA_TEXT こんにちは是 doc/strscan/strscan.md 预定义的常量。五个平假名各占 3 字节UTF-8共 15 字节。当pos 3时字节位置指向第 4 个字节即第一个「こ」之后的んにちは目标子串rest变为んにちは字符位置charpos为 1已越过 1 个字符。这与pos的读取语义完全对称——pos返回的始终是字节位置见 get_pos.md 与 C 实现 strscan_get_pos直接返回内部游标p-curr。负值语义从存储字符串末尾倒数当n为负数时位置从存储字符串的末尾倒数计算。原文档示例scanner.pos -9 # -9 scanner.pos # 6 scanner.rest # にちは scanner.charpos # 2结合底层实现看这一行为由 strscan_set_pos 中的一行换算完成i NUM2LONG(v); if (i 0) i S_LEN(p); // 负值加上字符串字节总长即实际位置 字符串字节长度 n。对于 15 字节的こんにちは15 (-9) 6所以pos变为 6越过两个三字节字符rest为にちはcharpos为 2。由此可以推断几个重要边界pos 0等价于reset位置回到开头rest为整个存储字符串pos -字符串长度也回到开头换算后为 0pos 字符串长度或-0之外与末尾对齐的负值等价于terminaterest变为空字符串到达流末尾eos?为真测试 test_stringscanner.rb#L776-L780 验证了正数定位s.pos 7后s.rest为ring。越界行为抛出RangeErrorpos对越界值有严格的校验超出范围会抛出RangeErrorindex out of range。这在 C 实现中清晰可见i NUM2LONG(v); if (i 0) i S_LEN(p); if (i 0) rb_raise(rb_eRangeError, index out of range); if (i S_LEN(p)) rb_raise(rb_eRangeError, index out of range); p-curr i; return LONG2NUM(i);关键点校验发生在负值换算之后因此pos -(长度1)会触发 RangeErrorpos 长度1也会触发 RangeError任何通过校验的位置都会被写入内部游标p-curr并返回换算后的最终值所以负值赋值时返回值是转换后的非负位置而非原参数。别名与配套读取方法pos在 C 层注册了别名pointer两者指向同一个 C 函数 strscan_set_posrb_define_method(StringScanner, pos, strscan_set_pos, 1); rb_define_method(StringScanner, pointer, strscan_set_pos, 1);读取侧也有对应别名pos与pointer均调用 strscan_get_pos返回p-curr字节位置。因此pointer/pointer是历史遗留的、语义等同的名称二者可互换使用。与位置相关的配套读取方法还包括方法含义实现要点#pos/#pointer字节位置直接返回p-currstrscan.c#L555-L562#charpos字符位置用rb_enc_strlen从存储字符串开头计算到当前游标的字符数strscan.c#L572-L582#rest目标子串从字节位置到字符串末尾的尾随子串#rest_size目标子串字节数rest.sizecharpos的实现值得注意它不是独立存储的变量而是按需从字符串开头重新计算得到的因此pos设定字节位置后charpos会立即反映新位置对应的字符数详见 get_charpos.md 中的多字节示例两次getch后pos为 6 而charpos为 2。多字节字符串中的定位实践由于pos操作的是字节索引而非字符索引在多字节编码如 UTF-8下使用时需要特别注意避免将位置指向某个字符的中间字节这不会报错但后续getch等按字符消费的方法会解析出乱码或异常字符。推荐的做法是组合使用require strscan scanner StringScanner.new(こんにちは) # 直接以字节数跳跃 scanner.pos 6 # 跳过 2 个字符6 字节 scanner.charpos # 2 scanner.rest # にちは # 或借助字符位置反推先 getch 消费再记录 pos scanner.reset scanner.getch # こ scanner.pos # 3doc/strscan/strscan.md中 Character Position 一节的完整示例展示了同样的原理对Helloこんにちは5 个单字节字符 5 个三字节字符共 20 字节scan(/Hello/)后pos为 5、charpos为 5再getch后pos为 8、charpos为 6——字节位置与字符位置的差值正是多字节字符带来的。位置改写对目标子串与后续匹配的影响pos会立即改变目标子串target substring从而影响后续所有搜索/遍历方法的匹配起点。根据 doc/strscan/strscan.md搜索类方法check、check_until、exist?、match?、peek等在目标子串上查找不推进位置遍历类方法scan、getch、scan_until、skip_until等匹配成功后推进位置并缩短目标子串。因此pos常用于两类场景跳过已知长度的字节段把游标直接拨到感兴趣的区域再开始scan配合unscan/ 手动回退实现回溯先记录pos匹配失败或需要重新解析时再pos恢复。scanner StringScanner.new(foo|bar|baz) scanner.pos 4 # 跳过 foo| scanner.scan(/\w/) # bar测试 test_stringscanner.rb#L776-L780 即为这类用法的直接验证设定位置后rest立即从新位置截取。注意事项与最佳实践总结返回值语义非负n返回n负n返回换算后的实际字节位置越界即抛错pos对负值与过大值均抛出RangeErrorindex out of range且负值校验在换算之后不影响匹配值pos不会清除matched等最近匹配结果这一点与reset、terminate不同——后两者会清除匹配值字节 vs 字符pos只认字节索引多字节文本中请结合charpos确认字符语义别名pointer与pos完全等价可放心混用配套操作回到开头用reset或pos 0跳到末尾用terminate或pos 字符串长度。掌握pos的这套字节定位语义与底层换算逻辑你就能在字符串流式解析中精确控制扫描游标写出可靠且可预测的 Ruby 词法分析代码。【免费下载链接】rubyThe Ruby Programming Language项目地址: https://gitcode.com/GitHub_Trending/ru/ruby创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Ruby StringScanner 源码解析：掌握 `pos=` 字节定位与 `pointer=` 别名的完整语义
Ruby StringScanner 源码解析掌握pos字节定位与pointer别名的完整语义【免费下载链接】rubyThe Ruby Programming Language项目地址: https://gitcode.com/GitHub_Trending/ru/rubyStringScannerstrscan是 Ruby 标准库中基于流式游标cursor处理字符串的扫描器而pos是其中唯一一个允许直接改写扫描位置的方法它同时设定字节位置并联动调整字符位置为回溯、跳跃式解析提供了基础能力。本文以doc/strscan/methods/set_pos.md文档为主体结合ext/strscan/strscan.c的 C 实现与test/strscan/test_stringscanner.rb测试系统讲解pos的参数语义、负值换算规则、越界行为、别名方法以及底层实现原理帮助你精确控制扫描器的位置状态。方法签名与核心作用pos的完整定义如下源码文档入口C 层实现在 ext/strscan/strscan.c#L584-L606pos n - n pointer n - n # 别名该方法做两件事设定字节位置byte position为n同步调整字符位置character position即charpos的返回值。同时它返回赋值参数n注意非负时原样返回负值时返回的是换算后的正值详见下文并且不会影响匹配值match values——即matched、pre_match、post_match、captures等最近一次匹配结果保持不变参考文档原文 Does not affect [match values][9]。StringScanner对象的全部位置操作可归纳为下表源自 doc/strscan/strscan.md方法作用#reset两个位置归零回到存储字符串开头#terminate两个位置移动到存储字符串末尾#pos(new_byte_position)设定字节位置并联动调整字符位置基本用法非负n直接定位当n非负时位置被直接设定为n零基字节下标。原文档示例scanner StringScanner.new(HIRAGANA_TEXT) scanner.string # こんにちは scanner.pos 3 # 3 scanner.rest # んにちは scanner.charpos # 1这里HIRAGANA_TEXT こんにちは是 doc/strscan/strscan.md 预定义的常量。五个平假名各占 3 字节UTF-8共 15 字节。当pos 3时字节位置指向第 4 个字节即第一个「こ」之后的んにちは目标子串rest变为んにちは字符位置charpos为 1已越过 1 个字符。这与pos的读取语义完全对称——pos返回的始终是字节位置见 get_pos.md 与 C 实现 strscan_get_pos直接返回内部游标p-curr。负值语义从存储字符串末尾倒数当n为负数时位置从存储字符串的末尾倒数计算。原文档示例scanner.pos -9 # -9 scanner.pos # 6 scanner.rest # にちは scanner.charpos # 2结合底层实现看这一行为由 strscan_set_pos 中的一行换算完成i NUM2LONG(v); if (i 0) i S_LEN(p); // 负值加上字符串字节总长即实际位置 字符串字节长度 n。对于 15 字节的こんにちは15 (-9) 6所以pos变为 6越过两个三字节字符rest为にちはcharpos为 2。由此可以推断几个重要边界pos 0等价于reset位置回到开头rest为整个存储字符串pos -字符串长度也回到开头换算后为 0pos 字符串长度或-0之外与末尾对齐的负值等价于terminaterest变为空字符串到达流末尾eos?为真测试 test_stringscanner.rb#L776-L780 验证了正数定位s.pos 7后s.rest为ring。越界行为抛出RangeErrorpos对越界值有严格的校验超出范围会抛出RangeErrorindex out of range。这在 C 实现中清晰可见i NUM2LONG(v); if (i 0) i S_LEN(p); if (i 0) rb_raise(rb_eRangeError, index out of range); if (i S_LEN(p)) rb_raise(rb_eRangeError, index out of range); p-curr i; return LONG2NUM(i);关键点校验发生在负值换算之后因此pos -(长度1)会触发 RangeErrorpos 长度1也会触发 RangeError任何通过校验的位置都会被写入内部游标p-curr并返回换算后的最终值所以负值赋值时返回值是转换后的非负位置而非原参数。别名与配套读取方法pos在 C 层注册了别名pointer两者指向同一个 C 函数 strscan_set_posrb_define_method(StringScanner, pos, strscan_set_pos, 1); rb_define_method(StringScanner, pointer, strscan_set_pos, 1);读取侧也有对应别名pos与pointer均调用 strscan_get_pos返回p-curr字节位置。因此pointer/pointer是历史遗留的、语义等同的名称二者可互换使用。与位置相关的配套读取方法还包括方法含义实现要点#pos/#pointer字节位置直接返回p-currstrscan.c#L555-L562#charpos字符位置用rb_enc_strlen从存储字符串开头计算到当前游标的字符数strscan.c#L572-L582#rest目标子串从字节位置到字符串末尾的尾随子串#rest_size目标子串字节数rest.sizecharpos的实现值得注意它不是独立存储的变量而是按需从字符串开头重新计算得到的因此pos设定字节位置后charpos会立即反映新位置对应的字符数详见 get_charpos.md 中的多字节示例两次getch后pos为 6 而charpos为 2。多字节字符串中的定位实践由于pos操作的是字节索引而非字符索引在多字节编码如 UTF-8下使用时需要特别注意避免将位置指向某个字符的中间字节这不会报错但后续getch等按字符消费的方法会解析出乱码或异常字符。推荐的做法是组合使用require strscan scanner StringScanner.new(こんにちは) # 直接以字节数跳跃 scanner.pos 6 # 跳过 2 个字符6 字节 scanner.charpos # 2 scanner.rest # にちは # 或借助字符位置反推先 getch 消费再记录 pos scanner.reset scanner.getch # こ scanner.pos # 3doc/strscan/strscan.md中 Character Position 一节的完整示例展示了同样的原理对Helloこんにちは5 个单字节字符 5 个三字节字符共 20 字节scan(/Hello/)后pos为 5、charpos为 5再getch后pos为 8、charpos为 6——字节位置与字符位置的差值正是多字节字符带来的。位置改写对目标子串与后续匹配的影响pos会立即改变目标子串target substring从而影响后续所有搜索/遍历方法的匹配起点。根据 doc/strscan/strscan.md搜索类方法check、check_until、exist?、match?、peek等在目标子串上查找不推进位置遍历类方法scan、getch、scan_until、skip_until等匹配成功后推进位置并缩短目标子串。因此pos常用于两类场景跳过已知长度的字节段把游标直接拨到感兴趣的区域再开始scan配合unscan/ 手动回退实现回溯先记录pos匹配失败或需要重新解析时再pos恢复。scanner StringScanner.new(foo|bar|baz) scanner.pos 4 # 跳过 foo| scanner.scan(/\w/) # bar测试 test_stringscanner.rb#L776-L780 即为这类用法的直接验证设定位置后rest立即从新位置截取。注意事项与最佳实践总结返回值语义非负n返回n负n返回换算后的实际字节位置越界即抛错pos对负值与过大值均抛出RangeErrorindex out of range且负值校验在换算之后不影响匹配值pos不会清除matched等最近匹配结果这一点与reset、terminate不同——后两者会清除匹配值字节 vs 字符pos只认字节索引多字节文本中请结合charpos确认字符语义别名pointer与pos完全等价可放心混用配套操作回到开头用reset或pos 0跳到末尾用terminate或pos 字符串长度。掌握pos的这套字节定位语义与底层换算逻辑你就能在字符串流式解析中精确控制扫描游标写出可靠且可预测的 Ruby 词法分析代码。【免费下载链接】rubyThe Ruby Programming Language项目地址: https://gitcode.com/GitHub_Trending/ru/ruby创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考