MatchData: match と match_length を追加 (Ruby 3.1)

どちらも Ruby 3.1 で追加されたメソッド。実機で確認し #@SInCE 3.1 で分岐した。

  MatchData#match         単一グループにマッチした部分文字列
  MatchData#match_length  単一グループにマッチした部分文字列の長さ (文字数)

配置は関連する MatchData#[] 群の後、MatchData#begin の前にした。

match は MatchData#[] と似ているが、範囲や複数要素の指定はできず単一グループ
だけを返す点を書いた。match_length の長さは文字数で数えることを、
ひらがな 3 文字の例 (match_length(1) が 3) で示した。どちらもマッチしていない
グループでは nil、範囲外の数値や存在しない名前では IndexError になる。

bitclust のデータベース生成を 3.0 / 3.1 / 3.4 / 4.0 で実行してエラーが出ないこと、
登録されるメソッドが 0 / 2 / 2 / 2 件と 3.1 追加どおりになることを確認済み。
サンプルコードは対象の全バージョンで実行して出力を確認した。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: Watson1978

manual/api/_builtin/MatchData.md

@@ -68,6 +68,60 @@ p /\$(?<dollars>\d+)\.(?<cents>\d+)/.match("$3.67")[:cents] # => "67"
 p /(?<alpha>[a-zA-Z]+)|(?<num>\d+)/.match("aZq")[:num] # => nil
 ```
 
+#@since 3.1
+### def match(n) -> String | nil
+### def match(name) -> String | nil
+
+n 番目、または name という名前のグループにマッチした部分文字列を返します。
+
+[m:MatchData#\[\]] と似ていますが、範囲や複数要素の指定はできず、
+単一のグループに対応する部分文字列だけを返します。
+マッチしていないグループを指定した場合は nil を返します。
+
+- **param** `n` -- 返す部分文字列のインデックスを 0 以上の整数で指定します。
+           0 はマッチ全体を意味します。
+- **param** `name` -- 名前付きグループの名前を [c:String] か [c:Symbol] で指定します。
+- **raise** `IndexError` -- 範囲外の n や、存在しない name を指定した場合に発生します。
+
+```ruby title="例"
+m = /(.)(.)(\d+)(\d)(\w)?/.match("THX1138.")
+p m.match(0) # => "HX1138"
+p m.match(4) # => "8"
+p m.match(5) # => nil
+
+m = /(?<foo>.)(.)(?<bar>.+)/.match("hoge")
+p m.match(:foo) # => "h"
+p m.match(:bar) # => "ge"
+```
+
+- **SEE** [m:MatchData#\[\]], [m:MatchData#match_length]
+
+### def match_length(n) -> Integer | nil
+### def match_length(name) -> Integer | nil
+
+n 番目、または name という名前のグループにマッチした部分文字列の長さを
+文字数で返します。
+
+マッチしていないグループを指定した場合は nil を返します。
+
+- **param** `n` -- 対象の部分文字列のインデックスを 0 以上の整数で指定します。
+           0 はマッチ全体を意味します。
+- **param** `name` -- 名前付きグループの名前を [c:String] か [c:Symbol] で指定します。
+- **raise** `IndexError` -- 範囲外の n や、存在しない name を指定した場合に発生します。
+
+```ruby title="例"
+m = /(.)(.)(\d+)(\d)(\w)?/.match("THX1138.")
+p m.match_length(0) # => 6
+p m.match_length(4) # => 1
+p m.match_length(5) # => nil
+
+# 長さは文字数で数える
+p /(\p{Hiragana}+)/.match("あいう").match_length(1) # => 3
+```
+
+- **SEE** [m:MatchData#match]
+#@end
+
 ### def begin(n) -> Integer | nil
 
 n 番目の部分文字列先頭のオフセットを返します。