Class: MatchData
Overview
MatchData
is the type of the special variable $~
, and is the type of the object returned by Regexp#match and Regexp.last_match. It encapsulates all the results of a pattern match, results normally accessed through the special variables $&
, $'
, $`
, $1
, $2
, and so on.
Instance Method Summary
-
#==(mtch2) ⇒ Boolean
(also: #eql?)
Equality—Two matchdata are equal if their target strings, patterns, and matched positions are identical.
-
#[](i) ⇒ String?
Match Reference –
MatchData
acts as an array, and may be accessed using the normal array indexing techniques. -
#begin(n) ⇒ Integer
Returns the offset of the start of the nth element of the match array in the string.
-
#captures ⇒ Array
Returns the array of captures; equivalent to
mtch.to_a[1..-1]
. -
#end(n) ⇒ Integer
Returns the offset of the character immediately following the end of the nth element of the match array in the string.
-
#eql?(mtch2) ⇒ Boolean
Alias for #==.
-
#hash ⇒ Integer
Produce a hash based on the target string, regexp and matched positions of this matchdata.
-
#inspect ⇒ String
Returns a printable version of mtch.
-
#length ⇒ Integer
(also: #size)
Returns the number of elements in the match array.
-
#names ⇒ Array, ...
Returns a list of names of captures as an array of strings.
-
#offset(n) ⇒ Array
Returns a two-element array containing the beginning and ending offsets of the nth match.
-
#post_match ⇒ String
Returns the portion of the original string after the current match.
-
#pre_match ⇒ String
Returns the portion of the original string before the current match.
-
#regexp ⇒ Regexp
Returns the regexp.
-
#size ⇒ Integer
Alias for #length.
-
#string ⇒ String
Returns a frozen copy of the string passed in to
match
. -
#to_a ⇒ Array
Returns the array of matches.
-
#to_s ⇒ String
Returns the entire matched string.
-
#values_at([index]*) ⇒ Array
Uses each index to access the matching values, returning an array of the corresponding matches.
Instance Method Details
#==(mtch2) ⇒ Boolean
#eql?(mtch2) ⇒ Boolean
Also known as: #eql?
Boolean
#eql?(mtch2) ⇒ Boolean
Equality—Two matchdata are equal if their target strings, patterns, and matched positions are identical.
Match Reference – MatchData
acts as an array, and may be accessed using the normal array indexing techniques. mtch[0]
is equivalent to the special variable $&
, and returns the entire matched string. mtch[1]
, mtch[2]
, and so on return the values of the matched backreferences (portions of the pattern between parentheses).
m = /(.)(.)(\d+)(\d)/.match("THX1138.")
m #=> #<MatchData "HX1138" 1:"H" 2:"X" 3:"113" 4:"8">
m[0] #=> "HX1138"
m[1, 2] #=> ["H", "X"]
m[1..3] #=> ["H", "X", "113"]
m[-3, 2] #=> ["X", "113"]
m = /(?<foo>a+)b/.match("ccaaab")
m #=> #<MatchData "aaab" foo:"aaa">
m["foo"] #=> "aaa"
m[:foo] #=> "aaa"
#begin(n) ⇒ Integer
Returns the offset of the start of the nth element of the match array in the string. n can be a string or symbol to reference a named capture.
m = /(.)(.)(\d+)(\d)/.match("THX1138.")
m.begin(0) #=> 1
m.begin(2) #=> 2
m = /(?<foo>.)(.)(?<bar>.)/.match("hoge")
p m.begin(:foo) #=> 0
p m.begin(: ) #=> 2
#captures ⇒ Array
Returns the array of captures; equivalent to mtch.to_a[1..-1]
.
f1,f2,f3,f4 = /(.)(.)(\d+)(\d)/.match("THX1138.").captures
f1 #=> "H"
f2 #=> "X"
f3 #=> "113"
f4 #=> "8"
#end(n) ⇒ Integer
Returns the offset of the character immediately following the end of the nth element of the match array in the string. n can be a string or symbol to reference a named capture.
m = /(.)(.)(\d+)(\d)/.match("THX1138.")
m.end(0) #=> 7
m.end(2) #=> 3
m = /(?<foo>.)(.)(?<bar>.)/.match("hoge")
p m.end(:foo) #=> 1
p m.end(: ) #=> 3
#==(mtch2) ⇒ Boolean
#eql?(mtch2) ⇒ Boolean
Boolean
#eql?(mtch2) ⇒ Boolean
Alias for #==.
#hash ⇒ Integer
Produce a hash based on the target string, regexp and matched positions of this matchdata.
See also Object#hash.
#inspect ⇒ String
Returns a printable version of mtch.
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">
Also known as: #size
Returns the number of elements in the match array.
m = /(.)(.)(\d+)(\d)/.match("THX1138.")
m.length #=> 5
m.size #=> 5
#names ⇒ Array, ...
Returns a list of names of captures as an array of strings. It is same as mtch.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) ⇒ Array
Returns a two-element array containing the beginning and ending offsets of the nth match. n can be a string or symbol to reference a named capture.
m = /(.)(.)(\d+)(\d)/.match("THX1138.")
m.offset(0) #=> [1, 7]
m.offset(4) #=> [6, 7]
m = /(?<foo>.)(.)(?<bar>.)/.match("hoge")
p m.offset(:foo) #=> [0, 1]
p m.offset(: ) #=> [2, 3]
#post_match ⇒ String
Returns the portion of the original string after the current match. Equivalent to the special variable $'
.
m = /(.)(.)(\d+)(\d)/.match("THX1138: The Movie")
m.post_match #=> ": The Movie"
#pre_match ⇒ String
Returns the portion of the original string before the current match. Equivalent to the special variable $`
.
m = /(.)(.)(\d+)(\d)/.match("THX1138.")
m.pre_match #=> "T"
#regexp ⇒ Regexp
Returns the regexp.
m = /a.*b/.match("abc")
m.regexp #=> /a.*b/
Alias for #length.
#string ⇒ String
Returns a frozen copy of the string passed in to match
.
m = /(.)(.)(\d+)(\d)/.match("THX1138.")
m.string #=> "THX1138."
#to_a ⇒ Array
Returns the array of matches.
m = /(.)(.)(\d+)(\d)/.match("THX1138.")
m.to_a #=> ["HX1138", "H", "X", "113", "8"]
Because to_a
is called when expanding *
variable, there's a useful assignment shortcut for extracting matched fields. This is slightly slower than accessing the fields directly (as an intermediate array is generated).
all,f1,f2,f3 = * /(.)(.)(\d+)(\d)/.match("THX1138.")
all #=> "HX1138"
f1 #=> "H"
f2 #=> "X"
f3 #=> "113"
#to_s ⇒ String
Returns the entire matched string.
m = /(.)(.)(\d+)(\d)/.match("THX1138.")
m.to_s #=> "HX1138"
#values_at([index]*) ⇒ Array
Uses each index to access the matching values, returning an array of the corresponding matches.
m = /(.)(.)(\d+)(\d)/.match("THX1138: The Movie")
m.to_a #=> ["HX1138", "H", "X", "113", "8"]
m.values_at(0, 2, -2) #=> ["HX1138", "X", "113"]