class MatchData (Ruby 3.3 リファレンスマニュアル)

要約

正規表現のマッチに関する情報を扱うためのクラス。

このクラスのインスタンスは、

などにより得られます。

インスタンスメソッド

eql?(other) -> bool[permalink][rdoc][edit]

self == other -> bool

self と other のマッチ対象になった文字列、元になった正規表現オブジェクト、マッチした位置が等しければ true を返します。そうでない場合には false を返します。

[PARAM] other:: 比較対象のオブジェクトを指定します。

文字列

s = "abc"
m1 = s.match("a")
m2 = s.match("b")
m1 == m2  # => false
m2 = s.match("a")
m1 == m2  # => true

正規表現

r = /abc/
m1 = r.match("abc")   # => #<MatchData "abc">
m2 = r.match("abcde") # => #<MatchData "abc">
m1 == m2  # => false
m2 = r.match("abc")   # => #<MatchData "abc">
m1 == m2  # => true

正規表現のマッチした位置

r = /abc/
m1 = r.match("abcabc")    # => #<MatchData "abc">
m2 = r.match("abcabc", 3) # => #<MatchData "abc">
m1 == m2  # => false
m2 = r.match("abcabc", 0) # => #<MatchData "abc">
m1 == m2  # => true

self[n] -> String | nil[permalink][rdoc][edit]

n 番目の部分文字列を返します。

0 はマッチ全体を意味します。 n の値が負の時には末尾からのインデックスと見倣します(末尾の要素が -1 番目)。n 番目の要素が存在しない時には nil を返します。

[PARAM] n:: 返す部分文字列のインデックスを指定します。

例

/(foo)(bar)(BAZ)?/ =~ "foobarbaz"
p $~.to_a       # => ["foobar", "foo", "bar", nil]
p $~[0]         # => "foobar"
p $~[1]         # => "foo"
p $~[2]         # => "bar"
p $~[3]         # => nil        (マッチしていない)
p $~[4]         # => nil        (範囲外)
p $~[-2]        # => "bar"

self[range] -> [String][permalink][rdoc][edit]

Range オブジェクト range の範囲にある要素からなる部分配列を返します。

[PARAM] range:: start..end 範囲式。

例

/(foo)(bar)/ =~ "foobarbaz"
p $~[0..2]      # => ["foobar", "foo", "bar"]

self[start, length] -> [String][permalink][rdoc][edit]

start 番目から length 個の要素を含む部分配列を返します。

例

/(foo)(bar)/ =~ "foobarbaz"
p $~[0, 3]      # => ["foobar", "foo", "bar"]

[SEE_ALSO] Array#[]

self[name] -> String | nil[permalink][rdoc][edit]

name という名前付きグループにマッチした文字列を返します。

[PARAM] name:: 名前(シンボルか文字列)
[EXCEPTION] IndexError:: 指定した名前が正規表現内に含まれていない場合に発生します

例

/\$(?<dollars>\d+)\.(?<cents>\d+)/.match("$3.67")[:cents] # => "67"
/(?<alpha>[a-zA-Z]+)|(?<num>\d+)/.match("aZq")[:num] # => nil

begin(n) -> Integer | nil[permalink][rdoc][edit]

n 番目の部分文字列先頭のオフセットを返します。

0 はマッチ全体を意味します。 n 番目の部分文字列がマッチしていなければ nilを返します。

[PARAM] n:: 部分文字列を指定する数値。
[EXCEPTION] IndexError:: 範囲外の n を指定した場合に発生します。

例

/(foo)(bar)(BAZ)?/ =~ "foobarbaz"
p $~.begin(0)   # => 0
p $~.begin(1)   # => 0
p $~.begin(2)   # => 3
p $~.begin(3)   # => nil
p $~.begin(4)   # => `begin': index 4 out of matches (IndexError)

[SEE_ALSO] MatchData#end

byteoffset(n) -> [Integer, Integer] | [nil, nil][permalink][rdoc][edit]

n 番目の部分文字列のバイト単位のオフセットの配列 [start, end] を返します。

n番目の部分文字列がマッチしていなければ [nil, nil] を返します。

[PARAM] n:: 部分文字列を指定する数値
[EXCEPTION] IndexError:: 範囲外の n を指定した場合に発生します。

[SEE_ALSO] MatchData#offset

byteoffset(name) -> [Integer, Integer] | [nil, nil][permalink][rdoc][edit]

name という名前付きグループに対応する部分文字列のバイト単位のオフセットの配列 [start, end] を返します。

nameの名前付きグループにマッチした部分文字列がなければ [nil, nil] を返します。

[PARAM] name:: 名前(シンボルか文字列)
[EXCEPTION] IndexError:: 正規表現中で定義されていない name を指定した場合に発生します。

例

/(?<year>\d{4})年(?<month>\d{1,2})月(?:(?<day>\d{1,2})日)?/ =~ "2021年1月"
p $~.byteoffset('year')    # => [0, 4]
p $~.byteoffset(:year)     # => [0, 4]
p $~.byteoffset('month')   # => [7, 8]
p $~.byteoffset(:month)    # => [7, 8]
p $~.byteoffset('day')     # => [nil, nil]
p $~.byteoffset('century') # => `offset': undefined group name reference: century (IndexError)

[SEE_ALSO] MatchData#offset

captures -> [String][permalink][rdoc][edit]

deconstruct -> [String]

$1, $2, ... を格納した配列を返します。

MatchData#to_a と異なり $& を要素に含みません。グループにマッチした部分文字列がなければ対応する要素は nil になります。

例

/(foo)(bar)(BAZ)?/ =~ "foobarbaz"
p $~.to_a       # => ["foobar", "foo", "bar", nil]
p $~.captures   # => ["foo", "bar", nil]

[SEE_ALSO] MatchData#to_a, MatchData#named_captures, パターンマッチ/非プリミティブなオブジェクトのマッチ: deconstruct メソッドと deconstruct_keys メソッド

deconstruct_keys(array_of_names) -> Hash[permalink][rdoc][edit]

引数で指定された名前の名前付きキャプチャを Hash で返します。

Hash のキーは名前付きキャプチャの名前のシンボル、値はキーの名前に対応した名前付きグループのうち最後にマッチした文字列です。

[PARAM] array_of_names:: 名前付きキャプチャの名前の配列を指定します。nil の場合は全ての名前付きキャプチャを意味します。

例

m = /(?<hours>\d{2}):(?<minutes>\d{2}):(?<seconds>\d{2})/.match("18:37:22")
m.deconstruct_keys([:hours, :minutes]) # => {:hours => "18", :minutes => "37"}
m.deconstruct_keys(nil) # => {:hours => "18", :minutes => "37", :seconds => "22"}

# 名前付きキャプチャが定義されていなかった場合は空のハッシュを返す
m = /(\d{2}):(\d{2}):(\d{2})/.match("18:37:22")
m.deconstruct_keys(nil) # => {}

[SEE_ALSO] パターンマッチ/非プリミティブなオブジェクトのマッチ: deconstruct メソッドと deconstruct_keys メソッド

end(n) -> Integer | nil[permalink][rdoc][edit]

n 番目の部分文字列終端のオフセットを返します。

0 はマッチ全体を意味します。 n 番目の部分文字列がマッチしていなければ nil を返します。

[PARAM] n:: 部分文字列を指定する数値。
[EXCEPTION] IndexError:: 範囲外の n を指定した場合に発生します。

例

/(foo)(bar)(BAZ)?/ =~ "foobarbaz"
p $~.end(0)   # => 6
p $~.end(1)   # => 3
p $~.end(2)   # => 6
p $~.end(3)   # => nil
p $~.end(4)   # => `end': index 4 out of matches (IndexError)

[SEE_ALSO] MatchData#begin

hash -> Integer[permalink][rdoc][edit]

self のマッチ対象になった文字列、元になった正規表現オブジェクト、マッチした位置を元にハッシュ値を計算して返します。

inspect -> String[permalink][rdoc][edit]

self の内容を人間に読みやすい文字列にして返します。

例

puts /.$/.match("foo").inspect
# => #<MatchData "o">

puts /(.)(.)(.)/.match("foo").inspect
# => #<MatchData "foo" 1:"f" 2:"o" 3:"o">

puts /(.)(.)?(.)/.match("fo").inspect
# => #<MatchData "fo" 1:"f" 2:nil 3:"o">

puts /(?<foo>.)(?<bar>.)(?<baz>.)/.match("hoge").inspect
# => #<MatchData "hog" foo:"h" bar:"o" baz:"g">

length -> Integer[permalink][rdoc][edit]

size -> Integer

部分文字列の数を返します(self.to_a.size と同じです)。

例

/(foo)(bar)(BAZ)?/ =~ "foobarbaz"
p $~.size       # => 4

named_captures -> Hash[permalink][rdoc][edit]

名前付きキャプチャをHashで返します。

Hashのキーは名前付きキャプチャの名前です。Hashの値はキーの名前に対応した名前付きグループのうち最後にマッチした文字列です。

例

m = /(?<a>.)(?<b>.)/.match("01")
m.named_captures # => {"a" => "0", "b" => "1"}

m = /(?<a>.)(?<b>.)?/.match("0")
m.named_captures # => {"a" => "0", "b" => nil}

m = /(?<a>.)(?<a>.)/.match("01")
m.named_captures # => {"a" => "1"}

m = /(?<a>x)|(?<a>y)/.match("x")
m.named_captures # => {"a" => "x"}

[SEE_ALSO] MatchData#captures, MatchData#deconstruct_keys

names -> [String][permalink][rdoc][edit]

名前付きキャプチャの名前を文字列配列で返します。

self.regexp.names と同じです。

例

/(?<foo>.)(?<bar>.)(?<baz>.)/.match("hoge").names
# => ["foo", "bar", "baz"]

m = /(?<x>.)(?<y>.)?/.match("a") # => #<MatchData "a" x:"a" y:nil>
m.names                          # => ["x", "y"]

offset(n) -> [Integer, Integer] | [nil, nil][permalink][rdoc][edit]

n 番目の部分文字列のオフセットの配列 [start, end] を返します。

例

[ self.begin(n), self.end(n) ]

と同じです。n番目の部分文字列がマッチしていなければ [nil, nil] を返します。

[PARAM] n:: 部分文字列を指定する数値
[EXCEPTION] IndexError:: 範囲外の n を指定した場合に発生します。

[SEE_ALSO] MatchData#begin, MatchData#end, MatchData#offset

offset(name) -> [Integer, Integer] | [nil, nil][permalink][rdoc][edit]

name という名前付きグループに対応する部分文字列のオフセットの配列 [start, end] を返します。

例

[ self.begin(name), self.end(name) ]

と同じです。nameの名前付きグループにマッチした部分文字列がなければ [nil, nil] を返します。

[PARAM] name:: 名前(シンボルか文字列)
[EXCEPTION] IndexError:: 正規表現中で定義されていない name を指定した場合に発生します。

例

/(?<year>\d{4})年(?<month>\d{1,2})月(?:(?<day>\d{1,2})日)?/ =~ "2021年1月"
p $~.offset('year')    # => [0, 4]
p $~.offset(:year)     # => [0, 4]
p $~.offset('month')   # => [5, 6]
p $~.offset(:month)    # => [5, 6]
p $~.offset('day')     # => [nil, nil]
p $~.offset('century') # => `offset': undefined group name reference: century (IndexError)

[SEE_ALSO] MatchData#begin, MatchData#end, MatchData#offset

post_match -> String[permalink][rdoc][edit]

マッチした部分より後ろの文字列を返します($'と同じ)。

例

/(bar)(BAZ)?/ =~ "foobarbaz"
p $~.post_match # => "baz"

[SEE_ALSO] MatchData#pre_match

pre_match -> String[permalink][rdoc][edit]

マッチした部分より前の文字列を返します($`と同じ)。

例

/(bar)(BAZ)?/ =~ "foobarbaz"
p $~.pre_match  # => "foo"

[SEE_ALSO] MatchData#post_match

regexp -> Regexp[permalink][rdoc][edit]

自身の元になった正規表現オブジェクトを返します。

例

m = /a.*b/.match("abc")
m.regexp # => /a.*b/

string -> String[permalink][rdoc][edit]

マッチ対象になった文字列の複製を返します。

返す文字列はフリーズ(Object#freeze)されています。

例

m = /(.)(.)(\d+)(\d)/.match("THX1138.")
m.string   # => "THX1138."

to_a -> [String][permalink][rdoc][edit]

$&, $1, $2,... を格納した配列を返します。

例

/(foo)(bar)(BAZ)?/ =~ "foobarbaz"
p $~.to_a       # => ["foobar", "foo", "bar", nil]

[SEE_ALSO] MatchData#captures

to_s -> String[permalink][rdoc][edit]

マッチした文字列全体を返します。

例

/bar/ =~ "foobarbaz"
p $~            # => #<MatchData:0x401b1be4>
p $~.to_s       # => "bar"

values_at(*index) -> [String][permalink][rdoc][edit]

正規表現中の n 番目の括弧にマッチした部分文字列の配列を返します。

0 番目は $& のようにマッチした文字列全体を表します。

[PARAM] index:: インデックスを整数またはシンボル(名前付きキャプチャの場合)で 0 個以上指定します。

例

m = /(foo)(bar)(baz)/.match("foobarbaz")
# same as m.to_a.values_at(...)
p m.values_at(0, 1, 2, 3, 4)      # => ["foobarbaz", "foo", "bar", "baz", nil]
p m.values_at(-1, -2, -3, -4, -5) # => ["baz", "bar", "foo", nil, nil]

m = /(?<a>\d+) *(?<op>[+\-*\/]) *(?<b>\d+)/.match("1 + 2")
m.to_a                   # => ["1 + 2", "1", "+", "2"]
m.values_at(:a, :b, :op) # => ["1", "2", "+"]

[SEE_ALSO] Array#values_at, Array#[]

要約

目次

インスタンスメソッド