mruby-enum-ext 全解析：为 mruby 的 Enumerable 补齐的 30+ 实用扩展方法

编程语言语言运行时编译器解释器嵌入式【免费下载链接】mrubyLightweight Ruby项目地址https://gitcode.com/gh_mirrors/mr/mruby点击查看免费下载mruby-enum-ext是 mruby 官方 mrbgem 体系中专门扩展Enumerable模块的标准库扩展之一它为Array、Range、Hash以及所有include Enumerable的自定义集合类补上了drop、take、group_by、minmax、tally、filter_map等一整套常用方法并顺带为Array实现了原地排序的sort_by!。阅读本文后你将能够在 build_config 中正确启用该 gem掌握其全部新增方法的语义、返回值与边界行为并借助仓库源码理解 mruby 内部辅助方法Integer.__ensure、Array#__svalue等如何支撑这些 Ruby 层实现。一、mrbgem 定位与集成方式mruby-enum-ext的官方定位一句话即可概括extend theEnumerablemodule in mruby with additional useful methods见 mrbgems/mruby-enum-ext/README.md。mruby 核心只提供最小化的Enumerable基础方法本 gem 把 CRuby 中常用的集合操作补全使嵌入式环境也能写出与桌面 Ruby 风格一致的迭代代码。1.1 它是一个标准库扩展core gem该 gem 被收录进官方标准库 gembox——mrbgems/stdlib.gembox 中通过conf.gem :core mruby-enum-ext启用。因此在使用default配置构建 mruby 时mrbgems/default.gembox 引用了stdlibgembox它默认就会被打入二进制。1.2 gem 元信息与测试依赖从 mrbgems/mruby-enum-ext/mrbgem.rake 可以看到spec.summary Enumerable module extension声明本 gem 的职责spec.license MITMIT 许可测试依赖mruby-fiber与mruby-enumerator前者用于验证count在 Fiber 场景下调用 Ruby的行为后者用于验证无块调用时返回的 Enumeratorto_enum。二、在自定义构建中启用若你的构建未使用默认 gembox可在build_config.rb中显式启用MRuby::Build.new do |conf| conf.gembox default # 已包含 mruby-enum-ext # 或者单独启用 # conf.gem :core mruby-enum-ext end由于无块调用形式依赖to_enum见后文枚举器集成建议同时启用mruby-enumerator。启用后mruby、mirb等二进制即可直接使用下述全部方法。三、截取与保留drop / take 家族与 first3.1drop(n)与take(n)drop(n)丢弃前n个元素返回剩余元素数组take(n)返回前n个元素数组。a [1, 2, 3, 4, 5, 0] a.drop(3) # [4, 5, 0] a.take(3) # [1, 2, 3]源码mrblib/enum.rb先调用内部方法Integer.__ensure(n)做严格类型转换再对负数抛ArgumentError, attempt to drop negative size/attempt to take negative size。注意take(0)直接返回空数组不做任何迭代[].first # nil [].first(3) # []first的实现enum.rb以参数个数分派无参形式返回首个元素空集合返回nil单参形式等价于take(n)多于 1 个参数抛ArgumentError。3.2drop_while与take_whiledrop_while一直丢弃直到遇到第一个使块返回nil/false的元素该元素本身保留返回剩余部分take_while一直收集直到块返回nil/false即停止返回已收集部分。a [1, 2, 3, 4, 5, 0] a.drop_while {|i| i 3 } # [3, 4, 5, 0] a.take_while {|i| i 3 } # [1, 2]实现上drop_whileenum.rb用布尔状态state记录是否已越过转折点take_whileenum.rb在块返回假值时直接return ary提前终止迭代。二者无块时均返回枚举器。四、分块迭代each_cons 与 each_sliceeach_cons(n)对每段连续的n个元素调用块滑动窗口each_slice(n)把元素按n个一组切分最后一个分块可能不足n。(1..10).each_cons(3) {|a| p a} # [1, 2, 3] [2, 3, 4] [3, 4, 5] [4, 5, 6] [5, 6, 7] [6, 7, 8] [7, 8, 9] [8, 9, 10] (1..10).each_slice(3) {|a| p a} # [1, 2, 3] [4, 5, 6] [7, 8, 9] [10]实现细节enum.rb二者先用Integer.__ensure(n)转换参数each_cons对n 0抛ArgumentError, invalid sizeeach_slice抛invalid slice sizeeach_cons用临时数组充当滑动窗口ary.shift if ary.size n后再追加满n时用ary.dup传给块避免块内修改污染窗口each_slice满n时直接传递ary并重置迭代结束后若残留不足n的尾巴还会再调用一次块block.call(ary) unless ary.empty?二者块形式返回nil测试 test/enum.rb 中assert_equal nil, b验证了这一点无块时返回枚举器。五、分组与排序group_by / sort_by / minmax 家族5.1group_by以块的返回值为键把元素归组为哈希(1..6).group_by {|i| i%3} # {0[3, 6], 1[1, 4], 2[2, 5]}实现enum.rb对每个元素求键h.key?(key)决定追加还是新建数组因此首次出现的顺序即哈希的键序。5.2sort_by与 Array 的优化版本%w(apple pear fig).sort_by { |word| word.length } # [fig, pear, apple]Enumerable#sort_byenum.rb实现很简洁self.to_a.sort_by(block)——先物化数组再委托给Array#sort_by。本 gem 同时为Array提供了优化的sort_by与sort_by!enum.rb。Array#sort_by采用经典的装饰-排序-还原策略把[键, 原始下标]成对收集并排序再按下标还原原数组避免反复调用块sort_by!通过self.replace(...)原地替换实现就地排序arr [apple, pear, fig] arr.sort_by! { |word| word.length } p arr # [fig, pear, apple]5.3max_by/min_by/minmax/minmax_by%w[albatross dog horse].max_by {|x| x.length } # albatross %w[albatross dog horse].min_by {|x| x.length } # dog a %w(albatross dog horse) a.minmax # [albatross, horse] a.minmax { |a, b| a.length b.length } # [dog, albatross] %w(albatross dog horse).minmax_by { |x| x.length } # [dog, albatross]四个方法的共同语义与实现要点enum.rb首元素直接作为初始极值不会被比较后续元素用比较当比较无结果返回nil时抛ArgumentError例如[1, a].minmax这类异类元素集合minmax的单遍扫描同时维护最小与最大无块形式用val max/val min有块形式两次调用块分别与上下界比较minmax_by每个元素只调用一次块用同一份键值同时更新上下界——测试 test/enum.rb 用计数器验证了调用次数等于元素个数而非两倍空集合上max_by/min_by返回nilminmax/minmax_by返回[nil, nil]。六、统计与聚合count / sum / tally6.1count的三种形态[1, 2, 3, 2].count # 4 无参总数 [1, 2, 3, 2].count(2) # 2 带参等于 item 的个数 [1, 2, 3, 4].count { |x| x%2 0 } # 2 带块块为真的个数实现enum.rb的关键行为参数优先于块——若同时传入参数和块按参数统计与 CRuby 一致测试 test/enum.rb 专门验证了这一点。比较元素时走内部方法Array#__svalue_eq见实现内幕一节遵循 CRubyrb_equal()的语义元素先被认定与自身相等即使其返回false也会被计入。6.2sum(initial0)[1, 2, 3].sum # 6 [1, 2, 3].sum(10) # 16 [1, 2, 3].sum { |x| x * 2 } # 12 ({a:1, b:2, c:3}).sum {|k,v| v} # 6实现enum.rb从init起步逐元素累加带块时累加块的返回值本质上就是reduce(:)的专用形态。6.3tally[a, b, c, b].tally # {a1, b2, c1}实现enum.rb用hash[x] (hash[x]||0)1计数键为元素本身。七、布尔判定四件套any? / all? / none? / one?这四个方法在核心中已有基础版本本 gem 为其增强了模式pattern形态即any?(pattern)用pattern element判定。四种形态统一enum.rb带块块返回真值的判定带模式pattern element判定使正则、类、Range 皆可作为模式无参无块以元素自身的真值性判定。%w(ant bear cat).none? { |word| word.length 5 } # true %w{ant bear cat}.none?(/d/) # true [1, 3.14, 42].none?(Float) # false %w(ant bear cat).one? { |word| word.length 4 } # true [nil, true, false].one? # true [nil, true, 99].one?(Integer) # true %w[ant bear cat].all? { |word| word.length 3 } # true [1, 2i, 3.14].all?(Numeric) # true [nil, true, 99].all? # false %w[ant bear cat].any? { |word| word.length 3 } # true [nil, true, 99].any?(Integer) # true [].any? # false实现要点any?/all?/none?均为短路判定——一旦确定结果立即return不遍历剩余元素one?统计命中数超过 1 立即返回falseenum.rb模式形态属于增强核心all?/any?只有块形态源码注释ISO 15.3.2.2.1、ISO 15.3.2.2.2即为核心版本的标注模式支持由本 gem 补上测试 test/enum.rb 以(enhancement)命名区分注意%w{ant bear cat}.one?(/t/)结果为false因为ant与cat都含t命中两次。原 README 对该例有版本相关的注释测试 test/enum.rb 给出了确定结论。八、变换与扁平化flat_map / filter_map / uniq / grep_v8.1flat_map别名collect_concat[1, 2, 3, 4].flat_map { |e| [e, -e] } # [1, -1, 2, -2, 3, -3, 4, -4] [[1, 2], [3, 4]].flat_map { |e| e [100] } # [1, 2, 100, 3, 4, 100]实现enum.rb对块的返回值做响应each就展平、否则直接收下的处理alias collect_concat flat_map提供别名。8.2filter_map[-2, -1, 0, 1, 2].filter_map { |x| x*2 if x 0 } # [2, 4]selectmap的合体只保留块的真值结果enum.rb。另注意同文件alias filter select为Enumerable补上了filter别名。8.3uniq[1, 2, 2, 3, 1].uniq # [1, 2, 3] [a, B, c, b].uniq { |s| s.downcase } # [a, B, c]实现enum.rb借助哈希去重hash[v] || v保证保留首次出现的元素带块时以block.call(v)为键。8.4grep_v(pattern)a [apple, banana, orange, grape] a.grep_v(/an/) # [apple, orange, grape] a.grep_v(/an/) { |s| s.upcase } # [APPLE, ORANGE, GRAPE]grep的反向版本返回不匹配pattern的元素带块时对结果逐个应用块enum.rb。测试 test/enum.rb 还展示了grep_v(2..4)这类 Range 模式用法。九、迭代与配对each_with_object / reverse_each / cycle / find_index / zip / to_h / each_entry9.1each_with_object(obj)带外部累积对象的迭代最终返回初始传入的对象(1..10).each_with_object([]) { |i, a| a i*2 } # [2, 4, 6, 8, 10, 12, 14, 16, 18, 20]实现enum.rb每次调用block.call(val.__svalue, obj)结束后return obj。9.2reverse_each(1..3).reverse_each { |v| p v } # 3 # 2 # 1实现enum.rb先self.to_a物化临时数组再按下标逆序遍历返回self测试用assert_same r, r.reverse_each {...}验证。9.3cycle(nnil)a [a, b, c] a.cycle(2) { |x| puts x } # 打印 a, b, c, a, b, c # a.cycle { |x| puts x } # 不传参则无限循环需谨慎使用实现enum.rb第一遍遍历时把元素存入内部数组此后对原集合的修改不再影响见源码注释n为nil时以n -1表示无限循环n 0或集合为空直接返回nil。9.4find_index(value)/find_index { |obj| block }(1..100).find_index { |i| i % 5 0 and i % 7 0 } # 34 (1..100).find_index(50) # 49实现enum.rb维护下标计数器比较值形态同样走__svalue_eq元素与自身相等的语义找不到返回nil。9.5zip(arg, ...)a [ 4, 5, 6 ] b [ 7, 8, 9 ] a.zip(b) # [[4, 7], [5, 8], [6, 9]] [1, 2].zip(a, b) # [[1, 4, 7], [2, 5, 8]] c [] a.zip(b) { |x, y| c x y } # nil c # [11, 13, 15]实现enum.rb所有参数先to_a物化不响应to_a抛TypeError结果序列长度等于self的迭代长度参数不足时补nil带块时返回nil否则返回数组的数组。9.6to_h%i[hello world].each_with_index.to_h # {:hello 0, :world 1}把可枚举对象解释为[key, value]对序列enum.rb。带块时先经块变换再取对元素不是 Array 抛TypeError长度不为 2 抛ArgumentError。测试 test/enum.rb 还覆盖了yield 1, 2多值产出场景。注意each_with_index来自 mruby-enumerator二者配合使用效果最佳。9.7each_entry把每次yield的多值参数统一折叠为单值再传给块class Foo include Enumerable def each yield 1 yield 1, 2 yield end end Foo.new.each_entry{ |o| p o } # 1 # [1, 2] # nil实现enum.rb对yield收集到的*a调用a.__svalue完成折叠并返回self。十、枚举器集成无块调用的统一约定上述绝大多数方法在无块调用时返回枚举器enumerator例如e [1, 2, 3].drop_while # #Enumerator: ...这一约定由 mruby-enumerator gem 提供to_enum/enum_for能力支撑这也是本 gem 的测试依赖之一。典型用法是链式惰性组合[1, 2, 3, 4, 5].each_with_index.to_h # {10, 21, 32, 43, 54}十一、实现内幕支撑全部方法的三个内部辅助阅读 mrblib/enum.rb 源码会发现所有方法都依赖三个下划线内部方法这正是 mruby 为 Ruby 层标准库提供的底层钩子Integer.__ensure(val)严格整数转换替代旧式val.__to_int。源码注释src/numeric.c说明它是对参数做检查而非向参数发消息——__to_int曾是普通公开方法对象可自行定义而绕过类型检查对应 issue #7014。take/drop/each_cons/each_slice/cycle/first的尺寸参数都经它把关测试 test/enum.rb 专门验证了拒绝重定义转换器的尺寸参数。Array#__svalue多值折叠器src/array.c0 个元素→nil1 个元素→该元素本身多个→原数组。Ruby 的each以yield 1, 2形式产出多值时*val收集为数组需经它还原为语义正确的单值。drop、take、group_by、count、zip、to_h、each_entry等全部依赖它。Array#__svalue_eq内部相等比较src/array.c返回true/false/:send三态。它遵循 C 层mrb_equal_in_c()的语义先认定元素与自身相等即使其拒绝自身若元素的用 Ruby 实现则返回:send由 Ruby 层在当前 VM 内发起调用——这样Fiber.yield无需穿越 C 栈帧测试 test/enum.rb 验证了这一行为。count、find_index的值比较形态均走此通道。从源码结构看这套设计的目标是让 Ruby 层标准库在保持语义与 CRuby 对齐的同时避免 C/Ruby 频繁跨界保证嵌入场景下的行为可预测。十二、测试覆盖与行为边界450 行的测试文件 mrbgems/mruby-enum-ext/test/enum.rb 是理解每个方法语义的权威参考除常规断言外还覆盖了大量边界行为负尺寸take/drop/first(n)对负数抛ArgumentError零尺寸take(0)/first(0)返回空数组cycle(0)直接返回nil无效尺寸each_cons(0)/each_slice(0)抛ArgumentError比较无结果minmax/max_by/min_by/minmax_by对返回nil的情形如[1, a]、含Float::NAN抛ArgumentError相等语义count/find_index的元素自相等优先、拒绝自身仍被计入返回类型each_cons/each_slice/zip块形式返回nilreverse_each/each_entry返回self。十三、使用注意事项小结所有带n尺寸参数的方法都要求严格整数传入无法转换的对象会抛TypeError负数/非正数按各方法规则抛ArgumentError无块调用返回枚举器需要mruby-enumeratorgem 配合sort_by在Array上另有原地版本sort_by!注意区分Enumerable#sort_by返回新数组与Array#sort_by!原地修改模式判定any?(pat)等依赖因此正则、类、Range 均可作为模式参数空集合的极值语义max_by/min_by→nilminmax/minmax_by→[nil, nil]none?/all?→trueany?/one?→false。至此mruby-enum-ext的每个扩展方法、其底层实现机制与边界行为都已覆盖。如需深入可直接阅读 mrblib/enum.rb 的完整注释每个方法均带call-seq文档与 test/enum.rb 的逐步断言。赞分享编程语言语言运行时编译器解释器嵌入式【免费下载链接】mrubyLightweight Ruby项目地址https://gitcode.com/gh_mirrors/mr/mruby点击查看免费下载相关推荐mruby-array-ext 深入指南为 mruby 的 Array 补齐标准库级数组能力mruby array ext 深入指南为 mruby 的 Array 补齐标准库级数组能力 mruby array ext 是 mruby 官方维护的核心扩编程语言语言运行时编译器解释器嵌入式mruby 的 Module/Class 反射扩展mruby-class-ext 完整指南mruby 的 Module/Class 反射扩展mruby class ext 完整指南 导读 mruby class ext 是 mruby 官方仓库中提编程语言语言运行时编译器解释器嵌入式mruby-dir 深度解析为 mruby 补齐 Dir 目录操作类的 mrbgem 完整指南mruby dir 深度解析为 mruby 补齐 Dir 目录操作类的 mrbgem 完整指南 mruby dir 是托管在 h2o 仓库 deps/mrub后端网络上一篇使用 Python 客户端调用 WhisperKit 本地服务器OpenAI SDK 兼容的转写与翻译实战指南下一篇RePKGWallpaper Engine壁纸资源提取与转换完全指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考