struct Range(B, E)

Overview

ARange 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

SeeRange 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 pushesy further away, thus leaving it outside of the range.

Ranges typically involve integers, but can be created using arbitrary objects as long as they definesucc (orpred 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 usingXs 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

Defined in:

range.cr
range/bsearch.cr

Constructors

.new(begin __arg0 : B, end __arg1 : E, exclusive : Bool = false)
Constructs aRange using the given beginning and end.

Instance Method Summary

#==(other : Range)
#===(value)
Same as#includes?, useful for thecase 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 newRange with#begin and#end cloned.
#covers?(value)
Same as#includes?.
#cycle
Returns anIterator 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 anIterator over the elements of this range.
#end : E
Returns the object that defines the end of the range.
#excludes_end? : Bool
Returnstrue if this range excludes theend element.
#exclusive? : Bool
Returnstrue if the range is exclusive.
#includes?(value) : Bool
Returnstrue if this range includes the givenvalue.
#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 anArray 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 reverseIterator over the elements of this range.
#sample(random : Random | Nil = nil)
Optimized version ofEnumerable#sample that runs in O(1) time whenself is anInt orFloat range.
#sample(n : Int, random : Random | Nil = nil)
Returns anArray ofn random elements fromself.
#size : Int32
Returns the number of values in this range.
#step(by = 1, &) : Nil
Iterates from#begin to#end incrementing by the amount ofstep on each iteration.
#step(by = 1) : Iterator
Iterates from#begin to#end incrementing by the amount ofstep on each iteration.
#sum(initial)
Optimized version ofEnumerable#sum that runs in O(1) time whenself is anInt range.
#to_s(io : IO) : Nil
Same as#inspect(io).

Instance methods inherited from module `Iterable(B)`

, , , , , , , , , , , ,

Instance methods inherited from module `Enumerable(B)`

, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,

Class methods inherited from module `Enumerable(B)`

Instance methods inherited from struct `Struct`

, , , ,

Class methods inherited from struct `Struct`

Instance methods inherited from struct `Value`

Instance methods inherited from class `Object`

, , , , , , , , , , , , , , , , , , , , , , , , , ,

Class methods inherited from class `Object`

Macros inherited from class `Object`

, , , , , , , , , , , , , , , , , , ,

Constructor Detail

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

Constructs aRange using the given beginning and end.

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

Instance Method Detail

def ==(other : Range) #

def ===(value) #

Same as#includes?, useful for thecase expression.

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

Produces:

high

See also:Object#===.

def begin : B #

Returns the object that defines the beginning of this range.

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

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

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

If the block returns a falsey value, the element to be found lies behind. If the block returns a truthy value, the element to be found is itself or lies in front.

Returnsnil if the block didn't return a truthy value for any element.

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

def clone #

Returns a newRange with#begin and#end cloned.

def covers?(value) #

Same as#includes?.

def cycle #

Returns anIterator that cycles over the values of this range.

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

def each(&) : Nil #

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

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

def each #

Returns anIterator over the elements of this range.

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

def end : E #

Returns the object that defines the end of the range.

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

def excludes_end? : Bool #

Returnstrue if this range excludes theend element.

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

def exclusive? : Bool #

Returnstrue if the range is exclusive. Returnsfalse otherwise (default).

def includes?(value) : Bool #

Returnstrue if this range includes the givenvalue.

(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

def inspect(io : IO) : Nil #

Description copied from struct Struct

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

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

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

Description copied from module Enumerable(B)

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

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

def reverse_each(&) : Nil #

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

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

def reverse_each #

Returns a reverseIterator over the elements of this range.

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

def sample(random : Random | Nil = nil) #

Optimized version ofEnumerable#sample that runs in O(1) time whenself is anInt orFloat range. In these cases, this range is considered to be a distribution of numeric values rather than a collection of elements, and the method simply callsrandom.rand(self).

RaisesArgumentError ifself is an open range.

def sample(n : Int, random : Random | Nil = nil) #

Returns anArray ofn random elements fromself. All elements have equal probability of being drawn. Sampling is done without replacement; if n is larger than the size of this collection, the returnedArray has the same size asself.

RaisesArgumentError ifn is negative.

[1, 2, 3, 4, 5].sample(2) # => [3, 5]
{1, 2, 3, 4, 5}.sample(2) # => [3, 4]

Uses therandom instance when provided if the randomness needs to be controlled or to follow some traits. For example the following calls use a custom seed or a secure random source:

{1, 2, 3, 4, 5}.sample(2, Random.new(1))  # => [1, 5]
{1, 2, 3, 4, 5}.sample(2, Random::Secure) # => [2, 5]

Ifself is not empty andn is equal to 1, calls#sample(random) exactly once. Thus,random will be left in a different state compared to the implementation inEnumerable.

def size : Int32 #

Returns the number of values in this range.

If both the beginning and the end of this range areInts, runs in constant time instead of linear.

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

RaisesOverflowError if the difference is bigger thanInt32. RaisesArgumentError if either#begin or#end arenil.

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

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

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]

IfB is aSteppable, implementation is delegated toSteppable#step. Otherwise#succ method is expected to be defined on#begin and its successors and iteration is based on calling#succ sequentially (step times per iteration).

RaisesArgumentError if#begin isnil.

def step(by = 1) : Iterator #

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

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]

RaisesArgumentError if#begin isnil.

def sum(initial) #

Optimized version ofEnumerable#sum that runs in O(1) time whenself is anInt range.

def to_s(io : IO) : Nil #

Description copied from struct Struct

Same as#inspect(io).

Crystal

struct Range(B, E)

Overview

Included Modules

Defined in:

Constructors

Instance Method Summary

Instance methods inherited from module Iterable(B)

Instance methods inherited from module Enumerable(B)

Class methods inherited from module Enumerable(B)

Instance methods inherited from struct Struct

Class methods inherited from struct Struct

Instance methods inherited from struct Value

Instance methods inherited from class Object

Class methods inherited from class Object

Macros inherited from class Object