Toit blocks

Blocks are a mechanism to conveniently and efficiently provide callbacks to functions. This mechanism is, for example, used for the methods int.repeat and List.do.

main:
  // Print the numbers from 1 to 10, one per line.
  10.repeat:
    print it + 1

  // Print the elements in the list, one per line.
  ["what", "a", "list"].do:
    print it

Here we used the automatic block argument, it, see below

Syntactically repeat and do look like they are built-in to the language like for and if are, but they are actually normal methods that use the block feature.

Basic use of blocks

Blocks are used extensively in the Toit standard library, so you need to know the basics of calling functions that accept blocks. A function that takes a block as an argument surrounds the parameter with brackets [ ]. For example, the function signature of int.repeat is

repeat [block]:
  // ...

The [block] parameter states that the repeat function takes exactly one argument which must be a block (because of the [ and ]).

On the caller side, block arguments look like a scope for if or for. For example, if you want to call repeat, you could write

main:
  4.repeat:
    print "again"

Just like for if and for, you can choose to put single line blocks on the same line as the call. For example

main:
  4.repeat: print "again"

Block arguments

Blocks often receive arguments when they are called as callbacks. For instance, List.do iterates over a list and calls the block with every element. When the block receives one argument you can refer to the argument with the keyword it. For example

main:
  ["Siri", "John", "Sue"].do:
    print it

prints

Siri
John
Sue

You can name the parameter of the block if you want to use something else than it. To do so, you start the block with the name enclosed in pipes |. For example

main:
  ["Siri", "John", "Sue"].do: | name |
    print name

prints

Siri
John
Sue

Some blocks receive more than one argument. In that case you have to use the | notation. You just write all the names in between the two pipes. For example, Map.do iterates all the key-value pairs of a Map, and calls the block with the key as the first argument and the value as the second:

main:
  map ::= {
    1234: "Siri",
    2345: "John",
    3456: "Sue"
    }
  map.do: | id name |
    print "$name has ID $id"

which prints

Siri has ID 1234
John has ID 2345
Sue has ID 3456

If a block accepts multiple arguments, but you only need to refer to the first, then you can omit the naming and just use it. If there are parameters that you don't need, then you can use a wildcard _ instead of giving them a name.

Returning from blocks and accessing variables

Blocks look like they are built-in which makes it important that they also act like they are built-in. This means that returning from a block with return, or accessing local variables must just work.

Non-local return

The non-local return is the most common return from blocks. It is best explained based on an example:

/**
Takes a list $list and returns the first negative number.
Returns null if $list contains no negative number.
*/
first_negative list:
  list.do:
    if it < 0: return it
  return null

main:
  print
    first_negative [1, 2, 3, -3, -2, -1]

which would print

-3

The return it in first_negative is a non-local return which means that it doesn't just return from the block or do, it returns from first_negative. This means that we can short circuit the search when we find the first negative number.

Local return

In some situations, it is useful to do a local return. That is, to just return from the block. To do this, you use the continue keyword followed by a dot . and the label of the function you want to continue in. For example

/**
Takes a list of integers $list and maps it to a list of
  odd numbers by incrementing even numbers by one.
*/
oddify list:
  return list.map:
    if it % 2 == 0:
      continue.map it + 1
    continue.map it

main:
  list := [1, 2, 3, 4]
  print
    oddify list

which prints

[1, 3, 3, 5]

Here the block given to map uses continue to do a local return of an odd value when it sees an even value. The snippet continue.map can be read as "continue in the map function".

Default return

The default return of a block is a local return. The block returns the value of the last statement in the block. For example

/**
Takes a list of words, and returns a new list with only the
  words that are 5 characters or fewer.
*/
short_words words:
  return words.filter:
    it.size < 6

main:
  words := ["word", "small", "minuscule", "tiny"]
  print
    short_words words

Here the block accepted by filter returns the value of the last statement which is it.size < 6, a boolean that indicates whether the size of the element is less than 6.

It prints

[word, small, tiny]

In the oddify example in section Local return, the last local return was unnecessary. If you replace continue.map it with it, then the block uses the default local return to return it from the block. That is

/**
Takes a list of integers $list and maps it to a list of odd
  numbers by incrementing even numbers by one.
*/
oddify list:
  return list.map:
    if it % 2 == 0:
      continue.map it + 1
    it

main:
  list := [1, 2, 3, 4]
  print
    oddify list

prints

 [1, 3, 3, 5]

Blocks referencing variables

Blocks can reference everything that can be referenced from the scope the block was defined in. This includes access to local variable, field variables, and globals.

my_stringify list -> string:
  is_first := true
  str := "["
  list.do:
    str += "$(is_first ? "" : ", ")$it"
    is_first = false
  str += "]"
  return str

main:
  print
    my_stringify [1, 2, 3]

Here the block (given to do) references both is_first and str. Notice that the block both accesses and modifies the variables.

The function returns a string representation of the list corresponding to the exact syntactic construct that creates a list, and thus prints

 [1, 2, 3]

Examples of block usage

Many for-loops follow a common pattern, where the loop uses a loop-variable to count from 0 to a given limit. For example say you want a function that prints the numbers from 1 to n, you could write

/// Prints the numbers from 1 to $n on separate lines.
print_numbers n:
  for i := 0; i < n; i++:
    print i + 1

main:
    print_numbers 5

As you can see, the for-loop is mostly boilerplate code. All you want to express is that the print statement should be executed n times. This is where blocks come in handy. We can rewrite the above snippet using int.repeat:

/// Prints the numbers from 1 to $n on separate lines.
print_numbers n:
  n.repeat:
    print it + 1

main:
    print_numbers 5

The new code isn't just shorter, but also expresses the intent more clearly.

We can do the same exercise for list iterations. Say you have written a function that prints the elements of a list:

/// Prints the elements of the list on separate lines.
print_list list:
  for i := 0; i < list.size; i++:
    print list[i]

main:
    print_list [1, 2, 3, 4, 5]

Again, you can use int.repeat to rewrite the for-loop:

/// Prints the elements of the list on separate lines.
print_list list:
  list.size.repeat:
    print list[it]

main:
  print_list [1, 2, 3, 4, 5]

Now the example is shorter, but it is still not clear what the intend is. You can do even better than the above. The collections in the Toit standard library have do functions that iterate the collections and call a block for each element. You can rewrite print_list to

/// Prints the elements of the list on separate lines.
print_list list:
  list.do:
    print it

main:
  print_list [1, 2, 3, 4, 5]

Now the intend is clear: you are do'ing something to the list which corresponds to visiting each element of the list.

Calling functions with named block parameters

Block parameters can also be named. This is indicated in the function signature by enclosing the named parameter in brackets [ ] (the same as for other block parameters). For instance, the signature of Map.remove is

remove key [--if_absent] -> none:

The named parameter is given in the same way as normal block parameter. For example we could make a throwing remove for Map

class Map:
  // ...

  throw_remove key:
    remove key --if_absent=:
      throw "No such entry"

We could also implement a remove that ignores the absence of a key:

class Map:
  // ...

  remove key:
    remove key --if_absent=: null

A function can take multiple blocks as arguments. Take the Map.get signature as an example:

get key [--if_present] [--if_absent]:

Map.get takes two block arguments. For the sake of readability, it is

announcer map key:
  map.get key
    --if_present=: | value |
      print "Proudly presenting $value!"
    --if_absent=:
      print "Unable to find $key"

main:
  map ::= {
    1: "Siri",
    2: "John",
    3: "Sue"
  }
  announcer map 1
  announcer map 4

This prints

Proudly presenting Siri!
Unable to find 4

Here we have formatted the arguments differently, so each of the block arguments are easily identified.

Blocks as values

Blocks are values in Toit which is why functions accept them as arguments. A block value is defined as a colon : followed by the body of the block which is either a statement on the same line of the block, such as : null, or a series of statements on separate lines following the : (all statements indented), such as

main:
  print "multi"
  print "line"

In all the examples so far where we have passed blocks as arguments to function, we were really defining the block value in place. Because blocks are values, they can be stored in local variables, just like other values. For example

main:
  block_variable := : print it + 1
  10.repeat block_variable

Syntactically, it looks a bit cryptic when blocks are stored in local variables. However, the main purpose of blocks is to pass snippets of code to functions.

Blocks aren't just "normal" functions as in other programming languages. They are much more efficient, but also come with some restrictions.

Restrictions

Blocks are stack allocated, which is what makes them so efficient, but it also limits where they can be used:

  • Blocks cannot be stored in instance fields, static class fields, and globals.

  • Blocks cannot be returned from functions and methods.

  • Lambdas cannot capture blocks.

  • Blocks cannot take blocks as arguments.

Defining functions that take block arguments

You can define your own functions that accept block arguments. You have already seen what the function signature should look like: block arguments must be enclosed by brackets [ ].

In order to execute a block, you simply call call on it. For example, this is how int.repeat is implemented:

class int:
  // ...
  repeat [block]:
    for i := 0; i < this; i++:
      block.call i

Note: non-named block parameters have to be the last in the function signature.