---
title: "1.4 Writing a function"
url: https://una-lang.org/en/learn/hello/writing-a-function/
release: v0.4.0
edition: "0.2"
---

# 1.4 Writing a function

## 1.4.1 What a function is

A **function** is a named piece of a program. It may take inputs, it does its work, and it may give back a value when it is done. Think of a price lookup at a till: you give it a SKU, the code of a product, and it gives back the price. You need only its name, what to give it, and what it gives back; you do not need to know how it finds the price.

A function's inputs are its **parameters**, and what it gives back is its **result**. Using a function is a **call**: you write its name and, in parentheses, the values it should work with, its **arguments**. The code that makes the call is the **caller**, and the call stands for the result.

A **value** is one piece of data a program works with, such as the text `"Good morning"`. Every value has a **type**, the kind of value it is: a text in double quotes has the type `Text`. [Chapter 2](https://una-lang.org/en/learn/numbers/values-types-and-names-let/#s2-1) covers values and types in full, and [chapter 3](https://una-lang.org/en/learn/text-and-conditions/text/#s3-1) covers text.

## 1.4.2 Why programs use functions

Here is a board by the entrance of a store, with the hours at the top and again at the bottom:

```una include="steps/10-repeated/src/board.una#main" title="src/board.una" verified="check, run"
--- Prints the board by the entrance: the hours at the top and again at the bottom.
pub main() -> Unit
  uses @console: Console[print]
=
  @console.print("Open today from 9:00 to 18:00")
  @console.print("Fresh stock: desk lamps and wool rugs")
  @console.print("The café opens at 10:00")
  @console.print("Open today from 9:00 to 18:00")
```

It works, but the hours are written twice. When the store changes its hours, you must change two lines, and a missed one prints two different hours on the same board. A function that gives back the hours writes them once:

```una include="steps/11-function/src/board.una" title="src/board.una" verified="check, run"
module board

--- When the store is open today.
pub opening_hours() -> Text = "Open today from 9:00 to 18:00"

--- Prints the board by the entrance: the hours at the top and again at the bottom.
pub main() -> Unit
  uses @console: Console[print]
=
  @console.print(opening_hours())
  @console.print("Fresh stock: desk lamps and wool rugs")
  @console.print("The café opens at 10:00")
  @console.print(opening_hours())
```

Both versions print the same board:

```text include="steps/11-function/expected/output.txt"
Open today from 9:00 to 18:00
Fresh stock: desk lamps and wool rugs
The café opens at 10:00
Open today from 9:00 to 18:00
```

Now the hours live in one place, under one name, `opening_hours`. A change there changes every line that uses it, and the name tells the reader what the text is.

## 1.4.3 How to write a function

A function is a header and a body. The function `opening_hours` takes no parameters and gives back a text:

:::steps
```una include="steps/11-function/src/board.una#opening_hours" title="src/board.una"
--- When the store is open today.
pub opening_hours() -> Text = "Open today from 9:00 to 18:00"
```

1. **`pub`.** Public, as for `main`: other modules may call it. Leave it out, and only its own module can.
2. **`opening_hours`.** The name: small letters, digits and `_`, starting with a letter, with no `__` and no `_` at the end. A good name says what the result is.
3. **`()`.** The parameters, in parentheses. `()` means none.
4. **`-> Text`.** The type of the result: this function gives back a text.
5. **`= "Open today from 9:00 to 18:00"`.** The body: the value the function gives back.
:::

A call writes the name and the parentheses: `opening_hours()` stands for the text `"Open today from 9:00 to 18:00"`. The parentheses are needed even when there are no arguments. In `main`, `@console.print(opening_hours())` first calls `opening_hours`, then prints the text the call gives back.

## 1.4.4 The forms of a function

The module `notices` has one function of each form, and a `main` that calls them:

```una include="steps/12-function-forms/src/notices.una" title="src/notices.una" verified="check, run"
module notices

--- When the store is open today: a function with no parameters, in the short form.
pub opening_hours() -> Text = "Open today from 9:00 to 18:00"

-- A private function: no `pub`, so only this module can call it.
cafe_hours() -> Text = "The café opens at 10:00"

--- Prints a heading and the notice under it: a function with two parameters, in the long
--- form, since its body has two steps.
pub section(heading: Text, notice: Text) -> Unit
  uses @console: Console[print]
=
  @console.print(heading)
  @console.print(notice)

--- Calls each function.
pub main() -> Unit
  uses @console: Console[print]
=
  section("Hours", notice: opening_hours())
  section("Café", notice: cafe_hours())
```

`una run .` prints:

```text include="steps/12-function-forms/expected/output.txt"
Hours
Open today from 9:00 to 18:00
Café
The café opens at 10:00
```

### 1.4.4.1 The short form: a body of one line

`opening_hours` has a body of one line, written on the header's line after `=`. This is the **short form**. Una asks for it whenever a function has no `uses` line and its body is one line: `una fmt .`, which lays code out the way Una expects, writes such a function this way.

### 1.4.4.2 Parameters, and labels at the call

`section(heading: Text, notice: Text)` takes two parameters, separated by a comma. Each is a name, `:` and a type. Inside the body, `heading` and `notice` stand for the arguments of the call.

A call with more than one argument names every argument after the first, with its parameter's name and `:`. The call `section("Hours", notice: opening_hours())` passes `"Hours"` as `heading`, since the first argument goes without its name, and the result of `opening_hours()` as `notice`. The name, the **label**, makes the call read the same a year from now, without a look at the header. One shorthand exists: an argument that is a name equal to its parameter's, such as `notice` for the parameter `notice`, counts as labeled ([section 6.1](https://una-lang.org/en/learn/functions/calls-in-depth-labels-the-order-of-evaluation-method-calls-on-your-own-kinds/#s6-1)).

### 1.4.4.3 The long form: a body of several steps

`section` has a body of two steps, so it is written in the **long form**: the header, `=` alone on its line, then the body, indented two spaces. The steps run in order, as in `main`. A function with a `uses` line is always written in the long form.

### 1.4.4.4 A function that gives back nothing: `Unit`

`section` is called for what it does, printing two lines, not for a value, so its result type is `Unit`, as `main`'s is. A call of it stands on its own line in a body, as a step: `section("Café", notice: cafe_hours())`.

### 1.4.4.5 Public and private

`cafe_hours` has no `pub`, so it is **private**: only the module `notices` can call it. Keep a function private until another module needs it. Here a plain `--` comment says what it is; a doc comment would do too, but it matters most on a public function, whose readers see its header and not its body.

## 1.4.5 How a call behaves

- **The arguments are worked out first.** In `section("Hours", notice: opening_hours())`, the call `opening_hours()` runs first, and its text becomes `notice`. Then the body of `section` runs.
- **The caller waits.** While `section` runs, `main` waits. When the body of `section` ends, `main` goes on with its next step.
- **A call gives back the type its header says.** `opening_hours()` is always a `Text`. Una checks the body against the header: change the body of `cafe_hours` to the number `10`, a value of type `Int`, the type of whole numbers ([chapter 2](https://una-lang.org/en/learn/numbers/)), and `una check .` reports:

```text include="steps/15-wrong-result/expected/rendered.txt#L1"
[U2001] Error: `cafe_hours` returns `Text`, found `Int`
```

- **Every parameter gets an argument.** Leave out the notice, `section(opening_hours())`, and the call is short of an argument:

```text include="steps/14-missing-argument/expected/rendered.txt#L1"
[U2001] Error: `section` is missing argument `notice`
```

- **The second argument carries its label.** Leave out `notice:`, as in `section("Hours", opening_hours())`, and `una check .` reports:

```text include="steps/13-missing-label/expected/rendered.txt"
[U2004] Error: argument 2 of `section` needs a label; only the first argument may go without one
    ╭─[ src/notices.una:21:20 ]
    │
 21 │   section("Hours", opening_hours())
    │                    ───────┬───────
    │                           ╰───────── argument 2 of `section` needs a label; only the first argument may go without one
    │
    │ Help: repair 1: label it `notice`; edit src/notices.una:21:20..21:35 to "notice: opening_hours()"
    │
    │ Note: run `una explain U2004` for an explanation
────╯
1 of 1 diagnostics have an edit that `una fix` applies (`una fix --dry-run` lists them)
```

The message says which argument needs a label, the second, and the `Help` line gives the exact repair: label it `notice`.

## 1.4.6 When to write a function

:::decide
**Which to use:**

| You want to… | Use |
| --- | --- |
| Use the same text in several places | a function that gives it back, such as `opening_hours()` |
| Give a few steps a name, and run them from several places | a function with a body of several steps, such as `section` |
| Keep a helper to its own module | a function without `pub` |
| Start the program | `pub main() -> Unit` in the entry module |
:::

## 1.4.7 Check yourself: functions

The help desk of a store prints this:

```una include="steps/16-order-of-calls/src/desk.una" title="src/desk.una"
module desk

--- Where customers can ask a question.
pub help_desk() -> Text = "Ask at the help desk by the main door"

--- Prints a heading and the notice under it.
pub section(heading: Text, notice: Text) -> Unit
  uses @console: Console[print]
=
  @console.print(heading)
  @console.print(notice)

--- Prints two sections, with a line of its own between them.
pub main() -> Unit
  uses @console: Console[print]
=
  section("Questions", notice: help_desk())
  @console.print("Thank you for shopping with us")
  section("Lost something?", notice: help_desk())
```

What does `una run .` print?

:::answer Show the answer
```text include="steps/16-order-of-calls/expected/output.txt"
Questions
Ask at the help desk by the main door
Thank you for shopping with us
Lost something?
Ask at the help desk by the main door
```

`main` has three steps, run in order. The first and the last call `section`, which prints its heading and then its notice, the text `help_desk()` gives back. The step between them prints its own line. The same text appears twice, written once.
:::
