Home / Docs / Language guide / Expressions and control flow

when

Release v0.4.0Edition 0.1 and laterU0101U2001U2007U2008U2022U4002U4008U5001

What it does

when v chooses an arm, one of the lines below it that each say what to do for some values, by the value of v. An arm can match:

Variant arms must cover every variant (U2007). Range and literal arms without else must be proven to cover every value. when is Una's only pattern match: match is not a keyword.

Learn more: Taking a sum apart: when.

una
module shop

pub kind Seats = Int in 0..5000

pub kind Availability = SoldOut | Few | Open

pub kind Lookup = Found(name: Text) | Missing

pub label(status: Availability) -> Text
=
  when status
    is SoldOut -> "sold out"
    is Few -> "few seats left"
    is Open -> "open"

pub name_of(lookup: Lookup) -> Text
=
  when lookup
    is Found(name) -> name
    is Missing -> "unknown"

pub band(remaining: Seats) -> Availability
=
  when remaining
    in 0..0 -> SoldOut
    in 1..<20 -> Few
    in 20..5000 -> Open

Forms

In the grammar below, each rule gives a name, =, what the name stands for and ;, quoted words are written as shown, NEWLINE, INDENT and DEDENT stand for a line break and for one more or one less level of indentation, [ ] marks an optional part, { } a part that may repeat, | separates alternatives, ( ) groups them, and (* *) holds a comment.

ebnf
when_expr       = "when" line_expr NEWLINE INDENT arm { arm } DEDENT ;
arm             = pattern "->" ( line_expr NEWLINE | NEWLINE INDENT block DEDENT ) ;
pattern         = "is" upper_ident [ "(" bind { "," bind } ")" ]
                | "is" literal
                | "in" range
                | "else" ;
bind            = lower_ident [ ":" lower_ident ] ;       (* field, or field: local name *)

Examples

A payload bound under another name, a block arm, and literal arms with else:

una
module shop

pub kind Registration
  name: Text

pub kind Lookup = Found(registration: Registration) | Missing

pub name_again(lookup: Lookup) -> Text
=
  when lookup
    is Found(registration: r) -> r.name
    is Missing -> "unknown"

pub reason(code: Int) -> Text
=
  when code
    is 200 -> "ok"
    is 404 -> "not found"
    else -> "other"

pub greeting(found: Lookup) -> Text
=
  when found
    is Missing ->
      let note = "try another name"
      note
    else -> "welcome"

A missing variant is rejected:

una
-- fails with U2007
module shop

pub kind Availability = SoldOut | Few | Open

pub label(status: Availability) -> Text
=
  when status
    is SoldOut -> "sold out"
    is Few -> "few"

Ranges that leave a gap are refuted: here 20 is not covered, and the counterexample shows it:

una
-- fails with U5001
module shop

pub kind Seats = Int in 0..5000

pub kind Availability = SoldOut | Few | Open

pub band(remaining: Seats) -> Availability
=
  when remaining
    in 0..0 -> SoldOut
    in 1..<20 -> Few
    in 21..5000 -> Open

Edge cases

else is last, and every arm is reachable:

una
-- fails with U2008
module shop

pub kind Availability = SoldOut | Few | Open

pub label(status: Availability) -> Text
=
  when status
    else -> "other"
    is SoldOut -> "sold out"

No nested patterns. Bind the field, then match it in a second when inside the arm:

una
-- fails with U0101
module shop

pub kind Parcel = Tube(length: Int) | Box(width: Int)

pub tube_length(parcel: Option[Parcel]) -> Int
=
  when parcel
    is Some(Tube(length)) -> length
    else -> 0

Variant arms need a sum. A record has no variants to match:

una
-- fails with U2001
module shop

pub kind Address
  number: Int

pub house_number(address: Address) -> Int
=
  when address
    is Address(number) -> number

Labeled values raise the program counter (the label of the conditions that decide whether a line runs; see Branches and failures: implicit flows). Every arm runs under the label of the value, so an arm cannot fail on secret data:

una
-- fails with U4002
module shop

pub kind CreditError = | Frozen

pub spendable(balance: secret Int) -> secret Int
  fails CreditError
=
  when balance
    is 0 -> fail Frozen
    else -> balance

Further rules:

Diagnostics

Edition

when is the same in editions 0.1 and 0.2. Edition 0.2 adds fixed-width integer types, whose arms take the value's type.

Normative source