<ppdoc>
<copyright>
Copyright (c) 2001 by Addison Wesley Longman, Inc. 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/).
<p/>
Distribution of substantively modified versions of this document is
prohibited without the explicit permission of the copyright holder.
<p/>
Distribution of the work or derivative of the work in any standard
(paper) book form is prohibited unless prior permission is obtained
from the copyright holder.
</copyright>
<class name="String" super="Object" type="class" ref="xref-000001">
<p/>
      A <classname>String</classname> object holds and manipulates an arbitrary sequence
      of bytes, typically representing characters. String objects may
      be created using <ccm><file>string</file><front>String</front><back>new</back><mref>new</mref></ccm> or as literals (see page
      202).
<p/>
  Because of aliasing issues, users of strings should be aware of the
  methods that modify the contents of a <classname>String</classname> object. Typically,
  methods with names ending in ``!'' modify their receiver, while those
  without a ``!'' return a new <classname>String</classname>. However, there are exceptions, such 
  as <cim><file>string</file><front>String</front><back>[]=</back><mref>_ob_cb_eq</mref></cim>.
  <mixins>
    <mixin name="Comparable">
   &lt;, &lt;=, ==, &gt;=, &gt;, between?</mixin>
    <mixin name="Enumerable">
   collect, detect, each_with_index, entries, find, find_all, grep,
   include?, map, max, member?, min, reject, select, sort, to_a</mixin>
  </mixins>
<p/>
  <methods type="class">
        <method name="new" ref="new">
      <callseq>
        String.new( <obj>aString</obj> )
        <returns><obj>aNewString</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns a new string object containing a copy of <obj>aString</obj>.
<p/>
      </desc>
    </method>
<p/>
  </methods>
<p/>
  <methods type="instance">
        <method name="%" ref="_pc">
      <callseq>
        <obj>str</obj> % <obj>arg</obj>
        <returns><obj>aString</obj></returns>
      </callseq>
      <desc>
<p/>
      Format---Uses <obj>str</obj> as a format
      specification, and returns the result of applying it to
      <obj>arg</obj>. If the format specification contains more than one
      substitution, then <obj>arg</obj> must be an <classname>Array</classname> containing the
      values to be substituted. See <mmm><file>kernel</file><front>Kernel</front><back>sprintf</back><mref>sprintf</mref></mmm>
      on page 423 for details of the format string.
<p/>
<codefragment>
<fullcode><![CDATA[         "%05d" % 123
         "%-5s: %08x" % [ "ID", self.id ]
]]></fullcode><rubycode>
<tr>
  <td><tt>"%05d"<nbsp/>%<nbsp/>123</tt></td>
  <td>&#187;</td>
  <td><tt>"00123"</tt></td>
</tr>
<tr>
  <td><tt>"%-5s:<nbsp/>%08x"<nbsp/>%<nbsp/>[<nbsp/>"ID",<nbsp/>self.id<nbsp/>]</tt></td>
  <td>&#187;</td>
  <td><tt>"ID<visible_space/><visible_space/><visible_space/>:<visible_space/>200e1670"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="*" ref="_st">
      <callseq>
        <obj>str</obj> * <obj>anInteger</obj>
        <returns><obj>aString</obj></returns>
      </callseq>
      <desc>
<p/>
      Copy---Returns a new <classname>String</classname> containing <obj>anInteger</obj> copies of
      the receiver.
<p/>
<codefragment>
<fullcode><![CDATA[         "Ho! " * 3
]]></fullcode><rubycode>
<tr>
  <td><tt>"Ho!<nbsp/>"<nbsp/>*<nbsp/>3</tt></td>
  <td>&#187;</td>
  <td><tt>"Ho!<nbsp/>Ho!<nbsp/>Ho!<nbsp/>"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="+" ref="_pl">
      <callseq>
        <obj>str</obj> + <obj>aString</obj>
        <returns><obj>aNewString</obj></returns>
      </callseq>
      <desc>
<p/>
      Concatenation---Returns a new <classname>String</classname> containing 
      <obj>aString</obj> concatenated to <obj>str</obj>. 
<p/>
<codefragment>
<fullcode><![CDATA[         "Hello from " + self.to_s
]]></fullcode><rubycode>
<tr>
  <td><tt>"Hello<nbsp/>from<nbsp/>"<nbsp/>+<nbsp/>self.to_s</tt></td>
  <td>&#187;</td>
  <td><tt>"Hello<nbsp/>from<nbsp/>main"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="&lt;&lt;" ref="_lt_lt">
      <callseq>
                    <obj>str</obj> &lt;&lt; <obj>aFixnum</obj> <returns><obj>str</obj></returns><br/><obj>str</obj> &lt;&lt; <obj>anObject</obj> <returns><obj>str</obj></returns>
      </callseq>
      <desc>
              Append---Concatenates the given object to <obj>str</obj>. If the object is a
      <classname>Fixnum</classname> between 0 and 255, it is converted to a character
      before concatenation.
<p/>
<codefragment>
<fullcode><![CDATA[         a = "hello "
         a << "world"
         a << 33
         a
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>a<nbsp/>=<nbsp/>"hello<nbsp/>"</tt></td>
</tr>
<tr>
  <td><tt>a<nbsp/>&lt;&lt;<nbsp/>"world"</tt></td>
  <td>&#187;</td>
  <td><tt>"hello<nbsp/>world"</tt></td>
</tr>
<tr>
  <td><tt>a<nbsp/>&lt;&lt;<nbsp/>33</tt></td>
  <td>&#187;</td>
  <td><tt>"hello<nbsp/>world!"</tt></td>
</tr>
<tr>
  <td><tt>a</tt></td>
  <td>&#187;</td>
  <td><tt>"hello<nbsp/>world!"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="&lt;=&gt;" ref="_lt_eq_lt">
      <callseq>
        <obj>str</obj> &lt;=&gt; <obj>aString</obj>
        <returns>-1, 0, +1</returns>
      </callseq>
      <desc>
<p/>
      Comparison---Returns -1 if <obj>str</obj> is less than, 0
      if <obj>str</obj> is equal to, and +1 if <obj>str</obj> is greater than
      <obj>aString</obj>. If the strings are of different lengths, and the
      strings are equal when compared up to the shortest length, then
      the longer string is considered greater than the shorter one. If
      the variable <var>$=</var> is <const>false</const>, the comparison is based
      on comparing the binary values of each character in the string.
      If <var>$=</var> is not <const>false</const>, then the comparison is
      case insensitive.<footnote>The locale is ignored when
        case-insensitive comparisons are performed, so ``\"o'' will not
        match ``\"O''.</footnote>
<p/>
      <meth>&lt;=&gt;</meth> is the basis for the methods <meth>&lt;</meth>,
      <meth>&lt;=</meth>, <meth>&gt;</meth>, <meth>&gt;=</meth>, and <meth>between?</meth>,
      included from module <modulename>Comparable</modulename>. The method <cim><file>string</file><front>String</front><back>==</back><mref>_eq_eq</mref></cim>
      does not use <mim><file>comparable</file><front>Comparable</front><back>==</back><mref>_eq_eq</mref></mim>.
<p/>
<codefragment>
<fullcode><![CDATA[        "abcdef" <=> "abcde"
        "abcdef" <=> "abcdef"
        "abcdef" <=> "abcdefg"
        "abcdef" <=> "ABCDEF"
        $= = true
        "abcdef" <=> "ABCDEF"
]]></fullcode><rubycode>
<tr>
  <td><tt>"abcdef"<nbsp/>&lt;=&gt;<nbsp/>"abcde"</tt></td>
  <td>&#187;</td>
  <td><tt>1</tt></td>
</tr>
<tr>
  <td><tt>"abcdef"<nbsp/>&lt;=&gt;<nbsp/>"abcdef"</tt></td>
  <td>&#187;</td>
  <td><tt>0</tt></td>
</tr>
<tr>
  <td><tt>"abcdef"<nbsp/>&lt;=&gt;<nbsp/>"abcdefg"</tt></td>
  <td>&#187;</td>
  <td><tt>-1</tt></td>
</tr>
<tr>
  <td><tt>"abcdef"<nbsp/>&lt;=&gt;<nbsp/>"ABCDEF"</tt></td>
  <td>&#187;</td>
  <td><tt>1</tt></td>
</tr>
<tr>
<td colspan="3"><tt>$=<nbsp/>=<nbsp/>true</tt></td>
</tr>
<tr>
  <td><tt>"abcdef"<nbsp/>&lt;=&gt;<nbsp/>"ABCDEF"</tt></td>
  <td>&#187;</td>
  <td><tt>0</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="==" ref="_eq_eq">
      <callseq>
        <obj>str</obj> == <obj>anObject</obj>
        <returns><const>true</const> or <const>false</const></returns>
      </callseq>
      <desc>
<p/>
      Equality---If <obj>anObject</obj> is not a <classname>String</classname>, returns
      <const>false</const>. Otherwise, returns <const>true</const> if <obj>str</obj> <tt>&lt;=&gt;</tt>
      <obj>anObject</obj> returns zero.
<p/>
      </desc>
    </method>
<p/>
        <method name="===" ref="_eq_eq_eq">
      <callseq>
        <obj>str</obj> === <obj>anObject</obj>
        <returns><const>true</const> or <const>false</const></returns>
      </callseq>
      <desc>
<p/>
      Case Equality---Synonym for <cim><file>string</file><front>String</front><back>==</back><mref>_eq_eq</mref></cim>.
<p/>
      </desc>
    </method>
<p/>
        <method name="=~" ref="_eq_sd">
      <callseq>
        <obj>str</obj> =~ <obj>anObject</obj>
        <returns><obj>aFixnum</obj> or <tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Match---If <obj>anObject</obj> is a <classname>Regexp</classname> or a <classname>String</classname>, uses it as a
      pattern to match against <obj>str</obj>.  Returns
      the position the match starts, or <const>nil</const> if there is no match.
      Otherwise, invokes
      <obj>anObject.=~</obj>, passing <obj>str</obj> as an argument. The
      default <tt>=~</tt> in <classname>Object</classname> returns <const>false</const>.
<p/>
<codefragment>
<fullcode><![CDATA[        "cat o' 9 tails" =~ "\\d"
        "cat o' 9 tails" =~ /\d/
        "cat o' 9 tails" =~ 9
]]></fullcode><rubycode>
<tr>
  <td><tt>"cat<nbsp/>o'<nbsp/>9<nbsp/>tails"<nbsp/>=~<nbsp/>"\\d"</tt></td>
  <td>&#187;</td>
  <td><tt>7</tt></td>
</tr>
<tr>
  <td><tt>"cat<nbsp/>o'<nbsp/>9<nbsp/>tails"<nbsp/>=~<nbsp/>/\d/</tt></td>
  <td>&#187;</td>
  <td><tt>7</tt></td>
</tr>
<tr>
  <td><tt>"cat<nbsp/>o'<nbsp/>9<nbsp/>tails"<nbsp/>=~<nbsp/>9</tt></td>
  <td>&#187;</td>
  <td><tt>false</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="[ ]" ref="_ob_cb">
      <callseq>
                    <obj>str</obj>[ <obj>aFixnum</obj> ] <returns><obj>aFixnum</obj> or <tt>nil</tt></returns><br/><obj>str</obj>[ <obj>aFixnum</obj>, <obj>aFixnum</obj> ] <returns><obj>aString</obj> or <tt>nil</tt></returns><br/><obj>str</obj>[ <obj>aRange</obj> ] <returns><obj>aString</obj> or <tt>nil</tt></returns><br/><obj>str</obj>[ <obj>aRegexp</obj> ] <returns><obj>aString</obj> or <tt>nil</tt></returns><br/><obj>str</obj>[ <obj>aString</obj> ] <returns><obj>aString</obj> or <tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
        Element Reference---If passed a single <classname>Fixnum</classname>, returns the
        code of the character at that position. If passed two
        <classname>Fixnum</classname> objects, returns a substring starting at the offset given
        by the first, and a length given by the second. If given a
        range, a substring containing characters at offsets given by
        the range is returned. In all three cases, if an offset is
        negative, it is counted from the end of <obj>str</obj>. Returns <tt>nil</tt>
        if the initial offset falls outside the string, the length is
        negative, or the beginning of the range is greater than the
        end.
<p/>
      If a <classname>Regexp</classname> is supplied, the matching portion of <obj>str</obj> is
      returned. If a <classname>String</classname> is given, that string is returned if it 
      occurs in <obj>str</obj>. In both cases, <const>nil</const> is returned if there
      is no match.
<p/>
<codefragment>
<fullcode><![CDATA[        a = "hello there"
        a[1]
        a[1,3]
        a[1..3]
        a[-3,2]
        a[-4..-2]
        a[-2..-4]
        a[/th[aeiou]/]
        a["lo"]
        a["bye"]
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>a<nbsp/>=<nbsp/>"hello<nbsp/>there"</tt></td>
</tr>
<tr>
  <td><tt>a[1]</tt></td>
  <td>&#187;</td>
  <td><tt>101</tt></td>
</tr>
<tr>
  <td><tt>a[1,3]</tt></td>
  <td>&#187;</td>
  <td><tt>"ell"</tt></td>
</tr>
<tr>
  <td><tt>a[1..3]</tt></td>
  <td>&#187;</td>
  <td><tt>"ell"</tt></td>
</tr>
<tr>
  <td><tt>a[-3,2]</tt></td>
  <td>&#187;</td>
  <td><tt>"er"</tt></td>
</tr>
<tr>
  <td><tt>a[-4..-2]</tt></td>
  <td>&#187;</td>
  <td><tt>"her"</tt></td>
</tr>
<tr>
  <td><tt>a[-2..-4]</tt></td>
  <td>&#187;</td>
  <td><tt>nil</tt></td>
</tr>
<tr>
  <td><tt>a[/th[aeiou]/]</tt></td>
  <td>&#187;</td>
  <td><tt>"the"</tt></td>
</tr>
<tr>
  <td><tt>a["lo"]</tt></td>
  <td>&#187;</td>
  <td><tt>"lo"</tt></td>
</tr>
<tr>
  <td><tt>a["bye"]</tt></td>
  <td>&#187;</td>
  <td><tt>nil</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="[ ]=" ref="_ob_cb_eq">
      <callseq>
                    <obj>str</obj>[ <obj>aFixnum</obj> ] = <obj>aFixnum</obj><br/><obj>str</obj>[ <obj>aFixnum</obj> ] = <obj>aString</obj><br/><obj>str</obj>[ <obj>aFixnum</obj>, <obj>aFixnum</obj> ] = <obj>aString</obj><br/><obj>str</obj>[ <obj>aRange</obj> ] = <obj>aString</obj><br/><obj>str</obj>[ <obj>aRegexp</obj> ] = <obj>aString</obj><br/><obj>str</obj>[ <obj>aString</obj> ] = <obj>aString</obj>
      </callseq>
      <desc>
<p/>
        Element Assignment---Replaces some or all of the content of
        <obj>str</obj>. The portion of the string affected is determined using
        the same criteria as <cim><file>string</file><front>String</front><back>[]</back><mref>_ob_cb</mref></cim>. If the replacement
        string is not the same length as the text it is replacing, the
        string will be adjusted accordingly.  
                The forms that take a <classname>Fixnum</classname> will raise an
        <exception>IndexError</exception> if the value is out of range; the <classname>Range</classname>
        form will raise a <exception>RangeError</exception>, and the <classname>Regexp</classname> and
        <classname>String</classname> forms will silently ignore the assignment.<codefragment>
<fullcode><![CDATA[      a = "hello"; a[2]       = 96;    a
      a = "hello"; a[2, 4]    = "xyz"; a
      a = "hello"; a[-4, 2]   = "xyz"; a
      a = "hello"; a[2..4]    = "xyz"; a
      a = "hello"; a[-4..-2]  = "xyz"; a
      a = "hello"; a[/[el]+/] = "xyz"; a
      a = "hello"; a["l"]     = "xyz"; a
      a = "hello"; a["ll"]    = "xyz"; a
      a = "hello"; a["bad"]   = "xyz"; a
      a = "hello"; a[2, 0]    = "xyz"; a
]]></fullcode><rubycode>
<tr>
  <td><tt>a<nbsp/>=<nbsp/>"hello";<nbsp/>a[2]<nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/>=<nbsp/>96;<nbsp/><nbsp/><nbsp/><nbsp/>a</tt></td>
  <td>&#187;</td>
  <td><tt>"he`lo"</tt></td>
</tr>
<tr>
  <td><tt>a<nbsp/>=<nbsp/>"hello";<nbsp/>a[2,<nbsp/>4]<nbsp/><nbsp/><nbsp/><nbsp/>=<nbsp/>"xyz";<nbsp/>a</tt></td>
  <td>&#187;</td>
  <td><tt>"hexyz"</tt></td>
</tr>
<tr>
  <td><tt>a<nbsp/>=<nbsp/>"hello";<nbsp/>a[-4,<nbsp/>2]<nbsp/><nbsp/><nbsp/>=<nbsp/>"xyz";<nbsp/>a</tt></td>
  <td>&#187;</td>
  <td><tt>"hxyzlo"</tt></td>
</tr>
<tr>
  <td><tt>a<nbsp/>=<nbsp/>"hello";<nbsp/>a[2..4]<nbsp/><nbsp/><nbsp/><nbsp/>=<nbsp/>"xyz";<nbsp/>a</tt></td>
  <td>&#187;</td>
  <td><tt>"hexyz"</tt></td>
</tr>
<tr>
  <td><tt>a<nbsp/>=<nbsp/>"hello";<nbsp/>a[-4..-2]<nbsp/><nbsp/>=<nbsp/>"xyz";<nbsp/>a</tt></td>
  <td>&#187;</td>
  <td><tt>"hxyzo"</tt></td>
</tr>
<tr>
  <td><tt>a<nbsp/>=<nbsp/>"hello";<nbsp/>a[/[el]+/]<nbsp/>=<nbsp/>"xyz";<nbsp/>a</tt></td>
  <td>&#187;</td>
  <td><tt>"hxyzo"</tt></td>
</tr>
<tr>
  <td><tt>a<nbsp/>=<nbsp/>"hello";<nbsp/>a["l"]<nbsp/><nbsp/><nbsp/><nbsp/><nbsp/>=<nbsp/>"xyz";<nbsp/>a</tt></td>
  <td>&#187;</td>
  <td><tt>"hexyzlo"</tt></td>
</tr>
<tr>
  <td><tt>a<nbsp/>=<nbsp/>"hello";<nbsp/>a["ll"]<nbsp/><nbsp/><nbsp/><nbsp/>=<nbsp/>"xyz";<nbsp/>a</tt></td>
  <td>&#187;</td>
  <td><tt>"hexyzo"</tt></td>
</tr>
<tr>
  <td><tt>a<nbsp/>=<nbsp/>"hello";<nbsp/>a["bad"]<nbsp/><nbsp/><nbsp/>=<nbsp/>"xyz";<nbsp/>a</tt></td>
  <td>&#187;</td>
  <td><tt>"hello"</tt></td>
</tr>
<tr>
  <td><tt>a<nbsp/>=<nbsp/>"hello";<nbsp/>a[2,<nbsp/>0]<nbsp/><nbsp/><nbsp/><nbsp/>=<nbsp/>"xyz";<nbsp/>a</tt></td>
  <td>&#187;</td>
  <td><tt>"hexyzllo"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="~" ref="_sd">
      <callseq>
        ~<obj>str</obj>
        <returns><obj>aFixnum</obj> or <tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Equivalent to <var>$_</var><tt><nbsp/>=~<nbsp/><obj>str</obj></tt>.
<p/>
      </desc>
    </method>
<p/>
        <method name="capitalize" ref="capitalize">
      <callseq>
        <obj>str</obj>.capitalize
        <returns><obj>aString</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns a copy of <obj>str</obj> with the first character converted to
      uppercase and the remainder to lowercase.
<p/>
<codefragment>
<fullcode><![CDATA[         "hello".capitalize
         "HELLO".capitalize
         "123ABC".capitalize
]]></fullcode><rubycode>
<tr>
  <td><tt>"hello".capitalize</tt></td>
  <td>&#187;</td>
  <td><tt>"Hello"</tt></td>
</tr>
<tr>
  <td><tt>"HELLO".capitalize</tt></td>
  <td>&#187;</td>
  <td><tt>"Hello"</tt></td>
</tr>
<tr>
  <td><tt>"123ABC".capitalize</tt></td>
  <td>&#187;</td>
  <td><tt>"123abc"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="capitalize!" ref="capitalize_oh">
      <callseq>
        <obj>str</obj>.capitalize!
        <returns><obj>str</obj> or <tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Modifies <obj>str</obj> by converting  the first character to
      uppercase and the remainder to lowercase. Returns <const>nil</const> if 
      no changes are made. <codefragment>
<fullcode><![CDATA[         a = "hello"
         a.capitalize!
         a
         a.capitalize!
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>a<nbsp/>=<nbsp/>"hello"</tt></td>
</tr>
<tr>
  <td><tt>a.capitalize!</tt></td>
  <td>&#187;</td>
  <td><tt>"Hello"</tt></td>
</tr>
<tr>
  <td><tt>a</tt></td>
  <td>&#187;</td>
  <td><tt>"Hello"</tt></td>
</tr>
<tr>
  <td><tt>a.capitalize!</tt></td>
  <td>&#187;</td>
  <td><tt>nil</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="center" ref="center">
      <callseq>
        <obj>str</obj>.center( <obj>anInteger</obj> )
        <returns><obj>aString</obj></returns>
      </callseq>
      <desc>
<p/>
      If <obj>anInteger</obj> is greater than the length of <obj>str</obj>, returns a
      new <classname>String</classname> of length <obj>anInteger</obj> with <obj>str</obj> centered
      between spaces; otherwise,
      returns <obj>str</obj>.
<p/>
<codefragment>
<fullcode><![CDATA[        "hello".center(4)
        "hello".center(20)
]]></fullcode><rubycode>
<tr>
  <td><tt>"hello".center(4)</tt></td>
  <td>&#187;</td>
  <td><tt>"hello"</tt></td>
</tr>
<tr>
  <td><tt>"hello".center(20)</tt></td>
  <td>&#187;</td>
  <td><tt>"<visible_space/><visible_space/><visible_space/><visible_space/><visible_space/><visible_space/><visible_space/>hello<visible_space/><visible_space/><visible_space/><visible_space/><visible_space/><visible_space/><visible_space/><visible_space/>"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="chomp" ref="chomp">
      <callseq>
        <obj>str</obj>.chomp( <obj>aString</obj>=<var>$/</var> )
        <returns><obj>aString</obj></returns>
      </callseq>
      <desc>
              Returns a new <classname>String</classname> with the given record separator removed 
      from the end of <obj>str</obj> (if present).
<p/>
<codefragment>
<fullcode><![CDATA[        "hello".chomp
        "hello\n".chomp
        "hello \n there".chomp
        "hello".chomp("llo")
]]></fullcode><rubycode>
<tr>
  <td><tt>"hello".chomp</tt></td>
  <td>&#187;</td>
  <td><tt>"hello"</tt></td>
</tr>
<tr>
  <td><tt>"hello\n".chomp</tt></td>
  <td>&#187;</td>
  <td><tt>"hello"</tt></td>
</tr>
<tr>
  <td><tt>"hello<nbsp/>\n<nbsp/>there".chomp</tt></td>
  <td>&#187;</td>
  <td><tt>"hello<nbsp/>\n<nbsp/>there"</tt></td>
</tr>
<tr>
  <td><tt>"hello".chomp("llo")</tt></td>
  <td>&#187;</td>
  <td><tt>"he"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="chomp!" ref="chomp_oh">
      <callseq>
        <obj>str</obj>.chomp!( <obj>aString</obj>=<var>$/</var> )
        <returns><obj>str</obj> or <tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Modifies <obj>str</obj> in place as described for <cim><file>string</file><front>String</front><back>chomp</back><mref>chomp</mref></cim>,
      returning <obj>str</obj>, or <const>nil</const> if no modifications were made.
      </desc>
    </method>
<p/>
        <method name="chop" ref="chop">
      <callseq>
        <obj>str</obj>.chop
        <returns><obj>aString</obj></returns>
      </callseq>
      <desc>
<p/>
            Returns a new <classname>String</classname> with the last character removed. If the 
      string ends with <tt>\r\n</tt>, both characters are
      removed. Applying <meth>chop</meth> to an empty string returns an
      empty string. <cim><file>string</file><front>String</front><back>chomp</back><mref>chomp</mref></cim> is often a safer alternative,
      as it leaves the string unchanged  if it doesn't end in a record 
      separator.
<p/>
<codefragment>
<fullcode><![CDATA[        "string\r\n".chop
        "string\n\r".chop
        "string\n".chop
        "string".chop
        "x".chop.chop
]]></fullcode><rubycode>
<tr>
  <td><tt>"string\r\n".chop</tt></td>
  <td>&#187;</td>
  <td><tt>"string"</tt></td>
</tr>
<tr>
  <td><tt>"string\n\r".chop</tt></td>
  <td>&#187;</td>
  <td><tt>"string\n"</tt></td>
</tr>
<tr>
  <td><tt>"string\n".chop</tt></td>
  <td>&#187;</td>
  <td><tt>"string"</tt></td>
</tr>
<tr>
  <td><tt>"string".chop</tt></td>
  <td>&#187;</td>
  <td><tt>"strin"</tt></td>
</tr>
<tr>
  <td><tt>"x".chop.chop</tt></td>
  <td>&#187;</td>
  <td><tt>""</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="chop!" ref="chop_oh">
      <callseq>
        <obj>str</obj>.chop!
        <returns><obj>str</obj> or <tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Processes <obj>str</obj> as for <cim><file>string</file><front>String</front><back>chop</back><mref>chop</mref></cim>, returning <obj>str</obj>,
      or <tt>nil</tt> if <obj>str</obj> is the empty string.  See also
      <cim><file>string</file><front>String</front><back>chomp!</back><mref>chomp_oh</mref></cim>.
<p/>
      </desc>
    </method>
<p/>
        <method name="concat" ref="concat">
      <callseq>
                    <obj>str</obj>.concat( <obj>aFixnum</obj> ) <returns><obj>str</obj></returns><br/><obj>str</obj>.concat( <obj>anObject</obj> ) <returns><obj>str</obj></returns>
      </callseq>
      <desc>
<p/>
      Synonym for <cim><file>string</file><front>String</front><back>&lt;&lt;</back><mref>_lt_lt</mref></cim>. 
<p/>
      </desc>
    </method>
<p/>
        <method name="count" ref="count">
      <callseq>
        <obj>str</obj>.count( <optn><obj>aString</obj></optn> )
        <returns><obj>aFixnum</obj></returns>
      </callseq>
      <desc>
<p/>
            Each <obj>aString</obj> parameter defines a set of characters to
      count. The intersection of these sets defines the characters to count
      in <obj>str</obj>. Any <obj>aString</obj> that starts with a caret (^) is
      negated. The sequence c<sub>1</sub>--c<sub>2</sub> means all characters between
      c<sub>1</sub> and c<sub>2</sub>.
<p/>
<codefragment>
<fullcode><![CDATA[        a = "hello world"
        a.count "lo"
        a.count "lo", "o"
        a.count "hello", "^l"
        a.count "ej-m"
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>a<nbsp/>=<nbsp/>"hello<nbsp/>world"</tt></td>
</tr>
<tr>
  <td><tt>a.count<nbsp/>"lo"</tt></td>
  <td>&#187;</td>
  <td><tt>5</tt></td>
</tr>
<tr>
  <td><tt>a.count<nbsp/>"lo",<nbsp/>"o"</tt></td>
  <td>&#187;</td>
  <td><tt>2</tt></td>
</tr>
<tr>
  <td><tt>a.count<nbsp/>"hello",<nbsp/>"^l"</tt></td>
  <td>&#187;</td>
  <td><tt>4</tt></td>
</tr>
<tr>
  <td><tt>a.count<nbsp/>"ej-m"</tt></td>
  <td>&#187;</td>
  <td><tt>4</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="crypt" ref="crypt">
      <callseq>
        <obj>str</obj>.crypt( <obj>aString</obj> )
        <returns><obj>aString</obj></returns>
      </callseq>
      <desc>
<p/>
      Applies a one-way      
      cryptographic hash to <obj>str</obj> by invoking the standard library
      function <meth>crypt</meth>. The argument is the salt
      string, which should be two characters long, each character
      drawn from <tt>[a-zA-Z0-9./]</tt>.
<p/>
      </desc>
    </method>
<p/>
        <method name="delete" ref="delete">
      <callseq>
        <obj>str</obj>.delete( <optn><obj>aString</obj></optn> )
        <returns><obj>aString</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns a copy of <obj>str</obj> with all characters in the intersection of
      its arguments deleted. Uses the same rules for building the set
      of characters as <cim><file>string</file><front>String</front><back>count</back><mref>count</mref></cim>.
<p/>
<codefragment>
<fullcode><![CDATA[        "hello".delete "l","lo"
        "hello".delete "lo"
        "hello".delete "aeiou", "^e"
        "hello".delete "ej-m"
]]></fullcode><rubycode>
<tr>
  <td><tt>"hello".delete<nbsp/>"l","lo"</tt></td>
  <td>&#187;</td>
  <td><tt>"heo"</tt></td>
</tr>
<tr>
  <td><tt>"hello".delete<nbsp/>"lo"</tt></td>
  <td>&#187;</td>
  <td><tt>"he"</tt></td>
</tr>
<tr>
  <td><tt>"hello".delete<nbsp/>"aeiou",<nbsp/>"^e"</tt></td>
  <td>&#187;</td>
  <td><tt>"hell"</tt></td>
</tr>
<tr>
  <td><tt>"hello".delete<nbsp/>"ej-m"</tt></td>
  <td>&#187;</td>
  <td><tt>"ho"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="delete!" ref="delete_oh">
      <callseq>
        <obj>str</obj>.delete!( <optn><obj>aString</obj></optn> )
        <returns><obj>str</obj> or <tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Performs a <tt>delete</tt> operation in place, returning <obj>str</obj>, or 
      <const>nil</const> if <obj>str</obj> was not modified. </desc>
    </method>
<p/>
        <method name="downcase" ref="downcase">
      <callseq>
        <obj>str</obj>.downcase <returns><obj>aString</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns a copy of <obj>str</obj> with all uppercase letters replaced
      with their lowercase counterparts. The operation is locale
      insensitive---only characters ``A'' to ``Z'' are affected. 
<p/>
<codefragment>
<fullcode><![CDATA[         "hEllO".downcase
]]></fullcode><rubycode>
<tr>
  <td><tt>"hEllO".downcase</tt></td>
  <td>&#187;</td>
  <td><tt>"hello"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="downcase!" ref="downcase_oh">
      <callseq>
        <obj>str</obj>.downcase!
        <returns><obj>str</obj> or <tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Downcases the contents of <obj>str</obj>, returning <const>nil</const> if no
      changes were made.
      </desc>
    </method>
<p/>
        <method name="dump" ref="dump">
      <callseq>
        <obj>str</obj>.dump <returns><obj>aString</obj></returns>
      </callseq>
      <desc>
<p/>
      Produces a version of <obj>str</obj> with all nonprinting characters
      replaced by <tt>\nnn</tt> notation and all special characters
      escaped. 
<p/>
      </desc>
    </method>
<p/>
        <method name="each" ref="each">
      <callseq>
        <obj>str</obj>.each( <obj>aString</obj>=<var>$/</var> )
        <block>{| substr | <blockbody>block</blockbody> }</block>
 <returns><obj>str</obj></returns>
      </callseq>
      <desc>
<p/>
      Splits <obj>str</obj> using the supplied parameter as the record
      separator (<var>$/</var> by default), passing each substring in turn 
      to the supplied block. If a zero-length record separator is
      supplied, the string is split on <tt>\n</tt> characters, except
      that multiple successive newlines are appended together.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        print "Example one\n"
        "hello\nworld".each {|s| p s}
        print "Example two\n"
        "hello\nworld".each('l') {|s| p s}
        print "Example three\n"
        "hello\n\n\nworld".each('') {|s| p s}
]]></fullcode>
print<nbsp/>"Example<nbsp/>one\n"
"hello\nworld".each<nbsp/>{|s|<nbsp/>p<nbsp/>s}
print<nbsp/>"Example<nbsp/>two\n"
"hello\nworld".each('l')<nbsp/>{|s|<nbsp/>p<nbsp/>s}
print<nbsp/>"Example<nbsp/>three\n"
"hello\n\n\nworld".each('')<nbsp/>{|s|<nbsp/>p<nbsp/>s}
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
Example<nbsp/>one
"hello\n"
"world"
Example<nbsp/>two
"hel"
"l"
"o\nworl"
"d"
Example<nbsp/>three
"hello\n\n\n"
"world"
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="each_byte" ref="each_byte">
      <callseq>
        <obj>str</obj>.each_byte <block>{| aFixnum | <blockbody>block</blockbody> }</block>
<p/>
        <returns><obj>str</obj></returns>
      </callseq>
      <desc>
<p/>
      Passes each byte in <obj>str</obj> to the given block.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        "hello".each_byte {|c| print c, ' ' }
!-        print "\n"
]]></fullcode>
"hello".each_byte<nbsp/>{|c|<nbsp/>print<nbsp/>c,<nbsp/>'<nbsp/>'<nbsp/>}
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
104<nbsp/>101<nbsp/>108<nbsp/>108<nbsp/>111
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="each_line" ref="each_line">
      <callseq>
        <obj>str</obj>.each_line( <obj>aString</obj>=<var>$/</var> )
        <block>{| substr | <blockbody>block</blockbody> }</block>
 <returns><obj>str</obj></returns>
      </callseq>
      <desc>
<p/>
      Synonym for <cim><file>string</file><front>String</front><back>each</back><mref>each</mref></cim>.
<p/>
      </desc>
    </method>
<p/>
        <method name="empty?" ref="empty_qm">
      <callseq>
        <obj>str</obj>.empty? <returns><const>true</const> or <const>false</const></returns>
      </callseq>
      <desc>
<p/>
      Returns <const>true</const> if <obj>str</obj> has a length of zero.
<p/>
<codefragment>
<fullcode><![CDATA[        "hello".empty?
        "".empty?
]]></fullcode><rubycode>
<tr>
  <td><tt>"hello".empty?</tt></td>
  <td>&#187;</td>
  <td><tt>false</tt></td>
</tr>
<tr>
  <td><tt>"".empty?</tt></td>
  <td>&#187;</td>
  <td><tt>true</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="gsub" ref="gsub">
      <callseq>
                    <obj>str</obj>.gsub( <obj>pattern</obj>, <obj>replacement</obj> )
          <returns><obj>aString</obj></returns><br/><obj>str</obj>.gsub( <obj>pattern</obj> ) <block>{| match | <blockbody>block</blockbody> }</block>
<p/>
          <returns><obj>aString</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns a copy of <obj>str</obj> with <em>all</em> occurrences of
      <obj>pattern</obj> replaced with either <obj>replacement</obj> or the
      value of the block. If a string is used as the replacement,
      special variables from the match (such as <var>$&amp;</var> and
      <var>$1</var>) cannot be substituted into it, as substitution into
      the string occurs before the pattern match starts. However, the
      sequences <tt>\1</tt>, <tt>\2</tt>, and so on may be used to
      interpolate successive groups in the match. These sequences are shown in
      Table 22.7 on page 371.
<p/>
      <figure type="table">
        <caption>Backslash sequences in substitution
          strings</caption>        
        <table>
<th>
  <td><b>Sequence</b></td>
  <td><b>Text That Is Substituted</b></td>
</th>
<tr>
  <td><tt>\1, \2, ... \9</tt></td>
  <td>The value matched by the
          <em>n</em>th grouped subexpression</td>
</tr>
<tr>
  <td><tt>\&amp;</tt></td>
  <td>The last match</td>
</tr>
<tr>
  <td><tt>\`</tt></td>
  <td>The part of the string before the match</td>
</tr>
<tr>
  <td><tt>\'</tt></td>
  <td>The part of the string after the match</td>
</tr>
<tr>
  <td><tt>\+</tt></td>
  <td>The highest-numbered group matched</td>
</tr>
<bottomrule/></table>
<p/>
      </figure>
<p/>
      In the block form, the current match is passed in as a
      parameter, and variables such as <var>$1</var>, <var>$2</var>,
      <var>$`</var>, <var>$&amp;</var>, and <var>$'</var> will be set
      appropriately. The value returned by the block will be
      substituted for the match on each call.
<p/>
      The result inherits any tainting in the original string or any
      supplied replacement string.
<p/>
<codefragment>
<fullcode><![CDATA[        "hello".gsub(/[aeiou]/, '*')
        "hello".gsub(/([aeiou])/, '<\1>')
        "hello".gsub('.') {|s| s[0].to_s + ' '}
]]></fullcode><rubycode>
<tr>
  <td><tt>"hello".gsub(/[aeiou]/,<nbsp/>'*')</tt></td>
  <td>&#187;</td>
  <td><tt>"h*ll*"</tt></td>
</tr>
<tr>
  <td><tt>"hello".gsub(/([aeiou])/,<nbsp/>'&lt;\1&gt;')</tt></td>
  <td>&#187;</td>
  <td><tt>"h&lt;e&gt;ll&lt;o&gt;"</tt></td>
</tr>
<tr>
  <td><tt>"hello".gsub('.')<nbsp/>{|s|<nbsp/>s[0].to_s<nbsp/>+<nbsp/>'<nbsp/>'}</tt></td>
  <td>&#187;</td>
  <td><tt>"104<nbsp/>101<nbsp/>108<nbsp/>108<nbsp/>111<nbsp/>"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="gsub!" ref="gsub_oh">
      <callseq>
                    <obj>str</obj>.gsub!( <obj>pattern</obj>, <obj>replacement</obj> )
          <returns><obj>str</obj> or <tt>nil</tt></returns><br/><obj>str</obj>.gsub!( <obj>pattern</obj> ) <block>{| match | <blockbody>block</blockbody> }</block>
<p/>
          <returns><obj>str</obj> or <tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Performs the substitutions of <cim><file>string</file><front>String</front><back>gsub</back><mref>gsub</mref></cim> in place,
      returning <obj>str</obj>, or <tt>nil</tt> if no substitutions were
      performed.
      </desc>
    </method>
<p/>
        <method name="hash" ref="hash">
      <callseq>
        <obj>str</obj>.hash <returns><obj>aFixnum</obj></returns>
      </callseq>
      <desc>
<p/>
      Generates a <classname>Fixnum</classname> hash value for <obj>str</obj>. If <var>$=</var> is
      <const>true</const>, the hash will be case insensitive.
<p/>
<codefragment>
<fullcode><![CDATA[        $= = true
        hash = { 'cat' => 'Feline', 'dog' => 'canine' }
        hash['cat']
        hash['cAt']
        $= = false
        hash.rehash     # re-calculate hash values
        hash['cat']
        hash['cAt']
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>$=<nbsp/>=<nbsp/>true</tt></td>
</tr>
<tr>
<td colspan="3"><tt>hash<nbsp/>=<nbsp/>{<nbsp/>'cat'<nbsp/>=&gt;<nbsp/>'Feline',<nbsp/>'dog'<nbsp/>=&gt;<nbsp/>'canine'<nbsp/>}</tt></td>
</tr>
<tr>
  <td><tt>hash['cat']</tt></td>
  <td>&#187;</td>
  <td><tt>"Feline"</tt></td>
</tr>
<tr>
  <td><tt>hash['cAt']</tt></td>
  <td>&#187;</td>
  <td><tt>"Feline"</tt></td>
</tr>
<tr>
<td colspan="3"><tt>$=<nbsp/>=<nbsp/>false</tt></td>
</tr>
<tr>
  <td><tt>hash.rehash<nbsp/><nbsp/><nbsp/><nbsp/><nbsp/>#<nbsp/>re-calculate<nbsp/>hash<nbsp/>values</tt></td>
  <td>&#187;</td>
  <td><tt>{"cat"=&gt;"Feline",<nbsp/>"dog"=&gt;"canine"}</tt></td>
</tr>
<tr>
  <td><tt>hash['cat']</tt></td>
  <td>&#187;</td>
  <td><tt>"Feline"</tt></td>
</tr>
<tr>
  <td><tt>hash['cAt']</tt></td>
  <td>&#187;</td>
  <td><tt>nil</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="hex" ref="hex">
      <callseq>
        <obj>str</obj>.hex <returns><obj>anInteger</obj></returns>
      </callseq>
      <desc>
<p/>
      Treats leading characters from <obj>str</obj> as a string of hexadecimal
      digits (with an optional sign and an optional <tt>0x</tt>) and
      returns the corresponding number. Zero is returned on error.
<p/>
<codefragment>
<fullcode><![CDATA[        "0x0a".hex
        "-1234".hex
        "0".hex
        "wombat".hex
]]></fullcode><rubycode>
<tr>
  <td><tt>"0x0a".hex</tt></td>
  <td>&#187;</td>
  <td><tt>10</tt></td>
</tr>
<tr>
  <td><tt>"-1234".hex</tt></td>
  <td>&#187;</td>
  <td><tt>-4660</tt></td>
</tr>
<tr>
  <td><tt>"0".hex</tt></td>
  <td>&#187;</td>
  <td><tt>0</tt></td>
</tr>
<tr>
  <td><tt>"wombat".hex</tt></td>
  <td>&#187;</td>
  <td><tt>0</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="include?" ref="include_qm">
      <callseq>
                    <obj>str</obj>.include? <obj>aString</obj> <returns><const>true</const> or <const>false</const></returns><br/><obj>str</obj>.include? <obj>aFixnum</obj> <returns><const>true</const> or <const>false</const></returns>
      </callseq>
      <desc>
<p/>
      Returns <const>true</const> if <obj>str</obj> contains the given string or character.
<p/>
<codefragment>
<fullcode><![CDATA[        "hello".include? "lo"
        "hello".include? "ol"
        "hello".include? ?h
]]></fullcode><rubycode>
<tr>
  <td><tt>"hello".include?<nbsp/>"lo"</tt></td>
  <td>&#187;</td>
  <td><tt>true</tt></td>
</tr>
<tr>
  <td><tt>"hello".include?<nbsp/>"ol"</tt></td>
  <td>&#187;</td>
  <td><tt>false</tt></td>
</tr>
<tr>
  <td><tt>"hello".include?<nbsp/>?h</tt></td>
  <td>&#187;</td>
  <td><tt>true</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="index" ref="index">
      <callseq>
                    <obj>str</obj>.index( <obj>aString</obj> <opt>, <obj>anOffset</obj></opt> )
            <returns><obj>aFixnum</obj> or <tt>nil</tt></returns><br/><obj>str</obj>.index( <obj>aFixnum</obj> <opt>, <obj>anOffset</obj></opt> )
            <returns><obj>aFixnum</obj> or <tt>nil</tt></returns><br/><obj>str</obj>.index( <obj>aRegexp</obj> <opt>, <obj>anOffset</obj></opt> )
            <returns><obj>aFixnum</obj> or <tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Returns the index of the first occurrence of the given substring,
      character, or pattern in <obj>str</obj>. Returns <const>nil</const> if not found.
      If the second parameter is present, it specifies the position in
      the string to begin the search.
<p/>
<codefragment>
<fullcode><![CDATA[        "hello".index('e')
        "hello".index('lo')
        "hello".index('a')
        "hello".index(101)
        "hello".index(/[aeiou]/, -3)
]]></fullcode><rubycode>
<tr>
  <td><tt>"hello".index('e')</tt></td>
  <td>&#187;</td>
  <td><tt>1</tt></td>
</tr>
<tr>
  <td><tt>"hello".index('lo')</tt></td>
  <td>&#187;</td>
  <td><tt>3</tt></td>
</tr>
<tr>
  <td><tt>"hello".index('a')</tt></td>
  <td>&#187;</td>
  <td><tt>nil</tt></td>
</tr>
<tr>
  <td><tt>"hello".index(101)</tt></td>
  <td>&#187;</td>
  <td><tt>1</tt></td>
</tr>
<tr>
  <td><tt>"hello".index(/[aeiou]/,<nbsp/>-3)</tt></td>
  <td>&#187;</td>
  <td><tt>4</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="intern" ref="intern">
      <callseq>
        <obj>str</obj>.intern <returns><obj>aSymbol</obj></returns>
      </callseq>
      <desc>
<p/>
            Returns the <classname>Symbol</classname> corresponding to <obj>str</obj>, creating the
      symbol if it did not previously exist. See <cim><file>symbol</file><front>Symbol</front><back>id2name</back><mref>id2name</mref></cim>
      on page 384. 
<p/>
<codefragment>
<fullcode><![CDATA[        "Koala".intern
]]></fullcode><rubycode>
<tr>
  <td><tt>"Koala".intern</tt></td>
  <td>&#187;</td>
  <td><tt>:Koala</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="length" ref="length">
      <callseq>
        <obj>str</obj>.length <returns><obj>anInteger</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the length of <obj>str</obj>.
<p/>
      </desc>
    </method>
<p/>
        <method name="ljust" ref="ljust">
      <callseq>
        <obj>str</obj>.ljust( <obj>anInteger</obj> )
        <returns><obj>aString</obj></returns>
      </callseq>
      <desc>
<p/>
      If <obj>anInteger</obj> is greater than the length of <obj>str</obj>, returns a
      new <classname>String</classname> of length <obj>anInteger</obj> with <obj>str</obj> left
      justified and space padded; otherwise, returns <obj>str</obj>.
<p/>
<codefragment>
<fullcode><![CDATA[        "hello".ljust(4)
        "hello".ljust(20)
]]></fullcode><rubycode>
<tr>
  <td><tt>"hello".ljust(4)</tt></td>
  <td>&#187;</td>
  <td><tt>"hello"</tt></td>
</tr>
<tr>
  <td><tt>"hello".ljust(20)</tt></td>
  <td>&#187;</td>
  <td><tt>"hello<visible_space/><visible_space/><visible_space/><visible_space/><visible_space/><visible_space/><visible_space/><visible_space/><visible_space/><visible_space/><visible_space/><visible_space/><visible_space/><visible_space/><visible_space/>"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="next" ref="next">
      <callseq>
        <obj>str</obj>.next
        <returns><obj>aString</obj></returns>
      </callseq>
      <desc>
<p/>
      Synonym for <cim><file>string</file><front>String</front><back>succ</back><mref>succ</mref></cim>.
<p/>
      </desc>
    </method>
<p/>
        <method name="next!" ref="next_oh">
      <callseq>
        <obj>str</obj>.next! <returns><obj>str</obj></returns>
      </callseq>
      <desc>
<p/>
      Synonym for <cim><file>string</file><front>String</front><back>succ!</back><mref>succ_oh</mref></cim>.
<p/>
      </desc>
    </method>
<p/>
        <method name="oct" ref="oct">
      <callseq>
        <obj>str</obj>.oct
        <returns><obj>anInteger</obj></returns>
      </callseq>
      <desc>
<p/>
      Treats leading characters of <obj>str</obj> as a string of octal digits (with an optional 
      sign) and returns the corresponding number.  Returns 0 if the
      conversion fails.
<p/>
<codefragment>
<fullcode><![CDATA[        "123".oct
        "-377".oct
        "bad".oct
        "0377bad".oct
]]></fullcode><rubycode>
<tr>
  <td><tt>"123".oct</tt></td>
  <td>&#187;</td>
  <td><tt>83</tt></td>
</tr>
<tr>
  <td><tt>"-377".oct</tt></td>
  <td>&#187;</td>
  <td><tt>-255</tt></td>
</tr>
<tr>
  <td><tt>"bad".oct</tt></td>
  <td>&#187;</td>
  <td><tt>0</tt></td>
</tr>
<tr>
  <td><tt>"0377bad".oct</tt></td>
  <td>&#187;</td>
  <td><tt>255</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="replace" ref="replace">
      <callseq>
        <obj>str</obj>.replace( <obj>aString</obj> )
        <returns><obj>str</obj></returns>
      </callseq>
      <desc>
<p/>
      Replaces the contents and taintedness of <obj>str</obj> with the
      corresponding values in <obj>aString</obj>.
<p/>
<codefragment>
<fullcode><![CDATA[         s = "hello"
         s.replace "world"
]]></fullcode><rubycode>
<tr>
  <td><tt>s<nbsp/>=<nbsp/>"hello"</tt></td>
  <td>&#187;</td>
  <td><tt>"hello"</tt></td>
</tr>
<tr>
  <td><tt>s.replace<nbsp/>"world"</tt></td>
  <td>&#187;</td>
  <td><tt>"world"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="reverse" ref="reverse">
      <callseq>
        <obj>str</obj>.reverse
        <returns><obj>aString</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns a new string  with the characters from <obj>str</obj> in
      reverse order.
<p/>
<codefragment>
<fullcode><![CDATA[        "stressed".reverse
]]></fullcode><rubycode>
<tr>
  <td><tt>"stressed".reverse</tt></td>
  <td>&#187;</td>
  <td><tt>"desserts"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="reverse!" ref="reverse_oh">
      <callseq>
        <obj>str</obj>.reverse! <returns><obj>str</obj></returns>
      </callseq>
      <desc>
<p/>
      Reverses <obj>str</obj> in place.
      </desc>
    </method>
<p/>
        <method name="rindex" ref="rindex">
      <callseq>
                    <obj>str</obj>.rindex( <obj>aString</obj> <opt>, <obj>aFixnum</obj></opt> )
            <returns><obj>aFixnum</obj> or <tt>nil</tt></returns><br/><obj>str</obj>.rindex( <obj>aFixnum</obj> <opt>, <obj>aFixnum</obj></opt> )
            <returns><obj>aFixnum</obj> or <tt>nil</tt></returns><br/><obj>str</obj>.rindex( <obj>aRegexp</obj> <opt>, <obj>aFixnum</obj></opt> )
            <returns><obj>aFixnum</obj> or <tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Returns the index of the last occurrence of the given substring,
      character, or pattern in <obj>str</obj>. Returns <const>nil</const> if not found.
      If the second parameter is present, it specifies the position in
      the string to end the search---characters beyond this point will 
      not be considered.
<p/>
<codefragment>
<fullcode><![CDATA[        "hello".rindex('e')
        "hello".rindex('l')
        "hello".rindex('a')
        "hello".rindex(101)
        "hello".rindex(/[aeiou]/, -2)
]]></fullcode><rubycode>
<tr>
  <td><tt>"hello".rindex('e')</tt></td>
  <td>&#187;</td>
  <td><tt>1</tt></td>
</tr>
<tr>
  <td><tt>"hello".rindex('l')</tt></td>
  <td>&#187;</td>
  <td><tt>3</tt></td>
</tr>
<tr>
  <td><tt>"hello".rindex('a')</tt></td>
  <td>&#187;</td>
  <td><tt>nil</tt></td>
</tr>
<tr>
  <td><tt>"hello".rindex(101)</tt></td>
  <td>&#187;</td>
  <td><tt>1</tt></td>
</tr>
<tr>
  <td><tt>"hello".rindex(/[aeiou]/,<nbsp/>-2)</tt></td>
  <td>&#187;</td>
  <td><tt>1</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="rjust" ref="rjust">
      <callseq>
        <obj>str</obj>.rjust( <obj>anInteger</obj> )
        <returns><obj>aString</obj></returns>
      </callseq>
      <desc>
<p/>
      If <obj>anInteger</obj> is greater than the length of <obj>str</obj>,
      returns a new <classname>String</classname> of length
      <obj>anInteger</obj> with <obj>str</obj> right justified and space padded;
      otherwise, returns <obj>str</obj>.
<p/>
<codefragment>
<fullcode><![CDATA[        "hello".rjust(4)
        "hello".rjust(20)
]]></fullcode><rubycode>
<tr>
  <td><tt>"hello".rjust(4)</tt></td>
  <td>&#187;</td>
  <td><tt>"hello"</tt></td>
</tr>
<tr>
  <td><tt>"hello".rjust(20)</tt></td>
  <td>&#187;</td>
  <td><tt>"<visible_space/><visible_space/><visible_space/><visible_space/><visible_space/><visible_space/><visible_space/><visible_space/><visible_space/><visible_space/><visible_space/><visible_space/><visible_space/><visible_space/><visible_space/>hello"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="scan" ref="scan">
      <callseq>
                    <obj>str</obj>.scan( <obj>pattern</obj> ) <returns><obj>anArray</obj></returns><br/><obj>str</obj>.scan( <obj>pattern</obj> ) <block>{| match, ...| <blockbody>block</blockbody> }</block>
 <returns><obj>str</obj></returns>
      </callseq>
      <desc>
<p/>
            Both forms iterate through <obj>str</obj>, matching the pattern (which
      may be a <classname>Regexp</classname> or a <classname>String</classname>). For each match, a result
      is generated and either added 
      to the result array or passed to the block. If the pattern
      contains no groups, each individual result consists of the matched
      string, <tt>$&amp;</tt>. If the pattern contains groups, each
      individual result is itself an array containing one entry per group.
<p/>
<codefragment>
<fullcode><![CDATA[        a = "cruel world"
        a.scan(/\w+/)
        a.scan(/.../)
        a.scan(/(...)/)
        a.scan(/(..)(..)/)
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>a<nbsp/>=<nbsp/>"cruel<nbsp/>world"</tt></td>
</tr>
<tr>
  <td><tt>a.scan(/\w+/)</tt></td>
  <td>&#187;</td>
  <td><tt>["cruel",<nbsp/>"world"]</tt></td>
</tr>
<tr>
  <td><tt>a.scan(/.../)</tt></td>
  <td>&#187;</td>
  <td><tt>["cru",<nbsp/>"el<nbsp/>",<nbsp/>"wor"]</tt></td>
</tr>
<tr>
  <td><tt>a.scan(/(...)/)</tt></td>
  <td>&#187;</td>
  <td><tt>[["cru"],<nbsp/>["el<nbsp/>"],<nbsp/>["wor"]]</tt></td>
</tr>
<tr>
  <td><tt>a.scan(/(..)(..)/)</tt></td>
  <td>&#187;</td>
  <td><tt>[["cr",<nbsp/>"ue"],<nbsp/>["l<nbsp/>",<nbsp/>"wo"]]</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      And the block form:
<p/>
<codefragment>
<alltt><fullcode><![CDATA[!-        a = "cruel world"
        a.scan(/\w+/) {|w| print "<<#{w}>> " }
        print "\n"
        a.scan(/(.)(.)/) {|a,b| print b, a }
        print "\n"
]]></fullcode>
a.scan(/\w+/)<nbsp/>{|w|<nbsp/>print<nbsp/>"&lt;&lt;#{w}&gt;&gt;<nbsp/>"<nbsp/>}
print<nbsp/>"\n"
a.scan(/(.)(.)/)<nbsp/>{|a,b|<nbsp/>print<nbsp/>b,<nbsp/>a<nbsp/>}
print<nbsp/>"\n"
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
&lt;&lt;cruel&gt;&gt;<nbsp/>&lt;&lt;world&gt;&gt;
rceu<nbsp/>lowlr
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="size" ref="size">
      <callseq>
        <obj>str</obj>.size <returns><obj>anInteger</obj></returns>
      </callseq>
      <desc>
<p/>
      Synonym for <cim><file>string</file><front>String</front><back>length</back><mref>length</mref></cim>.
<p/>
      </desc>
    </method>
<p/>
        <method name="slice" ref="slice">
      <callseq>
                  <obj>str</obj>.slice( <obj>aFixnum</obj> ) <returns><obj>aFixnum</obj> or <tt>nil</tt></returns><br/><obj>str</obj>.slice( <obj>aFixnum</obj>, <obj>aFixnum</obj> )
                                        <returns><obj>aString</obj> or <tt>nil</tt></returns><br/><obj>str</obj>.slice( <obj>aRange</obj> ) <returns><obj>aString</obj> or <tt>nil</tt></returns><br/><obj>str</obj>.slice( <obj>aRegexp</obj> ) <returns><obj>aString</obj> or <tt>nil</tt></returns><br/><obj>str</obj>.slice( <obj>aString</obj> ) <returns><obj>aString</obj> or <tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Synonym for <cim><file>string</file><front>String</front><back>[ ]</back><mref>_ob_cb</mref></cim>.
<p/>
<codefragment>
<fullcode><![CDATA[        a = "hello there"
        a.slice(1)
        a.slice(1,3)
        a.slice(1..3)
        a.slice(-3,2)
        a.slice(-4..-2)
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>a<nbsp/>=<nbsp/>"hello<nbsp/>there"</tt></td>
</tr>
<tr>
  <td><tt>a.slice(1)</tt></td>
  <td>&#187;</td>
  <td><tt>101</tt></td>
</tr>
<tr>
  <td><tt>a.slice(1,3)</tt></td>
  <td>&#187;</td>
  <td><tt>"ell"</tt></td>
</tr>
<tr>
  <td><tt>a.slice(1..3)</tt></td>
  <td>&#187;</td>
  <td><tt>"ell"</tt></td>
</tr>
<tr>
  <td><tt>a.slice(-3,2)</tt></td>
  <td>&#187;</td>
  <td><tt>"er"</tt></td>
</tr>
<tr>
  <td><tt>a.slice(-4..-2)</tt></td>
  <td>&#187;</td>
  <td><tt>"her"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
<codefragment>
<fullcode><![CDATA[!-      a = "hello there"        
        a.slice(-2..-4)
        a.slice(/th[aeiou]/)
        a.slice("lo")
        a.slice("bye")
]]></fullcode><rubycode>
<tr>
  <td><tt>a.slice(-2..-4)</tt></td>
  <td>&#187;</td>
  <td><tt>nil</tt></td>
</tr>
<tr>
  <td><tt>a.slice(/th[aeiou]/)</tt></td>
  <td>&#187;</td>
  <td><tt>"the"</tt></td>
</tr>
<tr>
  <td><tt>a.slice("lo")</tt></td>
  <td>&#187;</td>
  <td><tt>"lo"</tt></td>
</tr>
<tr>
  <td><tt>a.slice("bye")</tt></td>
  <td>&#187;</td>
  <td><tt>nil</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="slice!" ref="slice_oh">
      <callseq>
                  <obj>str</obj>.slice!( <obj>aFixnum</obj> ) <returns><obj>aFixnum</obj> or <tt>nil</tt></returns><br/><obj>str</obj>.slice!( <obj>aFixnum</obj>, <obj>aFixnum</obj> )
                                        <returns><obj>aString</obj> or <tt>nil</tt></returns><br/><obj>str</obj>.slice!( <obj>aRange</obj> ) <returns><obj>aString</obj> or <tt>nil</tt></returns><br/><obj>str</obj>.slice!( <obj>aRegexp</obj> ) <returns><obj>aString</obj> or <tt>nil</tt></returns><br/><obj>str</obj>.slice!( <obj>aString</obj> ) <returns><obj>aString</obj> or <tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Deletes the specified portion from <obj>str</obj>, and returns the portion
      deleted.         The forms that take a <classname>Fixnum</classname> will raise an
        <exception>IndexError</exception> if the value is out of range; the <classname>Range</classname>
        form will raise a <exception>RangeError</exception>, and the <classname>Regexp</classname> and
        <classname>String</classname> forms will silently ignore the assignment.<codefragment>
<fullcode><![CDATA[        string = "this is a string"
        string.slice!(2)
        string.slice!(3..6)
        string.slice!(/s.*t/)
        string.slice!("r")
        string
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>string<nbsp/>=<nbsp/>"this<nbsp/>is<nbsp/>a<nbsp/>string"</tt></td>
</tr>
<tr>
  <td><tt>string.slice!(2)</tt></td>
  <td>&#187;</td>
  <td><tt>105</tt></td>
</tr>
<tr>
  <td><tt>string.slice!(3..6)</tt></td>
  <td>&#187;</td>
  <td><tt>"<nbsp/>is<nbsp/>"</tt></td>
</tr>
<tr>
  <td><tt>string.slice!(/s.*t/)</tt></td>
  <td>&#187;</td>
  <td><tt>"sa<nbsp/>st"</tt></td>
</tr>
<tr>
  <td><tt>string.slice!("r")</tt></td>
  <td>&#187;</td>
  <td><tt>"r"</tt></td>
</tr>
<tr>
  <td><tt>string</tt></td>
  <td>&#187;</td>
  <td><tt>"thing"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="split" ref="split">
      <callseq>
        <obj>str</obj>.split( <obj>pattern</obj>=<var>$;</var>,
          <opt><obj>limit</obj></opt> ) <returns><obj>anArray</obj></returns>
      </callseq>
      <desc>
<p/>
            Divides <obj>str</obj> into substrings based on a delimiter, returning
      an array of these substrings.
<p/>
      If <obj>pattern</obj> is a <classname>String</classname>, then its contents are used as 
      the delimiter when splitting <obj>str</obj>. If <obj>pattern</obj> is a
      single space, <obj>str</obj> is split on whitespace, with leading
      whitespace and runs of contiguous whitespace characters ignored.
<p/>
      If <obj>pattern</obj> is a <classname>Regexp</classname>, <obj>str</obj> is divided where the
      pattern matches. Whenever the pattern matches a zero-length string,
      <obj>str</obj> is split into individual characters.
<p/>
      If <obj>pattern</obj> is omitted, the value of <var>$;</var> is
      used. If <var>$;</var> is <const>nil</const> (which is the default),
      <obj>str</obj> is split on whitespace as if `<visible_space/>' were specified.
<p/>
      If the <obj>limit</obj> parameter is omitted, trailing null fields are
      supressed. If <obj>limit</obj> is a positive number, at most that
      number of fields will be returned (if <obj>limit</obj> is <tt>1</tt>,
      the entire string is returned as the only entry in an array). If
      negative, there is no limit to the number of fields returned,
      and trailing null fields are not supressed.
<p/>
<codefragment>
<fullcode><![CDATA[        " now's  the time".split
        " now's  the time".split(' ') 
        " now's  the time".split(/ /) 
        "1, 2.34,56, 7".split(/,\s*/)
        "hello".split(//)
        "hello".split(//, 3)
        "hi mom".split(/\s*/)
]]></fullcode><rubycode>
<tr>
  <td><tt>"<nbsp/>now's<nbsp/><nbsp/>the<nbsp/>time".split</tt></td>
  <td>&#187;</td>
  <td><tt>["now's",<nbsp/>"the",<nbsp/>"time"]</tt></td>
</tr>
<tr>
  <td><tt>"<nbsp/>now's<nbsp/><nbsp/>the<nbsp/>time".split('<nbsp/>')</tt></td>
  <td>&#187;</td>
  <td><tt>["now's",<nbsp/>"the",<nbsp/>"time"]</tt></td>
</tr>
<tr>
  <td><tt>"<nbsp/>now's<nbsp/><nbsp/>the<nbsp/>time".split(/<nbsp/>/)</tt></td>
  <td>&#187;</td>
  <td><tt>["",<nbsp/>"now's",<nbsp/>"",<nbsp/>"the",<nbsp/>"time"]</tt></td>
</tr>
<tr>
  <td><tt>"1,<nbsp/>2.34,56,<nbsp/>7".split(/,\s*/)</tt></td>
  <td>&#187;</td>
  <td><tt>["1",<nbsp/>"2.34",<nbsp/>"56",<nbsp/>"7"]</tt></td>
</tr>
<tr>
  <td><tt>"hello".split(//)</tt></td>
  <td>&#187;</td>
  <td><tt>["h",<nbsp/>"e",<nbsp/>"l",<nbsp/>"l",<nbsp/>"o"]</tt></td>
</tr>
<tr>
  <td><tt>"hello".split(//,<nbsp/>3)</tt></td>
  <td>&#187;</td>
  <td><tt>["h",<nbsp/>"e",<nbsp/>"llo"]</tt></td>
</tr>
<tr>
  <td><tt>"hi<nbsp/>mom".split(/\s*/)</tt></td>
  <td>&#187;</td>
  <td><tt>["h",<nbsp/>"i",<nbsp/>"m",<nbsp/>"o",<nbsp/>"m"]</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
<codefragment>
<fullcode><![CDATA[        "mellow yellow".split("ello")
        "1,2,,3,4,,".split(',')
        "1,2,,3,4,,".split(',', 4)
        "1,2,,3,4,,".split(',', -4)
]]></fullcode><rubycode>
<tr>
  <td><tt>"mellow<nbsp/>yellow".split("ello")</tt></td>
  <td>&#187;</td>
  <td><tt>["m",<nbsp/>"w<nbsp/>y",<nbsp/>"w"]</tt></td>
</tr>
<tr>
  <td><tt>"1,2,,3,4,,".split(',')</tt></td>
  <td>&#187;</td>
  <td><tt>["1",<nbsp/>"2",<nbsp/>"",<nbsp/>"3",<nbsp/>"4"]</tt></td>
</tr>
<tr>
  <td><tt>"1,2,,3,4,,".split(',',<nbsp/>4)</tt></td>
  <td>&#187;</td>
  <td><tt>["1",<nbsp/>"2",<nbsp/>"",<nbsp/>"3,4,,"]</tt></td>
</tr>
<tr>
  <td><tt>"1,2,,3,4,,".split(',',<nbsp/>-4)</tt></td>
  <td>&#187;</td>
  <td><tt>["1",<nbsp/>"2",<nbsp/>"",<nbsp/>"3",<nbsp/>"4",<nbsp/>"",<nbsp/>""]</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="squeeze" ref="squeeze">
      <callseq>
        <obj>str</obj>.squeeze( <optz><obj>aString</obj></optz> )
        <returns><obj>aNewString</obj></returns>
      </callseq>
      <desc>
<p/>
      Builds a set of characters from the <obj>aString</obj> parameter(s)
      using the procedure described for <cim><file>string</file><front>String</front><back>count</back><mref>count</mref></cim>
      on page 368. Returns a new string where runs of
      the same character that occur in this set are replaced
      by a single character. If no arguments are given,
      all runs of identical characters are replaced by a single
      character.
<p/>
<codefragment>
<fullcode><![CDATA[         "yellow moon".squeeze
         "  now   is  the".squeeze(" ")
         "putters shoot balls".squeeze("m-z")
]]></fullcode><rubycode>
<tr>
  <td><tt>"yellow<nbsp/>moon".squeeze</tt></td>
  <td>&#187;</td>
  <td><tt>"yelow<nbsp/>mon"</tt></td>
</tr>
<tr>
  <td><tt>"<nbsp/><nbsp/>now<nbsp/><nbsp/><nbsp/>is<nbsp/><nbsp/>the".squeeze("<nbsp/>")</tt></td>
  <td>&#187;</td>
  <td><tt>"<nbsp/>now<nbsp/>is<nbsp/>the"</tt></td>
</tr>
<tr>
  <td><tt>"putters<nbsp/>shoot<nbsp/>balls".squeeze("m-z")</tt></td>
  <td>&#187;</td>
  <td><tt>"puters<nbsp/>shot<nbsp/>balls"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="squeeze!" ref="squeeze_oh">
      <callseq>
        <obj>str</obj>.squeeze!( <optz><obj>aString</obj></optz> )
        <returns><obj>str</obj> or <tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Squeezes <obj>str</obj> in place, returning either <obj>str</obj>, or
      <const>nil</const> if no changes were made.
      </desc>
    </method>
<p/>
        <method name="strip" ref="strip">
      <callseq>
        <obj>str</obj>.strip <returns><obj>aString</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns a copy of <obj>str</obj> with leading and trailing whitespace removed.
<p/>
<codefragment>
<fullcode><![CDATA[         "    hello    ".strip
         "\tgoodbye\r\n".strip
]]></fullcode><rubycode>
<tr>
  <td><tt>"<nbsp/><nbsp/><nbsp/><nbsp/>hello<nbsp/><nbsp/><nbsp/><nbsp/>".strip</tt></td>
  <td>&#187;</td>
  <td><tt>"hello"</tt></td>
</tr>
<tr>
  <td><tt>"\tgoodbye\r\n".strip</tt></td>
  <td>&#187;</td>
  <td><tt>"goodbye"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="strip!" ref="strip_oh">
      <callseq>
        <obj>str</obj>.strip! <returns><obj>str</obj> or <tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Removes leading and trailing whitespace from <obj>str</obj>. Returns
      <const>nil</const> if <obj>str</obj> was not altered.
      </desc>
    </method>
<p/>
        <method name="sub" ref="sub">
      <callseq>
                    <obj>str</obj>.sub( <obj>pattern</obj>, <obj>replacement</obj> )
          <returns><obj>aString</obj></returns><br/><obj>str</obj>.sub( <obj>pattern</obj> ) <block>{| match | <blockbody>block</blockbody> }</block>
 <returns><obj>aString</obj></returns>
      </callseq>
      <desc>
<p/>
        Returns a copy of <obj>str</obj> with the <em>first</em> occurrence of
        <obj>pattern</obj> replaced with either <obj>replacement</obj> or the
        value of the block. If the string form of the method is used,
        special variables such as <var>$&amp;</var> will not be useful, as
        substitution into the string occurs before the pattern match
        starts. However, the sequences <tt>\1</tt>, <tt>\2</tt>,
        listed in Table 22.7 on page 371 may be used.
<p/>
        In the block form, the current match is passed in as a
        parameter, and variables such as <var>$1</var>,
        <var>$2</var>, <var>$`</var>,         <var>$&amp;</var>, and <var>$'</var>        will be set appropriately. The value returned by the block
        will be substituted for the match on each call.
<p/>
<codefragment>
<fullcode><![CDATA[        "hello".sub(/[aeiou]/, '*')
        "hello".sub(/([aeiou])/, '<\1>')
        "hello".sub('.') {|s| s[0].to_s + ' ' }
]]></fullcode><rubycode>
<tr>
  <td><tt>"hello".sub(/[aeiou]/,<nbsp/>'*')</tt></td>
  <td>&#187;</td>
  <td><tt>"h*llo"</tt></td>
</tr>
<tr>
  <td><tt>"hello".sub(/([aeiou])/,<nbsp/>'&lt;\1&gt;')</tt></td>
  <td>&#187;</td>
  <td><tt>"h&lt;e&gt;llo"</tt></td>
</tr>
<tr>
  <td><tt>"hello".sub('.')<nbsp/>{|s|<nbsp/>s[0].to_s<nbsp/>+<nbsp/>'<nbsp/>'<nbsp/>}</tt></td>
  <td>&#187;</td>
  <td><tt>"104<nbsp/>ello"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="sub!" ref="sub_oh">
      <callseq>
                    <obj>str</obj>.sub!( <obj>pattern</obj>, <obj>replacement</obj> )
          <returns><obj>str</obj> or <tt>nil</tt></returns><br/><obj>str</obj>.sub!( <obj>pattern</obj> ) <block>{| match | <blockbody>block</blockbody> }</block>
<p/>
          <returns><obj>str</obj> or <tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Performs the substitutions of <cim><file>string</file><front>String</front><back>sub</back><mref>sub</mref></cim> in place,
      returning <obj>str</obj>, or <const>nil</const> if no substitutions were
      performed.
      </desc>
    </method>
<p/>
        <method name="succ" ref="succ">
      <callseq>
        <obj>str</obj>.succ
        <returns><obj>aString</obj></returns>
      </callseq>
      <desc>
              Returns the successor to <obj>str</obj>. The successor is calculated by
      incrementing characters starting from the rightmost 
      alphanumeric (or the rightmost character if there are no
      alphanumerics) in the string. Incrementing a digit always results
      in another digit, and incrementing a letter results in another
      letter of the same case. Incrementing nonalphanumerics uses the 
      underlying character set's collating sequence.
<p/>
      If the increment generates a ``carry,'' the character to the
      left of it is incremented. This process repeats until there is
      no carry, adding an additional character if necessary.
<p/>
<codefragment>
<fullcode><![CDATA[         "abcd".succ
         "THX1138".succ
         "<<koala>>".succ
         "1999zzz".succ
         "ZZZ9999".succ
         "***".succ
]]></fullcode><rubycode>
<tr>
  <td><tt>"abcd".succ</tt></td>
  <td>&#187;</td>
  <td><tt>"abce"</tt></td>
</tr>
<tr>
  <td><tt>"THX1138".succ</tt></td>
  <td>&#187;</td>
  <td><tt>"THX1139"</tt></td>
</tr>
<tr>
  <td><tt>"&lt;&lt;koala&gt;&gt;".succ</tt></td>
  <td>&#187;</td>
  <td><tt>"&lt;&lt;koalb&gt;&gt;"</tt></td>
</tr>
<tr>
  <td><tt>"1999zzz".succ</tt></td>
  <td>&#187;</td>
  <td><tt>"2000aaa"</tt></td>
</tr>
<tr>
  <td><tt>"ZZZ9999".succ</tt></td>
  <td>&#187;</td>
  <td><tt>"AAAA0000"</tt></td>
</tr>
<tr>
  <td><tt>"***".succ</tt></td>
  <td>&#187;</td>
  <td><tt>"**+"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="succ!" ref="succ_oh">
      <callseq>
        <obj>str</obj>.succ! <returns><obj>str</obj></returns>
      </callseq>
      <desc>
<p/>
      Equivalent to <cim><file>string</file><front>String</front><back>succ</back><mref>succ</mref></cim>, but modifies the receiver in place.
      </desc>
    </method>
<p/>
        <method name="sum" ref="sum">
      <callseq>
        <obj>str</obj>.sum( <obj>aFixnum</obj>=16 )
        <returns><obj>anInteger</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns a basic      
      <em>n</em>-bit checksum of the characters in
      <obj>str</obj>, where <em>n</em> is the optional parameter, defaulting to 16. The
      result is simply the sum of the binary value of each character
      in <obj>str</obj> modulo 2<sup>n</sup> - 1. This is not a particularly good checksum.
<p/>
      </desc>
    </method>
<p/>
        <method name="swapcase" ref="swapcase">
      <callseq>
        <obj>str</obj>.swapcase <returns><obj>aString</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns a copy of <obj>str</obj> with uppercase alphabetic characters 
      converted to lowercase and lowercase characters converted to uppercase.
<p/>
<codefragment>
<fullcode><![CDATA[        "Hello".swapcase
        "cYbEr_PuNk11".swapcase
]]></fullcode><rubycode>
<tr>
  <td><tt>"Hello".swapcase</tt></td>
  <td>&#187;</td>
  <td><tt>"hELLO"</tt></td>
</tr>
<tr>
  <td><tt>"cYbEr_PuNk11".swapcase</tt></td>
  <td>&#187;</td>
  <td><tt>"CyBeR_pUnK11"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="swapcase!" ref="swapcase_oh">
      <callseq>
        <obj>str</obj>.swapcase! <returns><obj>str</obj> or <tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Equivalent to <cim><file>string</file><front>String</front><back>swapcase</back><mref>swapcase</mref></cim>, but modifies the receiver in
      place, returning <obj>str</obj>, or <const>nil</const> if no changes were
      made. </desc>
    </method>
<p/>
        <method name="to_f" ref="to_f">
      <callseq>
        <obj>str</obj>.to_f <returns><obj>aFloat</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the result of interpreting leading characters in <obj>str</obj>
      as a floating point number. Extraneous characters past the end
      of a valid number are ignored. If there is not a valid number at 
      the start of <obj>str</obj>, <tt>0.0</tt> is returned. The method never
      raises an exception.
<p/>
<codefragment>
<fullcode><![CDATA[         "123.45e1".to_f
         "45.67 degrees".to_f
         "thx1138".to_f
]]></fullcode><rubycode>
<tr>
  <td><tt>"123.45e1".to_f</tt></td>
  <td>&#187;</td>
  <td><tt>1234.5</tt></td>
</tr>
<tr>
  <td><tt>"45.67<nbsp/>degrees".to_f</tt></td>
  <td>&#187;</td>
  <td><tt>45.67</tt></td>
</tr>
<tr>
  <td><tt>"thx1138".to_f</tt></td>
  <td>&#187;</td>
  <td><tt>0.0</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="to_i" ref="to_i">
      <callseq>
        <obj>str</obj>.to_i <returns><obj>anInteger</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the result of interpreting leading characters in <obj>str</obj>
      as a decimal integer. Extraneous characters past the end
      of a valid number are ignored. If there is not a valid number at 
      the start of <obj>str</obj>, <tt>0</tt> is returned. The method never
      raises an exception.
<p/>
<codefragment>
<fullcode><![CDATA[         "12345".to_i
         "99 red balloons".to_i
         "0x0a".to_i
         "hello".to_i
]]></fullcode><rubycode>
<tr>
  <td><tt>"12345".to_i</tt></td>
  <td>&#187;</td>
  <td><tt>12345</tt></td>
</tr>
<tr>
  <td><tt>"99<nbsp/>red<nbsp/>balloons".to_i</tt></td>
  <td>&#187;</td>
  <td><tt>99</tt></td>
</tr>
<tr>
  <td><tt>"0x0a".to_i</tt></td>
  <td>&#187;</td>
  <td><tt>0</tt></td>
</tr>
<tr>
  <td><tt>"hello".to_i</tt></td>
  <td>&#187;</td>
  <td><tt>0</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="to_s" ref="to_s">
      <callseq>
        <obj>str</obj>.to_s <returns><obj>str</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the receiver.
<p/>
      </desc>
    </method>
<p/>
        <method name="to_str" ref="to_str">
      <callseq>
        <obj>str</obj>.to_str <returns><obj>str</obj></returns>
      </callseq>
      <desc>
<p/>
      Synonym for <cim><file>string</file><front>String</front><back>to_s</back><mref>to_s</mref></cim>. <meth>to_str</meth> is
      used by methods such as <cim><file>string</file><front>String</front><back>concat</back><mref>concat</mref></cim> to convert their
      arguments to a string. Unlike <meth>to_s</meth>, which is supported 
      by almost all classes, <meth>to_str</meth> is normally implemented
      only by those classes that act like strings. Of the built-in
      classes, only <classname>Exception</classname>
      and <classname>String</classname> implement <meth>to_str</meth>.
<p/>
      </desc>
    </method>
<p/>
        <method name="tr" ref="tr">
      <callseq>
        <obj>str</obj>.tr( <obj>fromString</obj>, <obj>toString</obj> )
        <returns><obj>aString</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns a copy of <obj>str</obj> with the characters in
      <obj>fromString</obj> replaced by the corresponding characters in
      <obj>toString</obj>. If <obj>toString</obj> is shorter than
      <obj>fromString</obj>, it is padded with its last character. Both
      strings may use the c<sub>1</sub>--c<sub>2</sub> notation to denote ranges of
      characters, and <obj>fromString</obj> may start with a <tt>^</tt>,
      which denotes all characters except those listed.
<p/>
<codefragment>
<fullcode><![CDATA[        "hello".tr('aeiou', '*')
        "hello".tr('^aeiou', '*')
        "hello".tr('el', 'ip')
        "hello".tr('a-y', 'b-z')
]]></fullcode><rubycode>
<tr>
  <td><tt>"hello".tr('aeiou',<nbsp/>'*')</tt></td>
  <td>&#187;</td>
  <td><tt>"h*ll*"</tt></td>
</tr>
<tr>
  <td><tt>"hello".tr('^aeiou',<nbsp/>'*')</tt></td>
  <td>&#187;</td>
  <td><tt>"*e**o"</tt></td>
</tr>
<tr>
  <td><tt>"hello".tr('el',<nbsp/>'ip')</tt></td>
  <td>&#187;</td>
  <td><tt>"hippo"</tt></td>
</tr>
<tr>
  <td><tt>"hello".tr('a-y',<nbsp/>'b-z')</tt></td>
  <td>&#187;</td>
  <td><tt>"ifmmp"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="tr!" ref="tr_oh">
      <callseq>
        <obj>str</obj>.tr!( <obj>fromString</obj>, <obj>toString</obj> )
        <returns><obj>str</obj> or <tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Translates <obj>str</obj> in place, using the same rules as
      <cim><file>string</file><front>String</front><back>tr</back><mref>tr</mref></cim>. Returns <obj>str</obj>, or <const>nil</const> if no changes were 
      made.
      </desc>
    </method>
<p/>
        <method name="tr_s" ref="tr_s">
      <callseq>
        <obj>str</obj>.tr_s( <obj>fromString</obj>, <obj>toString</obj> )
        <returns><obj>aString</obj></returns>
      </callseq>
      <desc>
<p/>
      Processes a copy of <obj>str</obj> as described under <cim><file>string</file><front>String</front><back>tr</back><mref>tr</mref></cim>,
      then removes duplicate characters in regions that were affected
      by the translation.
<p/>
<codefragment>
<fullcode><![CDATA[        "hello".tr_s('l', 'r')
        "hello".tr_s('el', '*')
        "hello".tr_s('el', 'hx')
]]></fullcode><rubycode>
<tr>
  <td><tt>"hello".tr_s('l',<nbsp/>'r')</tt></td>
  <td>&#187;</td>
  <td><tt>"hero"</tt></td>
</tr>
<tr>
  <td><tt>"hello".tr_s('el',<nbsp/>'*')</tt></td>
  <td>&#187;</td>
  <td><tt>"h*o"</tt></td>
</tr>
<tr>
  <td><tt>"hello".tr_s('el',<nbsp/>'hx')</tt></td>
  <td>&#187;</td>
  <td><tt>"hhxo"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="tr_s!" ref="tr_s_oh">
      <callseq>
        <obj>str</obj>.tr_s!( <obj>fromString</obj>, <obj>toString</obj> )
        <returns><obj>str</obj> or <tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Performs <cim><file>string</file><front>String</front><back>tr_s</back><mref>tr_s</mref></cim> processing on <obj>str</obj> in place,
      returning <obj>str</obj>, or <const>nil</const> if no changes were made.
      </desc>
    </method>
<p/>
        <method name="unpack" ref="unpack">
      <callseq>
        <obj>str</obj>.unpack( <obj>format</obj> )
        <returns><obj>anArray</obj></returns>
      </callseq>
      <desc>
<p/>
            Decodes      
      <obj>str</obj> (which may contain binary data) according to the format
      string, returning an array of each value extracted.  The format
      string consists of a sequence of single-character directives,
      summarized in Table 22.8 on page 379.  Each directive may be
      followed by a number, indicating the number of times to repeat
      with this directive.  An asterisk (``<tt>*</tt>'') will use up all
      remaining elements.  The directives <tt>sSiIlL</tt> may each be followed
      by an underscore (``<tt>_</tt>'') to use the underlying platform's
      native size for the specified type; otherwise, it uses a
      platform-independent consistent size.  Spaces are ignored in the format
      string. See also <cim><file>array</file><front>Array</front><back>pack</back><mref>pack</mref></cim> on page 286.
      <figure type="table">
<p/>
        <caption>Directives for <cim><file>string</file><front>String</front><back>unpack</back><mref>unpack</mref></cim></caption>        <table>
<th>
  <td><b>Format</b></td>
  <td><b>Function</b></td>
  <td><b>Returns</b></td>
</th>
<tr>
  <td>A</td>
  <td>String with trailing nulls and spaces removed.</td>
  <td>String</td>
</tr>
<tr>
  <td>a</td>
  <td>String.</td>
  <td>String</td>
</tr>
<tr>
  <td>B</td>
  <td>Extract bits from each character (msb first).</td>
  <td>String</td>
</tr>
<tr>
  <td>b</td>
  <td>Extract bits from each character (lsb first).</td>
  <td>String</td>
</tr>
<tr>
  <td>C</td>
  <td>Extract a character as an unsigned integer.</td>
  <td>Fixnum</td>
</tr>
<tr>
  <td>c</td>
  <td>Extract a character as an integer.</td>
  <td>Fixnum</td>
</tr>
<tr>
  <td>d</td>
  <td>Treat <em>sizeof(double)</em> characters as a native
          double.</td>
  <td>Float</td>
</tr>
<tr>
  <td>E</td>
  <td>Treat <em>sizeof(double)</em> characters as a double in
          little-endian byte order.</td>
  <td>Float</td>
</tr>
<tr>
  <td>e</td>
  <td>Treat <em>sizeof(float)</em> characters as a float in
          little-endian byte order.</td>
  <td>Float</td>
</tr>
<tr>
  <td>f</td>
  <td>Treat <em>sizeof(float)</em> characters as a native float.</td>
  <td>Float</td>
</tr>
<tr>
  <td>G</td>
  <td>Treat <em>sizeof(double)</em> characters as a double in
          network byte order.</td>
  <td>Float</td>
</tr>
<tr>
  <td>g</td>
  <td>Treat <em>sizeof(float)</em> characters as a float in
          network byte order.</td>
  <td>Float</td>
</tr>
<tr>
  <td>H</td>
  <td>Extract hex nibbles from each character (most
          significant first).</td>
  <td>String</td>
</tr>
<tr>
  <td>h</td>
  <td>Extract hex nibbles from each character (least
          significant first).</td>
  <td>String</td>
</tr>
<tr>
  <td>I</td>
  <td>Treat <em>sizeof(int)</em><sup>1</sup> successive
          characters as an unsigned native integer.</td>
  <td>Integer</td>
</tr>
<tr>
  <td>i</td>
  <td>Treat <em>sizeof(int)</em><sup>1</sup> successive
          characters as a signed native integer.</td>
  <td>Integer</td>
</tr>
<tr>
  <td>L</td>
  <td>Treat four<sup>1</sup> successive
          characters as an unsigned native
          long integer.</td>
  <td>Integer</td>
</tr>
<tr>
  <td>l</td>
  <td>Treat four<sup>1</sup> successive
          characters as a signed native
          long integer.</td>
  <td>Integer</td>
</tr>
<tr>
  <td>M</td>
  <td>Extract a quoted-printable string.</td>
  <td>String</td>
</tr>
<tr>
  <td>m</td>
  <td>Extract a base64 encoded string.</td>
  <td>String</td>
</tr>
<tr>
  <td>N</td>
  <td>Treat four characters as an unsigned long in network
          byte order.</td>
  <td>Fixnum</td>
</tr>
<tr>
  <td>n</td>
  <td>Treat two characters as an unsigned short in network
          byte order.</td>
  <td>Fixnum</td>
</tr>
<tr>
  <td>P</td>
  <td>Treat <em>sizeof(char *)</em> characters as a pointer, and 
          return <em>len</em> characters from the referenced location.</td>
  <td>String</td>
</tr>
<tr>
  <td>p</td>
  <td>Treat <em>sizeof(char *)</em> characters as a pointer to a 
          null-terminated string.</td>
  <td>String</td>
</tr>
<tr>
  <td>S</td>
  <td>Treat two<sup>1</sup> successive characters as an unsigned
          short in
          native byte order.</td>
  <td>Fixnum</td>
</tr>
<tr>
  <td>s</td>
  <td>Treat two<sup>1</sup> successive
          characters as a signed short in
          native byte order.</td>
  <td>Fixnum</td>
</tr>
<tr>
  <td>U</td>
  <td>Extract UTF-8 characters as unsigned integers.</td>
  <td>Integer</td>
</tr>
<tr>
  <td>u</td>
  <td>Extract a UU-encoded string.</td>
  <td>String</td>
</tr>
<tr>
  <td>V</td>
  <td>Treat four characters as an unsigned long in little-endian
          byte order.</td>
  <td>Fixnum</td>
</tr>
<tr>
  <td>v</td>
  <td>Treat two characters as an unsigned short in little-endian
          byte order.</td>
  <td>Fixnum</td>
</tr>
<tr>
  <td>X</td>
  <td>Skip backward one character.</td>
  <td>---</td>
</tr>
<tr>
  <td>x</td>
  <td>Skip forward one character.</td>
  <td>---</td>
</tr>
<tr>
  <td>Z</td>
  <td>String with trailing nulls removed.</td>
  <td>String</td>
</tr>
<tr>
  <td>@</td>
  <td>Skip to the offset given by the length argument.</td>
  <td>---</td>
</tr>
<bottomrule/></table>
<p/>
        <sup>1</sup><nbsp/>May be modified by appending ``_'' to the directive.
<p/>
      </figure>
<p/>
<codefragment>
<fullcode><![CDATA[         "abc \0\0abc \0\0".unpack('A6Z6')
         "abc \0\0".unpack('a3a3')
         "aa".unpack('b8B8')
         "aaa".unpack('h2H2c')
         "\xfe\xff\xfe\xff".unpack('sS')
         "now=20is".unpack('M*')
         "whole".unpack('xax2aX2aX1aX2a')
]]></fullcode><rubycode>
<tr>
  <td><tt>"abc<nbsp/>\0\0abc<nbsp/>\0\0".unpack('A6Z6')</tt></td>
  <td>&#187;</td>
  <td><tt>["abc",<nbsp/>"abc<nbsp/>"]</tt></td>
</tr>
<tr>
  <td><tt>"abc<nbsp/>\0\0".unpack('a3a3')</tt></td>
  <td>&#187;</td>
  <td><tt>["abc",<nbsp/>"<nbsp/>\000\000"]</tt></td>
</tr>
<tr>
  <td><tt>"aa".unpack('b8B8')</tt></td>
  <td>&#187;</td>
  <td><tt>["10000110",<nbsp/>"01100001"]</tt></td>
</tr>
<tr>
  <td><tt>"aaa".unpack('h2H2c')</tt></td>
  <td>&#187;</td>
  <td><tt>["16",<nbsp/>"61",<nbsp/>97]</tt></td>
</tr>
<tr>
  <td><tt>"\xfe\xff\xfe\xff".unpack('sS')</tt></td>
  <td>&#187;</td>
  <td><tt>[-2,<nbsp/>65534]</tt></td>
</tr>
<tr>
  <td><tt>"now=20is".unpack('M*')</tt></td>
  <td>&#187;</td>
  <td><tt>["now<nbsp/>is"]</tt></td>
</tr>
<tr>
  <td><tt>"whole".unpack('xax2aX2aX1aX2a')</tt></td>
  <td>&#187;</td>
  <td><tt>["h",<nbsp/>"e",<nbsp/>"l",<nbsp/>"l",<nbsp/>"o"]</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="upcase" ref="upcase">
      <callseq>
        <obj>str</obj>.upcase <returns><obj>aString</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns a copy of <obj>str</obj> with all lowercase letters replaced
      with their uppercase counterparts. The operation is locale
      insensitive---only characters ``a'' to ``z'' are affected.
<p/>
<codefragment>
<fullcode><![CDATA[         "hEllO".upcase
]]></fullcode><rubycode>
<tr>
  <td><tt>"hEllO".upcase</tt></td>
  <td>&#187;</td>
  <td><tt>"HELLO"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="upcase!" ref="upcase_oh">
      <callseq>
        <obj>str</obj>.upcase! <returns><obj>str</obj> or <tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Upcases the contents of <obj>str</obj>, returning <const>nil</const> if no
      changes were made.
      </desc>
    </method>
<p/>
        <method name="upto" ref="upto">
      <callseq>
        <obj>str</obj>.upto( <obj>aString</obj> )
        <block>{| s | <blockbody>block</blockbody> }</block>
 <returns><obj>str</obj></returns>
      </callseq>
      <desc>
<p/>
      Iterates through successive values, starting at <obj>str</obj> and
      ending at <obj>aString</obj> inclusive, passing each value in turn to
      the block. The <cim><file>string</file><front>String</front><back>succ</back><mref>succ</mref></cim> method is used to generate each
      value.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        "a8".upto("b6") {|s| print s, ' ' }
!-        print "\n"
        for s in "a8".."b6"
          print s, ' '
        end
!-         print "\n"
]]></fullcode>
"a8".upto("b6")<nbsp/>{|s|<nbsp/>print<nbsp/>s,<nbsp/>'<nbsp/>'<nbsp/>}
for<nbsp/>s<nbsp/>in<nbsp/>"a8".."b6"
<nbsp/><nbsp/>print<nbsp/>s,<nbsp/>'<nbsp/>'
end
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
a8<nbsp/>a9<nbsp/>b0<nbsp/>b1<nbsp/>b2<nbsp/>b3<nbsp/>b4<nbsp/>b5<nbsp/>b6
a8<nbsp/>a9<nbsp/>b0<nbsp/>b1<nbsp/>b2<nbsp/>b3<nbsp/>b4<nbsp/>b5<nbsp/>b6
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
  </methods>
<p/>
</class>
</ppdoc>
