<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="Range" super="Object" type="class">    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>