Home / Docs / Language guide / Functions and contracts

ensures

Release v0.4.0Edition 0.1 and laterU0102U2012U2014U5001U5002

What it does

ensures q states a postcondition, a promise about the result: what holds of result and the arguments when the function returns normally. It is checked at both ends:

So a caller can rely on a function's header alone, without reading its body.

Learn more: Postconditions: ensures and counterexamples.

una
module shop

pub clamp(n: Int, low: Int, high: Int) -> Int
  requires low <= high
  ensures result >= low and result <= high
  ensures n >= low and n <= high implies result == n
=
  if n < low then low else if n > high then high else n

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

A postcondition the body does not keep is refuted, with a counterexample (the values for which it fails):

una
-- fails with U5001
module shop

pub next_price(cents: Int) -> Int
  ensures result > cents
=
  cents

Callers assume what they are promised. attempt keeps the promise for its Ok arm (the is Ok line of the when), so add_or_keep is proven from add_units's header alone:

una
module shop

pub kind OrderError = | TooMany

pub add_units(units: Int) -> Int
  ensures result > units
  fails OrderError
=
  if units > 100 then fail TooMany else units + 1

pub add_or_keep(units: Int) -> Int
  ensures result >= units
=
  let outcome = attempt add_units(units)
  when outcome
    is Ok(value) -> value
    is Err -> units

In edition 0.2, an edit parameter's postcondition relates its final value to old:

una
module shop

pub kind Visits
  seen: Int

pub record_visit(edit visits: Visits) -> Unit
  ensures visits.seen == old(visits).seen + 1
=
  visits.seen = visits.seen + 1

Promise versus coverage

A contract is a promise the implementation must prove; it does not establish that the promise captures the product requirement. This example is valid but weak: the body returns SoldOut for every input, and its single postcondition says nothing about positive inventory.

una.tomltoml
[package]
name = "demo"
version = "0.1.0"
edition = "0.3"
src/demo.unauna
module demo

pub kind Availability = SoldOut | Few | Open

pub classify(seats: Int) -> Availability
  requires seats >= 0
  ensures seats == 0 implies result is SoldOut
=
  SoldOut

A complete contract states each intended band, and the implementation must prove them:

una
module demo

pub kind Availability = SoldOut | Few | Open

pub classify(seats: Int) -> Availability
  requires seats >= 0
  ensures seats == 0 implies result is SoldOut
  ensures seats > 0 and seats < 20 implies result is Few
  ensures seats >= 20 implies result is Open
=
  if seats == 0 then SoldOut else if seats < 20 then Few else Open

example "zero"
  do classify(0)
  expect result is SoldOut

example "lower band"
  do classify(1)
  expect result is Few

example "upper band"
  do classify(20)
  expect result is Open

The examples give concrete runtime checks; the proof obligation is the contract. This deliberately broken implementation is refuted with U5001:

una
-- fails with U5001
module demo

pub kind Availability = SoldOut | Few | Open

pub classify(seats: Int) -> Availability
  requires seats >= 0
  ensures seats == 0 implies result is SoldOut
  ensures seats > 0 and seats < 20 implies result is Few
  ensures seats >= 20 implies result is Open
=
  SoldOut

Neither passing examples nor proving postconditions establishes that they capture the complete business requirement. Review requires and ensures against the requirement and its owner. The report can mark a trivial ensures such as ensures true; it does not infer semantic completeness.

Edge cases

Only the refinement language. * needs a literal operand, so side * side cannot be stated:

una
-- fails with U2014
module shop

pub tile_area(side: Int) -> Int
  ensures result == side * side
=
  side * side

Further rules:

Diagnostics

Edition

ensures is the same in editions 0.1 and 0.2. Edition 0.2 adds edit parameters, and old(x) with them. Editions 0.3 and 0.4 keep the rules of edition 0.2 (spec/13 §7).

Normative source