summaryrefslogtreecommitdiff
path: root/range.c
diff options
context:
space:
mode:
authordave <dave@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2003-12-24 04:29:32 +0000
committerdave <dave@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2003-12-24 04:29:32 +0000
commitbba2f6d4052235e9c8d62c0c3b7294e8dae1d7b7 (patch)
treed3f421fb8103f06beaa31d7a7dc6bb13b4704616 /range.c
parentf0346bd249ae29cdf4d9c2e88b09e63c41ff1ce8 (diff)
Michael Granger added RDoc for range.c
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@5273 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'range.c')
-rw-r--r--range.c184
1 files changed, 184 insertions, 0 deletions
diff --git a/range.c b/range.c
index a7f553b..bd9286f 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()
{