mruby-regexp: add the regexp form of String#sub! and String#gsub! - #7061

mruby-regexp overrides String#sub and String#gsub so that they accept a Regexp, but it does not override String#sub! and String#gsub!. Those keep the core definitions in mrblib/string.rb, which decide whether a substitution took place with self.index(args[0]). String#index only takes a String, so a Regexp pattern raises there instead of substituting.

s = "hello world"
s.sub!(/o/, "0")
# CRuby: "hell0 world"
# mruby: TypeError (Regexp cannot be converted to String)

mruby-regexp is part of default.gembox through stdlib.gembox, so a plain rake build reproduces it:

$ ./build/host/bin/mruby -e 's = "hello world"; p s.sub!(/o/, "0")'
-e:1:in index: Regexp cannot be converted to String (TypeError)

Every form that reaches the index call is affected: a replacement string, a block, backreferences. The two that return before it are already right, by accident. "abc".sub!(/b/) raises the ArgumentError CRuby raises, because the String#sub override checks its argument count first, and "abc".gsub!(/a/) hands back an Enumerator that raises only once iterated. String patterns substitute correctly.

Cause

gsub! and sub! in mrblib/string.rb both delegate the substitution to gsub/sub and then ask self.index(args[0]) whether anything matched. index is a String search, so the question cannot be asked about a Regexp.

Fix

Override both in mrbgems/mruby-regexp/mrblib/string_regexp.rb, next to the sub and gsub they belong with, and decide the same question with a match.

match and not match?: a failed match has to clear $~, which is what CRuby leaves behind for a sub! that substituted nothing. The match is also what decides the return value, so a substitution that leaves the string as it was is still a substitution.

s = "aaa"
s.gsub!(/a/, "a")   # self, not nil

The overrides take String patterns over from the core definitions as well, so they resolve the argument exactly the way sub and gsub do: Regexp.__check_pattern rejects anything that is neither a Regexp nor a String, and an accepted String is quoted with Regexp.new(Regexp.escape(pattern)) rather than compiled, so "a.c".sub!(".", "X") still replaces the dot and not the a. Skipping the resolver would reopen, one method over, the hole #7001 closed.

The resolved pattern is then what goes on to sub/gsub, so a String is quoted and compiled once rather than twice. They match again and republish $~ over the match made here, which leaves the caller what CRuby leaves: the single match for sub!, the last one for gsub!, and a block's own matches where the block made any.

The order the arguments are read in follows CRuby, where the two methods differ:

So sub! checks the arguments before the receiver, and gsub! checks the receiver first, ahead of the Enumerator its one-argument form otherwise returns. "abc".gsub!(:b) on an unfrozen string still yields an Enumerator that raises on the first iteration, as gsub does.

Matching self and then overwriting it with replace is safe, and no dup of the subject is needed. MatchData used to hold the string it matched by reference, which would have made the $~ left behind describe the replaced string; create_matchdata() has snapshotted the subject since #7053.

s = "hello world"
s.sub!(/o/, "0")
$~[0]        # "o"
$~.string    # "hello world"

Behaviour

Every cell in the "after" column is what CRuby 4.0.6 answers.

Tests

Seven asserts in mrbgems/mruby-regexp/test/regexp.rb, covering the substitution itself in both the replacement-string and the block form, backreferences, the receiver coming back rather than a copy, nil only for a failed match, String patterns staying literal and non-patterns being rejected, the argument counts and their messages, the Enumerator from gsub!, the frozen receiver in both orders, and the $~ left behind, cleared included.

rake test passes: 1994 asserts, 0 KO.

Summary by CodeRabbit

• New Features

  • Added String#sub! for replacing the first matching substring.
  • Added String#gsub! for replacing all matching substrings.
  • Supports regular expression and literal string patterns, replacement strings, and blocks.
  • Returns nil when no replacement occurs and preserves frozen-string protections.

• Tests

  • Added comprehensive coverage for replacements, argument validation, enumerators, frozen strings, return values, and match-state behavior.