Home / Docs / Language guide / Functions and contracts

requires

Release v0.4.0Edition 0.1 and laterU0102U2012U2014U5001U5002

What it does

requires p states a precondition: what must hold of the arguments for the function to be called. It is checked at both ends:

A precondition is proven, not tested at run time, so it costs nothing when the program runs.

Learn more: Preconditions: requires.

una
module shop

pub initial(name: Text) -> Text
  requires name.len >= 1
  ensures result.len == 1
=
  name.slice(start: 0, end: 1)

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
clause          = "requires" line_expr NEWLINE
                | "ensures" line_expr NEWLINE
                | "uses" cap_ref ":" cap_type NEWLINE
                | "uses" "of" lower_ident NEWLINE                   (* edition 0.2 *)
                | "fails" upper_ident NEWLINE
                | "fails" "of" lower_ident NEWLINE                  (* edition 0.2 *)
                | "derived" "from" upper_ident { "," upper_ident } NEWLINE ;

Examples

Inside initial, name.len >= 1 is assumed, which proves the precondition of slice. Every caller must prove a precondition in turn. Here a call of half_price with a literal argument breaks its precondition, and the diagnostic shows the refuted goal (the fact that the verifier found false):

una
-- fails with U5001
module shop

pub half_price(cents: Int) -> Int
  requires cents >= 0
  ensures result * 2 <= cents
=
  cents / 2

pub broken_discount() -> Int = half_price(-1)

Several clauses describe a range of valid arguments, and the branches of a guard give the facts a caller needs:

una
module shop

pub kind Seats = Int in 0..5000

pub kind Event
  name: Text
  remaining: Seats

pub kind BookingError = | InvalidCount

pub seats_after(e: Event, count: Int) -> Seats
  requires count >= 1
  requires count <= e.remaining
=
  e.remaining - count

pub book(e: Event, count: Int) -> Seats
  fails BookingError
=
  if count < 1 or count > e.remaining
    fail InvalidCount
  else
    seats_after(e, count)

Edge cases

Only the refinement language. A precondition is decided by the solver (the program that una check asks to prove each fact). The ordering of Text, for example, is outside the refinement language:

una
-- fails with U2014
module shop

pub early_name(name: Text) -> Text
  requires name < "b"
=
  name

result is not in scope. A precondition speaks of the arguments. result belongs to ensures and expect lines:

una
-- fails with U2012
module shop

pub restock(units: Int) -> Int
  requires result > 0
=
  units

Clause order. requires comes before ensures:

una
-- fails with U0102
module shop

pub next_order(order: Int) -> Int
  ensures result > order
  requires order > 0
=
  order + 1

Further rules:

Diagnostics

Edition

requires is the same in editions 0.1 and 0.2.

Normative source