<ppdoc>
<copyright>
    Copyright (c) 2001 by Addison Wesley Longman.  This
    material may be distributed only subject to the terms and
    conditions set forth in the Open Publication License, v1.0 or
    later (the latest version is presently available at
    http://www.opencontent.org/openpub/).
</copyright>
<class name="MatchData" super="Object" type="class">
<p/>
  <tt>MatchData</tt> is the type of the special variable <var>$~</var>,
  and is the type of the object returned by <cim><file>regexp</file><front>Regexp</front><back>match</back><mref>match</mref></cim> and
  <cim><file>regexp</file><front>Regexp</front><back>last_match</back><mref>last_match</mref></cim>. It
  encapsulates all the results of a pattern match, results normally
  accessed through the special variables <tt>$&amp;</tt>, <tt>$'</tt>,
  <tt>$`</tt>, <tt>$1</tt>, <tt>$2</tt>, and so on.
<p/>
  <methods type="instance">
        <method name="[ ]" ref="_ob_cb">
      <callseq>
                  <obj>mtch</obj>[<obj>i</obj>] <returns><obj>anObject</obj></returns><br/><obj>mtch</obj>[<obj>start</obj>, <obj>length</obj>] <returns><obj>anArray</obj></returns><br/><obj>mtch</obj>[<obj>aRange</obj>] <returns><obj>anArray</obj></returns>
      </callseq>
      <desc>
<p/>
        Match Reference---<tt>MatchData</tt> acts as an array, and may
        be accessed using the normal array indexing techniques.
        <obj>mtch</obj>[0] is equivalent to the special variable <var>$&amp;</var>, and
        returns the entire matched string. <obj>mtch</obj>[1], <obj>mtch</obj>[2], and so
        on return the
        values of the matched backreferences (portions of the pattern
        between parentheses).
<p/>
<codefragment>
<fullcode><![CDATA[         m = /(.)(.)(\d+)(\d)/.match("THX1138.")
         m[0]
         m[1, 2]
         m[1..3]
         m[-3, 2]
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>m<nbsp/>=<nbsp/>/(.)(.)(\d+)(\d)/.match("THX1138.")</tt></td>
</tr>
<tr>
  <td><tt>m[0]</tt></td>
  <td>&#187;</td>
  <td><tt>"HX1138"</tt></td>
</tr>
<tr>
  <td><tt>m[1,<nbsp/>2]</tt></td>
  <td>&#187;</td>
  <td><tt>["H",<nbsp/>"X"]</tt></td>
</tr>
<tr>
  <td><tt>m[1..3]</tt></td>
  <td>&#187;</td>
  <td><tt>["H",<nbsp/>"X",<nbsp/>"113"]</tt></td>
</tr>
<tr>
  <td><tt>m[-3,<nbsp/>2]</tt></td>
  <td>&#187;</td>
  <td><tt>["X",<nbsp/>"113"]</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="begin" ref="begin">
      <callseq>
        <obj>mtch</obj>.begin( <obj>n</obj> ) <returns><obj>anInteger</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the offset of the start of the <em>n</em>th element of the
      match array in the string.
<p/>
<codefragment>
<fullcode><![CDATA[         m = /(.)(.)(\d+)(\d)/.match("THX1138.")
         m.begin(0)
         m.begin(2)
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>m<nbsp/>=<nbsp/>/(.)(.)(\d+)(\d)/.match("THX1138.")</tt></td>
</tr>
<tr>
  <td><tt>m.begin(0)</tt></td>
  <td>&#187;</td>
  <td><tt>1</tt></td>
</tr>
<tr>
  <td><tt>m.begin(2)</tt></td>
  <td>&#187;</td>
  <td><tt>2</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="end" ref="end">
      <callseq>
        <obj>mtch</obj>.end( <obj>n</obj> ) <returns><obj>anInteger</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the offset of the character immediately following the
      end of the <em>n</em>th element of the match array in the string.
<p/>
<codefragment>
<fullcode><![CDATA[         m = /(.)(.)(\d+)(\d)/.match("THX1138.")
         m.end(0)
         m.end(2)
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>m<nbsp/>=<nbsp/>/(.)(.)(\d+)(\d)/.match("THX1138.")</tt></td>
</tr>
<tr>
  <td><tt>m.end(0)</tt></td>
  <td>&#187;</td>
  <td><tt>7</tt></td>
</tr>
<tr>
  <td><tt>m.end(2)</tt></td>
  <td>&#187;</td>
  <td><tt>3</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="length" ref="length">
      <callseq>
        <obj>mtch</obj>.length <returns><obj>anInteger</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the number of elements in the match array.
<p/>
<codefragment>
<fullcode><![CDATA[         m = /(.)(.)(\d+)(\d)/.match("THX1138.")
         m.length
         m.size
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>m<nbsp/>=<nbsp/>/(.)(.)(\d+)(\d)/.match("THX1138.")</tt></td>
</tr>
<tr>
  <td><tt>m.length</tt></td>
  <td>&#187;</td>
  <td><tt>5</tt></td>
</tr>
<tr>
  <td><tt>m.size</tt></td>
  <td>&#187;</td>
  <td><tt>5</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="offset" ref="offset">
      <callseq>
        <obj>mtch</obj>.offset( <obj>n</obj> ) <returns><obj>anArray</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns a two-element array containing the beginning and ending
      offsets of the <em>n</em>th match.
<p/>
<codefragment>
<fullcode><![CDATA[         m = /(.)(.)(\d+)(\d)/.match("THX1138.")
         m.offset(0)
         m.offset(4)
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>m<nbsp/>=<nbsp/>/(.)(.)(\d+)(\d)/.match("THX1138.")</tt></td>
</tr>
<tr>
  <td><tt>m.offset(0)</tt></td>
  <td>&#187;</td>
  <td><tt>[1,<nbsp/>7]</tt></td>
</tr>
<tr>
  <td><tt>m.offset(4)</tt></td>
  <td>&#187;</td>
  <td><tt>[6,<nbsp/>7]</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="post_match" ref="post_match">
      <callseq>
        <obj>mtch</obj>.post_match <returns><obj>aString</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the portion of the original string after the current
      match. Equivalent to the special variable <var>$'</var>.
<p/>
<codefragment>
<fullcode><![CDATA[         m = /(.)(.)(\d+)(\d)/.match("THX1138: The Movie")
         m.post_match
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>m<nbsp/>=<nbsp/>/(.)(.)(\d+)(\d)/.match("THX1138:<nbsp/>The<nbsp/>Movie")</tt></td>
</tr>
<tr>
  <td><tt>m.post_match</tt></td>
  <td>&#187;</td>
  <td><tt>":<nbsp/>The<nbsp/>Movie"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="pre_match" ref="pre_match">
      <callseq>
        <obj>mtch</obj>.pre_match <returns><obj>aString</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the portion of the original string before the current
      match. Equivalent to the special variable <var>$`</var>.
<p/>
<codefragment>
<fullcode><![CDATA[         m = /(.)(.)(\d+)(\d)/.match("THX1138.")
         m.pre_match
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>m<nbsp/>=<nbsp/>/(.)(.)(\d+)(\d)/.match("THX1138.")</tt></td>
</tr>
<tr>
  <td><tt>m.pre_match</tt></td>
  <td>&#187;</td>
  <td><tt>"T"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="size" ref="size">
      <callseq>
        <obj>mtch</obj>.size <returns><obj>anInteger</obj></returns>
      </callseq>
      <desc>
<p/>
      A synonym for <cim><file>matchdata</file><front>MatchData</front><back>length</back><mref>length</mref></cim>.
<p/>
      </desc>
    </method>
<p/>
        <method name="string" ref="string">
      <callseq>
        <obj>mtch</obj>.string <returns><obj>aString</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns a frozen copy of the string passed in to <tt>match</tt>.
<p/>
<codefragment>
<fullcode><![CDATA[         m = /(.)(.)(\d+)(\d)/.match("THX1138.")
         m.string
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>m<nbsp/>=<nbsp/>/(.)(.)(\d+)(\d)/.match("THX1138.")</tt></td>
</tr>
<tr>
  <td><tt>m.string</tt></td>
  <td>&#187;</td>
  <td><tt>"THX1138."</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="to_a" ref="to_a">
      <callseq>
        <obj>mtch</obj>.to_a <returns><obj>anArray</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the array of matches.
<p/>
<codefragment>
<fullcode><![CDATA[         m = /(.)(.)(\d+)(\d)/.match("THX1138.")
         m.to_a
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>m<nbsp/>=<nbsp/>/(.)(.)(\d+)(\d)/.match("THX1138.")</tt></td>
</tr>
<tr>
  <td><tt>m.to_a</tt></td>
  <td>&#187;</td>
  <td><tt>["HX1138",<nbsp/>"H",<nbsp/>"X",<nbsp/>"113",<nbsp/>"8"]</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="to_s" ref="to_s">
      <callseq>
        <obj>mtch</obj>.to_s <returns><obj>aString</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the entire matched string.
<p/>
<codefragment>
<fullcode><![CDATA[         m = /(.)(.)(\d+)(\d)/.match("THX1138.")
         m.to_s
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>m<nbsp/>=<nbsp/>/(.)(.)(\d+)(\d)/.match("THX1138.")</tt></td>
</tr>
<tr>
  <td><tt>m.to_s</tt></td>
  <td>&#187;</td>
  <td><tt>"HX1138"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
  </methods>
<p/>
</class>
</ppdoc>