Home / Learn / 1 Hello, Una

Release v0.4.0Edition 0.2

1.4 Writing a function

Page 5 of 11

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 covers values and types in full, and chapter 3 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:

src/board.unacheckrununa
--- 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:

src/board.unacheckrununa
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:

Output
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:

src/board.unauna
--- 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:

src/notices.unacheckrununa
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:

Output
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).

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

Diagnostic
[U2001] Error: `cafe_hours` returns `Text`, found `Int`
Diagnostic
[U2001] Error: `section` is missing argument `notice`
Diagnostic
[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

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:

src/desk.unauna
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?

Show the answer
Output
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.

Next:1.5 Printing: the console, print and uses