ruby-changes:21909
From: drbrain <ko1@a...>
Date: Tue, 6 Dec 2011 08:37:32 +0900 (JST)
Subject: [ruby-changes:21909] drbrain:r33958 (trunk): * range.c: Improve documentation for Range. Patch by Chris Zetter.
drbrain 2011-12-06 08:36:53 +0900 (Tue, 06 Dec 2011) New Revision: 33958 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=33958 Log: * range.c: Improve documentation for Range. Patch by Chris Zetter. [Ruby 1.9 - Bug #5656] Modified files: trunk/ChangeLog trunk/range.c Index: ChangeLog =================================================================== --- ChangeLog (revision 33957) +++ ChangeLog (revision 33958) @@ -1,3 +1,8 @@ +Tue Dec 6 07:26:37 2011 Eric Hodel <drbrain@s...> + + * range.c: Improve documentation for Range. Patch by Chris Zetter. + [Ruby 1.9 - Bug #5656] + Mon Dec 5 19:08:04 2011 Nobuyoshi Nakada <nobu@r...> * regparse.c (PFETCH_READY): separate gcc specific trick. Index: range.c =================================================================== --- range.c (revision 33957) +++ range.c (revision 33958) @@ -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 <i>start</i> and <i>end</i>. If the third - * parameter is omitted or is <code>false</code>, the <i>range</i> will include + * Constructs a range using the given +begin+ and +end+. If the +exclude_end+ + * parameter is omitted or is <code>false</code>, 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 <code>true</code> if <i>rng</i> excludes its end value. + * Returns <code>true</code> 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 <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 <code>exclude_end?</code> setting as <i>rng</i>. + * Returns <code>true</code> only if +obj+ is a Range, has equivalent + * begin and end items (by comparing them with <code>==</code>), 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 <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>. + * Returns <code>true</code> only if +obj+ is a Range, has equivalent + * begin and end items (by comparing them with <code>eql?</code>), + * 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 <code>eql?</code>), and the same + * #exclude_end? value will generate the same hash-code. */ static VALUE @@ -318,29 +321,32 @@ * rng.step(n=1) {| obj | block } -> rng * rng.step(n=1) -> an_enumerator * - * Iterates over <i>rng</i>, passing each <i>n</i>th element to the block. If - * the range contains numbers, <i>n</i> is added for each iteration. 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. + * Iterates over the range, passing each <code>n</code>th element to the block. + * If begin and end are numeric, +n+ is added for each iteration. + * Otherwise <code>step</code> invokes <code>succ</code> 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} + * range = Xs.new(1)..Xs.new(10) + * range.step(2) {|x| puts x} + * puts + * 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 + * 1 x + * 3 xxx + * 5 xxxxx + * 7 xxxxxxx + * 9 xxxxxxxxx + * + * 1 x + * 4 xxxx + * 7 xxxxxxx + * 10 xxxxxxxxxx + * + * See Range for the definition of class Xs. */ @@ -455,20 +461,20 @@ * rng.each {| i | block } -> rng * rng.each -> an_enumerator * - * Iterates over the elements <i>rng</i>, 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 (like Float). + * * If no block is given, an enumerator is returned instead. * - * (10..15).each do |n| - * print n, ' ' - * end + * (10..15).each {|n| print n, ' ' } + * # prints: 10 11 12 13 14 15 * - * <em>produces:</em> - * - * 10 11 12 13 14 15 + * (2.5..5).each {|n| print n, ' ' } + * # raises: TypeError: can't iterate from Float */ static VALUE @@ -523,7 +529,9 @@ * call-seq: * rng.begin -> obj * - * Returns the first object in <i>rng</i>. + * Returns the object that defines the beginning of the range. + * + * (1..10).begin #=> 1 */ static VALUE @@ -537,7 +545,7 @@ * call-seq: * rng.end -> obj * - * Returns the object that defines the end of <i>rng</i>. + * Returns the object that defines the end of the range. * * (1..10).end #=> 10 * (1...10).end #=> 10 @@ -570,7 +578,11 @@ * rng.first -> obj * rng.first(n) -> an_array * - * Returns the first object in <i>rng</i>, 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 +606,16 @@ * rng.last -> obj * rng.last(n) -> an_array * - * Returns the last object in <i>rng</i>, 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 +631,13 @@ * rng.min -> obj * rng.min {| a,b | block } -> obj * - * Returns the minimum value in <i>rng</i>. 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 <code>a <=> b</code>. + * + * (10..20).min #=> 10 */ @@ -639,10 +663,13 @@ * rng.max -> obj * rng.max {| a,b | block } -> obj * - * Returns the maximum value in <i>rng</i>. 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 <code>a <=> b</code>. + * + * (10..20).max #=> 20 */ static VALUE @@ -749,7 +776,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 +818,7 @@ * rng.inspect -> string * * Convert this range object to a printable form (using - * <code>inspect</code> to convert the start and end + * <code>inspect</code> to convert the begin and end * objects). */ @@ -805,10 +833,9 @@ * 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. + * Returns <code>true</code> if +obj+ is an element of the range, + * <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" @@ -830,15 +857,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 <code>true</code> if <i>obj</i> is an element of - * <i>rng</i>, <code>false</code> otherwise. If beg and end are - * numeric, comparison is done according magnitude of values. + * Returns <code>true</code> if +obj+ is an element of + * the range, <code>false</code> 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 +919,17 @@ /* * call-seq: - * rng.cover?(val) -> true or false + * rng.cover?(obj) -> true or false * - * Returns <code>true</code> if <i>obj</i> is between beg and end, - * i.e <code>beg <= obj <= end</code> (or <i>end</i> exclusive when - * <code>exclude_end?</code> is true). + * Returns <code>true</code> if +obj+ is between the begin and end of + * the range. * + * This tests <code>begin <= obj <= end</code> when #exclude_end? is +false+ + * and <code>begin <= obj < end</code> when #exclude_end? is +true+. + * * ("a".."z").cover?("c") #=> true * ("a".."z").cover?("5") #=> false + * ("a".."z").cover?("cc") #=> true */ static VALUE @@ -958,11 +989,11 @@ } /* A <code>Range</code> 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 * <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 + * Range::new. Ranges constructed using <code>..</code> + * run from the beginning 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. * @@ -971,11 +1002,21 @@ * ('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. + * == Custom Objects in Ranges * + * Ranges can be constructed using any objects that can be compared + * using the <code><=></code> operator. + * Methods that treat the range as a sequence (#each and methods inherited + * from Enumerable) expect the begin object to implement a + * <code>succ</code> method to return the next object in sequence. + * The #step and #include? methods require the begin + * object to implement <code>succ</code> or to be numeric. + * + * In the <code>Xs</code> class below both <code><=></code> and + * <code>succ</code> are implemented so <code>Xs</code> can be used + * to construct ranges. Note that the Comparable module is included + * so the <code>==</code> method is defined in terms of <code><=></code>. + * * class Xs # represent a string of 'x's * include Comparable * attr :length @@ -996,17 +1037,12 @@ * end * end * + * A example of using <code>Xs</code> to construct a range: + * * 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 -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/