<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="Regexp" super="Object" type="class" ref="xref-000001">
    A <classname>Regexp</classname> holds a regular expression, used to match a pattern against
  strings. Regexps are created using the <tt>/.../</tt> and <tt>%r{...}</tt>
  literals, and by the <ccm><file>regexp</file><front>Regexp</front><back>new</back><mref>new</mref></ccm> constructor.  
<p/>
  <constants>
<tr>
  <td><constant>
       <constname>EXTENDED</constname>
       <constval></constval>
       <constdesc>Ignore spaces and newlines in regexp.</constdesc>
     </constant>
<p/>
  <constant>
       <constname>IGNORECASE</constname>
       <constval></constval>
       <constdesc>Matches are case insensitive.</constdesc>
     </constant>
<p/>
  <constant>
       <constname>MULTILINE</constname>
       <constval></constval>
       <constdesc>Newlines treated as any other character.</constdesc>
     </constant>
</td>
</tr>
</constants>
<p/>
  <methods type="class">
<p/>
        <method name="compile" ref="compile">
      <callseq>
                Regexp.compile( <obj>pattern</obj>
         <opt>, <obj>options</obj> <opt><obj>lang</obj></opt></opt> )
         <returns><obj>aRegexp</obj></returns>
      </callseq>
      <desc>
<p/>
      Synonym for <tt>Regexp.new</tt>.
<p/>
      </desc>
    </method>
<p/>
        <method name="escape" ref="escape">
      <callseq>
        Regexp.escape( <obj>aString</obj> )
        <returns><obj>aNewString</obj></returns>
      </callseq>
      <desc>
<p/>
      Escapes any characters that would have special meaning in a
      regular expression. For any string,
      <tt>Regexp.escape(<obj>str</obj>)=~<obj>str</obj></tt> will be true.      
<p/>
<codefragment>
<fullcode><![CDATA[!-class String
!-  def inspect()
!-    to_s
!-  end
!-end
         Regexp.escape('\\[]*?{}.')
]]></fullcode><rubycode>
<tr>
  <td><tt>Regexp.escape('\\*?{}.')</tt></td>
  <td>&#187;</td>
  <td><tt>\\\\\*\?\{\}\.</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="last_match" ref="last_match">
      <callseq>
        Regexp.last_match
        <returns><obj>aMatchData</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the <classname>MatchData</classname> object generated by the last
      successful pattern match. Equivalent to reading the global
      variable <var>$~</var>. <classname>MatchData</classname> is described
      on page 336.
<p/>
      </desc>
    </method>
<p/>
        <method name="new" ref="new">
      <callseq>
        Regexp.new( <obj>pattern</obj>
                                    <opt>, <obj>options</obj> <opt><obj>lang</obj></opt></opt> )
        <returns><obj>aRegexp</obj></returns>
      </callseq>
      <desc>
<p/>
      Constructs a new regular expression from <obj>pattern</obj>, which can 
      be either a <tt>String</tt> or a <tt>Regexp</tt> (in which case that
      regexp's options are not propagated). If <obj>options</obj> is
      a <tt>Fixnum</tt>, it should be one or more of the constants
      <tt>Regexp::EXTENDED</tt>, <tt>Regexp::IGNORECASE</tt>, and
      <tt>Regexp::POSIXLINE</tt>, <em>or</em>-ed together.
      Otherwise, if <obj>options</obj> is not
      <tt>nil</tt>, the regexp will be case insensitive. The <obj>lang</obj>
      parameter enables multibyte support for the regexp: `n', `N' = none,
      `e', `E' =  EUC, `s', `S' = SJIS, `u',
      `U' = UTF-8.
<p/>
<codefragment>
<fullcode><![CDATA[        r1 = Regexp.new('^[a-z]+:\\s+\w+')
        r2 = Regexp.new(r1, true)
        r3 = Regexp.new(r2, Regexp::EXTENDED)
]]></fullcode><rubycode>
<tr>
  <td><tt>r1<nbsp/>=<nbsp/>Regexp.new('^a-z+:\\s+\w+')</tt></td>
  <td>&#187;</td>
  <td><tt>/^a-z+:\s+\w+/</tt></td>
</tr>
<tr>
  <td><tt>r2<nbsp/>=<nbsp/>Regexp.new(r1,<nbsp/>true)</tt></td>
  <td>&#187;</td>
  <td><tt>/^a-z+:\s+\w+/i</tt></td>
</tr>
<tr>
  <td><tt>r3<nbsp/>=<nbsp/>Regexp.new(r2,<nbsp/>Regexp::EXTENDED)</tt></td>
  <td>&#187;</td>
  <td><tt>/^a-z+:\s+\w+/x</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="quote" ref="quote">
      <callseq>
        Regexp.quote( <obj>aString</obj> )
        <returns><obj>aNewString</obj></returns>
      </callseq>
      <desc>
<p/>
      Synonym for <tt>Regexp.escape</tt>.
<p/>
      </desc>
    </method>
<p/>
  </methods>
<p/>
  <methods type="instance">
<p/>
        <method name="==" ref="_eq_eq">
      <callseq>
        <obj>rxp</obj> == <obj>aRegexp</obj>
        <returns><const>true</const> or <const>false</const></returns>
      </callseq>
      <desc>
<p/>
      Equality---Two regexps are equal if their patterns are identical, they have 
      the same character set code, and their <tt>casefold?</tt> values are 
      the same.
<p/>
<codefragment>
<fullcode><![CDATA[        /abc/  == /abc/x
        /abc/  == /abc/i
        /abc/u == /abc/n
]]></fullcode><rubycode>
<tr>
  <td><tt>/abc/<nbsp/><nbsp/>==<nbsp/>/abc/x</tt></td>
  <td>&#187;</td>
  <td><tt>false</tt></td>
</tr>
<tr>
  <td><tt>/abc/<nbsp/><nbsp/>==<nbsp/>/abc/i</tt></td>
  <td>&#187;</td>
  <td><tt>false</tt></td>
</tr>
<tr>
  <td><tt>/abc/u<nbsp/>==<nbsp/>/abc/n</tt></td>
  <td>&#187;</td>
  <td><tt>false</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="===" ref="_eq_eq_eq">
      <callseq>
        <obj>rxp</obj> === <obj>aString</obj> <returns><const>true</const> or <const>false</const></returns>
      </callseq>
      <desc>
<p/>
      Case Equality---Synonym for <cim><file>regexp</file><front>Regexp</front><back>=~</back><mref>_eq_sd</mref></cim> used in case statements.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[      a = "HELLO"
      case a
      when /^[a-z]*$/; print "Lower case\n"
      when /^[A-Z]*$/; print "Upper case\n"
      else;            print "Mixed case\n"
      end
]]></fullcode>
a<nbsp/>=<nbsp/>"HELLO"
case<nbsp/>a
when<nbsp/>/^a-z*$/;<nbsp/>print<nbsp/>"Lower<nbsp/>case\n"
when<nbsp/>/^A-Z*$/;<nbsp/>print<nbsp/>"Upper<nbsp/>case\n"
else;<nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/>print<nbsp/>"Mixed<nbsp/>case\n"
end
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
Upper<nbsp/>case
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="=~" ref="_eq_sd">
      <callseq>
        <obj>rxp</obj> =~ <obj>aString</obj>
        <returns><obj>anInteger</obj> or <tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Match---Matches <obj>rxp</obj> against <obj>aString</obj>, returning the offset 
      of the start of the match or <tt>nil</tt> if the match failed.
<p/>
<codefragment>
<fullcode><![CDATA[          /SIT/  =~ "insensitive"
          /SIT/i =~ "insensitive"
]]></fullcode><rubycode>
<tr>
  <td><tt>/SIT/<nbsp/><nbsp/>=~<nbsp/>"insensitive"</tt></td>
  <td>&#187;</td>
  <td><tt>nil</tt></td>
</tr>
<tr>
  <td><tt>/SIT/i<nbsp/>=~<nbsp/>"insensitive"</tt></td>
  <td>&#187;</td>
  <td><tt>5</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="~" ref="_sd">
      <callseq>
        ~ <obj>rxp</obj>
        <returns><obj>anInteger</obj> or <tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Match---Matches <obj>rxp</obj> against the contents of <tt>$_</tt>. Equivalent to
      <tt><obj>rxp</obj><nbsp/>=~<nbsp/>$_</tt>.
<p/>
<codefragment>
<fullcode><![CDATA[        $_ = "input data"
        ~ /at/
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>$_<nbsp/>=<nbsp/>"input<nbsp/>data"</tt></td>
</tr>
<tr>
  <td><tt>~<nbsp/>/at/</tt></td>
  <td>&#187;</td>
  <td><tt>7</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="casefold?" ref="casefold_qm">
      <callseq>
        <obj>rxp</obj>.casefold? <returns><const>true</const> or <const>false</const></returns>
      </callseq>
      <desc>
<p/>
      Returns the value of the case-insensitive flag.
<p/>
      </desc>
    </method>
<p/>
        <method name="kcode" ref="kcode">
      <callseq>
        <obj>rxp</obj>.kcode <returns><obj>aString</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the  character set code for the regexp.
<p/>
      </desc>
    </method>
<p/>
        <method name="match" ref="match">
      <callseq>
        <obj>rxp</obj>.match(<obj>aString</obj>)
        <returns><obj>aMatchData</obj> or <tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
        Returns a <classname>MatchData</classname> object (see page 336)
        describing the match, or <tt>nil</tt> if there was no match. This
        is equivalent to retrieving the value of the special variable
        <var>$~</var> following a normal match.
<p/>
<codefragment>
<fullcode><![CDATA[        /(.)(.)(.)/.match("abc")[2]
]]></fullcode><rubycode>
<tr>
  <td><tt>/(.)(.)(.)/.match("abc")[2]</tt></td>
  <td>&#187;</td>
  <td><tt>"b"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="source" ref="source">
      <callseq>
        <obj>rxp</obj>.source <returns><obj>aString</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the original string of the pattern.
<p/>
<codefragment>
<fullcode><![CDATA[         /ab+c/ix.source
]]></fullcode><rubycode>
<tr>
  <td><tt>/ab+c/ix.source</tt></td>
  <td>&#187;</td>
  <td><tt>"ab+c"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
  </methods>
<p/>
</class>
</ppdoc>
