Class: Range
Relationships & Source Files | |
Super Chains via Extension / Inclusion / Inheritance | |
Instance Chain:
self,
::Enumerable
|
|
Inherits: | Object |
Defined in: | range.c |
Overview
A Range
represents an interval—a set of values with a beginning and an end. Ranges may be constructed using the s..
e and s...
e literals, or with .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.
(-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"]
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
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
An example of using Xs
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
Class Method Summary
- .new(begin, end, exclude_end=false) ⇒ Range constructor
Instance Attribute Summary
-
#exclude_end? ⇒ Boolean
readonly
Returns
true
if the range excludes its end value.
::Enumerable - Included
Instance Method Summary
-
#==(obj) ⇒ Boolean
Returns
true
only ifobj
is aRange
, has equivalent begin and end items (by comparing them with==
), and has the same #exclude_end? setting as the range. -
#===(obj) ⇒ Boolean
Returns
true
ifobj
is an element of the range,false
otherwise. -
#begin ⇒ Object
Returns the object that defines the beginning of the range.
-
#bsearch {|obj| ... } ⇒ value
By using binary search, finds a value in range which meets the given condition in O(log n) where n is the size of the range.
-
#cover?(obj) ⇒ Boolean
Returns
true
ifobj
is between the begin and end of the range. -
#each {|i| ... } ⇒ Range
Iterates over the elements of range, passing each in turn to the block.
-
#end ⇒ Object
Returns the object that defines the end of the range.
-
#eql?(obj) ⇒ Boolean
Returns
true
only ifobj
is aRange
, has equivalent begin and end items (by comparing them witheql?
), and has the same #exclude_end? setting as the range. -
#first ⇒ Object
Returns the first object in the range, or an array of the first
n
elements. -
#hash ⇒ Fixnum
Compute a hash-code for this range.
-
#include?(obj) ⇒ Boolean
Alias for #member?.
-
#inspect ⇒ String
Convert this range object to a printable form (using
inspect
to convert the begin and end objects). -
#last ⇒ Object
Returns the last object in the range, or an array of the last
n
elements. -
#max ⇒ Object
Returns the maximum value in the range.
-
#member?(obj) ⇒ Boolean
(also: #include?)
Returns
true
ifobj
is an element of the range,false
otherwise. -
#min ⇒ Object
Returns the minimum value in the range.
-
#size ⇒ Numeric
Returns the number of elements in the range.
-
#step(n = 1) {|obj| ... } ⇒ Range
Iterates over the range, passing each
n
th element to the block. -
#to_s ⇒ String
Convert this range object to a printable form (using #to_s to convert the begin and end objects).
::Enumerable - Included
#chunk | Enumerates over the items, chunking them together based on the return value of the block. |
#chunk_while | Creates an enumerator for each chunked elements. |
#collect | Alias for Enumerable#map. |
#collect_concat | Alias for Enumerable#flat_map. |
#count | Returns the number of items in |
#cycle | Calls block for each element of enum repeatedly n times or forever if none or |
#detect | Alias for Enumerable#find. |
#drop | Drops first n elements from enum, and returns rest elements in an array. |
#drop_while | Drops elements up to, but not including, the first element for which the block returns |
#each_cons | Iterates the given block for each array of consecutive <n> elements. |
#each_entry | Calls block once for each element in |
#each_slice | Iterates the given block for each slice of <n> elements. |
#each_with_index | Calls block with two arguments, the item and its index, for each item in enum. |
#each_with_object | Iterates the given block for each element with an arbitrary object given, and returns the initially given object. |
#entries | Alias for Enumerable#to_a. |
#find | Passes each entry in enum to block. |
#find_all | Alias for Enumerable#select. |
#find_index | Compares each entry in enum with value or passes to block. |
#first | Returns the first element, or the first |
#flat_map | Returns a new array with the concatenated results of running block once for every element in enum. |
#grep | Returns an array of every element in enum for which |
#grep_v | Inverted version of Enumerable#grep. |
#group_by | Groups the collection by result of the block. |
#include? | Alias for Enumerable#member?. |
#inject | Combines all elements of enum by applying a binary operation, specified by a block or a symbol that names a method or operator. |
#lazy | Returns a lazy enumerator, whose methods map/collect, flat_map/collect_concat, select/find_all, reject, grep, grep_v, zip, take, take_while, drop, and drop_while enumerate values only on an as-needed basis. |
#map | Returns a new array with the results of running block once for every element in enum. |
#max | Returns the object in enum with the maximum value. |
#max_by | Returns the object in enum that gives the maximum value from the given block. |
#member? | Returns |
#min | Returns the object in enum with the minimum value. |
#min_by | Returns the object in enum that gives the minimum value from the given block. |
#minmax | Returns a two element array which contains the minimum and the maximum value in the enumerable. |
#minmax_by | Returns a two element array containing the objects in enum that correspond to the minimum and maximum values respectively from the given block. |
#partition | Returns two arrays, the first containing the elements of enum for which the block evaluates to true, the second containing the rest. |
#reduce | Alias for Enumerable#inject. |
#reject | Returns an array for all elements of |
#reverse_each | Builds a temporary array and traverses that array in reverse order. |
#select | Returns an array containing all elements of |
#slice_after | Creates an enumerator for each chunked elements. |
#slice_before | Creates an enumerator for each chunked elements. |
#slice_when | Creates an enumerator for each chunked elements. |
#sort | Returns an array containing the items in enum sorted, either according to their own |
#sort_by | Sorts enum using a set of keys generated by mapping the values in enum through the given block. |
#take | Returns first n elements from enum. |
#take_while | Passes elements to the block until the block returns |
#to_a | Returns an array containing the items in enum. |
#to_h | Returns the result of interpreting enum as a list of |
#zip | Takes one element from enum and merges corresponding elements from each args. |
Constructor Details
.new(begin, end, exclude_end=false) ⇒ Range
Instance Attribute Details
#exclude_end? ⇒ Boolean
(readonly)
Returns true
if the range excludes its end value.
(1..5).exclude_end? #=> false
(1...5).exclude_end? #=> true
Instance Method Details
#==(obj) ⇒ Boolean
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
(0..2) == (0...2) #=> false
#===(obj) ⇒ Boolean
Returns true
if obj
is an element of the range, 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
#begin ⇒ Object
Returns the object that defines the beginning of the range.
(1..10).begin #=> 1
#bsearch {|obj| ... } ⇒ value
By using binary search, finds a value in range which meets the given condition in O(log n) where n is the size of the range.
You can use this method in two use cases: a find-minimum mode and a find-any mode. In either case, the elements of the range must be monotone (or sorted) with respect to the block.
In find-minimum mode (this is a good choice for typical use case), the block must return true or false, and there must be a value x so that:
-
the block returns false for any value which is less than x, and
-
the block returns true for any value which is greater than or equal to x.
If x is within the range, this method returns the value x. Otherwise, it returns nil.
ary = [0, 4, 7, 10, 12]
(0...ary.size).bsearch {|i| ary[i] >= 4 } #=> 1
(0...ary.size).bsearch {|i| ary[i] >= 6 } #=> 2
(0...ary.size).bsearch {|i| ary[i] >= 8 } #=> 3
(0...ary.size).bsearch {|i| ary[i] >= 100 } #=> nil
(0.0...Float::INFINITY).bsearch {|x| Math.log(x) >= 0 } #=> 1.0
In find-any mode (this behaves like libc's bsearch(3)), the block must return a number, and there must be two values x and y (x <= y) so that:
-
the block returns a positive number for v if v < x,
-
the block returns zero for v if x <= v < y, and
-
the block returns a negative number for v if y <= v.
This method returns any value which is within the intersection of the given range and x…y (if any). If there is no value that satisfies the condition, it returns nil.
ary = [0, 100, 100, 100, 200]
(0..4).bsearch {|i| 100 - ary[i] } #=> 1, 2 or 3
(0..4).bsearch {|i| 300 - ary[i] } #=> nil
(0..4).bsearch {|i| 50 - ary[i] } #=> nil
You must not mix the two modes at a time; the block must always return either true/false, or always return a number. It is undefined which value is actually picked up at each iteration.
#cover?(obj) ⇒ Boolean
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
#each {|i| ... } ⇒ Range
#each ⇒ Enumerator
Range
#each ⇒ Enumerator
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 {|n| print n, ' ' }
# prints: 10 11 12 13 14 15
(2.5..5).each {|n| print n, ' ' }
# raises: TypeError: can't iterate from Float
#end ⇒ Object
Returns the object that defines the end of the range.
(1..10).end #=> 10
(1...10).end #=> 10
#eql?(obj) ⇒ Boolean
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
(0..2).eql?(0...2) #=> false
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]
#hash ⇒ Fixnum
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.
See also Object#hash.
#member?(obj) ⇒ Boolean
#include?(obj) ⇒ Boolean
Boolean
#include?(obj) ⇒ Boolean
Alias for #member?.
#inspect ⇒ String
Convert this range object to a printable form (using inspect
to convert the begin and end objects).
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]
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
#member?(obj) ⇒ Boolean
#include?(obj) ⇒ Boolean
Also known as: #include?
Boolean
#include?(obj) ⇒ Boolean
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
#size ⇒ Numeric
#step(n = 1) {|obj| ... } ⇒ Range
#step(n = 1) ⇒ Enumerator
Range
#step(n = 1) ⇒ Enumerator
Iterates over the range, passing each n
th 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}
puts
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
See Range for the definition of class Xs.
#to_s ⇒ String
Convert this range object to a printable form (using #to_s
to convert the begin and end objects).