---
title: "7.1 A value that may be missing: Option"
url: https://una-lang.org/en/learn/failure/a-value-that-may-be-missing-option/
release: v0.4.0
edition: "0.2"
---

# 7.1 A value that may be missing: Option

## 7.1.1 What an `Option` is

Some questions have no answer. Ask a store for the price of a product it does not sell, ask the text `"seven"` for the number it holds, or ask a SKU for the position of a `/` it does not have: there is nothing to give back. An **`Option`** is the type of an answer that may be missing. Think of a parcel locker at a pickup point: you open it, and either a parcel is inside or the locker is empty. Before you carry anything away, you look.

`Option[T]` is a generic sum kind of the prelude ([section 4.4](https://una-lang.org/en/learn/kinds/generic-kinds-and-constraints/#s4-4)) with two variants:

- `Some(value)` holds one value of the type `T`. A price lookup that finds the price gives `Some(1990)`, an `Option[Int]`.
- `None` holds nothing. It means "there is no value here".

`T` is the **type parameter**: it stands for whatever type the option may hold. `Option[Int]` may hold an `Int`, and `Option[Product]` a `Product`. An `Option[Int]` is not an `Int`: you cannot add it to a number, compare it with `<`, or use it where an `Int` is expected, until you have said what happens when it is `None`.

## 7.1.2 Why absence needs its own type

In many languages a search that finds nothing returns a special value, often called null, of the same type as a real answer. The type then says that a product is always there, and the first line that uses a missing product fails while the program runs, often far from the search.

In Una the type says it. Each example of this chapter is a package, made as [chapter 2](https://una-lang.org/en/learn/numbers/values-types-and-names-let/#each-step-is-a-package) explains, and the chapter's download, `07-failure.tar.gz`, holds them all. Here, `find_product` gives back an `Option[Product]`, and `price_of` reads the price from it as if the product were always found:

```diff include="steps/01-option..steps/02-missing-price:src/lookup.una" context="1" title="src/lookup.una"
--- a/src/lookup.una
+++ b/src/lookup.una
@@ -21,5 +21,3 @@
   let found = find_product(sku)
-  when found
-    is Some(product) -> Some(product.cents)
-    is None -> None
+  Some(found.cents)
 
```

`una check .` reports:

```text include="steps/02-missing-price/expected/rendered.txt"
[U1001] Error: `Option[Product]` has no field `cents`, and no function `cents` in scope applies
    ╭─[ src/lookup.una:22:14 ]
    │
 22 │   Some(found.cents)
    │              ──┬──
    │                ╰──── `Option[Product]` has no field `cents`, and no function `cents` in scope applies
    │
    │ Note: run `una explain U1001` for an explanation
────╯
```

Read it from the top. `found` is an `Option[Product]`, and the message says that this type has no field `cents`: the field belongs to `Product`, which the option may or may not hold. The mark points at `.cents`. The checker does not guess what a missing product should mean. You decide, with one of the forms of the next part, and the decision is written where the value is used.

## 7.1.3 How to write and use an `Option`

The step of this part shows each form on a shelf count, which a clerk may not have taken yet:

```una include="steps/03-option-forms/src/counts.una#shown..typed_units" title="steps/03-option-forms/src/counts.una"
--- What a shelf label shows for a count that may be missing: `when` with both arms.
shown(count: Option[Int]) -> Text
=
  when count
    is Some(units) -> "{units} on the shelf"
    is None -> "not counted yet"

--- Whether a shelf holds more than 10 units: `when` with an `else` arm.
well_stocked(count: Option[Int]) -> Bool
=
  when count
    is Some(units) -> units > 10
    else -> false

--- The units to order for a shelf: a missing count orders a full shelf of 12.
to_order(count: Option[Int]) -> Int = 12 - count.or_else(default: 0)

--- Whether a shelf still needs counting: a test of the variant, in a condition.
needs_count(count: Option[Int]) -> Bool = count is None

--- The units typed by a clerk, or 0 when the text is not a number: `if none use`.
typed_units(raw: Text) -> Int
=
  let units = raw.trim.to_int()
    if none use 0
  units
```

### 7.1.3.1 Making one: `Some`, `None`, and the functions that return one

```una include="steps/03-option-forms/src/counts.una#L33-L35" title="steps/03-option-forms/src/counts.una"
  let counted = Some(14)
  let missing: Option[Int] = None
  @console.print("{counted} {missing}")
```

```text include="steps/03-option-forms/expected/output.txt#L1"
Some(14) None
```

`Some(14)` wraps a value. `None` holds nothing, so it says nothing about the type: write the type on the name, `let missing: Option[Int] = None`, as [section 2.1](https://una-lang.org/en/learn/numbers/values-types-and-names-let/#s2-1) shows for any `let`. More often an `Option` comes from a function. Two functions of the prelude on a text return one: `to_int`, which reads a whole number, and `find`, which gives the position of the first place a smaller text appears:

```una include="steps/03-option-forms/src/counts.una#L44-L48" title="steps/03-option-forms/src/counts.una"
  let sku = "LAMP-01"
  let dash = sku.find(text: "-")
  let number = sku.slice(start: 5, end: 7).to_int()
  let slash = sku.find(text: "/")
  @console.print("{dash} {number} {slash}")
```

```text include="steps/03-option-forms/expected/output.txt#L8"
Some(4) Some(1) None
```

`find` gives the position of the first `-` in `LAMP-01`, counted from 0. `to_int` reads the digits `01` as 1. `LAMP-01` has no `/`, so the last search gives `None`.

### 7.1.3.2 Both cases: `when`

A `when` ([section 4.3](https://una-lang.org/en/learn/kinds/taking-a-sum-apart-when/#s4-3)) takes an `Option` apart, as it takes apart any sum kind. `shown` has one arm per variant: `is Some(units)` binds the value inside to the name `units`, and `is None` says what to do without one. Each arm gives a `Text`, so the `when` gives one too.

```una include="steps/03-option-forms/src/counts.una#L36" title="steps/03-option-forms/src/counts.una"
  @console.print("{shown(counted)} / {shown(missing)}")
```

```text include="steps/03-option-forms/expected/output.txt#L2"
14 on the shelf / not counted yet
```

### 7.1.3.3 One case and the rest: `else`

When only the `Some` case needs work, an `else` arm covers the other. `well_stocked` answers `false` for a missing count:

```una include="steps/03-option-forms/src/counts.una#L37" title="steps/03-option-forms/src/counts.una"
  @console.print("{well_stocked(counted)} {well_stocked(missing)}")
```

```text include="steps/03-option-forms/expected/output.txt#L3"
true false
```

### 7.1.3.4 A default: `or_else`

`count.or_else(default: 0)` is the value inside `Some`, or the default for `None`. It is the short form of a `when` whose `None` arm is a plain value. `to_order` orders a full shelf of 12 units when no count is known:

```una include="steps/03-option-forms/src/counts.una#L38" title="steps/03-option-forms/src/counts.una"
  @console.print("{to_order(Some(5))} {to_order(missing)}")
```

```text include="steps/03-option-forms/expected/output.txt#L4"
7 12
```

### 7.1.3.5 A question about the case: `is None` and `is_some`

`count is None` is a condition, `true` or `false`, that tests the variant with `is` ([section 4.2](https://una-lang.org/en/learn/kinds/sum-kinds-and-is/#s4-2)) without taking the value out. `is_some()` asks the same question the other way round:

```una include="steps/03-option-forms/src/counts.una#L39" title="steps/03-option-forms/src/counts.una"
  @console.print("{needs_count(missing)} {missing.is_some()}")
```

```text include="steps/03-option-forms/expected/output.txt#L5"
true false
```

### 7.1.3.6 A default under the line: `if none use`

`typed_units` writes the default on its own line under the call: `if none use 0`. After that line, `units` is a plain `Int`. This line is a **handling clause**. It and `if none fail`, which turns a missing value into a failure, are taught with the other clauses in [section 7.3](https://una-lang.org/en/learn/failure/handling-a-failure-the-clauses/#s7-3).

```una include="steps/03-option-forms/src/counts.una#L40-L42" title="steps/03-option-forms/src/counts.una"
  let typed = typed_units(" 7 ")
  let spelled = typed_units("seven")
  @console.print("{typed} {spelled}")
```

```text include="steps/03-option-forms/expected/output.txt#L6"
7 0
```

## 7.1.4 Looking up a price

The forms together, in a price lookup. `find_product` makes the option, `price_of` passes the absence on to its caller, and `label` decides what it means:

:::steps
```una include="steps/01-option/src/lookup.una" title="steps/01-option/src/lookup.una" verified="check, run"
module lookup

--- A product the store sells, with the price of one unit in cents.
kind Product
  sku: Text
  cents: Int

--- The product with the SKU `sku`, or `None` when the store does not sell it.
find_product(sku: Text) -> Option[Product]
=
  if sku == "LAMP-01"
    Some(Product(sku: "LAMP-01", cents: 1990))
  else if sku == "DESK-02"
    Some(Product(sku: "DESK-02", cents: 15900))
  else
    None

--- The price of `sku`, or `None` when the store does not sell it.
price_of(sku: Text) -> Option[Int]
=
  let found = find_product(sku)
  when found
    is Some(product) -> Some(product.cents)
    is None -> None

--- What a product page shows for `sku`.
label(sku: Text) -> Text
=
  let price = price_of(sku)
  when price
    is Some(cents) -> "{sku}: {cents} cents"
    is None -> "{sku}: not sold here"

--- Prints two product pages, and three values that may be missing.
pub main() -> Unit
  uses @console: Console[print]
=
  @console.print(label("DESK-02"))
  @console.print(label("CHAIR-09"))
  let missing = price_of("CHAIR-09")
  @console.print("{missing} or {missing.or_else(default: 0)}")
  let typed = "3".to_int()
  let dash = "LAMP-01".find(text: "-")
  @console.print("{typed} and {dash}")
```

1. **`find_product(sku: Text) -> Option[Product]`.** A function of your own that returns an `Option`: `Some` with the product for the two SKUs the store sells, and `None` for any other. Each branch of the `if` ([section 3.4](https://una-lang.org/en/learn/text-and-conditions/choosing-between-two-values-if/#s3-4)) gives an `Option[Product]`.
2. **`when found`.** One arm per case, `is Some(product)` and `is None`. The name in `Some(product)` binds the value inside.
3. **`Some(product.cents)`.** `price_of` itself returns an `Option`, so its caller decides what a missing price means. `label` decides: it prints "not sold here".
4. **`missing.or_else(default: 0)`.** The short form when a default is right: the value inside `Some`, or the default for `None`.
5. **`"3".to_int()` and `"LAMP-01".find(text: "-")`.** Two functions of the prelude that return an `Option`.
:::

`una run .` prints:

```text include="steps/01-option/expected/output.txt"
DESK-02: 15900 cents
CHAIR-09: not sold here
None or 0
Some(3) and Some(4)
```

An `Option` is printed as `Some(3)` or `None`, which helps while you look for a mistake, but a report should say what the absence means, as `label` does.

## 7.1.5 How an `Option` behaves

### 7.1.5.1 A `when` covers both cases

A `when` over an `Option` must have an arm for `Some` and one for `None`, or an `else`. Leave the `None` arm out of `shown`, and `una check .` reports:

```text include="steps/04-no-none-arm/expected/rendered.txt"
[U2007] Error: `when` does not match variant `None` of `Option`
   ╭─[ src/counts.una:6:3 ]
   │
 6 │   when count
   │   ──┬─
   │     ╰─── `when` does not match variant `None` of `Option`
   │
   │ Help: repair 1: add an arm for each missing variant, such as `is None`, or an `else` arm
   │
   │ Note: run `una explain U2007` for an explanation
───╯
```

The message names the variant that has no arm, `None`, and the mark points at the `when`. The `Help` line gives both repairs: an arm `is None`, or an `else` arm. So when the day comes that a value is missing, the program already says what to do.

### 7.1.5.2 Options compare by what they hold

```una include="steps/03-option-forms/src/counts.una#L43" title="steps/03-option-forms/src/counts.una"
  @console.print("{counted == Some(14)} {missing == None}")
```

```text include="steps/03-option-forms/expected/output.txt#L7"
true true
```

`Some(14) == Some(14)` holds, and `None == None` holds. `Some(0)` and `None` differ: a count of zero is a count, and a missing count is not.

### 7.1.5.3 The default of `or_else` is computed first

> [!NOTE]
> The default of `or_else` is an argument like any other, so it is computed before the call, whether it is used or not. Keep it a plain value, such as `0` or `"other"`. A call that prints or can fail cannot be the default: give its result a name with `let` first.

## 7.1.6 Choosing how to use an `Option`

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

| You want to… | Use |
| --- | --- |
| Do different things when the value is there and when it is not | `when` with `is Some(v)` and `is None` |
| Work only on the value, with one answer for the rest | `when` with `is Some(v)` and `else` |
| Carry on with a default | `or_else(default: v)`, or `if none use v` on the line under the call ([section 7.3](https://una-lang.org/en/learn/failure/handling-a-failure-the-clauses/#s7-3)) |
| Know only whether there is a value | `is_some()`, or `o is None` in a condition |
| Make a missing value a failure of your function | `if none fail V` ([section 7.3](https://una-lang.org/en/learn/failure/handling-a-failure-the-clauses/#s7-3)) |
:::

Prefer a `when` when the absence needs its own words, as on a product page. Prefer `or_else` when the default is the honest answer, as 0 units on a shelf nobody stocked.

## 7.1.7 Check yourself: `Option`

The three functions of [How to write and use an `Option`](#how-to-write-and-use-an-option) get one more set of counts:

```una include="steps/03-option-forms/src/counts.una#L49" title="steps/03-option-forms/src/counts.una"
  @console.print("{shown(Some(0))} / {to_order(Some(12))} / {well_stocked(Some(10))}")
```

What does the line print?

:::answer Show the answer
```text include="steps/03-option-forms/expected/output.txt#L9"
0 on the shelf / 0 / false
```

`Some(0)` is a count of zero, not a missing count, so `shown` takes the `Some` arm. `to_order(Some(12))` is 12 − 12 = 0. `well_stocked(Some(10))` takes the `Some` arm, and 10 > 10 is `false`.
:::
