match

        # Regexp.match

(from ruby core)
---
    rxp.match(str, pos=0)                   -> matchdata or nil
    rxp.match(str, pos=0) {|match| block }  -> obj

---

Returns a MatchData object describing the match, or `nil` if there was
no match. This is equivalent to retrieving the value of the special
variable `$~` following a normal match.  If the second parameter is
present, it specifies the position in the string to begin the search.

    /(.)(.)(.)/.match("abc")[2]   #=> "b"
    /(.)(.)/.match("abc", 1)[2]   #=> "c"

If a block is given, invoke the block with MatchData if match succeed,
so that you can write

    /M(.*)/.match("Matz") do |m|
      puts m[0]
      puts m[1]
    end

instead of

    if m = /M(.*)/.match("Matz")
      puts m[0]
      puts m[1]
    end

The return value is a value from block execution in this case.