Class: Range

Inherits:
Object show all
Includes:
Enumerable
Defined in:
range.c

Overview

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.

Instance Method Summary collapse

Methods included from Enumerable

#all?, #any?, #collect, #detect, #each_with_index, #entries, #find, #find_all, #grep, #inject, #map, #max, #min, #partition, #reject, #select, #sort, #sort_by, #to_a, #zip

Constructor Details

#new(start, end) ⇒ Object

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.



77
78
79
 
# File 'range.c', line 77

static VALUE
range_initialize(argc, argv, range)
int argc;

Instance Method Details

#==(obj) ⇒ Boolean

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 <i>rng</t>.

(0..2) == (0..2)            #=> true
(0..2) == Range.new(0,2)    #=> true
(0..2) == (0...2)           #=> false

Returns:

  • (Boolean) 


124
125
126
 
# File 'range.c', line 124

static VALUE
range_eq(range, obj)
VALUE range, obj;

#===(obj) ⇒ Boolean #member?(val) ⇒ Boolean #include?(val) ⇒ Boolean

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

Overloads:

  • #===(obj) ⇒ Boolean

    Returns:

    • (Boolean)
  • #member?(val) ⇒ Boolean

    Returns:

    • (Boolean)
  • #include?(val) ⇒ Boolean

    Returns:

    • (Boolean) 


574
575
576
 
# File 'range.c', line 574

static VALUE
range_include(range, val)
VALUE range, val;

#first ⇒ Object #begin ⇒ Object

Returns the first object in rng.

Overloads:



437
438
439
 
# File 'range.c', line 437

static VALUE
range_first(range)
VALUE range;

#each {|i| ... } ⇒ Object

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).

(10..15).each do |n|
   print n, ' '
end

produces:

10 11 12 13 14 15

Yields:

  • (i) 


392
393
394
 
# File 'range.c', line 392

static VALUE
range_each(range)
VALUE range;

#end ⇒ Object #last ⇒ Object

Returns the object that defines the end of rng.

(1..10).end    #=> 10
(1...10).end   #=> 10

Overloads:



457
458
459
 
# File 'range.c', line 457

static VALUE
range_last(range)
VALUE range;

#eql?(obj) ⇒ Boolean

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

Returns:

  • (Boolean) 


182
183
184
 
# File 'range.c', line 182

static VALUE
range_eql(range, obj)
VALUE range, obj;

#exclude_end? ⇒ Boolean

Returns true if rng excludes its end value.

Returns:

  • (Boolean) 


102
103
104
 
# File 'range.c', line 102

static VALUE
range_exclude_end_p(range)
VALUE range;

#first ⇒ Object #begin ⇒ Object

Returns the first object in rng.

Overloads:



437
438
439
 
# File 'range.c', line 437

static VALUE
range_first(range)
VALUE range;

#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.

Returns:



209
210
211
 
# File 'range.c', line 209

static VALUE
range_hash(range)
VALUE range;

#===(obj) ⇒ Boolean #member?(val) ⇒ Boolean #include?(val) ⇒ Boolean

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

Overloads:

  • #===(obj) ⇒ Boolean

    Returns:

    • (Boolean)
  • #member?(val) ⇒ Boolean

    Returns:

    • (Boolean)
  • #include?(val) ⇒ Boolean

    Returns:

    • (Boolean) 


574
575
576
 
# File 'range.c', line 574

static VALUE
range_include(range, val)
VALUE range, val;

#inspect ⇒ String

Convert this range object to a printable form (using inspect to convert the start and end objects).

Returns:



536
537
538
 
# File 'range.c', line 536

static VALUE
range_inspect(range)
VALUE range;

#end ⇒ Object #last ⇒ Object

Returns the object that defines the end of rng.

(1..10).end    #=> 10
(1...10).end   #=> 10

Overloads:



457
458
459
 
# File 'range.c', line 457

static VALUE
range_last(range)
VALUE range;

#===(obj) ⇒ Boolean #member?(val) ⇒ Boolean #include?(val) ⇒ Boolean

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

Overloads:

  • #===(obj) ⇒ Boolean

    Returns:

    • (Boolean)
  • #member?(val) ⇒ Boolean

    Returns:

    • (Boolean)
  • #include?(val) ⇒ Boolean

    Returns:

    • (Boolean) 


574
575
576
 
# File 'range.c', line 574

static VALUE
range_include(range, val)
VALUE range, val;

#step(n = 1) {|obj| ... } ⇒ Object

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

Yields:

  • (obj) 


297
298
299
 
# File 'range.c', line 297

static VALUE
range_step(argc, argv, range)
int argc;

#to_s ⇒ String

Convert this range object to a printable form.

Returns:



510
511
512
 
# File 'range.c', line 510

static VALUE
range_to_s(range)
VALUE range;