struct Range(B, E)

• Range(B, E)
• Struct
• Value
• Object

Overview

A Range represents an interval: a set of values with a beginning and an end.

Ranges may be constructed using the usual .new method or with literals:

x..y  # an inclusive range, in mathematics: [x, y]
x...y # an exclusive range, in mathematics: [x, y)
(x..) # an endless range, in mathematics: >= x
..y   # a beginless inclusive range, in mathematics: <= y
...y  # a beginless exclusive range, in mathematics: < y

See Range literals in the language reference.

An easy way to remember which one is inclusive and which one is exclusive it to think of the extra dot as if it pushes y further away, thus leaving it outside of the range.

Ranges typically involve integers, but can be created using arbitrary objects as long as they define succ (or pred for #reverse_each), to get the next element in the range, and < and #==, to know when the range reached the end:

# Represents a string of 'x's.
struct Xs
  include Comparable(Xs)

  getter size

  def initialize(@size : Int32)
  end

  def succ
    Xs.new(@size + 1)
  end

  def <=>(other)
    @size <=> other.size
  end

  def inspect(io)
    @size.times { io << 'x' }
  end

  def to_s(io)
    io << @size << ' '
    inspect(io)
  end
end

An example of using Xs to construct a range:

r = Xs.new(3)..Xs.new(6)
r.to_s                 # => "xxx..xxxxxx"
r.to_a                 # => [Xs.new(3), Xs.new(4), Xs.new(5), Xs.new(6)]
r.includes?(Xs.new(5)) # => true

Included Modules

• Enumerable(B)
• Iterable(B)

Defined in:

Constructors

• .new(begin __arg0 : B, end __arg1 : E, exclusive : Bool = false)

  Constructs a Range using the given beginning and end.

Instance Method Summary

• #==(other : Range)
• #===(value)

  Same as #includes?, useful for the case expression.

• #begin : B

  Returns the object that defines the beginning of this range.

• #bsearch(&block : B | E -> _)

  By using binary search, returns the first element for which the passed block returns a truthy value.

• #clone

  Returns a new Range with #begin and #end cloned.

• #covers?(value)

  Same as #includes?.

• #cycle

  Returns an Iterator that cycles over the values of this range.

• #each(&) : Nil

  Iterates over the elements of this range, passing each in turn to the block.

• #each

  Returns an Iterator over the elements of this range.

• #end : E

  Returns the object that defines the end of the range.

• #excludes_end? : Bool

  Returns true if this range excludes the end element.

• #exclusive? : Bool

  Returns true if the range is exclusive.

• #includes?(value) : Bool

  Returns true if this range includes the given value.

• #inspect(io : IO) : Nil

  Appends this struct's name and instance variables names and values to the given IO.

• #map(&block : B -> U) forall U

  Returns an Array with the results of running the block against each element of the collection.

• #reverse_each(&) : Nil

  Iterates over the elements of this range in reverse order, passing each in turn to the block.

• #reverse_each

  Returns a reverse Iterator over the elements of this range.

• #sample(random : Random = Random::DEFAULT)

  Optimized version of Enumerable#sample that runs in O(1) time when self is an Int or Float range.

• #sample(n : Int, random = Random::DEFAULT)

  :inherit:

• #size : Int32

  Returns the number of values in this range.

• #step(by = 1, &) : Nil

  Iterates from #begin to #end incrementing by the amount of step on each iteration.

• #step(by = 1) : Iterator

  Iterates from #begin to #end incrementing by the amount of step on each iteration.

• #sum(initial)

  Optimized version of Enumerable#sum that runs in O(1) time when self is an Int range.

• #to_s(io : IO) : Nil

  Same as #inspect(io).

Constructor Detail

Range.new(1, 10)                  # => 1..10
Range.new(1, 10, exclusive: true) # => 1...10

Instance Method Detail

case 79
when 1..50   then puts "low"
when 51..75  then puts "medium"
when 76..100 then puts "high"
end

high

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

(0..10).bsearch { |x| x >= 5 }                       # => 5
(0..Float64::INFINITY).bsearch { |x| x ** 4 >= 256 } # => 4

(1..3).cycle.first(5).to_a # => [1, 2, 3, 1, 2]

(10..15).each { |n| print n, ' ' }
# prints: 10 11 12 13 14 15

(1..3).each.skip(1).to_a # => [2, 3]

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

(1..10).excludes_end?  # => false
(1...10).excludes_end? # => true

(1..10).includes?(4)  # => true
(1..10).includes?(10) # => true
(1..10).includes?(11) # => false

(1...10).includes?(9)  # => true
(1...10).includes?(10) # => false

struct Point
  def initialize(@x : Int32, @y : Int32)
  end
end

p1 = Point.new 1, 2
p1.to_s    # "Point(@x=1, @y=2)"
p1.inspect # "Point(@x=1, @y=2)"

[1, 2, 3].map { |i| i * 10 } # => [10, 20, 30]

(10...15).reverse_each { |n| print n, ' ' }
# prints: 14 13 12 11 10

(1..3).reverse_each.skip(1).to_a # => [2, 1]

(3..8).size  # => 6
(3...8).size # => 5

ary = [] of Int32
(1..4).step(by: 2) do |x|
  ary << x
end
ary                      # => [1, 3]
(1..4).step(by: 2).to_a  # => [1, 3]
(1..4).step(by: 1).to_a  # => [1, 2, 3, 4]
(1...4).step(by: 1).to_a # => [1, 2, 3]

ary = [] of Int32
(1..4).step(by: 2) do |x|
  ary << x
end
ary                      # => [1, 3]
(1..4).step(by: 2).to_a  # => [1, 3]
(1..4).step(by: 1).to_a  # => [1, 2, 3, 4]
(1...4).step(by: 1).to_a # => [1, 2, 3]