[Feature #21943] Add StringScanner#integer_at (#205)

See also: https://bugs.ruby-lang.org/issues/21943

This is semantically equivalent to `scanner[specifier]&.to_i(base)` but
this is faster than `scanner[specifier]&.to_i(base)` because
`integer_at` doesn't create a temporary String when possible.

This PR also includes a benchmark for them:

```console
$ ruby -v -S benchmark-driver benchmark/integer_at.yaml
ruby 4.1.0dev (2026-05-01T19:25:51Z master f2845eab29) +PRISM [x86_64-linux]
Warming up --------------------------------------
             [].to_i    24.272M i/s -     25.109M times in 1.034481s (41.20ns/i, 32clocks/i)
          integer_at    61.188M i/s -     62.491M times in 1.021289s (16.34ns/i, 62clocks/i)
Calculating -------------------------------------
             [].to_i    26.831M i/s -     72.816M times in 2.713883s (37.27ns/i, 169clocks/i)
          integer_at    81.331M i/s -    183.564M times in 2.256998s (12.30ns/i, 43clocks/i)

Comparison:
          integer_at:  81331225.5 i/s 
             [].to_i:  26831046.3 i/s - 3.03x  slower
```

In this environment, `integer_at` is 3.03x faster than `[].to_i`.

Co-authored-by: jinroq <jinroq@gmail.com>

Author: kou

Rakefile

@@ -58,13 +58,24 @@ task :test do
   ruby("run-test.rb", *ENV["TESTOPTS"]&.shellsplit)
 end
 
-desc "Run benchmark"
-task :benchmark do
-  ruby("-S",
-       "benchmark-driver",
-       "benchmark/scan.yaml")
+benchmark_tasks = []
+namespace :benchmark do
+  Dir.glob("benchmark/*.yaml").sort.each do |yaml|
+    name = File.basename(yaml, ".*")
+    desc "Run #{name} benchmark"
+    task name do
+      puts("```console")
+      print("$ ")
+      sh(RbConfig.ruby, "-v", "-S", "benchmark-driver", yaml)
+      puts("```")
+    end
+    benchmark_tasks << "benchmark:#{name}"
+  end
 end
 
+desc "Run all benchmarks"
+task :benchmark => benchmark_tasks
+
 RDoc::Task.new
 
 release_task = Rake.application["release"]

benchmark/integer_at.yaml

@@ -0,0 +1,10 @@
+prelude: |
+  $LOAD_PATH.unshift(File.expand_path("lib"))
+  require "strscan"
+  scanner = StringScanner.new("2026")
+  scanner.scan(/(2026)/)
+benchmark:
+  "[].to_i": |
+    scanner[1].to_i
+  integer_at: |
+    scanner.integer_at(1)

ext/strscan/extconf.rb

@@ -5,6 +5,7 @@
   have_func("onig_region_memsize(NULL)")
   have_func("rb_reg_onig_match", "ruby/re.h")
   have_func("rb_deprecate_constant")
+  have_func("rb_int_parse_cstr", "ruby.h") # RUBY_VERSION >= 2.5
   have_func("rb_gc_location", "ruby.h") # RUBY_VERSION >= 2.7
   have_const("RUBY_TYPED_EMBEDDABLE", "ruby.h") # RUBY_VERSION >= 3.3
   create_makefile 'strscan'

ext/strscan/strscan.c

@@ -1689,6 +1689,38 @@ name_to_backref_number(struct re_registers *regs, VALUE regexp, const char* name
                  rb_long2int(name_end - name), name);
 }
 
+/*
+ * Resolve capture group index from Integer, Symbol, or String.
+ * Returns the resolved register index, or -1 if unmatched/out of range.
+ * For Symbol/String specifiers, raises IndexError if the named group
+ * does not exist.
+ */
+static long
+resolve_capture_index(struct strscanner *p, VALUE specifier)
+{
+    const char *name;
+    long i;
+    if (! MATCHED_P(p)) return -1;
+    switch (TYPE(specifier)) {
+        case T_SYMBOL:
+            specifier = rb_sym2str(specifier);
+            /* fall through */
+        case T_STRING:
+            RSTRING_GETMEM(specifier, name, i);
+            i = name_to_backref_number(&(p->regs), p->regex, name, name + i,
+                                       rb_enc_get(specifier));
+            break;
+        default:
+            i = NUM2LONG(specifier);
+    }
+    if (i < 0)
+        i += p->regs.num_regs;
+    if (i < 0)                 return -1;
+    if (i >= p->regs.num_regs) return -1;
+    if (p->regs.beg[i] == -1)  return -1;
+    return i;
+}
+
 /*
  *
  * :markup: markdown
@@ -1763,36 +1795,93 @@ name_to_backref_number(struct re_registers *regs, VALUE regexp, const char* name
 static VALUE
 strscan_aref(VALUE self, VALUE idx)
 {
-    const char *name;
     struct strscanner *p;
     long i;
 
     GET_SCANNER(self, p);
-    if (! MATCHED_P(p))        return Qnil;
-
-    switch (TYPE(idx)) {
-        case T_SYMBOL:
-            idx = rb_sym2str(idx);
-            /* fall through */
-        case T_STRING:
-            RSTRING_GETMEM(idx, name, i);
-            i = name_to_backref_number(&(p->regs), p->regex, name, name + i, rb_enc_get(idx));
-            break;
-        default:
-            i = NUM2LONG(idx);
-    }
-
-    if (i < 0)
-        i += p->regs.num_regs;
-    if (i < 0)                 return Qnil;
-    if (i >= p->regs.num_regs) return Qnil;
-    if (p->regs.beg[i] == -1)  return Qnil;
+    i = resolve_capture_index(p, idx);
+    if (i < 0) return Qnil;
 
     return extract_range(p,
                          adjust_register_position(p, p->regs.beg[i]),
                          adjust_register_position(p, p->regs.end[i]));
 }
 
+/*
+ * :markup: markdown
+ *
+ * call-seq:
+ *   integer_at(specifier, base=10) -> integer or nil
+ *
+ * Returns the captured substring at the given `specifier` as an Integer,
+ * following the behavior of `String#to_i(base)`.
+ *
+ * `specifier` can be an Integer (positive, negative, or zero), a Symbol,
+ * or a String for named capture groups.
+ *
+ * Returns `nil` if:
+ * - No match has been performed or the last match failed
+ * - The `specifier` is an Integer and is out of range
+ * - The group at `specifier` did not participate in the match
+ *
+ * Raises IndexError if `specifier` is a Symbol or String that does not
+ * correspond to a named capture group, consistent with
+ * `StringScanner#[]`.
+ *
+ * This is semantically equivalent to `self[specifier]&.to_i(base)`
+ * but avoids the allocation of a temporary String when possible.
+ *
+ * ```rb
+ * scanner = StringScanner.new("2024-06-15")
+ * scanner.scan(/(\d{4})-(\d{2})-(\d{2})/)
+ * scanner.integer_at(1)       # => 2024
+ * scanner.integer_at(1, 16)   # => 8228
+ * ```
+ */
+static VALUE
+strscan_integer_at(int argc, VALUE *argv, VALUE self)
+{
+    struct strscanner *p;
+    long i;
+    long beg, end, len;
+    const char *ptr;
+    VALUE rb_specifier;
+    VALUE rb_base;
+    int base = 10;
+
+    GET_SCANNER(self, p);
+    rb_scan_args(argc, argv, "11", &rb_specifier, &rb_base);
+    if (argc > 1)
+        base = NUM2INT(rb_base);
+    i = resolve_capture_index(p, rb_specifier);
+    if (i < 0)
+        return Qnil;
+
+    beg = adjust_register_position(p, p->regs.beg[i]);
+    end = adjust_register_position(p, p->regs.end[i]);
+    len = end - beg;
+    ptr = S_PBEG(p) + beg;
+#ifdef HAVE_RB_INT_PARSE_CSTR
+    {
+      /*
+       * Ruby 2.5 or later export the rb_int_parse_cstr() symbol but
+       * prototype definition isn't provided. Ruby 4.1 or later
+       * provide prototype definition.
+       */
+#  ifndef RB_INT_PARSE_DEFAULT
+        VALUE rb_int_parse_cstr(const char *str, ssize_t len, char **endp,
+                                size_t *ndigits, int base, int flags);
+#    define RB_INT_PARSE_DEFAULT 0x07
+#  endif
+        char *endp;
+        return rb_int_parse_cstr(ptr, len, &endp, NULL, base,
+                                 RB_INT_PARSE_DEFAULT);
+    }
+#else
+    return rb_str_to_inum(rb_str_new(ptr, len), base, 0);
+#endif
+}
+
 /*
  * :markup: markdown
  * :include: strscan/link_refs.txt
@@ -2353,6 +2442,7 @@ Init_strscan(void)
     rb_define_method(StringScanner, "matched",     strscan_matched,     0);
     rb_define_method(StringScanner, "matched_size", strscan_matched_size, 0);
     rb_define_method(StringScanner, "[]",          strscan_aref,        1);
+    rb_define_method(StringScanner, "integer_at",  strscan_integer_at, -1);
     rb_define_method(StringScanner, "pre_match",   strscan_pre_match,   0);
     rb_define_method(StringScanner, "post_match",  strscan_post_match,  0);
     rb_define_method(StringScanner, "size",        strscan_size,        0);

lib/strscan/strscan.rb

@@ -1,6 +1,12 @@
 # frozen_string_literal: true
 
 class StringScanner
+  unless method_defined?(:integer_at) # For JRuby
+    def integer_at(specifier, *to_i_args)
+      self[specifier]&.to_i(*to_i_args)
+    end
+  end
+
   # :markup: markdown
   #
   # call-seq:

lib/strscan/truffleruby.rb

@@ -133,6 +133,8 @@ def [](group)
     end
   end
 
+  def integer_at(group, *to_i_args) = self[group]&.to_i(*to_i_args)
+
   def values_at(*groups) = @last_match&.values_at(*groups)
 
   def captures = @last_match&.captures

test/strscan/test_stringscanner.rb

@@ -525,6 +525,59 @@ def test_AREF
     end
   end
 
+  def assert_integer_at(s, specifier, *to_i_args)
+    assert_equal(s[specifier]&.to_i(*to_i_args),
+                 s.integer_at(specifier, *to_i_args))
+  end
+
+  def test_integer_at
+    s = create_string_scanner("before 20260514 after")
+    s.skip_until(" ")
+    assert_equal("20260514", s.scan(/(\d{4})(\d{2})(\d{2})/))
+    assert_integer_at(s, 0)  # 20260514
+    assert_integer_at(s, 1)  # 2026
+    assert_integer_at(s, 2)  # 5
+    assert_integer_at(s, 3)  # 14
+    assert_integer_at(s, 4)  # nil
+    assert_integer_at(s, -1) # 14
+    assert_integer_at(s, -2) # 5
+    assert_integer_at(s, -3) # 2026
+    assert_integer_at(s, -4) # 20260514
+    assert_integer_at(s, -5) # nil
+  end
+
+  def test_integer_at_name_string
+    s = create_string_scanner("before 20260514 after")
+    s.skip_until(" ")
+    assert_equal("20260514", s.scan(/(?<y>\d{4})(?<m>\d{2})(?<d>\d{2})/))
+    assert_integer_at(s, "y")
+    assert_integer_at(s, "m")
+    assert_integer_at(s, "d")
+  end
+
+  def test_integer_at_name_symbol
+    s = create_string_scanner("before 20260514 after")
+    s.skip_until(" ")
+    assert_equal("20260514", s.scan(/(?<y>\d{4})(?<m>\d{2})(?<d>\d{2})/))
+    assert_integer_at(s, :y)
+    assert_integer_at(s, :m)
+    assert_integer_at(s, :d)
+  end
+
+  def test_integer_at_base
+    s = create_string_scanner("before 111 after")
+    s.skip_until(" ")
+    assert_equal("111", s.scan(/\d+/))
+    assert_integer_at(s, 0, 2)
+  end
+
+  def test_integer_at_base_auto
+    s = create_string_scanner("before 0xa_f after")
+    s.skip_until(" ")
+    assert_equal("0xa_f", s.scan(/0x[\h_]+/))
+    assert_integer_at(s, 0, 0) # 0xaf
+  end
+
   def test_pre_match
     s = create_string_scanner('a b c d e')
     s.scan(/\w/)