<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="Range" super="Object" type="class" ref="xref-000001">    A <classname>Range</classname> represents an interval---a set of values with a start
  and an end. Ranges may be constructed using the
  <em>s</em><tt>..</tt><em>e</em> and <em>s</em><tt>...</tt><em>e</em> literals, or
  with <ccm><file>range</file><front>Range</front><back>new</back><mref>new</mref></ccm>. Ranges constructed using <tt>..</tt> run from the
  start to the end inclusively. Those created using <tt>...</tt> exclude the 
  end value.  When used as an iterator, ranges return each value in
  the sequence.
<p/>
<codefragment>
<fullcode><![CDATA[    (-1..-5).to_a
    (-5..-1).to_a
    ('a'..'e').to_a
    ('a'...'e').to_a
]]></fullcode><rubycode>
<tr>
  <td><tt>(-1..-5).to_a</tt></td>
  <td>&#187;</td>
  <td><tt>[]</tt></td>
</tr>
<tr>
  <td><tt>(-5..-1).to_a</tt></td>
  <td>&#187;</td>
  <td><tt>[-5,<nbsp/>-4,<nbsp/>-3,<nbsp/>-2,<nbsp/>-1]</tt></td>
</tr>
<tr>
  <td><tt>('a'..'e').to_a</tt></td>
  <td>&#187;</td>
  <td><tt>["a",<nbsp/>"b",<nbsp/>"c",<nbsp/>"d",<nbsp/>"e"]</tt></td>
</tr>
<tr>
  <td><tt>('a'...'e').to_a</tt></td>
  <td>&#187;</td>
  <td><tt>["a",<nbsp/>"b",<nbsp/>"c",<nbsp/>"d"]</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
  Ranges can be constructed using objects of any type, as long as the
  objects can be compared using their <tt>&lt;=&gt;</tt> operator and they
  support the <meth>succ</meth> method to return the next object in
  sequence.
<p/>
<codefragment>
<fullcode><![CDATA[    class Xs                # represent a string of 'x's
      include Comparable
      attr :length
      def initialize(n)
        @length = n
      end
      def succ
        Xs.new(@length + 1)
      end
      def <=>(other)
        raise TypeError unless other.kind_of? Xs
        @length <=> other.length
      end
      def inspect
        'x' * @length
      end
    end

    r = Xs.new(3)..Xs.new(6)
    r.to_a
    r.member?(Xs.new(5))
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>class<nbsp/>Xs<nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/>#<nbsp/>represent<nbsp/>a<nbsp/>string<nbsp/>of<nbsp/>'x's</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>include<nbsp/>Comparable</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>attr<nbsp/>:length</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>def<nbsp/>initialize(n)</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/><nbsp/><nbsp/>@length<nbsp/>=<nbsp/>n</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>end</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>def<nbsp/>succ</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/><nbsp/><nbsp/>Xs.new(@length<nbsp/>+<nbsp/>1)</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>end</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>def<nbsp/>&lt;=&gt;(other)</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/><nbsp/><nbsp/>raise<nbsp/>TypeError<nbsp/>unless<nbsp/>other.kind_of?<nbsp/>Xs</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/><nbsp/><nbsp/>@length<nbsp/>&lt;=&gt;<nbsp/>other.length</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>end</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>def<nbsp/>inspect</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/><nbsp/><nbsp/>'x'<nbsp/>*<nbsp/>@length</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>end</tt></td>
</tr>
<tr>
<td colspan="3"><tt>end</tt></td>
</tr>
<tr>
<td colspan="3"><tt></tt></td>
</tr>
<tr>
  <td><tt>r<nbsp/>=<nbsp/>Xs.new(3)..Xs.new(6)</tt></td>
  <td>&#187;</td>
  <td><tt>xxx..xxxxxx</tt></td>
</tr>
<tr>
  <td><tt>r.to_a</tt></td>
  <td>&#187;</td>
  <td><tt>[xxx,<nbsp/>xxxx,<nbsp/>xxxxx,<nbsp/>xxxxxx]</tt></td>
</tr>
<tr>
  <td><tt>r.member?(Xs.new(5))</tt></td>
  <td>&#187;</td>
  <td><tt>true</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
  <mixins>
    <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>
        Range.new( <obj>start</obj>,
        <obj>end</obj>, <obj>exclusive</obj><tt>=false</tt> )
        <returns><obj>aRange</obj></returns>
      </callseq>
      <desc>
<p/>
      Constructs a range using the given <obj>start</obj> and <obj>end</obj>. If the
      third parameter is omitted or is <const>false</const>, the range will
      include the end object; otherwise, it will be excluded.
<p/>
      </desc>
    </method>
<p/>
  </methods>
<p/>
  <methods type="instance">
<p/>
        <method name="===" ref="_eq_eq_eq">
      <callseq>
        <obj>rng</obj> === <obj>anObject</obj> <returns><const>true</const> or <const>false</const></returns>
      </callseq>
      <desc>
<p/>
      Returns <const>true</const> if <obj>anObject</obj> is an element of <obj>rng</obj>, 
      <const>false</const> otherwise. Conveniently, <tt>===</tt> is the comparison
      operator used by <kw>case</kw> statements.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        case 79
        when 1..50   then   print "low\n"
        when 51..75  then   print "medium\n"
        when 76..100 then   print "high\n"
        end
]]></fullcode>
case<nbsp/>79
when<nbsp/>1..50<nbsp/><nbsp/><nbsp/>then<nbsp/><nbsp/><nbsp/>print<nbsp/>"low\n"
when<nbsp/>51..75<nbsp/><nbsp/>then<nbsp/><nbsp/><nbsp/>print<nbsp/>"medium\n"
when<nbsp/>76..100<nbsp/>then<nbsp/><nbsp/><nbsp/>print<nbsp/>"high\n"
end
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
high
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="begin" ref="begin">
      <callseq>
        <obj>rng</obj>.begin <returns><obj>anObject</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the first object of <obj>rng</obj>.
<p/>
      </desc>
    </method>
<p/>
        <method name="each" ref="each">
      <callseq>
        <obj>rng</obj>.each <block>{| i | <blockbody>block</blockbody> }</block>
 <returns><obj>rng</obj></returns>
      </callseq>
      <desc>
<p/>
      Iterates over the elements <obj>rng</obj>, passing each in turn to the
      block.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        (10..15).each do |n|
           print n, ' '
        end
!-        print "\n"
]]></fullcode>
(10..15).each<nbsp/>do<nbsp/>|n|
<nbsp/><nbsp/><nbsp/>print<nbsp/>n,<nbsp/>'<nbsp/>'
end
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
10<nbsp/>11<nbsp/>12<nbsp/>13<nbsp/>14<nbsp/>15
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="end" ref="end">
      <callseq>
        <obj>rng</obj>.end <returns><obj>anObject</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the object that defines the end of <obj>rng</obj>. See also
      <cim><file>range</file><front>Range</front><back>length</back><mref>length</mref></cim>.
<p/>
<codefragment>
<fullcode><![CDATA[         (1..10).end
         (1...10).end
]]></fullcode><rubycode>
<tr>
  <td><tt>(1..10).end</tt></td>
  <td>&#187;</td>
  <td><tt>10</tt></td>
</tr>
<tr>
  <td><tt>(1...10).end</tt></td>
  <td>&#187;</td>
  <td><tt>10</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="exclude_end?" ref="exclude_end_qm">
      <callseq>
        <obj>rng</obj>.exclude_end?
        <returns><const>true</const> or <const>false</const></returns>
      </callseq>
      <desc>
<p/>
      Returns <const>true</const> if <obj>rng</obj> excludes its end value.
<p/>
      </desc>
    </method>
<p/>
        <method name="first" ref="first">
      <callseq>
        <obj>rng</obj>.first <returns><obj>anObject</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the first object in <obj>rng</obj>.
<p/>
      </desc>
    </method>
<p/>
        <method name="last" ref="last">
      <callseq>
        <obj>rng</obj>.last <returns><obj>anObject</obj></returns>
      </callseq>
      <desc>
<p/>
      Synonym for <cim><file>range</file><front>Range</front><back>end</back><mref>end</mref></cim>.
<p/>
      </desc>
    </method>
<p/>
        <method name="length" ref="length">
      <callseq>
        <obj>rng</obj>.length <returns><obj>anInteger</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the number of objects in <obj>rng</obj>.
<p/>
<codefragment>
<fullcode><![CDATA[        (1..10).length
        (1...10).length
]]></fullcode><rubycode>
<tr>
  <td><tt>(1..10).length</tt></td>
  <td>&#187;</td>
  <td><tt>10</tt></td>
</tr>
<tr>
  <td><tt>(1...10).length</tt></td>
  <td>&#187;</td>
  <td><tt>9</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="size" ref="size">
      <callseq>
        <obj>rng</obj>.size <returns><obj>anInteger</obj></returns>
      </callseq>
      <desc>
<p/>
      Synonym for <cim><file>range</file><front>Range</front><back>length</back><mref>length</mref></cim>.
<p/>
      </desc>
    </method>
<p/>
  </methods>
<p/>
</class>
</ppdoc>
