Class

MatchData

Inheritance
< Object

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. Matchdata is also known as MatchingData.

Methods

Instance

Visibility Signature
public [] (...)
public begin (p1)
public captures ()
public end (p1)
public inspect ()
public length ()
public offset (p1)
public post_match ()
public pre_match ()
public pretty_print (q)
public select (...)
public size ()
public string ()
public to_a ()
public to_s ()
public values_at (...)

Instance Method Detail

mtch[i] => obj
mtch[start, length] => array
mtch[range] => array

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[0]       #=> "HX1138"
   m[1, 2]    #=> ["H", "X"]
   m[1..3]    #=> ["H", "X", "113"]
   m[-3, 2]   #=> ["X", "113"]

mtch.begin(n) => integer

Returns the offset of the start of the nth element of the match array in the string.

   m = /(.)(.)(\d+)(\d)/.match("THX1138.")
   m.begin(0)   #=> 1
   m.begin(2)   #=> 2

mtch.captures => array

Returns the array of captures; equivalent to mtch.to_a.

   f1,f2,f3,f4 = /(.)(.)(\d+)(\d)/.match("THX1138.").captures
   f1    #=> "H"
   f2    #=> "X"
   f3    #=> "113"
   f4    #=> "8"

mtch.end(n) => integer

Returns the offset of the character immediately following the end of the nth element of the match array in the string.

   m = /(.)(.)(\d+)(\d)/.match("THX1138.")
   m.end(0)   #=> 7
   m.end(2)   #=> 3

mtch.inspect => str

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">

mtch.length => integer
mtch.size => integer

Returns the number of elements in the match array.

   m = /(.)(.)(\d+)(\d)/.match("THX1138.")
   m.length   #=> 5
   m.size     #=> 5

mtch.offset(n) => array

Returns a two-element array containing the beginning and ending offsets of the nth match.

   m = /(.)(.)(\d+)(\d)/.match("THX1138.")
   m.offset(0)   #=> [1, 7]
   m.offset(4)   #=> [6, 7]

mtch.post_match => str

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"

mtch.pre_match => str

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"

pretty_print(q)

mtch.select{|obj| block} => array

Returns an array containing match strings for which block gives true. MatchData#select will be removed from Ruby 1.9.

   m = /(.)(.)(\d+)(\d)/.match("THX1138: The Movie")
   p m.select{|x| /X/ =~ x}   #=> ["HX1138", "X"]

mtch.length => integer
mtch.size => integer

Returns the number of elements in the match array.

   m = /(.)(.)(\d+)(\d)/.match("THX1138.")
   m.length   #=> 5
   m.size     #=> 5

mtch.string => str

Returns a frozen copy of the string passed in to match.

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

mtch.to_a => anArray

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"

mtch.to_s => str

Returns the entire matched string.

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

mtch.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"]