Index: range.c
===================================================================
--- range.c (revision 33809)
+++ range.c (working copy)
@@ -68,10 +68,10 @@
/*
* call-seq:
- * Range.new(start, end, exclusive=false) -> range
+ * Range.new(begin, end, exclude_end=false) -> rng
*
- * Constructs a range using the given start and end. If the third
- * parameter is omitted or is false, the range will include
+ * Constructs a range using the given +begin+ and +end+. If the +exclude_end+
+ * parameter is omitted or is false, the +rng+ will include
* the end object; otherwise, it will be excluded.
*/
@@ -95,7 +95,10 @@
* call-seq:
* rng.exclude_end? -> true or false
*
- * Returns true if rng excludes its end value.
+ * Returns true if the range excludes its end value.
+ *
+ * (1..5).exclude_end? #=> false
+ * (1...5).exclude_end? #=> true
*/
static VALUE
@@ -123,9 +126,9 @@
* call-seq:
* rng == obj -> true or false
*
- * Returns true only if obj is a Range, has equivalent
- * beginning and end items (by comparing them with ==), and has
- * the same exclude_end? setting as rng.
+ * Returns true only if +obj+ is a Range, has equivalent
+ * begin and end items (by comparing them with ==), and has
+ * the same #exclude_end? setting as the range.
*
* (0..2) == (0..2) #=> true
* (0..2) == Range.new(0,2) #=> true
@@ -191,9 +194,9 @@
* call-seq:
* rng.eql?(obj) -> true or false
*
- * Returns true only if obj is a Range, has equivalent
- * beginning and end items (by comparing them with #eql?), and has the same
- * #exclude_end? setting as rng.
+ * Returns true only if +obj+ is a Range, has equivalent
+ * begin and end items (by comparing them with eql?),
+ * and has the same #exclude_end? setting as the range.
*
* (0..2).eql?(0..2) #=> true
* (0..2).eql?(Range.new(0,2)) #=> true
@@ -234,9 +237,9 @@
* call-seq:
* rng.hash -> fixnum
*
- * Generate a hash value such that two ranges with the same start and
- * end points, and the same value for the "exclude end" flag, generate
- * the same hash value.
+ * Compute a hash-code for this range. Two ranges with equal
+ * begin and end points (using eql?), and the same
+ * #exclude_end? value will generate the same hash-code.
*/
static VALUE
@@ -318,29 +321,20 @@
* rng.step(n=1) {| obj | block } -> rng
* rng.step(n=1) -> an_enumerator
*
- * Iterates over rng, passing each nth element to the block. If
- * the range contains numbers, n is added for each iteration. Otherwise
- * step invokes succ to iterate through range
- * elements. The following code uses class Xs, which is defined
- * in the class-level documentation.
+ * Iterates over the range, passing each nth element to the block.
+ * If begin and end are numeric, +n+ is added for each iteration.
+ * Otherwise step invokes succ to iterate through
+ * range elements.
*
* If no block is given, an enumerator is returned instead.
*
- * range = Xs.new(1)..Xs.new(10)
- * range.step(2) {|x| puts x}
- * range.step(3) {|x| puts x}
+ * (3..10).step(3) {|n| puts n }
*
* produces:
*
- * 1 x
- * 3 xxx
- * 5 xxxxx
- * 7 xxxxxxx
- * 9 xxxxxxxxx
- * 1 x
- * 4 xxxx
- * 7 xxxxxxx
- * 10 xxxxxxxxxx
+ * 3
+ * 6
+ * 9
*/
@@ -455,20 +449,19 @@
* rng.each {| i | block } -> rng
* rng.each -> an_enumerator
*
- * Iterates over the elements rng, passing each in turn to the
- * block. You can only iterate if the start object of the range
- * supports the +succ+ method (which means that you can't iterate over
- * ranges of +Float+ objects).
+ * Iterates over the elements of range, passing each in turn to the
+ * block.
*
+ * The +each+ method can only be used if the begin object of the range
+ * supports the +succ+ method. A TypeError is raised if the object
+ * does not have +succ+ method defined.
+ *
* If no block is given, an enumerator is returned instead.
+ * (10..15).each {|n| print n, ' ' }
+ * # prints: 10 11 12 13 14 15
*
- * (10..15).each do |n|
- * print n, ' '
- * end
- *
- * produces:
- *
- * 10 11 12 13 14 15
+ * ((2.5)..5).each {|n| print n, ' ' }
+ * # raises: TypeError: can't iterate from Float
*/
static VALUE
@@ -523,7 +516,9 @@
* call-seq:
* rng.begin -> obj
*
- * Returns the first object in rng.
+ * Returns the object that defines the beginning of the range.
+ *
+ * (1..10).begin #=> 1
*/
static VALUE
@@ -537,7 +532,7 @@
* call-seq:
* rng.end -> obj
*
- * Returns the object that defines the end of rng.
+ * Returns the object that defines the end of the range.
*
* (1..10).end #=> 10
* (1...10).end #=> 10
@@ -570,7 +565,11 @@
* rng.first -> obj
* rng.first(n) -> an_array
*
- * Returns the first object in rng, or the first +n+ elements.
+ * Returns the first object in the range,
+ * or an array of the first +n+ elements.
+ *
+ * (10..20).first #=> 10
+ * (10..20).first(3) #=> [10, 11, 12]
*/
static VALUE
@@ -594,7 +593,16 @@
* rng.last -> obj
* rng.last(n) -> an_array
*
- * Returns the last object in rng, or the last +n+ elements.
+ * Returns the last object in the range,
+ * or an array of the last +n+ elements.
+ *
+ * Note that with no arguments +last+ will return the object that defines
+ * the end of the range even if #exclude_end? is +true+.
+ *
+ * (10..20).last #=> 20
+ * (10...20).last #=> 20
+ * (10..20).last(3) #=> [18, 19, 20]
+ * (10...20).last(3) #=> [17, 18, 19]
*/
static VALUE
@@ -610,10 +618,13 @@
* rng.min -> obj
* rng.min {| a,b | block } -> obj
*
- * Returns the minimum value in rng. The second uses
- * the block to compare values. Returns nil if the first
- * value in range is larger than the last value.
+ * Returns the minimum value in the range. Returns +nil+ if the begin
+ * value of the range is larger than the end value.
*
+ * Can be given an optional block to override the default comparison
+ * method a <=> b.
+ *
+ * (10..20).min #=> 10
*/
@@ -639,10 +650,13 @@
* rng.max -> obj
* rng.max {| a,b | block } -> obj
*
- * Returns the maximum value in rng. The second uses
- * the block to compare values. Returns nil if the first
- * value in range is larger than the last value.
+ * Returns the maximum value in the range. Returns +nil+ if the begin
+ * value of the range larger than the end value.
*
+ * Can be given an optional block to override the default comparison
+ * method a <=> b.
+ *
+ * (10..20).max #=> 20
*/
static VALUE
@@ -749,7 +763,8 @@
* call-seq:
* rng.to_s -> string
*
- * Convert this range object to a printable form.
+ * Convert this range object to a printable form (using
+ * to_s to convert the begin and end objects).
*/
static VALUE
@@ -790,7 +805,7 @@
* rng.inspect -> string
*
* Convert this range object to a printable form (using
- * inspect to convert the start and end
+ * inspect to convert the begin and end
* objects).
*/
@@ -805,20 +820,8 @@
* call-seq:
* rng === obj -> true or false
*
- * Returns true if obj is an element of
- * rng, false otherwise. Conveniently,
- * === is the comparison operator used by
- * case 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
- *
- * produces:
- *
- * high
+ * Returns true if +obj+ is an element of
+ * the range, false otherwise.
*/
static VALUE
@@ -830,15 +833,16 @@
/*
* call-seq:
- * rng.member?(val) -> true or false
- * rng.include?(val) -> true or false
+ * rng.member?(obj) -> true or false
+ * rng.include?(obj) -> true or false
*
- * Returns true if obj is an element of
- * rng, false otherwise. If beg and end are
- * numeric, comparison is done according magnitude of values.
+ * Returns true if +obj+ is an element of
+ * the range, false otherwise. If begin and end are
+ * numeric, comparison is done according to the magnitude of the values.
*
- * ("a".."z").include?("g") # -> true
- * ("a".."z").include?("A") # -> false
+ * ("a".."z").include?("g") #=> true
+ * ("a".."z").include?("A") #=> false
+ * ("a".."z").include?("cc") #=> false
*/
static VALUE
@@ -891,14 +895,17 @@
/*
* call-seq:
- * rng.cover?(val) -> true or false
+ * rng.cover?(obj) -> true or false
*
- * Returns true if obj is between beg and end,
- * i.e beg <= obj <= end (or end exclusive when
- * exclude_end? is true).
+ * Returns true if +obj+ is between the begin and end of
+ * the range.
*
+ * This tests begin <= obj <= end when #exclude_end? is +false+
+ * and begin <= obj < end when #exclude_end? is +true+.
+ *
* ("a".."z").cover?("c") #=> true
* ("a".."z").cover?("5") #=> false
+ * ("a".."z").cover?("cc") #=> true
*/
static VALUE
@@ -958,11 +965,11 @@
}
/* A Range represents an interval---a set of values with a
- * start and an end. Ranges may be constructed using the
+ * beginning and an end. Ranges may be constructed using the
* s..e and
* s...e literals, or with
- * Range::new. Ranges constructed using ..
- * run from the start to the end inclusively. Those created using
+ * Range::new. Ranges constructed using ..
+ * run from the beginning to the end inclusively. Those created using
* ... exclude the end value. When used as an iterator,
* ranges return each value in the sequence.
*
@@ -971,11 +978,20 @@
* ('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 <=> operator and
- * they support the succ method to return the next object
- * in sequence.
+ * == Custom Objects in Ranges
+ * Ranges can be constructed using any objects that can be compared
+ * using the <=> operator.
+ * Methods that treat the range as a sequence (#each and methods inherited
+ * from Enumerable) expect the begin object to implement a
+ * succ method to return the next object in sequence.
+ * The #step and #include? methods require the begin
+ * object to implement succ or to be numeric.
*
+ * In the Xs class below both <=> and
+ * succ are implemented so Xs can be used
+ * to construct ranges. Note that the Comparable module is included
+ * so the == method is defined in terms of <=>.
+ *
* class Xs # represent a string of 'x's
* include Comparable
* attr :length
@@ -988,25 +1004,36 @@
* def <=>(other)
* @length <=> other.length
* end
- * def to_s
- * sprintf "%2d #{inspect}", @length
- * end
* def inspect
* 'x' * @length
* end
* end
*
+ * A example of using Xs to construct a range follows:
+ *
* 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 Xs includes the
- * Comparable module. This is because
- * Enumerable#member? checks for equality using
- * ==. Including Comparable ensures that the
- * == method is defined in terms of the <=>
- * method implemented in Xs.
+ * == Ranges in Case Statements
*
+ * When Ranges are compared to other objects using the ===
+ * operator true is returned if the object is an element
+ * of range, false otherwise. Since === is
+ * the comparison operator used by case statements this
+ * allows ranges to be used as conditions in case statements such as
+ * in the following:
+ *
+ * case 79
+ * when 1..50 then puts "low"
+ * when 51..75 then puts "medium"
+ * when 76..100 then puts "high"
+ * end
+ *
+ * produces:
+ *
+ * high
+ *
*/
void