Skip to content

4. Functions

Every step in a pipeline takes a function. filter takes the test that keeps an element, map the function that transforms one, sort the key to order by. Functions are the part of an HQL program you write most often, and they are values: a function can be bound to a name, passed to a step, and returned from another function.

A function has a type, written with an arrow: Int -> Int takes an Int and returns an Int. The type is a contract between the function and the code that calls it, and hql checks both sides before the program runs:

fn days(pages: Int, per_day: Int) : Int = (pages + per_day - 1) / per_day
days("412", 40)
check error[type-mismatch]: this argument is String, and parameter `pages` takes Int
 --> <expression>:2:6
  |
2 | days("412", 40)
  |      ^^^^^
fn label(pages: Int) : String = pages
label(412)
check error[type-mismatch]: `label` is declared to return String but its body is Int
 --> <expression>:1:33
  |
1 | fn label(pages: Int) : String = pages
  |                                 ^^^^^

The first program calls days with the wrong argument. The second has a body that does not return what the declaration promises. A function's caller can rely on its declared type, and the body can rely on its parameters.

HQL writes functions in several forms. Each one gives a function value with a type, and each value is used the same way:

d2 diagram

Lambdas

n => n * 2 is a lambda: a function written in place, with its parameters before => and its body after it. Passed to a step, a lambda takes its parameter type from the step, so n below is an Int:

[412, 280] | map(n => n * 2)
[824, 560]

The checker uses that type to check the body. A body that does not fit the element type is rejected:

[412, 280] | map(n => n.upper())
check error[type-mismatch]: `upper` needs String, not Int
 --> <expression>:1:23
  |
1 | [412, 280] | map(n => n.upper())
  |                       ^^^^^^^^^

A lambda bound to a name has no step to take its type from, so its parameters must be typed:

double = (n: Int) => n * 2
[412, 280] | map(double)
[824, 560]
double = (n: Int) => n * 2
double
Int -> Int

A function of two parameters has the type (Int, Int) -> Int. A lambda's body is a single expression. A function that needs several steps is declared with fn.

Calling a function

f(x) calls a function. A pipe calls one too: x | f is f(x), and x | f(y) is f(x, y). The piped value becomes the first argument:

fn days(pages: Int, per_day: Int) : Int = (pages + per_day - 1) / per_day
[days(412, 40), 412 | days(40)]
[11, 11]

This is why steps such as map and filter read left to right: each is a function whose first argument is the value piped into it.

In this chapter

Page What it covers
Declaring a function fn, typed parameters and result, recursion, functions taken and returned, variadic parameters
Function bodies a body as one expression or as a block, and how a block is scoped
Generic functions type parameters, and bounds on them
Aliases and holes naming a pipeline fragment with :=, and leaving an argument open with _

What is next

Chapter 5 moves functions into modules: files that a program imports, with public and private declarations.