Michael Granger added RDoc for range.c

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@5273 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

1 files changed, 184 insertions, 0 deletions

diff --git a/range.c b/range.c
index a7f553be57..bd9286f096 100644
--- a/range.c
+++ b/range.c
@@ -66,6 +66,15 @@ rb_range_new(beg, end, exclude_end)
     return range;
 }
 
+/*
+ *  call-seq:
+ *     Range.new(start, end, exclusive=false)    => range
+ *  
+ *  Constructs a range using the given <i>start</i> and <i>end</i>. If the third
+ *  parameter is omitted or is <code>false</code>, the <i>range</i> will include
+ *  the end object; otherwise, it will be excluded.
+ */
+
 static VALUE
 range_initialize(argc, argv, range)
     int argc;
@@ -83,6 +92,14 @@ range_initialize(argc, argv, range)
     return Qnil;
 }
 
+
+/*
+ *  call-seq:
+ *     rng.exclude_end?    => true or false
+ *  
+ *  Returns <code>true</code> if <i>rng</i> excludes its end value.
+ */
+
 static VALUE
 range_exclude_end_p(range)
     VALUE range;
@@ -90,6 +107,21 @@ range_exclude_end_p(range)
     return EXCL(range) ? Qtrue : Qfalse;
 }
 
+
+/*
+ *  call-seq:
+ *     rng == obj    => true or false
+ *  
+ *  Returns <code>true</code> only if <i>obj</i> is a Range, has equivalent
+ *  beginning and end items (by comparing them with <code>==</code>), and has
+ *  the same #exclude_end? setting as <i>rng</t>.
+ *     
+ *    (0..2) == (0..2)            #=> true
+ *    (0..2) == Range.new(0,2)    #=> true
+ *    (0..2) == (0...2)           #=> false
+ *     
+ */
+
 static VALUE
 range_eq(range, obj)
     VALUE range, obj;
@@ -131,6 +163,20 @@ r_le(a, b)
 }
 
 
+/*
+ *  call-seq:
+ *     rng.eql?(obj)    => true or false
+ *  
+ *  Returns <code>true</code> only if <i>obj</i> is a Range, has equivalent
+ *  beginning and end items (by comparing them with #eql?), and has the same
+ *  #exclude_end? setting as <i>rng</i>.
+ *     
+ *    (0..2) == (0..2)            #=> true
+ *    (0..2) == Range.new(0,2)    #=> true
+ *    (0..2) == (0...2)           #=> false
+ *     
+ */
+
 static VALUE
 range_eql(range, obj)
     VALUE range, obj;
@@ -206,6 +252,34 @@ range_each_func(range, func, v, e, arg)
     }
 }
 
+/*
+ *  call-seq:
+ *     rng.step(n=1) {| obj | block }    => rng
+ *  
+ *  Iterates over <i>rng</i>, passing each <i>n</i>th element to the block. If
+ *  the range contains numbers or strings, natural ordering is used.  Otherwise
+ *  <code>step</code> invokes <code>succ</code> to iterate through range
+ *  elements. The following code uses class <code>Xs</code>, which is defined
+ *  in the class-level documentation.
+ *     
+ *     range = Xs.new(1)..Xs.new(10)
+ *     range.step(2) {|x| puts x}
+ *     range.step(3) {|x| puts x}
+ *     
+ *  <em>produces:</em>
+ *     
+ *      1 x
+ *      3 xxx
+ *      5 xxxxx
+ *      7 xxxxxxx
+ *      9 xxxxxxxxx
+ *      1 x
+ *      4 xxxx
+ *      7 xxxxxxx
+ *     10 xxxxxxxxxx
+ */
+
+
 static VALUE
 range_step(argc, argv, range)
     int argc;
@@ -282,6 +356,22 @@ each_i(v, arg)
     return rb_yield(v);
 }
 
+/*
+ *  call-seq:
+ *     rng.each {| i | block } => rng
+ *  
+ *  Iterates over the elements <i>rng</i>, passing each in turn to the
+ *  block.
+ *     
+ *     (10..15).each do |n|
+ *        print n, ' '
+ *     end
+ *     
+ *  <em>produces:</em>
+ *     
+ *     10 11 12 13 14 15
+ */
+
 static VALUE
 range_each(range)
     VALUE range;
@@ -318,6 +408,14 @@ range_each(range)
     return range;
 }
 
+/*
+ *  call-seq:
+ *     rng.first    => obj
+ *     rng.begin    => obj
+ *  
+ *  Returns the first object in <i>rng</i>.
+ */
+
 static VALUE
 range_first(range)
     VALUE range;
@@ -325,6 +423,19 @@ range_first(range)
     return rb_ivar_get(range, id_beg);
 }
 
+
+/*
+ *  call-seq:
+ *     rng.end    => obj
+ *     rng.last   => obj
+ *  
+ *  Returns the object that defines the end of <i>rng</i>.
+ *     
+ *     (1..10).end    #=> 10
+ *     (1...10).end   #=> 10
+ */
+
+
 static VALUE
 range_last(range)
     VALUE range;
@@ -435,6 +546,26 @@ range_member(range, val)
     return args[1];
 }
 
+/*
+ *  call-seq:
+ *     rng === obj    => true or false
+ *  
+ *  Returns <code>true</code> if <i>obj</i> is an element of
+ *  <i>rng</i>, <code>false</code> otherwise. Conveniently,
+ *  <code>===</code> is the comparison operator used by
+ *  <code>case</code> statements.
+ *     
+ *     case 79
+ *     when 1..50   then   print "low\n"
+ *     when 51..75  then   print "medium\n"
+ *     when 76..100 then   print "high\n"
+ *     end
+ *     
+ *  <em>produces:</em>
+ *     
+ *     high
+ */
+
 static VALUE
 range_include(range, val)
     VALUE range, val;
@@ -454,6 +585,59 @@ range_include(range, val)
     return Qfalse;
 }
 
+
+/*  A <code>Range</code> represents an interval---a set of values with a
+ *  start and an end. Ranges may be constructed using the
+ *  <em>s</em><code>..</code><em>e</em> and
+ *  <em>s</em><code>...</code><em>e</em> literals, or with
+ *  <code>Range::new</code>. Ranges constructed using <code>..</code>
+ *  run from the start to the end inclusively. Those created using
+ *  <code>...</code> exclude the end value. When used as an iterator,
+ *  ranges return each value in the sequence.
+ *     
+ *     (-1..-5).to_a      #=> []
+ *     (-5..-1).to_a      #=> [-5, -4, -3, -2, -1]
+ *     ('a'..'e').to_a    #=> ["a", "b", "c", "d", "e"]
+ *     ('a'...'e').to_a   #=> ["a", "b", "c", "d"]
+ *     
+ *  Ranges can be constructed using objects of any type, as long as the
+ *  objects can be compared using their <code><=></code> operator and
+ *  they support the <code>succ</code> method to return the next object
+ *  in sequence.
+ *     
+ *     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)
+ *         @length <=> other.length
+ *       end
+ *       def to_s
+ *         sprintf "%2d #{inspect}", @length
+ *       end
+ *       def inspect
+ *         'x' * @length
+ *       end
+ *     end
+ *     
+ *     r = Xs.new(3)..Xs.new(6)   #=> xxx..xxxxxx
+ *     r.to_a                     #=> [xxx, xxxx, xxxxx, xxxxxx]
+ *     r.member?(Xs.new(5))       #=> true
+ *     
+ *  In the previous code example, class <code>Xs</code> includes the
+ *  <code>Comparable</code> module. This is because
+ *  <code>Enumerable#member?</code> checks for equality using
+ *  <code>==</code>. Including <code>Comparable</code> ensures that the
+ *  <code>==</code> method is defined in terms of the <code><=></code>
+ *  method implemented in <code>Xs</code>.
+ *     
+ */
+
 void
 Init_Range()
 {