Blocks and Procs
Methods can accept a block of code that is executed
with the yield keyword. For example:
def twice
yield
yield
end
twice do
puts "Hello!"
end
The above program prints "Hello!" twice, once for each yield.
To define a method that receives a block, simply use yield inside it and the compiler will know. You can make this more evident by declaring a dummy block argument, indicated as a last argument prefixed with ampersand (&):
def twice(&block)
yield
yield
end
To invoke a method and pass a block, you use do ... end or { ... }. All of these are equivalent:
twice() do
puts "Hello!"
end
twice do
puts "Hello!"
end
twice { puts "Hello!" }
The difference between using do ... end and { ... } is that do ... end binds to the left-most call, while { ... } binds to the right-most call:
foo bar do
something
end
# The above is the same as
foo(bar) do
something
end
foo bar { something }
# The above is the same as
foo(bar { something })
The reason for this is to allow creating Domain Specific Languages (DSLs) using do ... end to have them be read as plain English:
open file "foo.cr" do
something
end
# Same as:
open(file("foo.cr")) do
end
You wouldn't want the above to be:
open(file("foo.cr") do
end)
Overloads
Two methods, one that yields and another that doesn't, are considered different overloads, as explained in the overloading section.
Yield arguments
The yield expression is similar to a call and can receive arguments. For example:
def twice
yield 1
yield 2
end
twice do |i|
puts "Got #{i}"
end
The above prints "Got 1" and "Got 2".
A curly braces notation is also available:
twice { |i| puts "Got #{i}" }
You can yield many values:
def many
yield 1, 2, 3
end
many do |x, y, z|
puts x + y + z
end
# Output: 6
A block can specify less than the arguments yielded:
def many
yield 1, 2, 3
end
many do |x, y|
puts x + y
end
# Output: 3
It's an error specifying more block arguments than those yielded:
def twice
yield
yield
end
twice do |i| # Error: too many block arguments
end
Each block variable has the type of every yield expression in that position. For example:
def some
yield 1, 'a'
yield true, "hello"
yield 2, nil
end
some do |first, second|
# first is Int32 | Bool
# second is Char | String | Nil
end
The block variable second also includes the Nil type because the last yield expression didn't include a second argument.
Short one-argument syntax
If a block has a single argument and invokes a method on it, the block can be replaced with the short syntax argument.
This:
method do |argument|
argument.some_method
end
and
method { |argument| argument.some_method }
can both be written as:
method &.some_method
Or like:
method(&.some_method)
In either case, &.some_method is an argument passed to method. This argument is syntactically equivalent to the block variants. It is only syntactic sugar and does not have any performance penalty.
If the method has other required parameters, the short syntax argument should also be supplied in the method's argument list.
["a", "b"].join(",", &.upcase)
Is equivalent to:
["a", "b"].join(",") { |s| s.upcase }
Arguments can be used with the short syntax argument as well:
["i", "o"].join(",", &.upcase(Unicode::CaseOptions::Turkic))
Operators can be invoked too:
method &.+(2)
method(&.[index])
yield value
The yield expression itself has a value: the last expression of the block. For example:
def twice
v1 = yield 1
puts v1
v2 = yield 2
puts v2
end
twice do |i|
i + 1
end
The above prints "2" and "3".
A yield expression's value is mostly useful for transforming and filtering values. The best examples of this are Enumerable#map and Enumerable#select:
ary = [1, 2, 3]
ary.map { |x| x + 1 } # => [2, 3, 4]
ary.select { |x| x % 2 == 1 } # => [1, 3]
A dummy transformation method:
def transform(value)
yield value
end
transform(1) { |x| x + 1 } # => 2
The result of the last expression is 2 because the last expression of the transform method is yield, whose value is the last expression of the block.
Type restrictions
The type of the block in a method that uses yield can be restricted using the &block syntax. For example:
def transform_int(start : Int32, &block : Int32 -> Int32)
result = yield start
result * 2
end
transform_int(3) { |x| x + 2 } # => 10
transform_int(3) { |x| "foo" } # Error: expected block to return Int32, not String
break
A break expression inside a block exits early from the method:
def thrice
puts "Before 1"
yield 1
puts "Before 2"
yield 2
puts "Before 3"
yield 3
puts "After 3"
end
thrice do |i|
if i == 2
break
end
end
The above prints "Before 1" and "Before 2". The thrice method didn't execute the puts "Before 3" expression because of the break.
break can also accept arguments: these become the method's return value. For example:
def twice
yield 1
yield 2
end
twice { |i| i + 1 } # => 3
twice { |i| break "hello" } # => "hello"
The first call's value is 3 because the last expression of the twice method is yield, which gets the value of the block. The second call's value is "hello" because a break was performed.
If there are conditional breaks, the call's return value type will be a union of the type of the block's value and the type of the many breaks:
value = twice do |i|
if i == 1
break "hello"
end
i + 1
end
value # :: Int32 | String
If a break receives many arguments, they are automatically transformed to a Tuple:
values = twice { break 1, 2 }
values # => {1, 2}
If a break receives no arguments, it's the same as receiving a single nil argument:
value = twice { break }
value # => nil
next
The next expression inside a block exits early from the block (not the method). For example:
def twice
yield 1
yield 2
end
twice do |i|
if i == 1
puts "Skipping 1"
next
end
puts "Got #{i}"
end
# Output:
# Skipping 1
# Got 2
The next expression accepts arguments, and these give the value of the yield expression that invoked the block:
def twice
v1 = yield 1
puts v1
v2 = yield 2
puts v2
end
twice do |i|
if i == 1
next 10
end
i + 1
end
# Output
# 10
# 3
If a next receives many arguments, they are automatically transformed to a Tuple. If it receives no arguments it's the same as receiving a single nil argument.
with ... yield
A yield expression can be modified, using the with keyword, to specify an object to use as the default receiver of method calls within the block:
class Foo
def one
1
end
def yield_with_self
with self yield
end
def yield_normally
yield
end
end
def one
"one"
end
Foo.new.yield_with_self { one } # => 1
Foo.new.yield_normally { one } # => "one"
Unpacking block arguments
A block argument can specify sub-arguments enclosed in parentheses:
array = [{1, "one"}, {2, "two"}]
array.each do |(number, word)|
puts "#{number}: #{word}"
end
The above is simply syntax sugar of this:
array = [{1, "one"}, {2, "two"}]
array.each do |arg|
number = arg[0]
word = arg[1]
puts "#{number}: #{word}"
end
That means that any type that responds to [] with integers can be unpacked in a block argument.
For Tuple arguments you can take advantage of auto-splatting and do not need parentheses:
array = [{1, "one", true}, {2, "two", false}]
array.each do |number, word, bool|
puts "#{number}: #{word} #{bool}"
end
Hash(K, V)#each:Nil-instance-method) passes Tuple(K, V) to the block so iterating key-value pairs works with auto-splatting:
h = {"foo" => "bar"}
h.each do |key, value|
key # => "foo"
value # => "bar"
end
Performance
When using blocks with yield, the blocks are always inlined: no closures, calls or function pointers are involved. This means that this:
def twice
yield 1
yield 2
end
twice do |i|
puts "Got: #{i}"
end
is exactly the same as writing this:
i = 1
puts "Got: #{i}"
i = 2
puts "Got: #{i}"
For example, the standard library includes a times method on integers, allowing you to write:
3.times do |i|
puts i
end
This looks very fancy, but is it as fast as a C for loop? The answer is: yes!
This is Int#times definition:
struct Int
def times
i = 0
while i < self
yield i
i += 1
end
end
end
Because a non-captured block is always inlined, the above method invocation is exactly the same as writing this:
i = 0
while i < 3
puts i
i += 1
end
Have no fear using blocks for readability or code reuse, it won't affect the resulting executable performance.