From bba2f6d4052235e9c8d62c0c3b7294e8dae1d7b7 Mon Sep 17 00:00:00 2001 From: dave Date: Wed, 24 Dec 2003 04:29:32 +0000 Subject: [PATCH] Michael Granger added RDoc for range.c git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@5273 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- range.c | 184 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 184 insertions(+) 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 start and end. If the third + * parameter is omitted or is false, the range 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 true if rng 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 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. + * + * (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 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. + * + * (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 rng, passing each nth element to the block. If + * the range contains numbers or strings, natural ordering is used. Otherwise + * step invokes succ to iterate through range + * elements. The following code uses class Xs, 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} + * + * produces: + * + * 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 rng, passing each in turn to the + * block. + * + * (10..15).each do |n| + * print n, ' ' + * end + * + * produces: + * + * 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 rng. + */ + 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 rng. + * + * (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 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 + */ + static VALUE range_include(range, val) VALUE range, val; @@ -454,6 +585,59 @@ range_include(range, val) return Qfalse; } + +/* A Range represents an interval---a set of values with a + * start 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 + * ... 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 <=> operator and + * they support the succ 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 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. + * + */ + void Init_Range() {