Dafny Reference Manual

The dafny-lang community

v3.11.0 release snapshot

Abstract: This is the Dafny reference manual; it describes the Dafny programming language and how to use the Dafny verification system. Parts of this manual are more tutorial in nature in order to help the user understand how to do proofs with Dafny.

(Link to current document as html)

1. Introduction

Dafny [@Leino:Dafny:LPAR16] is a programming language with built-in specification constructs, so that verifying a program’s correctness with respect to those specifications is a natural part of writing software. The Dafny static program verifier can be used to verify the functional correctness of programs. This document is a reference manual for the programming language and a user guide for the dafny tool that performs verification and compilation to an executable form.

The Dafny programming language is designed to support the static verification of programs. It is imperative, sequential, supports generic classes, inheritance and abstraction, methods and functions, dynamic allocation, inductive and coinductive datatypes, and specification constructs. The specifications include pre- and postconditions, frame specifications (read and write sets), and termination metrics. To further support specifications, the language also offers updatable ghost variables, recursive functions, and types like sets and sequences. Specifications and ghost constructs are used only during verification; the compiler omits them from the executable code.

The dafny verifier is run as part of the compiler. As such, a programmer interacts with it in much the same way as with the static type checker—when the tool produces errors, the programmer responds by changing the program’s type declarations, specifications, and statements.

(This document typically uses “Dafny” to refer to the programming language and dafny to refer to the software tool that verifies and compiles programs in the Dafny language.)

The easiest way to try out the Dafny language is to download the supporting tools and documentation and run dafny on your machine as you follow along with the Dafny tutorial. The dafny tool can be run from the command line (on Linux, MacOS, Windows or other platforms) or from an IDE such as emacs or an editor such as VSCode, which can provide syntax highlighting without the built-in verification.

The verifier is powered by Boogie [@Boogie:Architecture;@Leino:Boogie2-RefMan;@LeinoRuemmer:Boogie2] and Z3 [@deMouraBjorner:Z3:overview].

From verified programs, the dafny compiler can produce code for a number of different backends: the .NET platform via intermediate C# files, Java, Javascript, Go, and C++. Each language provides a basic Foreign Function Interface (through uses of :extern) and a supporting runtime library. However, there is no automatic FFI generator, so :extern stubs must be written by hand.

This reference manual for the Dafny verification system is based on the following references: [@Leino:Dafny:LPAR16], [@MSR:dafny:main], [@LEINO:Dafny:Calc], [@LEINO:Dafny:Coinduction], Co-induction Simply.

The main part of the reference manual is in top down order except for an initial section that deals with the lowest level constructs.

The details of using (and contributing to) the dafny tool are described in the User Guide (Section 25).

1.1. Dafny Example

To give a flavor of Dafny, here is the solution to a competition problem.

// VSComp 2010, problem 3, find a 0 in a linked list and return
// how many nodes were skipped until the first 0 (or end-of-list)
// was found.
// Rustan Leino, 18 August 2010.
//
// The difficulty in this problem lies in specifying what the
// return value 'r' denotes and in proving that the program
// terminates.  Both of these are addressed by declaring a ghost
// field 'List' in each linked-list node, abstractly representing
// the linked-list elements from the node to the end of the linked
// list.  The specification can now talk about that sequence of
// elements and can use 'r' as an index into the sequence, and
// termination can be proved from the fact that all sequences in
// Dafny are finite.
//
// We only want to deal with linked lists whose 'List' field is
// properly filled in (which can only happen in an acyclic list,
// for example).  To that end, the standard idiom in Dafny is to
// declare a predicate 'Valid()' that is true of an object when
// the data structure representing that object's abstract value
// is properly formed.  The definition of 'Valid()' is what one
// intuitively would think of as the ''object invariant'', and
// it is mentioned explicitly in method pre- and postconditions.
//
// As part of this standard idiom, one also declares a ghost
// variable 'Repr' that is maintained as the set of objects that
// make up the representation of the aggregate object--in this
// case, the Node itself and all its successors.

class Node {
  ghost var List: seq<int>
  ghost var Repr: set<Node>
  var head: int
  var next: Node? // Node? means a Node value or null

  predicate Valid()
    reads this, Repr
  {
    this in Repr &&
    1 <= |List| && List[0] == head &&
    (next == null ==> |List| == 1) &&
    (next != null ==>
      next in Repr && next.Repr <= Repr && this !in next.Repr &&
      next.Valid() && next.List == List[1..])
  }

  static method Cons(x: int, tail: Node?) returns (n: Node)
    requires tail == null || tail.Valid()
    ensures n.Valid()
    ensures if tail == null then n.List == [x]
                            else n.List == [x] + tail.List
  {
    n := new Node;
    n.head, n.next := x, tail;
    if (tail == null) {
      n.List := [x];
      n.Repr := {n};
    } else {
      n.List := [x] + tail.List;
      n.Repr := {n} + tail.Repr;
    }
  }
}

method Search(ll: Node?) returns (r: int)
  requires ll == null || ll.Valid()
  ensures ll == null ==> r == 0
  ensures ll != null ==>
            0 <= r && r <= |ll.List| &&
            (r < |ll.List| ==>
              ll.List[r] == 0 && 0 !in ll.List[..r]) &&
            (r == |ll.List| ==> 0 !in ll.List)
{
  if (ll == null) {
    r := 0;
  } else {
    var jj,i := ll,0;
    while (jj != null && jj.head != 0)
      invariant jj != null ==>
            jj.Valid() &&
            i + |jj.List| == |ll.List| &&
            ll.List[i..] == jj.List
      invariant jj == null ==> i == |ll.List|
      invariant 0 !in ll.List[..i]
      decreases |ll.List| - i
    {
      jj := jj.next;
      i := i + 1;
    }
    r := i;
  }
}

method Main()
{
  var list: Node? := null;
  list := list.Cons(0, list);
  list := list.Cons(5, list);
  list := list.Cons(0, list);
  list := list.Cons(8, list);
  var r := Search(list);
  print "Search returns ", r, "\n";
  assert r == 1;
}

2. Lexical and Low Level Grammar

Dafny uses the Coco/R lexer and parser generator for its lexer and parser (http://www.ssw.uni-linz.ac.at/Research/Projects/Coco)[@Linz:Coco]. The Dafny input file to Coco/R is the Dafny.atg file in the source tree. A Coco/R input file consists of code written in the target language (C# for the dafny tool) intermixed with these special sections:

  1. The Characters section which defines classes of characters that are used in defining the lexer.
  2. The Tokens section which defines the lexical tokens.
  3. The Productions section which defines the grammar. The grammar productions are distributed in the later parts of this document in the places where those constructs are explained.

The grammar presented in this document was derived from the Dafny.atg file but has been simplified by removing details that, though needed by the parser, are not needed to understand the grammar. In particular, the following transformations have been performed.

The names of character sets and tokens start with a lower case letter; the names of grammar non-terminals start with an upper-case letter.

The grammar uses Extended BNF notation. See the Coco/R Referenced manual for details. In summary:

In addition to the Coco rules, for the sake of readability we have adopted these additional conventions.

2.1. Dafny Input

Dafny source code files are readable text encoded in UTF-8. All program text other than the contents of comments, character, string and verbatim string literals consists of printable and white-space ASCII characters, that is, ASCII characters in the range ! to ~, plus space, tab, carriage return and newline (ASCII, 9, 10, 13, 32) characters.

2.2. Tokens and whitespace

The characters used in a Dafny program fall into four groups:

Each Dafny token consists of a sequence of consecutive characters from just one of these groups, excluding white-space. White-space is ignored except that it separates tokens.

A sequence of alphanumeric characters (with no preceding or following additional alphanumeric characters) is a single token. This is true even if the token is syntactically or semantically invalid and the sequence could be separated into more than one valid token. For example, assert56 is one identifier token, not a keyword assert followed by a number; ifb!=0 begins with the token ifb and not with the keyword if and token b; 0xFFFFZZ is an illegal token, not a valid hex number 0xFFFF followed by an identifier ZZ. White-space must be used to separate two such tokens in a program.

Somewhat differently, operator tokens need not be separated. Only specific sequences of operator characters are recognized and these are somewhat context-sensitive. For example, in seq<set<int>>, the grammar knows that >> is two individual > tokens terminating the nested type parameter lists; the right shift operator >> would never be valid here. Similarly, the sequence ==> is always one token; even if it were invalid in its context, separating it into == and > would always still be invalid.

In summary, except for required white space between alphanumeric tokens, adding white space between tokens or removing white space can never result in changing the meaning of a Dafny program. For the rest of this document, we consider Dafny programs as sequences of tokens.

2.3. Character Classes

This section defines character classes used later in the token definitions. In this section a backslash is used to start an escape sequence; so for example '\n' denotes the single linefeed character. Also in this section, double quotes enclose the set of characters constituting a character class; enclosing single quotes are used when there is just one character in the class. + indicates the union of two character classes; - is the set-difference between the two classes. ANY designates all unicode characters.

letter = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"

At present, a letter is an ASCII upper or lowercase letter. Other Unicode letters are not supported.

digit = "0123456789"

A digit is just one of the base-10 digits.

posDigit = "123456789"
posDigitFrom2 = "23456789"

A posDigit is a digit, excluding 0. posDigitFrom2 excludes both 0 and 1.

hexdigit = "0123456789ABCDEFabcdef"

A hexdigit character is a digit or one of the letters from ‘A’ to ‘F’ in either case.

special = "'_?"

The special characters are the characters in addition to alphanumeric characters that are allowed to appear in a Dafny identifier. These are

cr        = '\r'

A carriage return character.

lf        = '\n'

A line feed character.

tab       = '\t'

A tab character.

space     = ' '

A space character.

nondigitIdChar = letter + special

The characters that can be used in an identifier minus the digits.

idchar = nondigitIdChar + digit

The characters that can be used in an identifier.

nonidchar = ANY - idchar

Any character except those that can be used in an identifier. Here the scanner generator will interpret ANY as any unicode character. However, nonidchar is used only to mark the end of the !in token; in this context any character other than whitespace or printable ASCII will trigger a subsequent scanning or parsing error.

charChar = ANY - '\'' - '\\' - cr - lf

Characters that can appear in a character constant.

stringChar = ANY - '"' - '\\' - cr - lf

Characters that can appear in a string constant.

verbatimStringChar = ANY - '"'

Characters that can appear in a verbatim string.

2.4. Comments

Comments are in two forms.

Comments may be nested, but note that the nesting of multi-line comments is behavior that is different from most programming languages. In Dafny, 

method m() {
  /* comment
     /* nested comment
     */
     rest of outer comment
  */
}

is permitted; this feature is convenient for commenting out blocks of program statements that already have multi-line comments within them. Other than looking for end-of-comment delimiters, the contents of a comment are not interpreted. Comments may contain any characters.

Note that the nesting is not fool-proof. In 

method m() {
  /* var i: int;
     // */ line comment
     var j: int;
  */
}

and 

method m() {
  /* var i: int;
     var s: string := "a*/b";
     var j: int;
   */
}

the */ inside the line comment and the string are seen as the end of the outer comment, leaving trailing text that will provoke parsing errors.

2.5. Tokens

As with most languages, Dafny syntax is defined in two levels. First the stream of input characters is broken up into tokens. Then these tokens are parsed using the Dafny grammar. The Dafny tokens are defined in this section.

2.5.1. Reserved Words

The following reserved words appear in the Dafny grammar and may not be used as identifiers of user-defined entities:

reservedword =
    "abstract" | "allocated" | "as" | "assert" | "assume" |
    "bool" | "break" | "by" |
    "calc" | "case" | "char" | "class" | "codatatype" |
    "const" | "constructor" |
    "datatype" | "decreases" |
    "else" | "ensures" | "exists" | "export" | "extends" |
    "false" | "forall" | "fresh" | "function" | "ghost" |
    "if" | "imap" | "import" | "in" | "include" |
    "int" | "invariant" | "is" | "iset" | "iterator" |
    "label" | "lemma" | "map" | "match" | "method" |
    "modifies" | "modify" | "module" | "multiset" |
    "nameonly" | "nat" | "new" | "newtype" | "null" |
    "object" | "object?" | "old" | "opened" | "ORDINAL"
    "predicate" | "print" | "provides" |
    "reads" | "real" | "refines" | "requires" | "return" |
    "returns" | "reveal" | "reveals" |
    "seq" | "set" | "static" | "string" |
    "then" | "this" | "trait" | "true" | "twostate" | "type" |
    "unchanged" | "var" | "while" | "witness" |
    "yield" | "yields" |
    arrayToken | bvToken

arrayToken = "array" [ posDigitFrom2 | posDigit digit { digit }]["?"]

bvToken = "bv" ( 0 | posDigit { digit } )

An arrayToken is a reserved word that denotes an array type of given rank. array is an array type of rank 1 (aka a vector). array2 is the type of two-dimensional arrays, etc. array1 and array1? are not reserved words; they are just ordinary identifiers. Similarly, bv0, bv1, and bv8 are reserved words, but bv02 is an ordinary identifier.

2.5.2. Identifiers

ident = nondigitIdChar { idchar } - charToken - reservedword

In general Dafny identifiers are sequences of idchar characters where the first character is a nondigitIdChar. However tokens that fit this pattern are not identifiers if they look like a character literal or a reserved word (including array or bit-vector type tokens). Also, ident tokens that begin with an _ are not permitted as user identifiers.

2.5.3. Digits

digits = digit {['_'] digit}

A sequence of decimal digits, possibly interspersed with underscores for readability (but not beginning or ending with an underscore). Example: 1_234_567.

hexdigits = "0x" hexdigit {['_'] hexdigit}

A hexadecimal constant, possibly interspersed with underscores for readability (but not beginning or ending with an underscore). Example: 0xffff_ffff.

decimaldigits = digit {['_'] digit} '.' digit {['_'] digit}

A decimal fraction constant, possibly interspersed with underscores for readability (but not beginning or ending with an underscore). Example: 123_456.789_123.

2.5.4. Escaped Character

In this section the “\” characters are literal.

escapedChar =
    ( "\'" | "\"" | "\\" | "\0" | "\n" | "\r" | "\t"
      | "\u" hexdigit hexdigit hexdigit hexdigit
      | "\U{" hexdigit { hexdigit } "}"
    )

In Dafny character or string literals, escaped characters may be used to specify the presence of a single- or double-quote character, backslash, null, new line, carriage return, tab, or a Unicode character with given hexadecimal representation. Which Unicode escape form is allowed depends on the value of the --unicode-char option.

If --unicode-char:false is provided, \uXXXX escapes can be used to specify any UTF-16 code unit.

If --unicode-char:true is provided, \U{X..X} escapes can be used to specify any Unicode scalar value. There must be at least one hex digit in between the braces, and at most six. Surrogate code points are not allowed. The hex digits may be interspersed with underscores for readability (but not beginning or ending with an underscore), as in \U{1_F680}.

2.5.5. Character Constant Token

charToken = "'" ( charChar | escapedChar ) "'"

A character constant is enclosed by ' and includes either a character from the charChar set or an escaped character. Note that although Unicode letters are not allowed in Dafny identifiers, Dafny does support Unicode in its character, string, and verbatim strings constants and in its comments. A character constant has type char.

2.5.6. String Constant Token

stringToken =
    '"' { stringChar | escapedChar }  '"'
  | '@' '"' { verbatimStringChar | '"' '"' } '"'

A string constant is either a normal string constant or a verbatim string constant. A normal string constant is enclosed by " and can contain characters from the stringChar set and escapedChars.

A verbatim string constant is enclosed between @" and " and can consist of any characters (including newline characters) except that two successive double quotes represent one quote character inside the string. This is the mechanism for escaping a double quote character, which is the only character needing escaping in a verbatim string. Within a verbatim string constant, a backslash character represents itself and is not the first character of an escapedChar.

2.5.7. Ellipsis

ellipsis = "..."

The ellipsis symbol is typically used to designate something missing that will later be inserted through refinement or is already present in a parent declaration.

2.6. Low Level Grammar Productions

2.6.1. Identifier Variations

Ident = ident

The Ident non-terminal is just an ident token and represents an ordinary identifier.

DotSuffix =
  ( ident | digits | "requires" | "reads" )

When using the dot notation to denote a component of a compound entity, the token following the “.” may be an identifier, a natural number, or one of the keywords requires or reads.

NoUSIdent = ident - "_" { idchar }

A NoUSIdent is an identifier except that identifiers with a leading underscore are not allowed. The names of user-defined entities are required to be NoUSIdents or, in some contexts, a digits. We introduce more mnemonic names for these below (e.g. ClassName).

WildIdent = NoUSIdent | "_"

Identifier, disallowing leading underscores, except the “wildcard” identifier _. When _ appears it is replaced by a unique generated identifier distinct from user identifiers. This wildcard has several uses in the language, but it is not used as part of expressions.

2.6.2. NoUSIdent Synonyms

In the productions for the declaration of user-defined entities the name of the user-defined entity is required to be an identifier that does not start with an underscore, i.e., a NoUSIdent. To make the productions more mnemonic, we introduce the following synonyms for NoUSIdent and other identifier-related symbols.

IdentOrDigits = Ident | digits
NoUSIdentOrDigits = NoUSIdent | digits
ModuleName = NoUSIdent
ClassName = NoUSIdent    // also traits
DatatypeName = NoUSIdent
DatatypeMemberName = NoUSIdentOrDigits
NewtypeName = NoUSIdent
SynonymTypeName = NoUSIdent
IteratorName = NoUSIdent
TypeVariableName = NoUSIdent
MethodFunctionName = NoUSIdentOrDigits
LabelName = NoUSIdentOrDigits
AttributeName = NoUSIdent
ExportId = NoUSIdentOrDigits
TypeNameOrCtorSuffix = NoUSIdentOrDigits

2.6.3. Qualified Names

ModuleQualifiedName = ModuleName { "." ModuleName }

A qualified name starts with the name of the top-level entity and then is followed by zero or more DotSuffixs which denote a component. Examples:

The grammar does not actually have a production for qualified names except in the special case of a qualified name that is known to be a module name, i.e. a ModuleQualifiedName.

2.6.4. Identifier-Type Combinations

In this section, we describe some nonterminals that combine an identifier and a type.

IdentType = WildIdent ":" Type

In Dafny, a variable or field is typically declared by giving its name followed by a colon and its type. An IdentType is such a construct.

FIdentType = NoUSIdentOrDigits ":" Type

A FIdentType is used to declare a field. The Type is required because there is no initializer.

CIdentType = NoUSIdentOrDigits [ ":" Type ]

A CIdentType is used for a const declaration. The Type is optional because it may be inferred from the initializer.

GIdentType(allowGhostKeyword, allowNewKeyword, allowOlderKeyword, allowNameOnlyKeyword, allowDefault) =
    { "ghost" | "new" | "nameonly" | "older" } IdentType
    [ ":=" Expression(allowLemma: true, allowLambda: true) ]

A GIdentType is a typed entity declaration optionally preceded by ghost or new. The ghost qualifier means the entity is only used during verification and not in the generated code. Ghost variables are useful for abstractly representing internal state in specifications. If allowGhostKeyword is false, then ghost is not allowed. If allowNewKeyword is false, then new is not allowed. If allowNameOnlyKeyword is false, then nameonly is not allowed. If allowDefault is false, then := Expression is not allowed.

older is a context-sensitive keyword. It is recognized as a keyword only by GIdentType and only when allowOlderKeyword is true. If allowOlderKeyword is false, then a use of older is parsed by the IdentType production in GIdentType.

LocalIdentTypeOptional = WildIdent [ ":" Type ]

A LocalIdentTypeOptional is used when declaring local variables. If a value is specified for the variable, the type may be omitted because it can be inferred from the initial value. An initial value is not required.

IdentTypeOptional = WildIdent [ ":" Type ]

A IdentTypeOptional is typically used in a context where the type of the identifier may be inferred from the context. Examples are in pattern matching or quantifiers.

TypeIdentOptional =
    { "ghost" | "nameonly" } [ NoUSIdentOrDigits ":" ] Type
    [ ":=" Expression(allowLemma: true, allowLambda: true) ]

TypeIdentOptionals are used in FormalsOptionalIds. This represents situations where a type is given but there may not be an identifier. The default-value expression := Expression is allowed only if NoUSIdentOrDigits : is also provided. If modifier nameonly is given, then NoUSIdentOrDigits must also be used.

FormalsOptionalIds = "(" [ TypeIdentOptional
                           { "," TypeIdentOptional } ] ")"

A FormalsOptionalIds is a formal parameter list in which the types are required but the names of the parameters are optional. This is used in algebraic datatype definitions.

2.6.5. Quantifier Domains

Several Dafny constructs bind one or more variables to a range of possible values. For example, the quantifier forall x: nat | x <= 5 :: x * x <= 25 has the meaning “for all integers x between 0 and 5 inclusive, the square of x is at most 25”. Similarly, the set comprehension set x: nat | x <= 5 :: f(x) can be read as “the set containing the result of applying f to x, for each integer x from 0 to 5 inclusive”. The common syntax that specifies the bound variables and what values they take on is known as the quantifier domain; in the previous examples this is x: nat | x <= 5, which binds the variable x to the values 0, 1, 2, 3, 4, and 5.

Here are some more examples.

A quantifier domain declares one or more quantified variables, separated by commas. Each variable declaration can be nothing more than a variable name, but it may also include any of three optional elements:

  1. The optional syntax : T declares the type of the quantified variable. If not provided, it will be inferred from context.

  2. The optional syntax <- C attaches a collection expression C as a quantified variable domain. Here a collection is any value of a type that supports the in operator, namely sets, multisets, maps, and sequences. The domain restricts the bindings to the elements of the collection: x <- C implies x in C. The example above can also be expressed as var c := [0, 1, 2, 3, 4, 5]; forall x <- c :: x * x <= 25.

  3. The optional syntax | E attaches a boolean expression E as a quantified variable range, which restricts the bindings to values that satisfy this expression. In the example above x <= 5 is the range attached to the x variable declaration.

Note that a variable’s domain expression may reference any variable declared before it, and a variable’s range expression may reference the attached variable (and usually does) and any variable declared before it. For example, in the quantifier domain i | 0 <= i < |s|, y <- s[i] | i < y, the expression s[i] is well-formed because the range attached to i ensures i is a valid index in the sequence s.

Allowing per-variable ranges is not fully backwards compatible, and so it is not yet allowed by default; the /quantifierSyntax:4 option needs to be provided to enable this feature (See Section 25.8.5).

The general production for quantifier domains is:

QuantifierDomain(allowLemma, allowLambda) =
    QuantifierVarDecl(allowLemma, allowLambda) 
    { "," QuantifierVarDecl(allowLemma, allowLambda) }

QuantifierVarDecl(allowLemma, allowLambda) =
    IdentTypeOptional
    [ <- Expression(allowLemma, allowLambda) ]
    { Attribute }
    [ | Expression(allowLemma, allowLambda) ]

2.6.6. Numeric Literals

Nat = ( digits | hexdigits )

A Nat represents a natural number expressed in either decimal or hexadecimal.

Dec = decimaldigits

A Dec represents a decimal fraction literal.

3. Programs

Dafny = { IncludeDirective_ } { TopDecl } EOF

At the top level, a Dafny program (stored as files with extension .dfy) is a set of declarations. The declarations introduce (module-level) constants, methods, functions, lemmas, types (classes, traits, inductive and coinductive datatypes, newtypes, type synonyms, opaque types, and iterators) and modules, where the order of introduction is irrelevant. A class also contains a set of declarations, introducing fields, methods, and functions.

When asked to compile a program, Dafny looks for the existence of a Main() method. If a legal Main() method is found, the compiler will emit an executable appropriate to the target language; otherwise it will emit a library or individual files. The conditions for a legal Main() method are described in the User Guide (Section 25.7.1). If there is more than one Main(), Dafny will emit an error message.

An invocation of Dafny may specify a number of source files. Each Dafny file follows the grammar of the Dafny non-terminal.

A file consists of a sequence of optional include directives followed by top level declarations followed by the end of the file.

3.1. Include Directives

IncludeDirective_ = "include" stringToken

Include directives have the form "include" stringToken where the string token is either a normal string token or a verbatim string token. The stringToken is interpreted as the name of a file that will be included in the Dafny source. These included files also obey the Dafny grammar. Dafny parses and processes the transitive closure of the original source files and all the included files, but will not invoke the verifier on the included files unless they have been listed explicitly on the command line.

The file name may be a path using the customary /, ., and .. specifiers. The interpretation of the name (e.g., case-sensitivity) will depend on the underlying operating system. A path not beginning with / is looked up in the underlying file system relative to the current working directory (the one in which the dafny tool is invoked). Paths beginning with a device designator (e.g., C:) are only permitted on Windows systems.

3.2. Top Level Declarations

TopDecl =
  { DeclModifier }
  ( SubModuleDecl
  | ClassDecl
  | DatatypeDecl
  | NewtypeDecl
  | SynonymTypeDecl  // includes opaque types
  | IteratorDecl
  | TraitDecl
  | ClassMemberDecl(moduleLevelDecl: true)
  )

Top-level declarations may appear either at the top level of a Dafny file, or within a SubModuleDecl. A top-level declaration is one of various kinds of declarations described later. Top-level declarations are implicitly members of a default (unnamed) top-level module.

Declarations within a module or at the top-level all begin with reserved keywords and do not end with semicolons.

The ClassDecl, DatatypeDecl, NewtypeDecl, SynonymTypeDecl, IteratorDecl, and TraitDecl declarations are type declarations and are described in Section 6 and the following sections. Ordinarily ClassMemberDecls appear in class declarations but they can also appear at the top level. In that case they are included as part of an implicit top-level class and are implicitly static (but cannot be declared as static). In addition a ClassMemberDecl that appears at the top level cannot be a FieldDecl.

3.3. Declaration Modifiers

DeclModifier = ( "abstract" | "ghost" | "static" )

Top level declarations may be preceded by zero or more declaration modifiers. Not all of these are allowed in all contexts.

The abstract modifiers may only be used for module declarations. An abstract module can leave some entities underspecified. Abstract modules are not compiled.

The ghost modifier is used to mark entities as being used for specification only, not for compilation to code.

The static modifier is used for class members that are associated with the class as a whole rather than with an instance of the class.

The following table shows modifiers that are available for each of the kinds of declaration. In the table we use already-ghost (already-non-ghost) to denote that the item is not allowed to have the ghost modifier because it is already implicitly ghost (non-ghost).

Declaration allowed modifiers
module abstract
class -
trait -
datatype or codatatype -
field ghost
newtype -
synonym types -
iterators -
method ghost static
lemma already-ghost static
least lemma already-ghost static
greatest lemma already-ghost static
constructor -
function (non-method) already-ghost static
function method already-non-ghost static
predicate (non-method) already-ghost static
predicate method already-non-ghost static
least predicate already-ghost static
greatest predicate already-ghost static

4. Modules

SubModuleDecl = ( ModuleDefinition | ModuleImport | ModuleExport )

Structuring a program by breaking it into parts is an important part of creating large programs. In Dafny, this is accomplished via modules. Modules provide a way to group together related types, classes, methods, functions, and other modules, as well as to control the scope of declarations. Modules may import each other for code reuse, and it is possible to abstract over modules to separate an implementation from an interface.

4.1. Declaring New Modules

ModuleDefinition = "module" { Attribute } ModuleQualifiedName
        [ "refines" ModuleQualifiedName ]
        "{" { TopDecl } "}"

A ModuleQualifiedName is a qualified name that is expected to refer to a module; a qualified name is a sequence of .-separated identifiers, which designates a program entity by representing increasingly-nested scopes.

A new module is declared with the module keyword, followed by the name of the new module, and a pair of curly braces ({}) enclosing the body of the module:

module Mod { 
   ...
}

A module body can consist of anything that you could put at the top level. This includes classes, datatypes, types, methods, functions, etc.

module Mod {
  class C {
    var f: int
    method m()
  }
  datatype Option = A(int) | B(int)
  type T
  method m()
  function f(): int
}

You can also put a module inside another, in a nested fashion:

module Mod {
  module Helpers {
    class C {
      method doIt()
      var f: int
    }
  }
}

Then you can refer to the members of the Helpers module within the Mod module by prefixing them with “Helpers.”. For example:

module Mod {
  module Helpers {
    class C {
      constructor () { f := 0; }
      method doIt()
      var f: int
    }
  }
  method m() {
    var x := new Helpers.C();
    x.doIt();
    x.f := 4;
  }
}

Methods and functions defined at the module level are available like classes, with just the module name prefixing them. They are also available in the methods and functions of the classes in the same module.

module Mod {
  module Helpers {
    function method addOne(n: nat): nat {
      n + 1
    }
  }
  method m() {
    var x := 5;
    x := Helpers.addOne(x); // x is now 6
  }
}

Note that everything declared at the top-level (in all the files constituting the program) is implicitly part of a single implicit unnamed global module.

4.2. Declaring nested modules standalone

As described in the previous section, module declarations can be nested. It is also permitted to declare a nested module outside of its “containing” module. So instead of 

module A {
  module B {
  }
}

one can write 

module A {
}
module A.B {
}

The second module is completely separate; for example, it can be in a different file. This feature provides flexibility in writing and maintenance; for example, it can reduce the size of module A by extracting module A.B into a separate body of text.

However, it can also lead to confusion and program authors need to take care. It may not be apparent to a reader of module A that module A.B exists; the existence of A.B might cause names to be resolved differently and the semantics of the program might be (silently) different if A.B is present or absent.

4.3. Importing Modules

ModuleImport =
    "import"
    [ "opened" ]
    ( QualifiedModuleExport
    | ModuleName "=" QualifiedModuleExport
    | ModuleName ":" QualifiedModuleExport
    )

QualifiedModuleExport =
    ModuleQualifiedName [ "`" ModuleExportSuffix ]

ModuleExportSuffix =
    ( ExportId
    | "{" ExportId { "," ExportId } "}"
    )

Sometimes you want to refer to things from an existing module, such as a library. In this case, you can import one module into another. This is done via the import keyword, which has two forms with different meanings. The simplest form is the concrete import, which has the form import A = B. This declaration creates a reference to the module B (which must already exist), and binds it to the new name A. This form can also be used to create a reference to a nested module, as in import A = B.C. The other form, using a :, is described in Section 4.6.

As modules in the same scope must have different names, this ability to bind a module to a new name allows disambiguating separately developed external modules that have the same name. Note that the new name is only bound in the scope containing the import declaration; it does not create a global alias. For example, if Helpers was defined outside of Mod, then we could import it:

module Helpers {
  function method addOne(n: nat): nat {
    n + 1
  }
}
module Mod {
  import A = Helpers
  method m() {
    assert A.addOne(5) == 6;
  }
}

Note that inside m(), we have to use A instead of Helpers, as we bound it to a different name. The name Helpers is not available inside m(), as only names that have been bound inside Mod are available. In order to use the members from another module, that other module either has to be declared there with module or imported with import. (As described below, the resolution of the ModuleQualifiedName that follows the = in the import statement or the refines in a module declaration uses slightly different rules.)

We don’t have to give Helpers a new name, though, if we don’t want to. We can write import Helpers = Helpers to import the module under its own name; Dafny even provides the shorthand import Helpers for this behavior. You can’t bind two modules with the same name at the same time, so sometimes you have to use the = version to ensure the names do not clash. When importing nested modules, import B.C means import C = B.C; the implicit name is always the last name segment of the module designation.

The ModuleQualifiedName in the ModuleImport starts with a submodule of the importing module, with a sibling module of the importing module, or with a sibling module of some containing module. There is no way to refer to a containing module, only sibling modules (and their submodules).

Import statements may occur at the top-level of a program (that is, in the implicit top-level module of the program) as well. There they serve simply as a way to give a new name, perhaps a shorthand name, to a module. For example,

module MyModule { } // declare MyModule
import MyModule  // error: cannot add a module named MyModule
                 // because there already is one
import M = MyModule // OK. M and MyModule are equivalent

4.4. Opening Modules

Sometimes, prefixing the members of the module you imported with the name is tedious and ugly, even if you select a short name when importing it. In this case, you can import the module as opened, which causes all of its members to be available without adding the module name. The opened keyword, if present, must immediately follow import. For example, we could write the previous example as:

module Helpers {
  function method addOne(n: nat): nat {
    n + 1
  }
}
module Mod {
  import opened Helpers
  method m() {
    assert addOne(5) == 6;
  }
}

When opening modules, the newly bound members have lower priority than local definitions. This means if you define a local function called addOne, the function from Helpers will no longer be available under that name. When modules are opened, the original name binding is still present however, so you can always use the name that was bound to get to anything that is hidden.

module Helpers {
  function method addOne(n: nat): nat {
    n + 1
  }
}
module Mod {
  import opened Helpers
  function addOne(n: nat): nat {
    n - 1
  }
  method m() {
    assert addOne(5) == 6; // this is now false,
                           // as this is the function just defined
    assert Helpers.addOne(5) == 6; // this is still true
  }
}

If you open two modules that both declare members with the same name, then neither member can be referred to without a module prefix, as it would be ambiguous which one was meant. Just opening the two modules is not an error, however, as long as you don’t attempt to use members with common names. However, if the ambiguous references actually refer to the same declaration, then they are permitted. The opened keyword may be used with any kind of import declaration, including the module abstraction form.

An import opened may occur at the top-level as well. For example, 

module MyModule {  } // declares MyModule
import opened MyModule // does not declare a new module, but does
                       // make all names in MyModule available in
                       // the current scope, without needing
                       // qualification
import opened M = MyModule // names in MyModule are available in
                       // the current scope without qualification
                       // or qualified with either M or MyModule

The Dafny style guidelines suggest using opened imports sparingly. They are best used when the names being imported have obvious and unambiguous meanings and when using qualified names would be verbose enough to impede understanding.

There is a special case in which the behavior described above is altered. If a module M declares a type M and M is import opened without renaming inside another module X, then the rules above would have, within X, M mean the module and M.M mean the type. This is verbose. So in this somewhat common case, the type M is effectively made a local declaration of X so that it has precedence over the module name. Now M refers to the type. If one needs to refer to the module, it will have to be renamed as part of the import opened statement.

This special-case behavior does give rise to a source of ambiguity. Consider the example 

module Option {
  const a := 1
  datatype Option = A|B { static const a := 2 }
}

module X {
  import opened Option
  method M() { print Option.a; }
}

Option.a now means the a in the datatype instead of the a in the module. To avoid confusion in such cases, it is an ambiguity error to import open a module without renaming that contains a declaration with the same name as a declaration in a type in the module when the type has the same name as the module.

4.5. Export Sets and Access Control

ModuleExport =
  "export"
  [ ExportId ]
  [ "..." ]
  {
    "extends"  ExportId { "," ExportId }
  | "provides" ( ExportSignature { "," ExportSignature } | "*" )
  | "reveals"  ( ExportSignature { "," ExportSignature } | "*" )
  }

ExportSignature = TypeNameOrCtorSuffix [ "." TypeNameOrCtorSuffix ]

In some programming languages, keywords such as public, private, and protected are used to control access to (that is, visibility of) declared program entities. In Dafny, modules and export sets provide that capability. Modules combine declarations into logically related groups. Export sets then permit selectively exposing subsets of declarations; another module can import the export set appropriate to its needs. A user can define as many export sets as are needed to provide different kinds of access to the module’s declarations. Each export set designates a list of names, which must be names that are declared in the module (or in a refinement parent).

By default all the names declared in a module are available outside the module using the import mechanism. An export set enables a module to disallow the use of some declarations outside the module.

Export sets have names; those names are used in import statements to designate which export set of a module is being imported. If a module M has export sets E1 and E2, we can write import A = M`E1 to create a module alias A that contains only the names in E1. Or we can write import A = M`{E1,E2} to import the union of names in E1 and E2 as module alias A. As before, import M`E1 is an abbreviation of import M = M`E1.

If no export set is given in an import statement, the default export set of the module is used.

There are various defaults that apply differently in different cases. The following description is with respect to an example module M:

M has no export sets declared. Then another module may simply import Z = M to obtain access to all of M’s declarations.

M has one or more named export sets (e.g., E, F). Then another module can write import Z = M`E or import Z = M`{E,F} to obtain access to the names that are listed in export set E or to the union of those in export sets E and F, respectively. If no export set has the same name as the module, then an export set designator must be used: in that case you cannot write simply import Z = M.

M has an unnamed export set, along with other export sets (e.g., E). The unnamed export set is the default export set and implicitly has the same name as the module. Because there is a default export set, another module may write either import Z = M or import Z = M`M to import the names in that default export set. You can also still use the other export sets with the explicit designator: import Z = M`E

M declares an export set with the same name as the module. This is equivalent to declaring an export set without a name. import M and import M`M perform the same function in either case; the export set with or without the name of the module is the default export set for the module.

Note that names of module aliases (declared by import statements) are just like other names in a module; they can be included or omitted from export sets. Names brought into a module by refinement are treated the same as locally declared names and can be listed in export set declarations. However, names brought into a module by import opened (either into a module or a refinement parent of a module) may not be further exported. For example, 

module A {
  const a := 10;
  const z := 10;
}
module B {
  import opened Z = A // includes a, declares Z
  const b := Z.a; // OK
}
module C {
  import opened B // includes b, Z, but not a
  method m() {
    //assert b == a; // error: a is not known
    //assert b == B.a; // error: B.a is not valid
    //assert b == A.a; // error: A is not known
    assert b == Z.a; // OK: module Z is known and includes a
  }
}

However, in the above example,

The default export set is important in the resolution of qualified names, as described in Section 4.8.

There are a few unusual cases to be noted:

4.5.1. Provided and revealed names

Names can be exported from modules in two ways, designated by provides and reveals in the export set declaration.

When a name is exported as provided, then inside a module that has imported the name only the name is known, not the details of the name’s declaration.

For example, in the following code the constant a is exported as provided. 

module A {
  export provides a
  const a := 10;
  const b := 20;
}

module B {
  import A
  method m() {
    assert A.a == 10; // a is known, but not its value
    // assert A.b == 20; // b is not known through A`A
  }
}

Since a is imported into module B through the default export set A`A, it can be referenced in the assert statement. The constant b is not exported, so it is not available. But the assert about a is not provable because the value of a is not known in module B.

In contrast, if a is exported as revealed, as shown in the next example, its value is known and the assertion can be proved. 

module A {
  export reveals a
  const a := 10;
  const b := 20;
}

module B {
  import A
  method m() {
    assert A.a == 10; // a and its value are known
    // assert A.b == 20; // b is not known through A`A
  }
}

The following table shows which parts of a declaration are exported by an export set that provides or reveals the declaration.

 declaration         | what is exported    | what is exported
                     | with provides       | with reveals
---------------------|---------------------|---------------------
 const x: X := E     | const x: X          | const x: X := E
---------------------|---------------------|---------------------
 var x: X            | var x: X            | not allowed
---------------------|---------------------|---------------------
 function F(x: X): Y | function F(x: X): Y | function F(x: X): Y
   specification...  |   specification...  |   specification...
 {                   |                     | {
   Body              |                     |   Body
 }                   |                     | }
---------------------|---------------------|---------------------
 method M(x: X)      | method M(x: X)      | not allowed
   returns (y: Y)    |   returns (y: Y)    |
   specification...  |   specification...  |
 {                   |                     |
   Body;             |                     |
 }                   |                     |
---------------------|---------------------|---------------------
 type Opaque         | type Opaque         | type Opaque
 {                   |                     |
   // members...     |                     |
 }                   |                     |
---------------------|---------------------|---------------------
 type Synonym = T    | type Synonym        | type Synonym = T
---------------------|---------------------|---------------------
 type S = x: X       | type S              | type S = x: X
   | P witness E     |                     |   | P witness E
---------------------|---------------------|---------------------
 newtype N = x: X    | type N              | newtype N = x: X
   | P witness E     |                     |   | P witness E
 {                   |                     |
   // members...     |                     |
 }                   |                     |

---------------------|---------------------|---------------------
 datatype D =        | type D              | datatype D =
     Ctor0(x0: X0)   |                     |    Ctor0(x0: X0)
   | Ctor1(x1: X1)   |                     |  | Ctor1(x1: X1)
   | ...             |                     |  | ...
 {                   |                     |
   // members...     |                     |
 }                   |                     |
---------------------|---------------------|---------------------
 class Cl            | type Cl             | class Cl
   extends T0, ...   |                     |   extends T0, ...
 {                   |                     | {
   constructor ()    |                     |   constructor ()
     spec...         |                     |     spec...
   {                 |                     |
     Body;           |                     |
   }                 |                     |
   // members...     |                     |
 }                   |                     | }
---------------------|---------------------|---------------------
 trait Tr            | type Tr             | trait Tr
   extends T0, ...   |                     |   extends T0, ...
 {                   |                     |
   // members...     |                     |
 }                   |                     |
---------------------|---------------------|---------------------
 iterator Iter(x: X) | type Iter           | iterator Iter(x: X)
   yields (y: Y)     |                     |   yields (y: Y)
   specification...  |                     |   specification...
 {                   |                     |
   Body;             |                     |
 }                   |                     |
---------------------|---------------------|---------------------
 module SubModule    | module SubModule    | not allowed
   ...               |   ...               |
 {                   | {                   |
   export SubModule  |   export SubModule  |
     ...             |     ...             |
   export A ...      |                     |
   // decls...       |   // decls...       |
 }                   | }                   |
---------------------|---------------------|---------------------
 import L = MS       | import L = MS       | not allowed
---------------------|---------------------|---------------------

Variations of functions (e.g., predicate, twostate function) are handled like function above, and variations of methods (e.g., lemma and twostate lemma) are treated like method above. Since the whole signature is exported, a function or method is exported to be of the same kind, even through provides. For example, an exported twostate lemma is exported as a twostate lemma (and thus is known by importers to have two implicit heap parameters), and an exported least predicate P is exported as a least predicate P (and thus importers can use both P and its prefix predicate P#).

If C is a class, trait, or iterator, then provides C exports the non-null reference type C as an opaque type. This does not reveal that C is a reference type, nor does it export the nullable type C?.

In most cases, exporting a class, trait, datatype, codatatype, or opaque type does not automatically export its members. Instead, any member to be exported must be listed explicitly. For example, consider the type declaration

trait Tr {
  function F(x: int): int { 10 }
  function G(x: int): int { 12 }
  function H(x: int): int { 14 }
}

An export set that contains only reveals Tr has the effect of exporting

trait Tr {
}

and an export set that contains only provides Tr, Tr.F reveals Tr.H has the effect of exporting

type Tr {
  function F(x: int): int
  function H(x: int): int { 14 }
}

There is no syntax (for example, Tr.*) to export all members of a type.

Some members are exported automatically when the type is revealed. Specifically:

For a class, a constructor member can be exported only if the class is revealed. For a class or trait, a var member can be exported only if the class or trait is revealed (but a const member can be exported even if the enclosing class or trait is only provided).

When exporting a sub-module, only the sub-module’s eponymous export set is exported. There is no way for a parent module to export any other export set of a sub-module, unless it is done via an import declaration of the parent module.

The effect of declaring an import as opened is confined to the importing module. That is, the ability of use such imported names as unqualified is not passed on to further imports, as the following example illustrates:

module Library {
  const xyz := 16
}

module M {
  export
    provides Lib
    provides xyz // error: 'xyz' is not declared locally

  import opened Lib = Library

  const k0 := Lib.xyz
  const k1 := xyz
}

module Client {
  import opened M

  const a0 := M.Lib.xyz
  const a1 := Lib.xyz
  const a2 := M.xyz // error: M does not have a declaration 'xyz'
  const a3 := xyz // error: unresolved identifier 'xyz'
}

As highlighted in this example, module M can use xyz as if it were a local name (see declaration k1), but the unqualified name xyz is not made available to importers of M (see declarations a2 and a3), nor is it possible for M to export the name xyz.

A few other notes:

4.5.2. Extends list

An export set declaration may include an extends list, which is a list of one or more export set names from the same module containing the declaration (including export set names obtained from a refinement parent). The effect is to include in the declaration the union of all the names in the export sets in the extends list, along with any other names explicitly included in the declaration. So for example in 

module M {
  const a := 10;
  const b := 10;
  const c := 10;
  export A reveals a
  export B reveals b
  export C extends A, B
    reveals c
}

export set C will contain the names a, b, and c.

4.6. Module Abstraction

Sometimes, using a specific implementation is unnecessary; instead, all that is needed is a module that implements some interface. In that case, you can use an abstract module import. In Dafny, this is written import A : B. This means bind the name A as before, but instead of getting the exact module B, you get any module which adheres to B. Typically, the module B may have abstract type definitions, classes with bodiless methods, or otherwise be unsuitable to use directly. Because of the way refinement is defined, any refinement of B can be used safely. For example, if we start with:

module Interface {
  function method addSome(n: nat): nat
    ensures addSome(n) > n
}
abstract module Mod {
  import A : Interface
  method m() {
    assert 6 <= A.addSome(5);
  }
}

We can be more precise if we know that addSome actually adds exactly one. The following module has this behavior. Further, the postcondition is stronger, so this is actually a refinement of the Interface module.

module Implementation {
  function method addSome(n: nat): nat
    ensures addSome(n) == n + 1
  {
    n + 1
  }
}

We can then substitute Implementation for A in a new module, by declaring a refinement of Mod which defines A to be Implementation.

module Interface {
  function method addSome(n: nat): nat
    ensures addSome(n) > n
}
abstract module Mod {
  import A : Interface
  method m() {
    assert 6 <= A.addSome(5);
  }
}
module Implementation {
  function method addSome(n: nat): nat
    ensures addSome(n) == n + 1
  {
    n + 1
  }
}
module Mod2 refines Mod {
  import A = Implementation
  ...
}

When you refine an abstract import into a concrete one Dafny checks that the concrete module is a refinement of the abstract one. This means that the methods must have compatible signatures, all the classes and datatypes with their constructors and fields in the abstract one must be present in the concrete one, the specifications must be compatible, etc.

A module that includes an abstract import must be declared abstract.

4.7. Module Ordering and Dependencies

Dafny isn’t particular about the textual order in which modules are declared, but they must follow some rules to be well formed. In particular, there must be a way to order the modules in a program such that each only refers to things defined before it in the ordering. That doesn’t mean the modules have to be given textually in that order in the source text. Dafny will figure out that order for you, assuming you haven’t made any circular references. For example, this is pretty clearly meaningless:

import A = B
import B = A // error: circular

You can have import statements at the toplevel and you can import modules defined at the same level:

import A = B
method m() {
  A.whatever();
}
module B { method whatever() {} }

In this case, everything is well defined because we can put B first, followed by the A import, and then finally m(). If there is no permitted ordering, then Dafny will give an error, complaining about a cyclic dependency.

Note that when rearranging modules and imports, they have to be kept in the same containing module, which disallows some pathological module structures. Also, the imports and submodules are always considered to be before their containing module, even at the toplevel. This means that the following is not well formed:

method doIt() { }
module M {
  method m() {
    doIt(); // error: M precedes doIt
  }
}

because the module M must come before any other kind of members, such as methods. To define global functions like this, you can put them in a module (called Globals, say) and open it into any module that needs its functionality. Finally, if you import via a path, such as import A = B.C, then this creates a dependency of A on B, and B itself depends on its own nested module B.C.

4.8. Name Resolution

When Dafny sees something like A<T>.B<U>.C<V>, how does it know what each part refers to? The process Dafny uses to determine what identifier sequences like this refer to is name resolution. Though the rules may seem complex, usually they do what you would expect. Dafny first looks up the initial identifier. Depending on what the first identifier refers to, the rest of the identifier is looked up in the appropriate context.

In terms of the grammar, sequences like the above are represented as a NameSegment followed by 0 or more Suffixes. The form shown above contains three instances of AugmentedDotSuffix_.

The resolution is different depending on whether it is in a module context, an expression context or a type context.

4.8.1. Modules and name spaces

A module is a collection of declarations, each of which has a name. These names are held in two namespaces.

In addition names can be classified as local or imported.

Within each namespace, the local names are unique. Thus a module may not reuse a name that a refinement parent has declared (unless it is a refining declaration, which replaces both declarations, as described in Section 22).

Local names take precedence over imported names. If a name is used more than once among imported names (coming from different imports), then it is ambiguous to use the name without qualification.

4.8.2. Module Id Context Name Resolution

A qualified name may be used to refer to a module in an import statement or a refines clause of a module declaration. Such a qualified name is resolved as follows, with respect to its syntactic location within a module Z:

  1. The leading NameSegment is resolved as a local or imported module name of Z, if there is one with a matching name. The target of a refines clause does not consider local names, that is, in module Z refines A.B.C, any contents of Z are not considered in finding A.

  2. Otherwise, it is resolved as a local or imported module name of the most enclosing module of Z, iterating outward to each successive enclosing module until a match is found or the default toplevel module is reached without a match. No consideration of export sets, default or otherwise, is used in this step. However, if at any stage a matching name is found that is not a module declaration, the resolution fails. See the examples below.

3a. Once the leading NameSegment is resolved as say module M, the next NameSegment is resolved as a local or imported module name within M. The resolution is restricted to the default export set of M.

3b. If the resolved module name is a module alias (from an import statement) then the target of the alias is resolved as a new qualified name with respect to its syntactic context (independent of any resolutions or modules so far). Since Z depends on M, any such alias target will already have been resolved, because modules are resolved in order of dependency.

  1. Step 3 is iterated for each NameSegment in the qualified module id, resulting in a module that is the final resolution of the complete qualified id.

Ordinarily a module must be imported in order for its constituent declarations to be visible inside a given module M. However, for the resolution of qualified names this is not the case.

This example shows that the resolution of the refinement parent does not use any local names: 

module A {
  const a := 10
}

module B refines A { // the top-level A, not the submodule A
  module A { const a := 30 }
  method m() { assert a == 10; } // true
}

In the example, the A in refines A refers to the global A, not the submodule A.

4.8.3. Expression Context Name Resolution

The leading NameSegment is resolved using the first following rule that succeeds.

  1. Local variables, parameters and bound variables. These are things like x, y, and i in var x;, ... returns (y: int), and forall i :: .... The declaration chosen is the match from the innermost matching scope.

  2. If in a class, try to match a member of the class. If the member that is found is not static an implicit this is inserted. This works for fields, functions, and methods of the current class (if in a static context, then only static methods and functions are allowed). You can refer to fields of the current class either as this.f or f, assuming of course that f is not hidden by one of the above. You can always prefix this if needed, which cannot be hidden. (Note that a field whose name is a string of digits must always have some prefix.)

  3. If there is no Suffix, then look for a datatype constructor, if unambiguous. Any datatypes that don’t need qualification (so the datatype name itself doesn’t need a prefix) and also have a uniquely named constructor can be referred to just by name. So if datatype List = Cons(List) | Nil is the only datatype that declares Cons and Nil constructors, then you can write Cons(Cons(Nil)). If the constructor name is not unique, then you need to prefix it with the name of the datatype (for example List.Cons(List.Nil))). This is done per constructor, not per datatype.

  4. Look for a member of the enclosing module.

  5. Module-level (static) functions and methods

In each module, names from opened modules are also potential matches, but only after names declared in the module. If an ambiguous name is found or a name of the wrong kind (e.g. a module instead of an expression identifier), an error is generated, rather than continuing down the list.

After the first identifier, the rules are basically the same, except in the new context. For example, if the first identifier is a module, then the next identifier looks into that module. Opened modules only apply within the module it is opened into. When looking up into another module, only things explicitly declared in that module are considered.

To resolve expression E.id:

First resolve expression E and any type arguments.

4.8.4. Type Context Name Resolution

In a type context the priority of NameSegment resolution is:

  1. Type parameters.

  2. Member of enclosing module (type name or the name of a module).

To resolve expression E.id:

5. Specifications

Specifications describe logical properties of Dafny methods, functions, lambdas, iterators and loops. They specify preconditions, postconditions, invariants, what memory locations may be read or modified, and termination information by means of specification clauses. For each kind of specification, zero or more specification clauses (of the type accepted for that type of specification) may be given, in any order.

We document specifications at these levels:

This section documents the first two of these in a bottom-up manner. We first document the clauses and then the specifications that use them.

Specification clauses typically appear in a sequence. They all begin with a keyword and do not end with semicolons.

5.1. Specification Clauses

Within expressions in specification clauses, you can use specification expressions along with any other expressions you need.

5.1.1. Requires Clause

RequiresClause(allowLabel) =
  "requires" { Attribute }
  [ LabelName ":" ]  // Label allowed only if allowLabel is true
  Expression(allowLemma: false, allowLambda: false)

The requires clauses specify preconditions for methods, functions, lambda expressions and iterators. Dafny checks that the preconditions are met at all call sites. The callee may then assume the preconditions hold on entry.

If no requires clause is specified, then a default implicit clause requires true is used.

If more than one requires clause is given, then the precondition is the conjunction of all of the expressions from all of the requires clauses, with a collected list of all the given Attributes. The order of conjunctions (and hence the order of requires clauses with respect to each other) can be important: earlier conjuncts can set conditions that establish that later conjuncts are well-defined.

5.1.2. Ensures Clause

EnsuresClause(allowLambda) =
  "ensures" { Attribute } Expression(allowLemma: false,
                                     allowLambda)

An ensures clause specifies the post condition for a method, function or iterator.

If no ensures clause is specified, then a default implicit clause ensures true is used.

If more than one ensures clause is given, then the postcondition is the conjunction of all of the expressions from all of the ensures clauses, with a collected list of all the given Attributes. The order of conjunctions (and hence the order of ensures clauses with respect to each other) can be important: earlier conjuncts can set conditions that establish that later conjuncts are well-defined.

5.1.3. Decreases Clause

DecreasesClause(allowWildcard, allowLambda) =
  "decreases" { Attribute } DecreasesList(allowWildcard,
                                          allowLambda)

DecreasesList(allowWildcard, allowLambda) =
  PossiblyWildExpression(allowLambda, allowWildcard)
  { "," PossiblyWildExpression(allowLambda, allowWildcard) }

PossiblyWildExpression(allowLambda, allowWild) =
  ( "*"  // if allowWild is false, using '*' provokes an error
  | Expression(allowLemma: false, allowLambda)
  )

If allowWildcard is false but one of the PossiblyWildExpressions is a wild-card, an error is reported.

Decreases clauses are used to prove termination in the presence of recursion. If more than one decreases clause is given it is as if a single decreases clause had been given with the collected list of arguments and a collected list of Attributes. That is,

decreases A, B
decreases C, D

is equivalent to

decreases A, B, C, D

Note that changing the order of multiple decreases clauses will change the order of the expressions within the equivalent single decreases clause, and will therefore have different semantics.

Loops and compiled methods (but not functions and not ghost methods, including lemmas) can be specified to be possibly non-terminating. This is done by declaring the method or loop with decreases *, which causes the proof of termination to be skipped. If a * is present in a decreases clause, no other expressions are allowed in the decreases clause. A method that contains a possibly non-terminating loop or a call to a possibly non-terminating method must itself be declared as possibly non-terminating.

Termination metrics in Dafny, which are declared by decreases clauses, are lexicographic tuples of expressions. At each recursive (or mutually recursive) call to a function or method, Dafny checks that the effective decreases clause of the callee is strictly smaller than the effective decreases clause of the caller.

What does “strictly smaller” mean? Dafny provides a built-in well-founded order for every type and, in some cases, between types. For example, the Boolean false is strictly smaller than true, the integer 78 is strictly smaller than 102, the set {2,5} is strictly smaller than (because it is a proper subset of) the set {2,3,5}, and for s of type seq<Color> where Color is some inductive datatype, the color s[0] is strictly less than s (provided s is nonempty).

What does “effective decreases clause” mean? Dafny always appends a “top” element to the lexicographic tuple given by the user. This top element cannot be syntactically denoted in a Dafny program and it never occurs as a run-time value either. Rather, it is a fictitious value, which here we will denote $\top$, such that each value that can ever occur in a Dafny program is strictly less than $\top$. Dafny sometimes also prepends expressions to the lexicographic tuple given by the user. The effective decreases clause is any such prefix, followed by the user-provided decreases clause, followed by $\top$. We said “user-provided decreases clause”, but if the user completely omits a decreases clause, then Dafny will usually make a guess at one, in which case the effective decreases clause is any prefix followed by the guess followed by $\top$.

Here is a simple but interesting example: the Fibonacci function.

function Fib(n: nat) : nat
{
  if n < 2 then n else Fib(n-2) + Fib(n-1)
}

In this example, Dafny supplies a decreases n clause.

Let’s take a look at the kind of example where a mysterious-looking decreases clause like “Rank, 0” is useful.

Consider two mutually recursive methods, A and B: 

method A(x: nat)
{
  B(x);
}

method B(x: nat)
{
  if x != 0 { A(x-1); }
}

To prove termination of A and B, Dafny needs to have effective decreases clauses for A and B such that:

Satisfying the second of these conditions is easy, but what about the first? Note, for example, that declaring both A and B with “decreases x” does not work, because that won’t prove a strict decrease for the call from A(x) to B(x).

Here’s one possibility: 

method A(x: nat)
  decreases x, 1
{
  B(x);
}

method B(x: nat)
  decreases x, 0
{
  if x != 0 { A(x-1); }
}

For the call from A(x) to B(x), the lexicographic tuple "x, 0" is strictly smaller than "x, 1", and for the call from B(x) to A(x-1), the lexicographic tuple "x-1, 1" is strictly smaller than "x, 0".

Two things to note: First, the choice of “0” and “1” as the second components of these lexicographic tuples is rather arbitrary. It could just as well have been “false” and “true”, respectively, or the sets {2,5} and {2,3,5}. Second, the keyword decreases often gives rise to an intuitive English reading of the declaration. For example, you might say that the recursive calls in the definition of the familiar Fibonacci function Fib(n) “decreases n”. But when the lexicographic tuple contains constants, the English reading of the declaration becomes mysterious and may give rise to questions like “how can you decrease the constant 0?”. The keyword is just that—a keyword. It says “here comes a list of expressions that make up the lexicographic tuple we want to use for the termination measure”. What is important is that one effective decreases clause is compared against another one, and it certainly makes sense to compare something to a constant (and to compare one constant to another).

We can simplify things a little bit by remembering that Dafny appends $\top$ to the user-supplied decreases clause. For the A-and-B example, this lets us drop the constant from the decreases clause of A:

method A(x: nat)
   decreases x
{
  B(x);
}

method B(x: nat)
  decreases x, 0
{
  if x != 0 { A(x-1); }
}

The effective decreases clause of A is $(x, \top)$ and the effective decreases clause of B is $(x, 0, \top)$. These tuples still satisfy the two conditions $(x, 0, \top) < (x, \top)$ and $(x-1, \top) < (x, 0, \top)$. And as before, the constant “0” is arbitrary; anything less than $\top$ (which is any Dafny expression) would work.

Let’s take a look at one more example that better illustrates the utility of $\top$. Consider again two mutually recursive methods, call them Outer and Inner, representing the recursive counterparts of what iteratively might be two nested loops: 

method Outer(x: nat)
{
  // set y to an arbitrary non-negative integer
  var y :| 0 <= y;
  Inner(x, y);
}

method Inner(x: nat, y: nat)
{
  if y != 0 {
    Inner(x, y-1);
  } else if x != 0 {
    Outer(x-1);
  }
}

The body of Outer uses an assign-such-that statement to represent some computation that takes place before Inner is called. It sets “y” to some arbitrary non-negative value. In a more concrete example, Inner would do some work for each “y” and then continue as Outer on the next smaller “x”.

Using a decreases clause $(x, y)$ for Inner seems natural, but if we don’t have any bound on the size of the $y$ computed by Outer, there is no expression we can write in the decreases clause of Outer that is sure to lead to a strictly smaller value for $y$ when Inner is called. $\top$ to the rescue. If we arrange for the effective decreases clause of Outer to be $(x, \top)$ and the effective decreases clause for Inner to be $(x, y, \top)$, then we can show the strict decreases as required. Since $\top$ is implicitly appended, the two decreases clauses declared in the program text can be: 

method Outer(x: nat)
  decreases x
{
  // set y to an arbitrary non-negative integer
  var y :| 0 <= y;
  Inner(x, y);
}

method Inner(x: nat, y: nat)
  decreases x,y
{
  if y != 0 {
    Inner(x, y-1);
  } else if x != 0 {
    Outer(x-1);
  }
}

Moreover, remember that if a function or method has no user-declared decreases clause, Dafny will make a guess. The guess is (usually) the list of arguments of the function/method, in the order given. This is exactly the decreases clauses needed here. Thus, Dafny successfully verifies the program without any explicit decreases clauses: 

method Outer(x: nat)
{
  var y :| 0 <= y;
  Inner(x, y);
}

method Inner(x: nat, y: nat)
{
  if y != 0 {
    Inner(x, y-1);
  } else if x != 0 {
    Outer(x-1);
  }
}

The ingredients are simple, but the end result may seem like magic. For many users, however, there may be no magic at all – the end result may be so natural that the user never even has to be bothered to think about that there was a need to prove termination in the first place.

Though Dafny fixes a well-founded order that it uses when checking termination, Dafny does not surface this ordering directly in expressions. That is, syntactically, there is no single operator that stands for the well-founded ordering.

5.1.4. Framing

FrameExpression(allowLemma, allowLambda) =
  ( Expression(allowLemma, allowLambda) [ FrameField ]
  | FrameField
  )

FrameField = "`" IdentOrDigits

PossiblyWildFrameExpression(allowLemma, allowLambda, allowWild) =
  ( "*"  // error if !allowWild and '*'
  | FrameExpression(allowLemma, allowLambda)
  )

Frame expressions are used to denote the set of memory locations that a Dafny program element may read or write. A frame expression is a set expression. The form {} is the empty set. The type of the frame expression is set<object>.

Note that framing only applies to the heap, or memory accessed through references. Local variables are not stored on the heap, so they cannot be mentioned (well, they are not in scope in the declaration) in reads annotations. Note also that types like sets, sequences, and multisets are value types, and are treated like integers or local variables. Arrays and objects are reference types, and they are stored on the heap (though as always there is a subtle distinction between the reference itself and the value it points to.)

The FrameField construct is used to specify a field of a class object. The identifier following the back-quote is the name of the field being referenced. If the FrameField is preceded by an expression the expression must be a reference to an object having that field. If the FrameField is not preceded by an expression then the frame expression is referring to that field of the current object. This form is only used within a method of a class or trait.

A FrameField can be useful in the following case: When a method modifies only one field, rather than writing

class A {
  var i: int
  var x0: int
  var x1: int
  var x2: int
  var x3: int
  var x4: int
  method M()
    modifies this
    ensures unchanged(`x0) && unchanged(`x1) && unchanged(`x2) && unchanged(`x3) && unchanged(`x4)
  { i := i + 1; }
}

one can write the more concise:

class A {
  var i: int
  var x0: int
  var x1: int
  var x2: int
  var x3: int
  var x4: int
  method M()
    modifies `i
  { i := i + 1; }
}

There’s (unfortunately) no form of it for array elements – but to account for unchanged elements, you can always write forall i | 0 <= i < |a| :: unchanged(a[i]). A FrameField is not taken into consideration for lambda expressions.

5.1.5. Reads Clause

ReadsClause(allowLemma, allowLambda, allowWild) =
  "reads"
  { Attribute }
  PossiblyWildFrameExpression(allowLemma, allowLambda, allowWild)
  { "," PossiblyWildFrameExpression(allowLemma, allowLambda, allowWild) }

Functions are not allowed to have side effects; they may also be restricted in what they can read. The reading frame of a function (or predicate) is all the memory locations that the function is allowed to read. The reason we might limit what a function can read is so that when we write to memory, we can be sure that functions that did not read that part of memory have the same value they did before. For example, we might have two arrays, one of which we know is sorted. If we did not put a reads annotation on the sorted predicate, then when we modify the unsorted array, we cannot determine whether the other array stopped being sorted. While we might be able to give invariants to preserve it in this case, it gets even more complex when manipulating data structures. In this case, framing is essential to making the verification process feasible.

It is not just the body of a function that is subject to reads checks, but also its precondition and the reads clause itself.

A reads clause can list a wildcard *, which allows the enclosing function to read anything. In many cases, and in particular in all cases where the function is defined recursively, this makes it next to impossible to make any use of the function. Nevertheless, as an experimental feature, the language allows it (and it is sound). If a reads clause uses *, then the reads clause is not allowed to mention anything else (since anything else would be irrelevant, anyhow).

A reads clause specifies the set of memory locations that a function, lambda, or iterator may read. The memory locations are all the fields of all of the references given in the set specified in the frame expression and the single fields given in FrameField elements of the frame expression. For example, in 

class C {
  var x: int
  var y: int

  predicate f(c: C) 
    reads this, c`x
  {
    this.x == c.x
  }
}

the reads clause allows reading this.x, this,y, and c.x (which may be the same memory location as this.x). }

If more than one reads clause is given in a specification the effective read set is the union of the sets specified. If there are no reads clauses the effective read set is empty. If * is given in a reads clause it means any memory may be read.

If a reads clause refers to a sequence or multiset, that collection (call it c) is converted to a set by adding an implicit set comprehension of the form set o: object | o in c before computing the union of object sets from other reads clauses.

An expression in a reads clause is also allowed to be a function call whose value is a collection of references. Such an expression is converted to a set by taking the union of the function’s image over all inputs. For example, if F is a function from int to set<object>, then reads F has the meaning

set x: int, o: object | o in F(x) :: o

This is particularly useful when wanting to specify the reads set of another function. For example, function Sum adds up the values of f(i) where i ranges from lo to hi:

function Sum(f: int ~> real, lo: int, hi: int): real
  requires lo <= hi
  requires forall i :: lo <= i < hi ==> f.requires(i)
  reads f.reads
  decreases hi - lo
{
  if lo == hi then 0.0 else
    f(lo) + Sum(f, lo + 1, hi)
}

Its reads specification says that Sum(f, lo, hi) may read anything that f may read on any input. Note that f.reads is itself a function, whose type is int ~> set<object>. (The specification reads f.reads gives an overapproximation of what Sum will actually read. More precise would be to specify that Sum reads only what f reads on the values from lo to hi, but the larger set denoted by reads f.reads is easier to write down and is often good enough.)

Note, only reads clauses, not modifies clauses, are allowed to include functions as just described.

5.1.6. Modifies Clause

ModifiesClause(allowLambda) =
  "modifies" { Attribute }
  FrameExpression(allowLemma: false, allowLambda)
  { "," FrameExpression(allowLemma: false, allowLambda) }

Frames also affect methods. Methods are not required to list the things they read. Methods are allowed to read whatever memory they like, but they are required to list which parts of memory they modify, with a modifies annotation. These are almost identical to their reads cousins, except they say what can be changed, rather than what the value of the function depends on. In combination with reads, modification restrictions allow Dafny to prove properties of code that would otherwise be very difficult or impossible. Reads and modifies are one of the tools that allow Dafny to work on one method at a time, because they restrict what would otherwise be arbitrary modifications of memory to something that Dafny can reason about.

Just as for a reads clause, the memory locations allowed to be modified in a method are all the fields of any object reference in the frame expression set and any specific field denoted by a FrameField in the modifies clause. For example, in 

class C {
  var next: C?
  var value: int

  method M() 
    modifies next
  { 
    ... 
  }
}

method M is permitted to modify this.next.next and this.next.value but not this.next. To be allowed to modify this.next, the modifies clause must include this, or some expression that evaluates to this.

If an object is newly allocated within the body of a method or within the scope of a modifies statement or a loop’s modifies clause, then the fields of that object may always be modified.

It is also possible to frame what can be modified by a block statement by means of the block form of the modify statement (cf. Section 20.22).

A modifies clause specifies the set of memory locations that a method, iterator or loop body may modify. If more than one modifies clause is given in a specification, the effective modifies set is the union of the sets specified. If no modifies clause is given the effective modifies set is empty. A loop can also have a modifies clause. If none is given, the loop may modify anything the enclosing context is allowed to modify.

Note that modifies here is used in the sense of writes. That is, a field that may not be modified may not be written to, even with the same value it already has or even if the value is restored later. The terminology and semantics varies among specification languages. Some define frame conditions in this sense (a) of writes and others in the sense (b) that allows writing a field with the same value or changing the value so long as the original value is restored by the end of the scope. For example, JML defines assignable and modifies as synonyms in the sense (a), though KeY interprets JML’s assigns/modifies in sense (b). ACSL and ACSL++ use the assigns keyword, but with modify (b) semantics. Ada/SPARK’s dataflow contracts encode write (a) semantics.

5.1.7. Invariant Clause

InvariantClause_ =
  "invariant" { Attribute }
  Expression(allowLemma: false, allowLambda: true)

An invariant clause is used to specify an invariant for a loop. If more than one invariant clause is given for a loop the effective invariant is the conjunction of the conditions specified.

The invariant must hold on entry to the loop. And assuming it is valid on entry, Dafny must be able to prove that it then holds at the end of the loop.

5.2. Method Specification

MethodSpec =
  { ModifiesClause(allowLambda: false)
  | RequiresClause(allowLabel: true)
  | EnsuresClause(allowLambda: false)
  | DecreasesClause(allowWildcard: true, allowLambda: false)
  }

A method specification is zero or more modifies, requires, ensures or decreases clauses, in any order. A method does not have reads clauses because methods are allowed to read any memory.

5.3. Function Specification

FunctionSpec =
  { RequiresClause(allowLabel: true)
  | ReadsClause(allowLemma: false, allowLambda: false,
                                   allowWild: true)
  | EnsuresClause(allowLambda: false)
  | DecreasesClause(allowWildcard: false, allowLambda: false)
  }

A function specification is zero or more reads, requires, ensures or decreases clauses, in any order. A function specification does not have modifies clauses because functions are not allowed to modify any memory.

5.4. Lambda Specification

LambdaSpec =
  { ReadsClause(allowLemma: true, allowLambda: false,
                                  allowWild: true)
  | "requires" Expression(allowLemma: false, allowLambda: false)
  }

A lambda specification provides a specification for a lambda function expression; it consists of zero or more reads or requires clauses. Any requires clauses may not have labels or attributes. Lambda specifications do not have ensures clauses because the body is never opaque. Lambda specifications do not have decreases clauses because lambda expressions do not have names and thus cannot be recursive. A lambda specification does not have modifies clauses because lambdas are not allowed to modify any memory.

5.5. Iterator Specification

IteratorSpec =
  { ReadsClause(allowLemma: false, allowLambda: false,
                                  allowWild: false)
  | ModifiesClause(allowLambda: false)
  | [ "yield" ] RequiresClause(allowLabel: !isYield)
  | [ "yield" ] EnsuresClause(allowLambda: false)
  | DecreasesClause(allowWildcard: false, allowLambda: false)
  }

An iterator specification applies both to the iterator’s constructor method and to its MoveNext method. The reads and modifies clauses apply to both of them. For the requires and ensures clauses, if yield is not present they apply to the constructor, but if yield is present they apply to the MoveNext method.

Examples of iterators, including iterator specifications, are given in Section 16. Briefly

5.6. Loop Specification

LoopSpec =
  { InvariantClause_
  | DecreasesClause(allowWildcard: true, allowLambda: true)
  | ModifiesClause(allowLambda: true)
  }

A loop specification provides the information Dafny needs to prove properties of a loop. The InvariantClause_ clause is effectively a precondition and it along with the negation of the loop test condition provides the postcondition. The DecreasesClause clause is used to prove termination.

5.7. Auto-generated boilerplate specifications

AutoContracts is an experimental feature that inserts much of the dynamic-frames boilerplate into a class. The user simply

AutoContracts then

In all the following cases, no modifies clause or reads clause is added if the user has given one.

6. Types

Type = DomainType_ | ArrowType_

A Dafny type is a domain type (i.e., a type that can be the domain of an arrow type) optionally followed by an arrow and a range type.

DomainType_ =
  ( BoolType_ | CharType_ | IntType_ | RealType_
  | OrdinalType_ | BitVectorType_ | ObjectType_
  | FiniteSetType_ | InfiniteSetType_
  | MultisetType_
  | FiniteMapType_ | InfiniteMapType_
  | SequenceType_
  | NatType_
  | StringType_
  | ArrayType_
  | TupleType
  | NamedType
  )

The domain types comprise the builtin scalar types, the builtin collection types, tuple types (including as a special case a parenthesized type) and reference types.

Dafny types may be categorized as either value types or reference types.

6.1. Value Types

The value types are those whose values do not lie in the program heap. These are:

Data items having value types are passed by value. Since they are not considered to occupy memory, framing expressions do not reference them.

The nat type is a pre-defined subset type of int.

Dafny does not include types themselves as values, nor is there a type of types.

6.2. Reference Types

Dafny offers a host of reference types. These represent references to objects allocated dynamically in the program heap. To access the members of an object, a reference to (that is, a pointer to or object identity of) the object is dereferenced.

The reference types are class types, traits and array types. Dafny supports both reference types that contain the special null value (nullable types) and reference types that do not (non-null types).

6.3. Named Types

NamedType = NameSegmentForTypeName { "." NameSegmentForTypeName }

A NamedType is used to specify a user-defined type by name (possibly module-qualified). Named types are introduced by class, trait, inductive, coinductive, synonym and opaque type declarations. They are also used to refer to type variables.

NameSegmentForTypeName = Ident [ GenericInstantiation ]

A NameSegmentForTypeName is a type name optionally followed by a GenericInstantiation, which supplies type parameters to a generic type, if needed. It is a special case of a NameSegment (Section 21.41) that does not allow a HashCall.

The following sections describe each of these kinds of types in more detail.

7. Basic types

Dafny offers these basic types: bool for booleans, char for characters, int and nat for integers, real for reals, ORDINAL, and bit-vector types.

7.1. Booleans

BoolType_ = "bool"

There are two boolean values and each has a corresponding literal in the language: false and true.

Type bool supports the following operations:

operator precedence description
<==> 1 equivalence (if and only if)
==> 2 implication (implies)
<== 2 reverse implication (follows from)
&& 3 conjunction (and)
|| 3 disjunction (or)
== 4 equality
!= 4 disequality
! 10 negation (not)

Negation is unary; the others are binary. The table shows the operators in groups of increasing binding power, with equality binding stronger than conjunction and disjunction, and weaker than negation. Within each group, different operators do not associate, so parentheses need to be used. For example, 

A && B || C    // error

would be ambiguous and instead has to be written as either 

(A && B) || C

or 

A && (B || C)

depending on the intended meaning.

7.1.1. Equivalence Operator

The expressions A <==> B and A == B give the same value, but note that <==> is associative whereas == is chaining and they have different precedence. So, 

A <==> B <==> C

is the same as 

A <==> (B <==> C)

and 

(A <==> B) <==> C

whereas 

A == B == C

is simply a shorthand for 

A == B && B == C

7.1.2. Conjunction and Disjunction

Conjunction and disjunction are associative. These operators are short circuiting (from left to right), meaning that their second argument is evaluated only if the evaluation of the first operand does not determine the value of the expression. Logically speaking, the expression A && B is defined when A is defined and either A evaluates to false or B is defined. When A && B is defined, its meaning is the same as the ordinary, symmetric mathematical conjunction &. The same holds for || and |.

7.1.3. Implication and Reverse Implication

Implication is right associative and is short-circuiting from left to right. Reverse implication B <== A is exactly the same as A ==> B, but gives the ability to write the operands in the opposite order. Consequently, reverse implication is left associative and is short-circuiting from right to left. To illustrate the associativity rules, each of the following four lines expresses the same property, for any A, B, and C of type bool: 

A ==> B ==> C
A ==> (B ==> C) // parentheses redundant, ==> is right associative
C <== B <== A
(C <== B) <== A // parentheses redundant, <== is left associative

To illustrate the short-circuiting rules, note that the expression a.Length is defined for an array a only if a is not null (see Section 6.2), which means the following two expressions are well-formed: 

a != null ==> 0 <= a.Length
0 <= a.Length <== a != null

The contrapositives of these two expressions would be: 

a.Length < 0 ==> a == null  // not well-formed
a == null <== a.Length < 0  // not well-formed

but these expressions are not well-formed, since well-formedness requires the left (and right, respectively) operand, a.Length < 0, to be well-formed by itself.

Implication A ==> B is equivalent to the disjunction !A || B, but is sometimes (especially in specifications) clearer to read. Since, || is short-circuiting from left to right, note that 

a == null || 0 <= a.Length

is well-formed, whereas 

0 <= a.Length || a == null  // not well-formed

is not.

In addition, booleans support logical quantifiers (forall and exists), described in Section 21.35.

7.2. Numeric Types

IntType_ = "int"
RealType_ = "real"

Dafny supports numeric types of two kinds, integer-based, which includes the basic type int of all integers, and real-based, which includes the basic type real of all real numbers. User-defined numeric types based on int and real, either subset types or newtypes, are described in Section 11.3 and Section 12.

There is one built-in subset type, nat, representing the non-negative subrange of int.

The language includes a literal for each integer, like 0, 13, and 1985. Integers can also be written in hexadecimal using the prefix “0x”, as in 0x0, 0xD, and 0x7c1 (always with a lower case x, but the hexadecimal digits themselves are case insensitive). Leading zeros are allowed. To form negative literals, use the unary minus operator, as in -12, but not -(12).

There are also literals for some of the reals. These are written as a decimal point with a nonempty sequence of decimal digits on both sides, optionally prefixed by a - character. For example, 1.0, 1609.344, -12.5, and 0.5772156649. Real literals using exponents are not supported in Dafny. For now, you’d have to write your own function for that, e.g. 

// realExp(2.37, 100) computes 2.37e100
function method realExp(r: real, e: int): real decreases if e > 0 then e else -e {
  if e == 0 then r
  else if e < 0 then realExp(r/10.0, e+1)
  else realExp(r*10.0, e-1)
}

For integers (in both decimal and hexadecimal form) and reals, any two digits in a literal may be separated by an underscore in order to improve human readability of the literals. For example: 

const c1 := 1_000_000        // easier to read than 1000000
const c2 := 0_12_345_6789    // strange but legal formatting of 123456789
const c3 := 0x8000_0000      // same as 0x80000000 -- hex digits are
                             // often placed in groups of 4
const c4 := 0.000_000_000_1  // same as 0.0000000001 -- 1 Angstrom

In addition to equality and disequality, numeric types support the following relational operations, which have the same precedence as equality:

operator description
< less than
<= at most
>= at least
> greater than

Like equality and disequality, these operators are chaining, as long as they are chained in the “same direction”. That is, 

A <= B < C == D <= E

is simply a shorthand for 

A <= B && B < C && C == D && D <= E

whereas 

A < B > C

is not allowed.

There are also operators on each numeric type:

operator precedence description
+ 6 addition (plus)
- 6 subtraction (minus)
* 7 multiplication (times)
/ 7 division (divided by)
% 7 modulus (mod) – int only
- 10 negation (unary minus)

The binary operators are left associative, and they associate with each other in the two groups. The groups are listed in order of increasing binding power, with equality binding less strongly than any of these operators. There is no implicit conversion between int and real: use as int or as real conversions to write an explicit conversion (cf. Section 21.10).

Modulus is supported only for integer-based numeric types. Integer division and modulus are the Euclidean division and modulus. This means that modulus always returns a non-negative value, regardless of the signs of the two operands. More precisely, for any integer a and non-zero integer b, 

a == a / b * b + a % b
0 <= a % b < B

where B denotes the absolute value of b.

Real-based numeric types have a member Floor that returns the floor of the real value (as an int value), that is, the largest integer not exceeding the real value. For example, the following properties hold, for any r and r' of type real: 

method m(r: real, r': real) {
  assert 3.14.Floor == 3;
  assert (-2.5).Floor == -3;
  assert -2.5.Floor == -2; // This is -(2.5.Floor)
  assert r.Floor as real <= r;
  assert r <= r' ==> r.Floor <= r'.Floor;
}

Note in the third line that member access (like .Floor) binds stronger than unary minus. The fourth line uses the conversion function as real from int to real, as described in Section 21.10.

7.3. Bit-vector Types

BitVectorType_ = bvToken

Dafny includes a family of bit-vector types, each type having a specific, constant length, the number of bits in its values. Each such type is distinct and is designated by the prefix bv followed (without white space) by a postive integer without leading zeros or zero, stating the number of bits. For example, bv1, bv8, and bv32 are legal bit-vector type names. The type bv0 is also legal; it is a bit-vector type with no bits and just one value, 0x0.

Constant literals of bit-vector types are given by integer literals converted automatically to the designated type, either by an implicit or explicit conversion operation or by initialization in a declaration. Dafny checks that the constant literal is in the correct range. For example, 

const i: bv1 := 1
const j: bv8 := 195
const k: bv2 := 5 // error - out of range
const m := (194 as bv8) | (7 as bv8)

Bit-vector values can be converted to and from int and other bit-vector types, as long as the values are in range for the target type. Bit-vector values are always considered unsigned.

Bit-vector operations include bit-wise operators and arithmetic operators (as well as equality, disequality, and comparisons). The arithmetic operations truncate the high-order bits from the results; that is, they perform unsigned arithmetic modulo 2^{number of bits}, like 2’s-complement machine arithmetic.

operator precedence description
<< 5 bit-limited bit-shift left
>> 5 unsigned bit-shift right
+ 6 bit-limited addition
- 6 bit-limited subtraction
* 7 bit-limited multiplication
& 8 bit-wise and
| 8 bit-wise or
^ 8 bit-wise exclusive-or
- 10 bit-limited negation (unary minus)
! 10 bit-wise complement
.RotateLeft(n) 11 rotates bits left by n bit positions
.RotateRight(n) 11 rotates bits right by n bit positions

The groups of operators lower in the table above bind more tightly.1 All operators bind more tightly than equality, disequality, and comparisons. All binary operators are left-associative, but the bit-wise &, |, and ^ do not associate together (parentheses are required to disambiguate).

The right-hand operand of bit-shift operations is an int value, must be non-negative, and no more than the number of bits in the type. There is no signed right shift as all bit-vector values correspond to non-negative integers.

The argument of the RotateLeft and RotateRight operations is a non-negative int that is no larger than the bit-width of the value being rotated. RotateLeft moves bits to higher bit positions (e.g., (2 as bv4).RotateLeft(1) == (4 as bv4) and (8 as bv4).RotateLeft(1) == (1 as bv4)); RotateRight moves bits to lower bit positions, so b.RotateLeft(n).RotateRight(n) == b.

Here are examples of the various operations (all the assertions are true except where indicated): 

const i: bv4 := 9
const j: bv4 := 3

method m() {
  assert (i & j) == (1 as bv4);
  assert (i | j) == (11 as bv4);
  assert (i ^ j) == (10 as bv4);
  assert !i == (6 as bv4);
  assert -i == (7 as bv4);
  assert (i + i) == (2 as bv4);
  assert (j - i) == (10 as bv4);
  assert (i * j) == (11 as bv4);
  assert (i as int) / (j as int) == 3;
  assert (j << 1) == (6 as bv4);
  assert (i << 1) == (2 as bv4);
  assert (i >> 1) == (4 as bv4);
  assert i == 9; // auto conversion of literal to bv4
  assert i * 4 == j + 8 + 9; // arithmetic is modulo 16
  assert i + j >> 1 == (i + j) >> 1; // + - bind tigher than << >>
  assert i + j ^ 2 == i + (j^2);
  assert i * j & 1 == i * (j&1); // & | ^ bind tighter than + - *
}

The following are incorrectly formed: 

const i: bv4 := 9
const j: bv4 := 3

method m() {
  assert i & 4 | j == 0 ; // parentheses required
}

const k: bv4 := 9

method p() {
  assert k as bv5 == 9 as bv6; // error: mismatched types
}

These produce assertion errors: 

const i: bv4 := 9

method m() {
  assert i as bv3 == 1; // error: i is out of range for bv3
}

const j: bv4 := 9

method n() {
  assert j == 25; // error: 25 is out of range for bv4
}

Bit-vector constants (like all constants) can be initialized using expressions, but pay attention to how type inference applies to such expressions. For example, 

const a: bv3 := -1

is legal because Dafny interprets -1 as a bv3 expression, because a has type bv3. Consequently the - is bv3 negation and the 1 is a bv3 literal; the value of the expression -1 is the bv3 value 7, which is then the value of a.

On the other hand, 

const b: bv3 := 6 & 11

is illegal because, again, the & is bv3 bit-wise-and and the numbers must be valid bv3 literals. But 11 is not a valid bv3 literal.

7.4. Ordinal type

OrdinalType_ = "ORDINAL"

Values of type ORDINAL behave like nats in many ways, with one important difference: there are ORDINAL values that are larger than any nat. The smallest of these non-nat ordinals is represented as $\omega$ in mathematics, though there is no literal expression in Dafny that represents this value.

The natural numbers are ordinals. Any ordinal has a successor ordinal (equivalent to adding 1). Some ordinals are limit ordinals, meaning they are not a successor to any other ordinal; the natural number 0 and $\omega$ are limit ordinals.

The offset of an ordinal is the number of successor operations it takes to reach it from a limit ordinal.

The Dafny type ORDINAL has these member functions:

In addition,

In Dafny, ORDINALs are used primarily in conjunction with extreme functions and lemmas.

7.5. Characters

CharType_ = "char"

Dafny supports a type char of characters.
Its exact meaning is controlled by the command-line switch --unicode-char:true|false.

If --unicode-char is disabled, then char represents any UTF-16 code unit. This includes surrogate code points.

If --unicode-char is enabled, then char represents any Unicode scalar value. This excludes surrogate code points.

Character literals are enclosed in single quotes, as in 'D'. Their form is described by the charToken nonterminal in the grammar. To write a single quote as a character literal, it is necessary to use an escape sequence. Escape sequences can also be used to write other characters. The supported escape sequences are the following:

escape sequence meaning
\' the character '
\" the character "
\\ the character \
\0 the null character, same as \u0000 or \U{0}
\n line feed
\r carriage return
\t horizontal tab
\uxxxx UTF-16 code unit whose hexadecimal code is xxxx, where each x is a hexadecimal digit
\U{x..x} Unicode scalar value whose hexadecimal code is x..x, where each x is a hexadecimal digit

The escape sequence for a double quote is redundant, because '"' and '\"' denote the same character—both forms are provided in order to support the same escape sequences in string literals (Section 10.3.5).

In the form \uxxxx, which is only allowed if --unicode-char is disabled, the u is always lower case, but the four hexadecimal digits are case insensitive.

In the form \U{x..x}, which is only allowed if --unicode-char is enabled, the U is always upper case, but the hexadecimal digits are case insensitive, and there must be at least one and at most six digits. Surrogate code points are not allowed. The hex digits may be interspersed with underscores for readability (but not beginning or ending with an underscore), as in \U{1_F680}.

Character values are ordered and can be compared using the standard relational operators:

operator description
< less than
<= at most
>= at least
> greater than

Sequences of characters represent strings, as described in Section 10.3.5.

Character values can be converted to and from int values using the as int and as char conversion operations. The result is what would be expected in other programming languages, namely, the int value of a char is the ASCII or Unicode numeric value.

The only other operations on characters are obtaining a character by indexing into a string, and the implicit conversion to string when used as a parameter of a print statement.

8. Type parameters

GenericParameters(allowVariance) =
  "<" [ Variance ] TypeVariableName { TypeParameterCharacteristics }
  { "," [ Variance ] TypeVariableName { TypeParameterCharacteristics } }
  ">"

// The optional Variance indicator is permitted only if allowVariance is true
Variance = ( "*" | "+" | "!" | "-" )

TypeParameterCharacteristics = "(" TPCharOption { "," TPCharOption } ")"

TPCharOption = ( "==" | "0" | "00" | "!" "new" )

Many of the types, functions, and methods in Dafny can be parameterized by types. These type parameters are typically declared inside angle brackets and can stand for any type.

Dafny has some inference support that makes certain signatures less cluttered (described in Section 24.2).

8.1. Declaring restrictions on type parameters

It is sometimes necessary to restrict type parameters so that they can only be instantiated by certain families of types, that is, by types that have certain properties. These properties are known as type characteristics. The following subsections describe the type characteristics that Dafny supports.

In some cases, type inference will infer that a type-parameter must be restricted in a particular way, in which case Dafny will add the appropriate suffix, such as (==), automatically.

If more than one restriction is needed, they are either listed comma-separated, inside the parentheses or as multiple parenthesized elements: T(==,0) or T(==)(0).

8.1.1. Equality-supporting type parameters: T(==)

Designating a type parameter with the (==) suffix indicates that the parameter may only be replaced in non-ghost contexts with types that are known to support run-time equality comparisons (== and !=). All types support equality in ghost contexts, as if, for some types, the equality function is ghost.

For example, 

method Compare<T(==)>(a: T, b: T) returns (eq: bool)
{
  if a == b { eq := true; } else { eq := false; }
}

is a method whose type parameter is restricted to equality-supporting types when used in a non-ghost context. Again, note that all types support equality in ghost contexts; the difference is only for non-ghost (that is, compiled) code. Coinductive datatypes, arrow types, and inductive datatypes with ghost parameters are examples of types that are not equality supporting.

8.1.2. Auto-initializable types: T(0)

At every access of a variable x of a type T, Dafny ensures that x holds a legal value of type T. If no explicit initialization is given, then an arbitrary value is assumed by the verifier and supplied by the compiler, that is, the variable is auto-initialized. For example, 

method m() {
  var n: nat; // Auto-initialized to an arbitrary value of type `nat`
  assert n >= 0; // true, regardless of the value of n
  var i: int;
  assert i >= 0; // possibly false, arbitrary ints may be negative
}

For some types (known as auto-init types), the compiler can choose an initial value, but for others it does not. Variables and fields whose type the compiler does not auto-initialize are subject to definite-assignment rules. These ensure that the program explicitly assigns a value to a variable before it is used. For more details see Section 24.6 and the --strict-definite-assignment command-line option. More detail on auto-initializing is in this document.

Dafny supports auto-init as a type characteristic. To restrict a type parameter to auto-init types, mark it with the (0) suffix. For example, 

method AutoInitExamples<A(0), X>() returns (a: A, x: X)
{
  // 'a' does not require an explicit initialization, since A is auto-init
  // error: out-parameter 'x' has not been given a value
}

In this example, an error is reported because out-parameter x has not been assigned—since nothing is known about type X, variables of type X are subject to definite-assignment rules. In contrast, since type parameter A is declared to be restricted to auto-init types, the program does not need to explicitly assign any value to the out-parameter a.

8.1.3. Nonempty types: T(00)

Auto-init types are important in compiled contexts. In ghost contexts, it may still be important to know that a type is nonempty. Dafny supports a type characteristic for nonempty types, written with the suffix (00). For example, 

method NonemptyExamples<B(00), X>() returns (b: B, ghost g: B, ghost h: X)
{
  // error: non-ghost out-parameter 'b' has not been given a value
  // ghost out-parameter 'g' is fine, since its type is nonempty
  // error: 'h' has not been given a value
}

Because of B’s nonempty type characteristic, ghost parameter g does not need to be explicitly assigned. However, Dafny reports an error for the non-ghost b, since B is not an auto-init type, and reports an error for h, since the type X could be empty.

Note that every auto-init type is nonempty.

8.1.4. Non-heap based: T(!new)

Dafny makes a distinction between types whose values are on the heap, i.e. references, like classes and arrays, and those that are strictly value-based, like basic types and datatypes. The practical implication is that references depend on allocation state (e.g., are affected by the old operation) whereas non-reference values are not. Thus it can be relevant to know whether the values of a type parameter are heap-based or not. This is indicated by the mode suffix (!new).

A type parameter characterized by (!new) is recursively independent of the allocation state. For example, a datatype is not a reference, but for a parameterized data type such as 

datatype Result<T> = Failure(error: string) | Success(value: T)

the instantiation Result<int> satisfies (!new), whereas Result<array<int>> does not.

Note that this characteristic of a type parameter is operative for both verification and compilation. Also, opaque types at the topmost scope are always implicitly (!new).

Here are some examples: 

datatype Result<T> = Failure(error: string) | Success(v: T)
datatype ResultN<T(!new)> = Failure(error: string) | Success(v: T)

class C {}

method m() {
  var x1: Result<int>;
  var x2: ResultN<int>;
  var x3: Result<C>;
  var x4: ResultN<C>; // error
  var x5: Result<array<int>>;
  var x6: ResultN<array<int>>; // error
}

8.2. Type parameter variance

Type parameters have several different variance and cardinality properties. These properties of type parameters are designated in a generic type definition. For instance, in type A<+T> = ... , the + indicates that the T position is co-variant. These properties are indicated by the following notation:

notation variance cardinality-preserving
(nothing) non-variant yes
+ co-variant yes
- contra-variant not necessarily
* co-variant not necessarily
! non-variant not necessarily

Cardinality preserving means that the cardinality of the type being defined never exceeds the cardinality of any of its type parameters. For example type T<X> = X -> bool is illegal and returns the error message formal type parameter 'X' is not used according to its variance specification (it is used left of an arrow) (perhaps try declaring 'X' as '-X' or '!X') The type X -> bool has strictly more values than the type X. This affects certain uses of the type, so Dafny requires the declaration of T to explicitly say so. Marking the type parameter X with - or ! announces that the cardinality of T<X> may by larger than that of X. If you use -, you’re also declaring T to be contravariant in its type argument, and if you use !, you’re declaring that T is non-variant in its type argument.

To fix it, we use the variance !:

type T<!X> = X -> bool

This states that T does not preserve the cardinality of X, meaning there could be strictly more values of type T<E> than values of type E for any E.

A more detailed explanation of these topics is here.

9. Generic Instantiation

GenericInstantiation = "<" Type { "," Type } ">"

When a generic entity is used, actual types must be specified for each generic parameter. This is done using a GenericInstantiation. If the GenericInstantiation is omitted, type inference will try to fill these in (cf. Section 24.2).

10. Collection types

Dafny offers several built-in collection types.

10.1. Sets

FiniteSetType_ = "set" [ GenericInstantiation ]

InfiniteSetType_ = "iset" [ GenericInstantiation ]

For any type T, each value of type set<T> is a finite set of T values.

Set membership is determined by equality in the type T, so set<T> can be used in a non-ghost context only if T is equality supporting.

For any type T, each value of type iset<T> is a potentially infinite set of T values.

A set can be formed using a set display expression, which is a possibly empty, unordered, duplicate-insensitive list of expressions enclosed in curly braces. To illustrate, 

{}        {2, 7, 5, 3}        {4+2, 1+5, a*b}

are three examples of set displays. There is also a set comprehension expression (with a binder, like in logical quantifications), described in Section 21.36.

In addition to equality and disequality, set types support the following relational operations:

operator description
< proper subset
<= subset
>= superset
> proper superset

Like the arithmetic relational operators, these operators are chaining.

Sets support the following binary operators, listed in order of increasing binding power:

operator precedence description
!! 4 disjointness
+ 6 set union
- 6 set difference
* 7 set intersection

The associativity rules of +, -, and * are like those of the arithmetic operators with the same names. The expression A !! B, whose binding power is the same as equality (but which neither associates nor chains with equality), says that sets A and B have no elements in common, that is, it is equivalent to 

A * B == {}

However, the disjointness operator is chaining though in a slightly different way than other chaining operators: A !! B !! C !! D means that A, B, C and D are all mutually disjoint, that is 

A * B == {} && (A + B) * C == {} && (A + B + C) * D == {}

In addition, for any set s of type set<T> or iset<T> and any expression e of type T, sets support the following operations:

expression precedence result type description
e in s 4 bool set membership
e !in s 3 bool set non-membership
|s| 11 nat set cardinality (not for iset)

The expression e !in s is a syntactic shorthand for !(e in s).

10.2. Multisets

MultisetType_ = "multiset" [ GenericInstantiation ]

A multiset is similar to a set, but keeps track of the multiplicity of each element, not just its presence or absence. For any type T, each value of type multiset<T> is a map from T values to natural numbers denoting each element’s multiplicity. Multisets in Dafny are finite, that is, they contain a finite number of each of a finite set of elements. Stated differently, a multiset maps only a finite number of elements to non-zero (finite) multiplicities.

Like sets, multiset membership is determined by equality in the type T, so multiset<T> can be used in a non-ghost context only if T is equality supporting.

A multiset can be formed using a multiset display expression, which is a possibly empty, unordered list of expressions enclosed in curly braces after the keyword multiset. To illustrate, 

multiset{}   multiset{0, 1, 1, 2, 3, 5}   multiset{4+2, 1+5, a*b}

are three examples of multiset displays. There is no multiset comprehension expression.

In addition to equality and disequality, multiset types support the following relational operations:

operator description
< proper multiset subset
<= multiset subset
>= multiset superset
> proper multiset superset

Like the arithmetic relational operators, these operators are chaining.

Multisets support the following binary operators, listed in order of increasing binding power:

operator precedence description
!! 4 multiset disjointness
+ 6 multiset union
- 6 multiset difference
* 7 multiset intersection

The associativity rules of +, -, and * are like those of the arithmetic operators with the same names. The + operator adds the multiplicity of corresponding elements, the - operator subtracts them (but 0 is the minimum multiplicity), and the * has multiplicity that is the minimum of the multiplicity of the operands.

The expression A !! B says that multisets A and B have no elements in common, that is, it is equivalent to 

A * B == multiset{}

Like the analogous set operator, !! is chaining and means mutual disjointness.

In addition, for any multiset s of type multiset<T>, expression e of type T, and non-negative integer-based numeric n, multisets support the following operations:

expression precedence result type description
e in s 4 bool multiset membership
e !in s 4 bool multiset non-membership
|s| 11 nat multiset cardinality
s[e] 11 nat multiplicity of e in s
s[e := n] 11 multiset<T> multiset update (change of multiplicity)

The expression e in s returns true if and only if s[e] != 0. The expression e !in s is a syntactic shorthand for !(e in s). The expression s[e := n] denotes a multiset like s, but where the multiplicity of element e is n. Note that the multiset update s[e := 0] results in a multiset like s but without any occurrences of e (whether or not s has occurrences of e in the first place). As another example, note that s - multiset{e} is equivalent to: 

if e in s then s[e := s[e] - 1] else s

10.3. Sequences

SequenceType_ = "seq" [ GenericInstantiation ]

For any type T, a value of type seq<T> denotes a sequence of T elements, that is, a mapping from a finite downward-closed set of natural numbers (called indices) to T values.

10.3.1. Sequence Displays

A sequence can be formed using a sequence display expression, which is a possibly empty, ordered list of expressions enclosed in square brackets. To illustrate, 

[]        [3, 1, 4, 1, 5, 9, 3]        [4+2, 1+5, a*b]

are three examples of sequence displays.

There is also a sequence comprehension expression (Section 21.28): 

seq(5, i => i*i)

is equivalent to [0, 1, 4, 9, 16].

10.3.2. Sequence Relational Operators

In addition to equality and disequality, sequence types support the following relational operations:

operator description
< proper prefix
<= prefix

Like the arithmetic relational operators, these operators are chaining. Note the absence of > and >=.

10.3.3. Sequence Concatenation

Sequences support the following binary operator:

operator description
+ concatenation

Operator + is associative, like the arithmetic operator with the same name.

10.3.4. Other Sequence Expressions

In addition, for any sequence s of type seq<T>, expression e of type T, integer-based numeric i satisfying 0 <= i < |s|, and integer-based numerics lo and hi satisfying 0 <= lo <= hi <= |s|, sequences support the following operations:

expression precedence result type description
e in s 4 bool sequence membership
e !in s 4 bool sequence non-membership
|s| 11 nat sequence length
s[i] 11 T sequence selection
s[i := e] 11 seq<T> sequence update
s[lo..hi] 11 seq<T> subsequence
s[lo..] 11 seq<T> drop
s[..hi] 11 seq<T> take
s[slices] 11 seq<seq<T>> slice
multiset(s) 11 multiset<T> sequence conversion to a multiset<T>

Expression s[i := e] returns a sequence like s, except that the element at index i is e. The expression e in s says there exists an index i such that s[i] == e. It is allowed in non-ghost contexts only if the element type T is equality supporting. The expression e !in s is a syntactic shorthand for !(e in s).

Expression s[lo..hi] yields a sequence formed by taking the first hi elements and then dropping the first lo elements. The resulting sequence thus has length hi - lo. Note that s[0..|s|] equals s. If the upper bound is omitted, it defaults to |s|, so s[lo..] yields the sequence formed by dropping the first lo elements of s. If the lower bound is omitted, it defaults to 0, so s[..hi] yields the sequence formed by taking the first hi elements of s.

In the sequence slice operation, slices is a nonempty list of length designators separated and optionally terminated by a colon, and there is at least one colon. Each length designator is a non-negative integer-based numeric; the sum of the length designators is no greater than |s|. If there are k colons, the operation produces k + 1 consecutive subsequences from s, with the length of each indicated by the corresponding length designator, and returns these as a sequence of sequences. If slices is terminated by a colon, then the length of the last slice extends until the end of s, that is, its length is |s| minus the sum of the given length designators. For example, the following equalities hold, for any sequence s of length at least 10: 

method m(s: seq<int>) {
  var t := [3.14, 2.7, 1.41, 1985.44, 100.0, 37.2][1:0:3];
  assert |t| == 3 && t[0] == [3.14] && t[1] == [];
  assert t[2] == [2.7, 1.41, 1985.44];
  var u := [true, false, false, true][1:1:];
  assert |u| == 3 && u[0][0] && !u[1][0] && u[2] == [false, true];
  assume |s| > 10;
  assert s[10:][0] == s[..10];
  assert s[10:][1] == s[10..];
}

The operation multiset(s) yields the multiset of elements of sequence s. It is allowed in non-ghost contexts only if the element type T is equality supporting.

10.3.5. Strings

StringType_ = "string"

A special case of a sequence type is seq<char>, for which Dafny provides a synonym: string. Strings are like other sequences, but provide additional syntax for sequence display expressions, namely string literals. There are two forms of the syntax for string literals: the standard form and the verbatim form.

String literals of the standard form are enclosed in double quotes, as in "Dafny". To include a double quote in such a string literal, it is necessary to use an escape sequence. Escape sequences can also be used to include other characters. The supported escape sequences are the same as those for character literals (Section 7.5). For example, the Dafny expression "say \"yes\"" represents the string 'say "yes"'. The escape sequence for a single quote is redundant, because "\'" and "\'" denote the same string—both forms are provided in order to support the same escape sequences as do character literals.

String literals of the verbatim form are bracketed by @" and ", as in @"Dafny". To include a double quote in such a string literal, it is necessary to use the escape sequence "", that is, to write the character twice. In the verbatim form, there are no other escape sequences. Even characters like newline can be written inside the string literal (hence spanning more than one line in the program text).

For example, the following three expressions denote the same string: 

"C:\\tmp.txt"
@"C:\tmp.txt"
['C', ':', '\\', 't', 'm', 'p', '.', 't', 'x', 't']

Since strings are sequences, the relational operators < and <= are defined on them. Note, however, that these operators still denote proper prefix and prefix, respectively, not some kind of alphabetic comparison as might be desirable, for example, when sorting strings.

10.4. Finite and Infinite Maps

FiniteMapType_ = "map" [ GenericInstantiation ]

InfiniteMapType_ = "imap" [ GenericInstantiation ]

For any types T and U, a value of type map<T,U> denotes a (finite) map from T to U. In other words, it is a look-up table indexed by T. The domain of the map is a finite set of T values that have associated U values. Since the keys in the domain are compared using equality in the type T, type map<T,U> can be used in a non-ghost context only if T is equality supporting.

Similarly, for any types T and U, a value of type imap<T,U> denotes a (possibly) infinite map. In most regards, imap<T,U> is like map<T,U>, but a map of type imap<T,U> is allowed to have an infinite domain.

A map can be formed using a map display expression (see MapDisplayExpr), which is a possibly empty, ordered list of maplets, each maplet having the form t := u where t is an expression of type T and u is an expression of type U, enclosed in square brackets after the keyword map. To illustrate, 

map[]
map[20 := true, 3 := false, 20 := false]
map[a+b := c+d]

are three examples of map displays. By using the keyword imap instead of map, the map produced will be of type imap<T,U> instead of map<T,U>. Note that an infinite map (imap) is allowed to have a finite domain, whereas a finite map (map) is not allowed to have an infinite domain. If the same key occurs more than once in a map display expression, only the last occurrence appears in the resulting map.2 There is also a map comprehension expression, explained in Section 21.40.

For any map fm of type map<T,U>, any map m of type map<T,U> or imap<T,U>, any expression t of type T, any expression u of type U, and any d in the domain of m (that is, satisfying d in m), maps support the following operations:

expression precedence result type description
t in m 4 bool map domain membership
t !in m 4 bool map domain non-membership
|fm| 11 nat map cardinality
m[d] 11 U map selection
m[t := u] 11 map<T,U> map update
m.Keys 11 (i)set<T> the domain of m
m.Values 11 (i)set<U> the range of m
m.Items 11 (i)set<(T,U)> set of pairs (t,u) in m

|fm| denotes the number of mappings in fm, that is, the cardinality of the domain of fm. Note that the cardinality operator is not supported for infinite maps. Expression m[d] returns the U value that m associates with d. Expression m[t := u] is a map like m, except that the element at key t is u. The expression t in m says t is in the domain of m and t !in m is a syntactic shorthand for !(t in m).3

The expressions m.Keys, m.Values, and m.Items return, as sets, the domain, the range, and the 2-tuples holding the key-value associations in the map. Note that m.Values will have a different cardinality than m.Keys and m.Items if different keys are associated with the same value. If m is an imap, then these expressions return iset values.

Here is a small example, where a map cache of type map<int,real> is used to cache computed values of Joule-Thomson coefficients for some fixed gas at a given temperature: 

if K in cache {  // check if temperature is in domain of cache
  coeff := cache[K];  // read result in cache
} else {
  coeff := ComputeJTCoefficient(K); // do expensive computation
  cache := cache[K := coeff];  // update the cache
}

Dafny also overloads the + and - binary operators for maps. The + operator merges two maps or imaps of the same type, as if each (key,value) pair of the RHS is added in turn to the LHS (i)map. In this use, + is not commutative; if a key exists in both (i)maps, it is the value from the RHS (i)map that is present in the result.

The - operator implements a map difference operator. Here the LHS is a map<K,V> or imap<K,V> and the RHS is a set<K> (but not an iset); the operation removes from the LHS all the (key,value) pairs whose key is a member of the RHS set.

10.5. Iterating over collections

Collections are very commonly used in programming and one frequently needs to iterate over the elements of a collection. Dafny does not have built-in iterator methods, but the idioms by which to do so are straightforward. The subsections below give some introductory examples; more detail can be found in this power user note.

10.5.1. Sequences and arrays

Sequences and arrays are indexable and have a length. So the idiom to iterate over the contents is well-known. For an array: 

method m(a: array<int>) {
  var i := 0;
  var sum := 0;
  while i < a.Length {
    sum := sum + a[i];
    i := i + 1;
  }
}

For a sequence, the only difference is the length operator: 

method m(s: seq<int>) {
  var i := 0;
  var sum := 0;
  while i < |s| {
    sum := sum + s[i];
    i := i + 1;
  }
}

The forall statement (Section 20.21) can also be used with arrays where parallel assignment is needed: 

method m(s: array<int>) {
  var rev := new int[s.Length];
  forall i | 0 <= i < s.Length {
    rev[i] := s[s.Length-i-1];
  }
}

See Section 15.2 on how to convert an array to a sequence.

10.5.2. Sets

There is no intrinsic order to the elements of a set. Nevertheless, we can extract an arbitrary element of a nonempty set, performing an iteration as follows: 

method m(s: set<int>) {
  var ss := s;
  while ss != {}
    decreases |ss|
  {
    var i: int :| i in ss;
    ss := ss - {i};
    print i, "\n";
  }
}

Because isets may be infinite, Dafny does not permit iteration over an iset.

10.5.3. Maps

Iterating over the contents of a map uses the component sets: Keys, Values, and Items. The iteration loop follows the same patterns as for sets:

method m<T(==),U(==)> (m: map<T,U>) {
  var items := m.Items;
  while items != {}
    decreases |items|
  {
    var item :| item in items;
    items := items - { item };
    print item.0, " ", item.1, "\n";
  }
}

There are no mechanisms currently defined in Dafny for iterating over imaps.

11. Types that stand for other types

SynonymTypeDecl =
  SynonymTypeDecl_ | OpaqueTypeDecl_ | SubsetTypeDecl_

It is sometimes useful to know a type by several names or to treat a type abstractly. There are several mechanisms in Dafny to do this:

11.1. Type synonyms

SynonymTypeName = NoUSIdent

SynonymTypeDecl_ =
  "type" { Attribute } SynonymTypeName
   { TypeParameterCharacteristics }
   [ GenericParameters ]
   "=" Type

A type synonym declaration: 

type Y<T> = G

declares Y<T> to be a synonym for the type G. If the = G is omitted then the declaration just declares a name as an uninterpreted opaque type, as described in Section 11.2. Such types may be given a definition elsewhere in the Dafny program.

Here, T is a nonempty list of type parameters (each of which optionally has a type characteristics suffix), which can be used as free type variables in G. If the synonym has no type parameters, the “<T>” is dropped. In all cases, a type synonym is just a synonym. That is, there is never a difference, other than possibly in error messages produced, between Y<T> and G.

For example, the names of the following type synonyms may improve the readability of a program: 

type Replacements<T> = map<T,T>
type Vertex = int

The new type name itself may have type characteristics declared, though these are typically inferred from the definition, if there is one.

As already described in Section 10.3.5, string is a built-in type synonym for seq<char>, as if it would have been declared as follows: 

type string_(==,0,!new) = seq<char>

If the implicit declaration did not include the type characteristics, they would be inferred in any case.

11.2. Opaque types

OpaqueTypeDecl_ =
  "type" { Attribute } SynonymTypeName
   { TypeParameterCharacteristics }
   [ GenericParameters ]
   [ TypeMembers ]

TypeMembers =
  "{"
  {
    { DeclModifier }
    ClassMemberDecl(allowConstructors: false,
                    isValueType: true,
                    moduleLevelDecl: false,
                    isWithinAbstractModule: module.IsAbstract)
  }
  "}"

An opaque type is a special case of a type synonym that is underspecified. Such a type is declared simply by: 

type Y<T>

Its definition can be revealed in a refining module. The name Y can be immediately followed by a type characteristics suffix (Section 8.1). Because there is no defining RHS, the type characteristics cannot be inferred and so must be stated. If, in some refining module, a definition of the type is given, the type characteristics must match those of the new definition.

For example, the declarations 

type T
function F(t: T): T

can be used to model an uninterpreted function F on some arbitrary type T. As another example, 

type Monad<T>

can be used abstractly to represent an arbitrary parameterized monad.

Even as an opaque type, the type may be given members such as constants, methods or functions. For example, 

abstract module P {
  type T {
    function ToString(): string
  }
}

module X refines P {
  newtype T = i | 0 <= i < 10 {
    function ToString(): string {  "" }
  }
}

The abstract type P.T has a declared member ToString, which can be called wherever P.T may be used. In the refining module X, T is declared to be a newtype, in which ToString now has a body.

It would be an error to refine P.T as a simple type synonym or subset type in X, say type T = int, because type synonyms may not have members.

11.3. Subset types

SubsetTypeDecl_ =
  "type"
  { Attribute }
  SynonymTypeName [ GenericParameters ]
  "="
  LocalIdentTypeOptional
  "|"
  Expression(allowLemma: false, allowLambda: true)
  [ "ghost" "witness" Expression(allowLemma: false, allowLambda: true)
  | "witness" Expression((allowLemma: false, allowLambda: true)
  | "witness" "*"
  ]

NatType_ = "nat"

A subset type is a restricted use of an existing type, called the base type of the subset type. A subset type is like a combined use of the base type and a predicate on the base type.

An assignment from a subset type to its base type is always allowed. An assignment in the other direction, from the base type to a subset type, is allowed provided the value assigned does indeed satisfy the predicate of the subset type. This condition is checked by the verifier, not by the type checker. Similarly, assignments from one subset type to another (both with the same base type) are also permitted, as long as it can be established that the value being assigned satisfies the predicate defining the receiving subset type. (Note, in contrast, assignments between a newtype and its base type are never allowed, even if the value assigned is a value of the target type. For such assignments, an explicit conversion must be used, see Section 21.10.)

The declaration of a subset type permits an optional witness clause, to declare default values that the compiler can use to initialize variables of the subset type, or to assert the non-emptiness of the subset type.

Dafny builds in three families of subset types, as described next.

11.3.1. Type nat

The built-in type nat, which represents the non-negative integers (that is, the natural numbers), is a subset type: 

type nat = n: int | 0 <= n

A simple example that puts subset type nat to good use is the standard Fibonacci function: 

function Fib(n: nat): nat
{
  if n < 2 then n else Fib(n-2) + Fib(n-1)
}

An equivalent, but clumsy, formulation of this function (modulo the wording of any error messages produced at call sites) would be to use type int and to write the restricting predicate in pre- and postconditions: 

function Fib(n: int): int
  requires 0 <= n  // the function argument must be non-negative
  ensures 0 <= Fib(n)  // the function result is non-negative
{
  if n < 2 then n else Fib(n - 2) + Fib(n - 1)
}

11.3.2. Non-null types

Every class, trait, and iterator declaration C gives rise to two types.

One type has the name C? (that is, the name of the class, trait, or iterator declaration with a ? character appended to the end). The values of C? are the references to C objects, and also the value null. In other words, C? is the type of possibly null references (aka, nullable references) to C objects.

The other type has the name C (that is, the same name as the class, trait, or iterator declaration). Its values are the references to C objects, and does not contain the value null. In other words, C is the type of non-null references to C objects.

The type C is a subset type of C?: 

type C = c: C? | c != null

(It may be natural to think of the type C? as the union of type C and the value null, but, technically, Dafny defines C as a subset type with base type C?.)

From being a subset type, we get that C is a subtype of C?. Moreover, if a class or trait C extends a trait B, then type C is a subtype of B and type C? is a subtype of B?.

Every possibly-null reference type is a subtype of the built-in possibly-null trait type object?, and every non-null reference type is a subtype of the built-in non-null trait type object. (And, from the fact that object is a subset type of object?, we also have that object is a subtype of object?.)

Arrays are references and array types also come in these two flavors. For example, array? and array2? are possibly-null (1- and 2-dimensional) array types, and array and array2 are their respective non-null types.

Note that ? is not an operator. Instead, it is simply the last character of the name of these various possibly-null types.

11.3.3. Arrow types: ->, -->, and ~>

The built-in type -> stands for total functions, --> stands for partial functions (that is, functions with possible requires clauses), and ~> stands for all functions. More precisely, these are type constructors that exist for any arity (() -> X, A -> X, (A, B) -> X, (A, B, C) -> X, etc.).

For a list of types TT and a type U, the values of the arrow type (TT) ~> U are functions from TT to U. This includes functions that may read the heap and functions that are not defined on all inputs. It is not common to need this generality (and working with such general functions is difficult). Therefore, Dafny defines two subset types that are more common (and much easier to work with).

The type (TT) --> U denotes the subset of (TT) ~> U where the functions do not read the (mutable parts of the) heap. Values of type (TT) --> U are called partial functions, and the subset type (TT) --> U is called the partial arrow type. (As a mnemonic to help you remember that this is the partial arrow, you may think of the little gap between the two hyphens in --> as showing a broken arrow.)

The built-in partial arrow type is defined as follows (here shown for arrows with arity 1): 

type A --> B = f: A ~> B | forall a :: f.reads(a) == {}

(except that what is shown here left of the = is not legal Dafny syntax). That is, the partial arrow type is defined as those functions f whose reads frame is empty for all inputs. More precisely, taking variance into account, the partial arrow type is defined as 

type -A --> +B = f: A ~> B | forall a :: f.reads(a) == {}

The type (TT) -> U is, in turn, a subset type of (TT) --> U, adding the restriction that the functions must not impose any precondition. That is, values of type (TT) -> U are total functions, and the subset type (TT) -> U is called the total arrow type.

The built-in total arrow type is defined as follows (here shown for arrows with arity 1): 

type -A -> +B = f: A --> B | forall a :: f.requires(a)

That is, the total arrow type is defined as those partial functions f whose precondition evaluates to true for all inputs.

Among these types, the most commonly used are the total arrow types. They are also the easiest to work with. Because they are common, they have the simplest syntax (->).

Note, informally, we tend to speak of all three of these types as arrow types, even though, technically, the ~> types are the arrow types and the --> and -> types are subset types thereof. The one place where you may need to remember that --> and -> are subset types is in some error messages. For example, if you try to assign a partial function to a variable whose type is a total arrow type and the verifier is not able to prove that the partial function really is total, then you’ll get an error saying that the subset-type constraint may not be satisfied.

For more information about arrow types, see Section 17.

11.3.4. Witness clauses

The declaration of a subset type permits an optional witness clause. Types in Dafny are generally expected to be non-empty, in part because variables of any type are expected to have some value when they are used. In many cases, Dafny can determine that a newly declared type has some value. For example, a numeric type that includes 0 is known by Dafny to be non-empty. However, Dafny cannot always make this determination. If it cannot, a witness clause is required. The value given in the witness clause must be a valid value for the type and assures Dafny that the type is non-empty.

For example, 

type OddInt = x: int | x % 2 == 1

will give an error message, but 

type OddInt = x: int | x % 2 == 1 witness 73

does not. Here is another example: 

type NonEmptySeq = x: seq<int> | |x| > 0 witness [0]

If the witness is only available in ghost code, you can declare the witness as a ghost witness. In this case, the Dafny verifier knows that the type is non-empty, but it will not be able to auto-initialize a variable of that type in compiled code.

There is even room to do the following: 

type BaseType
predicate RHS(x: BaseType)
type MySubset = x: BaseType | RHS(x) ghost witness MySubsetWitness()

function MySubsetWitness(): BaseType
  ensures RHS(MySubsetWitness())

Here the type is given a ghost witness: the result of the expression MySubsetWitness(), which is a call of a (ghost) function. Now that function has a postcondition saying that the returned value is indeed a candidate value for the declared type, so the verifier is satisfied regarding the non-emptiness of the type. However, the function has no body, so there is still no proof that there is indeed such a witness. You can either supply a, perhaps complicated, body to generate a viable candidate or you can be very sure, without proof, that there is indeed such a value. If you are wrong, you have introduced an unsoundness into your program.

In addition though, types are allowed to be empty or possibly empty. This is indicated by the clause witness *, which tells the verifier not to check for a satisfying witness. A declaration like this produces an empty type: 

type ReallyEmpty = x: int | false witness *
``` <!-- %save ReallyEmpty.tmp -->
The type can be used in code like
<!-- %check-verify %use ReallyEmpty.tmp -->
```dafny
method M(x: ReallyEmpty) returns (seven: int)
  ensures seven == 7
{
  seven := 10;
}

which does verify. But the method can never be called because there is no value that can be supplied as the argument. Even this code 

method P() returns (seven: int)
  ensures seven == 7
{
  var x: ReallyEmpty;
  seven := 10;
}

does not complain about x unless x is actually used, in which case it must have a value. The postcondition in P does not verify, but not because of the empty type.

12. Newtypes

NewtypeDecl = "newtype" { Attribute } NewtypeName "="
  [ ellipsis ]
  ( LocalIdentTypeOptional
    "|"
    Expression(allowLemma: false, allowLambda: true)
    [ "ghost" "witness" Expression(allowLemma: false, allowLambda: true)
    | "witness" Expression((allowLemma: false, allowLambda: true)
    | "witness" "*"
    ]
  | Type
  )
  [ TypeMembers ]

A newtype is like a type synonym or subset type except that it declares a wholly new type name that is distinct from its base type. It also accepts an optional witness clause.

A new type can be declared with the newtype declaration, for example: 

newtype N = x: M | Q

where M is a type and Q is a boolean expression that can use x as a free variable. If M is an integer-based numeric type, then so is N; if M is real-based, then so is N. If the type M can be inferred from Q, the “: M” can be omitted. If Q is just true, then the declaration can be given simply as: 

newtype N = M

Type M is known as the base type of N. At present, Dafny only supports int and real as base types of newtypes.

A newtype is a type that supports the same operations as its base type. The newtype is distinct from and incompatible with other types; in particular, it is not assignable to its base type without an explicit conversion. An important difference between the operations on a newtype and the operations on its base type is that the newtype operations are defined only if the result satisfies the predicate Q, and likewise for the literals of the newtype.

For example, suppose lo and hi are integer-based numerics that satisfy 0 <= lo <= hi and consider the following code fragment: 

var mid := (lo + hi) / 2;

If lo and hi have type int, then the code fragment is legal; in particular, it never overflows, since int has no upper bound. In contrast, if lo and hi are variables of a newtype int32 declared as follows: 

newtype int32 = x | -0x8000_0000 <= x < 0x8000_0000

then the code fragment is erroneous, since the result of the addition may fail to satisfy the predicate in the definition of int32. The code fragment can be rewritten as 

var mid := lo + (hi - lo) / 2;

in which case it is legal for both int and int32.

Since a newtype is incompatible with its base type and since all results of the newtype’s operations are members of the newtype, a compiler for Dafny is free to specialize the run-time representation of the newtype. For example, by scrutinizing the definition of int32 above, a compiler may decide to store int32 values using signed 32-bit integers in the target hardware.

The incompatibility of a newtype and its basetype is intentional, as newtypes are meant to be used as distinct types from the basetype. If numeric types are desired that mix more readily with the basetype, the subset types described in Section 11.3 may be more appropriate.

Note that the bound variable x in Q has type M, not N. Consequently, it may not be possible to state Q about the N value. For example, consider the following type of 8-bit 2’s complement integers: 

newtype int8 = x: int | -128 <= x < 128

and consider a variable c of type int8. The expression 

-128 <= c < 128

is not well-defined, because the comparisons require each operand to have type int8, which means the literal 128 is checked to be of type int8, which it is not. A proper way to write this expression is to use a conversion operation, described in Section 12.1, on c to convert it to the base type: 

-128 <= c as int < 128

If possible, Dafny compilers will represent values of the newtype using a native type for the sake of efficiency. This action can be inhibited or a specific native data type selected by using the {:nativeType} attribute, as explained in Section 23.1.2.

Furthermore, for the compiler to be able to make an appropriate choice of representation, the constants in the defining expression as shown above must be known constants at compile-time. They need not be numeric literals; combinations of basic operations and symbolic constants are also allowed as described in Section 21.47.

12.1. Conversion operations

For every type N, there is a conversion operation with the name as N, described more fully in Section 21.10. It is a partial function defined when the given value, which can be of any type, is a member of the type converted to. When the conversion is from a real-based numeric type to an integer-based numeric type, the operation requires that the real-based argument have no fractional part. (To round a real-based numeric value down to the nearest integer, use the .Floor member, see Section 7.2.)

To illustrate using the example from above, if lo and hi have type int32, then the code fragment can legally be written as follows: 

var mid := (lo as int + hi as int) / 2;

where the type of mid is inferred to be int. Since the result value of the division is a member of type int32, one can introduce yet another conversion operation to make the type of mid be int32: 

var mid := ((lo as int + hi as int) / 2) as int32;

If the compiler does specialize the run-time representation for int32, then these statements come at the expense of two, respectively three, run-time conversions.

The as N conversion operation is grammatically a suffix operation like .field and array indexing, but binds less tightly than unary operations: - x as int is (- x) as int; a + b as int is a + (b as int).

The as N conversion can also be used with reference types. For example, if C is a class, c is an expression of type C, and o is an expression of type object, then c as object and c as object? are upcasts and o is C is a downcast. A downcast requires the LHS expression to have the RHS type, as is enforced by the verifier.

For some types (in particular, reference types), there is also a corresponding is operation (Section 21.10) that tests whether a value is valid for a given type.

13. Class types

ClassDecl = "class" { Attribute } ClassName [ GenericParameters ]
  ["extends" Type {"," Type} | ellipsis ]
  "{" { { DeclModifier }
        ClassMemberDecl(allowConstructors: true,
                        isValueType: false,
                        moduleLevelDecl: false,
                        isWithinAbstractModule: false) }
  "}"

ClassMemberDecl(allowConstructors, isValueType,
                moduleLevelDecl, isWithinAbstractModule) =
  ( FieldDecl(isValueType) // allowed iff moduleLevelDecl is false
  | ConstantFieldDecl(moduleLevelDecl)
  | FunctionDecl(isWithinAbstractModule)
  | MethodDecl(isGhost: "ghost" was present,
               allowConstructors, isWithinAbstractModule)
  )

Declarations within a class all begin with reserved keywords and do not end with semicolons.

The ClassMemberDecl parameter moduleLevelDecl will be true if the member declaration is at the top level or directly within a module declaration. It will be false for ClassMemberDecls that are part of a class or trait declaration. If moduleLevelDecl is true FieldDecls are not allowed.

A class C is a reference type declared as follows: 

class C<T> extends J1, ..., Jn
{
  _members_
}

where the list of type parameters T is optional. The text “extends J1, ..., Jn” is also optional and says that the class extends traits J1 … Jn. The members of a class are fields, functions, and methods. These are accessed or invoked by dereferencing a reference to a C instance.

A function or method is invoked on an instance of C, unless the function or method is declared static. A function or method that is not static is called an instance function or method.

An instance function or method takes an implicit receiver parameter, namely, the instance used to access the member. In the specification and body of an instance function or method, the receiver parameter can be referred to explicitly by the keyword this. However, in such places, members of this can also be mentioned without any qualification. To illustrate, the qualified this.f and the unqualified f refer to the same field of the same object in the following example: 

class C {
  var f: int
  var x: int
  method Example() returns (b: bool)
  {
    var x: int;
    b := f == this.f;
  }
}

so the method body always assigns true to the out-parameter b. However, in this example, x and this.x are different because the field x is shadowed by the declaration of the local variable x. There is no semantic difference between qualified and unqualified accesses to the same receiver and member.

A C instance is created using new. There are three forms of new, depending on whether or not the class declares any constructors (see Section 13.3.2):

c := new C;
c := new C.Init(args);
c := new C(args);

For a class with no constructors, the first two forms can be used. The first form simply allocates a new instance of a C object, initializing its fields to values of their respective types (and initializing each const field with a RHS to its specified value). The second form additionally invokes an initialization method (here, named Init) on the newly allocated object and the given arguments. It is therefore a shorthand for 

c := new C;
c.Init(args);

An initialization method is an ordinary method that has no out-parameters and that modifies no more than this.

For a class that declares one or more constructors, the second and third forms of new can be used. For such a class, the second form invokes the indicated constructor (here, named Init), which allocates and initializes the object. The third form is the same as the second, but invokes the anonymous constructor of the class (that is, a constructor declared with the empty-string name).

13.1. Field Declarations

FieldDecl(isValueType) =
  "var" { Attribute } FIdentType { "," FIdentType }

A FieldDecl is not permitted in a value type (i.e., if isValueType is true).

An FIdentType is used to declare a field. The field name is either an identifier (that is not allowed to start with a leading underscore) or some digits. Digits are used if you want to number your fields, e.g. “0”, “1”, etc.

A field x of some type T is declared as: 

var x: T

A field declaration declares one or more fields of the enclosing class. Each field is a named part of the state of an object of that class. A field declaration is similar to but distinct from a variable declaration statement. Unlike for local variables and bound variables, the type is required and will not be inferred.

Unlike method and function declarations, a field declaration cannot be given at the top level. Fields can be declared in either a class or a trait. A class that inherits from multiple traits will have all the fields declared in any of its parent traits.

Fields that are declared as ghost can only be used in specifications, not in code that will be compiled into executable code.

Fields may not be declared static.

13.2. Constant Field Declarations

ConstantFieldDecl(moduleLeavelDecl) =
  "const" { Attribute } CIdentType [ ellipsis ]
   [ ":=" Expression(allowLemma: false, allowLambda:true) ]

A const declaration declares a name bound to a value, which value is fixed after initialization.

The declaration must either have a type or an initializing expression (or both). If the type is omitted, it is inferred from the initializing expression.

13.3. Method Declarations

MethodDecl(isGhost, allowConstructors, isWithinAbstractModule) =
  MethodKeyword_ { Attribute } [ MethodFunctionName ]
  ( MethodSignature_(isGhost, isExtreme: true iff this is a least
                                   or greatest lemma declaration)
  | ellipsis
  )
  MethodSpec(isConstructor: true iff
                       this is a constructor declaration)
  [ BlockStmt ]

The isGhost parameter is true iff the ghost keyword preceded the method declaration.

If the allowConstructor parameter is false then the MethodDecl must not be a constructor declaration.

MethodKeyword_ = ( "method"
                 | "constructor"
                 | "lemma"
                 | "twostate" "lemma"
                 | "least" "lemma"
                 | "greatest" "lemma"
                 )

The method keyword is used to specify special kinds of methods as explained below.

MethodSignature_(isGhost, isExtreme) =
  [ GenericParameters ]
  [ KType ]    // permitted only if isExtreme == true
  Formals(allowGhostKeyword: !isGhost, allowNewKeyword: isTwostateLemma, allowOlderKeyword: false, allowDefault: true))
  [ "returns" Formals(allowGhostKeyword: !isGhost, allowNewKeyword: false, allowOlderKeyword: false, allowDefault: false) ]

A method signature specifies the method generic parameters, input parameters and return parameters. The formal parameters are not allowed to have ghost specified if ghost was already specified for the method. Within the body of a method, formal parameters are immutable, that is, they may not be assigned to, though their array elements or fields may be assigned, if otherwise permitted. The out-parameters are mutable and must be assigned in the body of the method.

A ellipsis is used when a method or function is being redeclared in a module that refines another module. (cf. Section 22) In that case the signature is copied from the module that is being refined. This works because Dafny does not support method or function overloading, so the name of the class method uniquely identifies it without the signature.

KType = "[" ( "nat" | "ORDINAL" ) "]"

The KType may be specified only for least and greatest lemmas and is described in Section 24.5.3 and subsequent sections.

Formals(allowGhostKeyword, allowNewKeyword, allowOlderKeyword, allowDefault) =
  "(" [ GIdentType(allowGhostKeyword, allowNewKeyword, allowOlderKeyword, allowNameOnlyKeyword: true, allowDefault)
        { "," GIdentType(allowGhostKeyword, allowNewKeyword, allowOlderKeyword, allowNameOnlyKeyword: true, allowDefault) }
      ]
  ")"

The Formals specifies the names and types of the method input or output parameters.

See Section 5.2 for a description of MethodSpec.

A method declaration adheres to the MethodDecl grammar above. Here is an example of a method declaration.

method {:att1}{:att2} M<T1, T2>(a: A, b: B, c: C)
                                        returns (x: X, y: Y, z: Z)
  requires Pre
  modifies Frame
  ensures Post
  decreases Rank
{
  Body
}

where :att1 and :att2 are attributes of the method, T1 and T2 are type parameters of the method (if generic), a, b, c are the method’s in-parameters, x, y, z are the method’s out-parameters, Pre is a boolean expression denoting the method’s precondition, Frame denotes a set of objects whose fields may be updated by the method, Post is a boolean expression denoting the method’s postcondition, Rank is the method’s variant function, and Body is a list of statements that implements the method. Frame can be a list of expressions, each of which is a set of objects or a single object, the latter standing for the singleton set consisting of that one object. The method’s frame is the union of these sets, plus the set of objects allocated by the method body. For example, if c and d are parameters of a class type C, then

modifies {c, d}
modifies {c} + {d}
modifies c, {d}
modifies c, d

all mean the same thing.

13.3.1. Ordinary methods

A method can be declared as ghost by preceding the declaration with the keyword ghost and as static by preceding the declaration with the keyword static. The default is non-static (i.e., instance) and non-ghost. An instance method has an implicit receiver parameter, this. A static method M in a class C can be invoked by C.M(…).

An ordinary method is declared with the method keyword; the section about constructors explains methods that instead use the constructor keyword; the section about lemmas discusses methods that are declared with the lemma keyword. Methods declared with the least lemma or greatest lemma keyword phrases are discussed later in the context of extreme predicates (see the section about greatest lemmas).

A method without a body is abstract. A method is allowed to be abstract under the following circumstances:

13.3.2. Constructors

To write structured object-oriented programs, one often relies on objects being constructed only in certain ways. For this purpose, Dafny provides constructor (method)s. A constructor is declared with the keyword constructor instead of method; constructors are permitted only in classes. A constructor is allowed to be declared as ghost, in which case it can only be used in ghost contexts.

A constructor can only be called at the time an object is allocated (see object-creation examples below). Moreover, when a class contains a constructor, every call to new for a class must be accompanied by a call to one of its constructors. A class may declare no constructors or one or more constructors.

In general, a constructor is responsible for initializating the instance fields of its class. However, any field that is given an initializer in its declaration may not be reassigned in the body of the constructor.

13.3.2.1. Classes with no explicit constructors

For a class that declares no constructors, an instance of the class is created with 

c := new C;

This allocates an object and initializes its fields to values of their respective types (and initializes each const field with a RHS to its specified value). The RHS of a const field may depend on other const or var fields, but circular dependencies are not allowed.

This simple form of new is allowed only if the class declares no constructors, which is not possible to determine in every scope. It is easy to determine whether or not a class declares any constructors if the class is declared in the same module that performs the new. If the class is declared in a different module and that module exports a constructor, then it is also clear that the class has a constructor (and thus this simple form of new cannot be used). (Note that an export set that reveals a class C also exports the anonymous constructor of C, if any.) But if the module that declares C does not export any constructors for C, then callers outside the module do not know whether or not C has a constructor. Therefore, this simple form of new is allowed only for classes that are declared in the same module as the use of new.

The simple new C is allowed in ghost contexts. Also, unlike the forms of new that call a constructor or initialization method, it can be used in a simultaneous assignment; for example 

c, d, e := new C, new C, 15;

is legal.

As a shorthand for writing 

c := new C;
c.Init(args);

where Init is an initialization method (see the top of the section about class types), one can write 

c := new C.Init(args);

but it is more typical in such a case to declare a constructor for the class.

(The syntactic support for initialization methods is provided for historical reasons. It may be deprecated in some future version of Dafny. In most cases, a constructor is to be preferred.)

13.3.2.2. Classes with one or more constructors

Like other class members, constructors have names. And like other members, their names must be distinct, even if their signatures are different. Being able to name constructors promotes names like InitFromList or InitFromSet (or just FromList and FromSet). Unlike other members, one constructor is allowed to be anonymous; in other words, an anonymous constructor is a constructor whose name is essentially the empty string. For example: 

class Item {
  constructor I(xy: int) // ...
  constructor (x: int, y: int)
  // ...
}

The named constructor is invoked as 

  i := new Item.I(42);

The anonymous constructor is invoked as 

  m := new Item(45, 29);

dropping the “.”.

13.3.2.3. Two-phase constructors

The body of a constructor contains two sections, an initialization phase and a post-initialization phase, separated by a new; statement. If there is no new; statement, the entire body is the initialization phase. The initialization phase is intended to initialize field variables that were not given values in their declaration; it may not reassign to fields that do have initializers in their declarations. In this phase, uses of the object reference this are restricted; a program may use this

A const field with a RHS is not allowed to be assigned anywhere else. A const field without a RHS may be assigned only in constructors, and more precisely only in the initialization phase of constructors. During this phase, a const field may be assigned more than once; whatever value the const field has at the end of the initialization phase is the value it will have forever thereafter.

For a constructor declared as ghost, the initialization phase is allowed to assign both ghost and non-ghost fields. For such an object, values of non-ghost fields at the end of the initialization phase are in effect no longer changeable.

There are no restrictions on expressions or statements in the post-initialization phase.

13.3.3. Lemmas

Sometimes there are steps of logic required to prove a program correct, but they are too complex for Dafny to discover and use on its own. When this happens, we can often give Dafny assistance by providing a lemma. This is done by declaring a method with the lemma keyword. Lemmas are implicitly ghost methods and the ghost keyword cannot be applied to them.

Syntactically, lemmas can be placed where ghost methods can be placed, but they serve a significantly different function. First of all, a lemma is forbidden to have modifies clause: it may not change anything about even the ghost state; ghost methods may have modifies clauses and may change ghost (but not non-ghost) state. Furthermore, a lemma is not allowed to allocate any new objects. And a lemma may be used in the program text in places where ghost methods may not, such as within expressions (cf. Section 21.1).

Lemmas may, but typically do not, have out-parameters.

In summary, a lemma states a logical fact, summarizing an inference that the verifier cannot do on its own. Explicitly “calling” a lemma in the program text tells the verifier to use that fact at that location with the actual arguments substituted for the formal parameters. The lemma is proved separately for all cases of its formal parameters that satisfy the preconditions of the lemma.

For an example, see the FibProperty lemma in Section 24.5.2.

See the Dafny Lemmas tutorial for more examples and hints for using lemmas.

13.3.4. Two-state lemmas and functions

The heap is an implicit parameter to every function, though a function is only allowed to read those parts of the mutable heap that it admits to in its reads clause. Sometimes, it is useful for a function to take two heap parameters, for example, so the function can return the difference between the value of a field in the two heaps. Such a two-state function is declared by twostate function (or twostate predicate, which is the same as a twostate function that returns a bool). A two-state function is always ghost. It is appropriate to think of these two implicit heap parameters as representing a “current” heap and an “old” heap.

For example, the predicate 

class Cell { var data: int  constructor(i: int) { data := i; } }
twostate predicate Increasing(c: Cell)
  reads c
{
  old(c.data) <= c.data
}
``` <!-- %save Increasing.tmp -->
returns `true` if the value of `c.data` has not been reduced from the old state to the
current. Dereferences in the current heap are written as usual (e.g., `c.data`) and
must, as usual, be accounted for in the function's `reads` clause. Dereferences in the
old heap are enclosed by `old` (e.g., `old(c.data)`), just like when one dereferences
a  method's initial heap. The function is allowed to read anything in the old heap;
the `reads` clause only declares dependencies on locations in the current heap.
Consequently, the frame axiom for a two-state function is sensitive to any change
in the old-heap parameter; in other words, the frame axiom says nothing about two
invocations of the two-state function with different old-heap parameters.

At a call site, the two-state function's current-heap parameter is always passed in
as the caller's current heap. The two-state function's old-heap parameter is by
default passed in as the caller's old heap (that is, the initial heap if the caller
is a method and the old heap if the caller is a two-state function). While there is
never a choice in which heap gets passed as the current heap, the caller can use
any preceding heap as the argument to the two-state function's old-heap parameter.
This is done by labeling a state in the caller and passing in the label, just like
this is done with the built-in `old` function.

For example, the following assertions all hold:
<!-- %check-verify %use Increasing.tmp -->
```dafny
method Caller(c: Cell)
  modifies c
{
  c.data := c.data + 10;
  label L:
  assert Increasing(c);
  c.data := c.data - 2;
  assert Increasing(c);
  assert !Increasing@L(c);
}

The first call to Increasing uses Caller’s initial state as the old-heap parameter, and so does the second call. The third call instead uses as the old-heap parameter the heap at label L, which is why the third call returns false. As shown in the example, an explicitly given old-heap parameter is given after an @-sign (which follows the name of the function and any explicitly given type parameters) and before the open parenthesis (after which the ordinary parameters are given).

A two-state function is allowed to be called only from a two-state context, which means a method, a two-state lemma (see below), or another two-state function. Just like a label used with an old expression, any label used in a call to a two-state function must denote a program point that dominates the call. This means that any control leading to the call must necessarily have passed through the labeled program point.

Any parameter (including the receiver parameter, if any) passed to a two-state function must have been allocated already in the old state. For example, the second call to Diff in method M is illegal, since d was not allocated on entry to M: 

twostate function Diff(c: Cell, d: Cell): int
  reads d
{
  d.data - old(c.data)
}

method M(c: Cell) {
  var d := new Cell(10);
  label L:
  ghost var x := Diff@L(c, d);
  ghost var y := Diff(c, d); // error: d is not allocated in old state
}

A two-state function can declare that it only assumes a parameter to be allocated in the current heap. This is done by preceding the parameter with the new modifier, as illustrated in the following example, where the first call to DiffAgain is legal: 

twostate function DiffAgain(c: Cell, new d: Cell): int
  reads d
{
  d.data - old(c.data)
}

method P(c: Cell) {
  var d := new Cell(10);
  ghost var x := DiffAgain(c, d);
  ghost var y := DiffAgain(d, c); // error: d is not allocated in old state
}

A two-state lemma works in an analogous way. It is a lemma with both a current-heap parameter and an old-heap parameter, it can use old expressions in its specification (including in the precondition) and body, its parameters may use the new modifier, and the old-heap parameter is by default passed in as the caller’s old heap, which can be changed by using an @-parameter.

Here is an example of something useful that can be done with a two-state lemma: 

function SeqSum(s: seq<Cell>): int
  reads s
{
  if s == [] then 0 else s[0].data + SeqSum(s[1..])
}

twostate lemma IncSumDiff(s: seq<Cell>)
  requires forall c :: c in s ==> Increasing(c)
  ensures old(SeqSum(s)) <= SeqSum(s)
{
  if s == [] {
  } else {
    calc {
      old(SeqSum(s));
    ==  // def. SeqSum
      old(s[0].data + SeqSum(s[1..]));
    ==  // distribute old
      old(s[0].data) + old(SeqSum(s[1..]));
    <=  { assert Increasing(s[0]); }
      s[0].data + old(SeqSum(s[1..]));
    <=  { IncSumDiff(s[1..]); }
      s[0].data + SeqSum(s[1..]);
    ==  // def. SeqSum
      SeqSum(s);
    }
  }
}

A two-state function can be used as a first-class function value, where the receiver (if any), type parameters (if any), and old-heap parameter are determined at the time the first-class value is mentioned. While the receiver and type parameters can be explicitly instantiated in such a use (for example, p.F<int> for a two-state instance function F that takes one type parameter), there is currently no syntactic support for giving the old-heap parameter explicitly. A caller can work around this restriction by using (fancy-word alert!) eta-expansion, meaning wrapping a lambda expression around the call, as in x => p.F<int>@L(x). The following example illustrates using such an eta-expansion: 

class P {
  twostate function F<X>(x: X): X
}

method EtaExample(p: P) returns (ghost f: int -> int) {
  label L:
  f := x => p.F<int>@L(x);
}

13.4. Function Declarations

FunctionDecl(isWithinAbstractModule) =
  ( [ "twostate" ] "function" [ "method" ] { Attribute }
    MethodFunctionName
    FunctionSignatureOrEllipsis_(allowGhostKeyword:
                                           ("method" present),
                                 allowNewKeyword:
                                           "twostate" present)
  | "predicate" [ "method" ] { Attribute }
    MethodFunctionName
    PredicateSignatureOrEllipsis_(allowGhostKeyword:
                                           ("method" present),
                                  allowNewKeyword:
                                           "twostate" present,
                                  allowOlderKeyword: true)
  | ( "least" | "greatest" ) "predicate" { Attribute }
    MethodFunctionName
    PredicateSignatureOrEllipsis_(allowGhostKeyword: false,
                         allowNewKeyword: "twostate" present,
                         allowOlderKeyword: false))
  )
  FunctionSpec
  [ FunctionBody ]

FunctionSignatureOrEllipsis_(allowGhostKeyword) =
  FunctionSignature_(allowGhostKeyword) | ellipsis

FunctionSignature_(allowGhostKeyword, allowNewKeyword) =
  [ GenericParameters ]
  Formals(allowGhostKeyword, allowNewKeyword, allowOlderKeyword: true, allowDefault: true)
  ":"
  ( Type
  | "(" GIdentType(allowGhostKeyword: false,
                   allowNewKeyword: false,
                   allowOlderKeyword: false,
                   allowNameOnlyKeyword: false,
                   allowDefault: false)
    ")"
  )

PredicateSignatureOrEllipsis_(allowGhostKeyword, allowNewKeyword, allowOlderKeyword) =
  PredicateSignature_(allowGhostKeyword, allowNewKeyword, allowOlderKeyword) | ellipsis

PredicateSignature_(allowGhostKeyword, allowNewKeyword, allowOlderKeyword) =
  [ GenericParameters ]
  [ KType ]
  Formals(allowGhostKeyword, allowNewKeyword, allowOlderKeyword, allowDefault: true)
  [
    ":"
    ( Type
    | "(" Ident ":" "bool" ")"
    )
  ]

FunctionBody = "{" Expression(allowLemma: true, allowLambda: true)
               "}" [ "by" "method" BlockStmt ]

13.4.1. Functions

In the above productions, allowGhostKeyword is true if the optional method keyword was specified. This allows some of the formal parameters of a function method to be specified as ghost.

See Section 5.3 for a description of FunctionSpec.

A Dafny function is a pure mathematical function. It is allowed to read memory that was specified in its reads expression but is not allowed to have any side effects.

Here is an example function declaration: 

function {:att1}{:att2} F<T1, T2>(a: A, b: B, c: C): T
  requires Pre
  reads Frame
  ensures Post
  decreases Rank
{
  Body
}

where :att1 and :att2 are attributes of the function, if any, T1 and T2 are type parameters of the function (if generic), a, b, c are the function’s parameters, T is the type of the function’s result, Pre is a boolean expression denoting the function’s precondition, Frame denotes a set of objects whose fields the function body may depend on, Post is a boolean expression denoting the function’s postcondition, Rank is the function’s variant function, and Body is an expression that defines the function’s return value. The precondition allows a function to be partial, that is, the precondition says when the function is defined (and Dafny will verify that every use of the function meets the precondition).

The postcondition is usually not needed, since the body of the function gives the full definition. However, the postcondition can be a convenient place to declare properties of the function that may require an inductive proof to establish, such as when the function is recursive. For example:

function Factorial(n: int): int
  requires 0 <= n
  ensures 1 <= Factorial(n)
{
  if n == 0 then 1 else Factorial(n-1) * n
}

says that the result of Factorial is always positive, which Dafny verifies inductively from the function body.

Within a postcondition, the result of the function is designated by a call of the function, such as Factorial(n) in the example above. Alternatively, a name for the function result can be given in the signature, as in the following rewrite of the example above.

function Factorial(n: int): (f: int)
  requires 0 <= n
  ensures 1 <= f
{
  if n == 0 then 1 else Factorial(n-1) * n
}

Pre v4.0, a function is ghost by default, and cannot be called from non-ghost code. To make it non-ghost, replace the keyword function with the two keywords “function method”. From v4.0 on, a function is non-ghost by default. To make it ghost, replace the keyword function with the two keywords “ghost function”. (See the /functionSyntax option for a description of the migration path for this change in behavior.}

Like methods, functions can be either instance (which they are by default) or static (when the function declaration contains the keyword static). An instance function, but not a static function, has an implicit receiver parameter, this. A static function F in a class C can be invoked by C.F(…). This provides a convenient way to declare a number of helper functions in a separate class.

As for methods, a ... is used when declaring a function in a module refinement (cf. Section 22). For example, if module M0 declares function F, a module M1 can be declared to refine M0 and M1 can then refine F. The refinement function, M1.F can have a ... which means to copy the signature from M0.F. A refinement function can furnish a body for a function (if M0.F does not provide one). It can also add ensures clauses.

If a function definition does not have a body, the program that contains it may still be verified. The function itself has nothing to verify. However, any calls of a body-less function are treated as unverified assumptions by the caller, asserting the preconditions and assuming the postconditions. Because body-less functions are unverified assumptions, Dafny will not compile them and will complain if called by dafny translate, dafny build or even dafny run

13.4.2. Predicates

A function that returns a bool result is called a predicate. As an alternative syntax, a predicate can be declared by replacing the function keyword with the predicate keyword and possibly omitting a declaration of the return type (if it is not named).

13.4.3. Function-by-method

A function with a by method clause declares a function-by-method. A function-by-method gives a way to implement a (deterministic, side-effect free) function by a method (whose body may be nondeterministic and may allocate objects that it modifies). This can be useful if the best implementation uses nondeterminism (for example, because it uses :| in a nondeterministic way) in a way that does not affect the result, or if the implementation temporarily makes use of some mutable data structures, or if the implementation is done with a loop. For example, here is the standard definition of the Fibonacci function but with an efficient implementation that uses a loop:

function Fib(n: nat): nat {
  if n < 2 then n else Fib(n - 2) + Fib(n - 1)
} by method {
  var x, y := 0, 1;
  for i := 0 to n
    invariant x == Fib(i) && y == Fib(i + 1)
  {
    x, y := y, x + y;
  }
  return x;
}

The by method clause is allowed only for non-ghost function or predicate declarations (without twostate, least, and greatest, but possibly with static); it inherits the in-parameters, attributes, and requires and decreases clauses of the function. The method also gets one out-parameter, corresponding to the function’s result value (and the name of it, if present). Finally, the method gets an empty modifies clause and a postcondition ensures r == F(args), where r is the name of the out-parameter and F(args) is the function with its arguments. In other words, the method body must compute and return exactly what the function says, and must do so without modifying any previously existing heap state.

The function body of a function-by-method is allowed to be ghost, but the method body must be compilable. In non-ghost contexts, the compiler turns a call of the function-by-method into a call that leads to the method body.

Note, the method body of a function-by-method may contain print statements. This means that the run-time evaluation of an expression may have print effects. Dafny does not track print effects, but this is the only situation that an expression can have a print effect.

13.4.4. Function Transparency

A function is said to be transparent in a location if the body of the function is visible at that point. A function is said to be opaque at a location if it is not transparent. However the FunctionSpec of a function is always available.

A function is usually transparent up to some unrolling level (up to 1, or maybe 2 or 3). If its arguments are all literals it is transparent all the way.

But the transparency of a function is affected by whether the function was given the {:opaque} attribute (as explained in Section 23.2.8).

The following table summarizes where the function is transparent. The module referenced in the table is the module in which the function is defined.

{:opaque}? Transparent Inside Module Transparent Outside Module
N Y Y
Y N N

When {:opaque} is specified for function g, g is opaque, however the statement reveal g(); is available to give the semantics of g whether in the defining module or outside.

13.4.5. Extreme (Least or Greatest) Predicates and Lemmas

See Section 24.5.3 for descriptions of extreme predicates and lemmas.

13.4.6. older parameters in predicates

A parameter of any predicate (more precisely, of any boolean-returning, non-extreme function) can be marked as older. This specifies that the truth of the predicate implies that the allocatedness of the parameter follows from the allocatedness of the non-older parameters.

To understand what this means and why this attribute is useful, consider the following example, which specifies reachability between nodes in a directed graph. A Node is declared to have any number of children:

class Node {
  var children: seq<Node>
}
``` <!-- %save Node.tmp -->

There are several ways one could specify reachability between
nodes. One way (which is used in `Test/dafny1/SchorrWaite.dfy` in the
Dafny test suite) is to define a type `Path`, representing lists of
`Node`s, and to define a predicate that checks if a given list of
`Node`s is indeed a path between two given nodes:

<!-- %check-verify %use Node.tmp -->
```dafny
datatype Path = Empty | Extend(Path, Node)

predicate ReachableVia(source: Node, p: Path, sink: Node, S: set<Node>)
  reads S
  decreases p
{
  match p
  case Empty =>
    source == sink
  case Extend(prefix, n) =>
    n in S && sink in n.children && ReachableVia(source, prefix, n, S)
}
``` <!-- %save ReachableVia.tmp -->

In a nutshell, the definition of `ReachableVia` says

* An empty path lets `source` reach `sink` just when
  `source` and `sink` are the same node.
* A path `Extend(prefix, n)` lets `source` reach `sink` just when
  the path `prefix` lets `source` reach `n` and `sink` is one of
  the children nodes of `n`.

To be admissible by Dafny, the recursive predicate must be shown to
terminate. Termination is assured by the specification `decreases p`,
since every such datatype value has a finite structure and every
recursive call passes in a path that is structurally included in the
previous. Predicate `ReachableVia` must also declare (an upper bound
on) which heap objects that it depends on. For this purpose, the
predicate takes an additional parameter `S`, which is used to limit
the set of intermediate nodes in the path. More precisely, predicate
`ReachableVia(source, p, sink, S)` returns `true` if and only if `p`
is a list of nodes in `S` and `source` can reach `sink` via `p`.

Using predicate `ReachableVia`, we can now define reachability in `S`:

<!-- %check-resolve Types.13.expect %use ReachableVia.tmp -->
```dafny
predicate Reachable(source: Node, sink: Node, S: set<Node>)
  reads S
{
  exists p :: ReachableVia(source, p, sink, S)
}

This looks like a good definition of reachability, but Dafny won’t admit it. The reason is twofold:

Often, it is easy to show that a quantifier is close-ended. In fact, if the type of a bound variable does not contain any object references, then the quantifier is trivially close-ended. For example,

forall x: int :: x <= Square(x)

is trivially close-ended.

Another innocent-looking quantifier occurs in the following example:

predicate IsCommutative<X>(r: (X, X) -> bool)
{
  forall x, y :: r(x, y) == r(y, x) // error: open-ended quantifier
}

Since nothing is known about type X, this quantifier might be open-ended. For example, if X were passed in as a class type, then the quantifier would be open-ended. One way to fix this predicate is to restrict it to non-heap based types, which is indicated with the (!new) type characteristic (see Section 8.1.4):

predicate IsCommutative<X(!new)>(r: (X, X) -> bool) // X is restricted to non-heap types
{
  forall x, y :: r(x, y) == r(y, x) // allowed
}

Another way to make IsCommutative close-ended is to constrain the values of the bound variables x and y. This can be done by adding a parameter to the predicate and limiting the quantified values to ones in the given set:

predicate IsCommutativeInS<X>(r: (X, X) -> bool, S: set<X>)
{
  forall x, y :: x in S && y in S ==> r(x, y) == r(y, x) // close-ended
}

Through a simple syntactic analysis, Dafny detects the antecedents x in S and y in S, and since S is a parameter and thus can only be passed in as something that the caller has already allocated, the quantifier in IsCommutativeInS is determined to be close-ended.

Note, the x in S trick does not work for the motivating example, Reachable. If you try to write

predicate Reachable(source: Node, sink: Node, S: set<Node>)
  reads S
{
  exists p :: p in S && ReachableVia(source, p, sink, S) // type error: p
}

you will get a type error, because p in S does not make sense if p has type Path. We need some other way to justify that the quantification in Reachable is close-ended.

Dafny offers a way to extend the x in S trick to more situations. This is where the older modifier comes in. Before we apply older in the Reachable example, let’s first look at what older does in a less cluttered example.

Suppose we rewrite IsCommutativeInS using a programmer-defined predicate In:

predicate In<X>(x: X, S: set<X>) {
  x in S
}

predicate IsCommutativeInS<X>(r: (X, X) -> bool, S: set<X>)
{
  forall x, y :: In(x, S) && In(y, S) ==> r(x, y) == r(y, x) // error: open-ended?
}

The simple syntactic analysis that looks for x in S finds nothing here, because the in operator is relegated to the body of predicate In. To inform the analysis that In is a predicate that, in effect, is like in, you can mark parameter x with older:

predicate In<X>(older x: X, S: set<X>) {
  x in S
}

This causes the simple syntactic analysis to accept the quantifier in IsCommutativeInS. Adding older also imposes a semantic check on the body of predicate In, enforced by the verifier. The semantic check is that all the object references in the value x are older (or equally old as) the object references that are part of the other parameters, in the event that the predicate returns true. That is, older is designed to help the caller only if the predicate returns true, and the semantic check amounts to nothing if the predicate returns false.

Finally, let’s get back to the motivating example. To allow the quantifier in Reachable, mark parameter p of ReachableVia with older:

class Node {
  var children: seq<Node>
}

datatype Path = Empty | Extend(Path, Node)

predicate Reachable(source: Node, sink: Node, S: set<Node>)
  reads S
{
  exists p :: ReachableVia(source, p, sink, S) // allowed because of 'older p' on ReachableVia
}

predicate ReachableVia(source: Node, older p: Path, sink: Node, S: set<Node>)
  reads S
  decreases p
{
  match p
  case Empty =>
    source == sink
  case Extend(prefix, n) =>
    n in S && sink in n.children && ReachableVia(source, prefix, n, S)
}

This example is more involved than the simpler In example above. Because of the older modifier on the parameter, the quantifier in Reachable is allowed. For intuition, you can think of the effect of older p as adding an antecedent p in {source} + {sink} + S (but, as we have seen, this is not type correct). The semantic check imposed on the body of ReachableVia makes sure that, if the predicate returns true, then every object reference in p is as old as some object reference in another parameter to the predicate.

14. Trait types

TraitDecl =
  "trait" { Attribute } ClassName [ GenericParameters ]
  [ "extends" Type { "," Type } | ellipsis ]
  "{"
   { { DeclModifier } ClassMemberDecl(allowConstructors: true,
                                      isValueType: false,
                                      moduleLevelDecl: false,
                                      isWithinAbstractModule: false) }
  "}"

A trait is an abstract superclass, similar to an “interface” or “mixin”. A trait can be extended only by another trait or by a class (and in the latter case we say that the class implements the trait). More specifically, algebraic datatypes cannot extend traits.4

The declaration of a trait is much like that of a class: 

trait J
{
  _members_
}

where members can include fields, functions, methods and declarations of nested traits, but no constructor methods. The functions and methods are allowed to be declared static.

A reference type C that extends a trait J is assignable to a variable of type J; a value of type J is assignable to a variable of a reference type C that extends J only if the verifier can prove that the reference does indeed refer to an object of allocated type C. The members of J are available as members of C. A member in J is not allowed to be redeclared in C, except if the member is a non-static function or method without a body in J. By doing so, type C can supply a stronger specification and a body for the member. There is further discussion on this point in Section 14.2.

new is not allowed to be used with traits. Therefore, there is no object whose allocated type is a trait. But there can of course be objects of a class C that implement a trait J, and a reference to such a C object can be used as a value of type J.

14.1. Type object

ObjectType_ = "object" | "object?"

There is a built-in trait object that is implicitly extended by all classes and traits. It produces two types: the type object? that is a supertype of all reference types and a subset type object that is a supertype of all non-null reference types. This includes reference types like arrays and iterators that do not permit explicit extending of traits. The purpose of type object is to enable a uniform treatment of dynamic frames. In particular, it is useful to keep a ghost field (typically named Repr for “representation”) of type set<object>.

It serves no purpose (but does no harm) to explicitly list the trait object as an extendee in a class or trait declaration.

Traits object? and object contain no members.

The dynamic allocation of objects is done using new C…, where C is the name of a class. The name C is not allowed to be a trait, except that it is allowed to be object. The construction new object allocates a new object (of an unspecified class type). The construction can be used to create unique references, where no other properties of those references are needed. (new object? makes no sense; always use new object instead because the result of new is always non-null.)

14.2. Inheritance

The purpose of traits is to be able to express abstraction: a trait encapsulates a set of behaviors; classes and traits that extend it inherit those behaviors, perhaps specializing them.

A trait or class may extend multiple other traits. The traits syntactically listed in a trait or class’s extends clause are called its direct parents; the transitive parents of a trait or class are its direct parents, the transitive parents of its direct parents, and the object trait (if it is not itself object). These are sets of traits, in that it does not matter if there are repetitions of a given trait in a class or trait’s direct or transitive parents. However, if a trait with type parameters is repeated, it must have the same actual type parameters in each instance. Furthermore, a trait may not be in its own set of transitive parents; that is, the graph of traits connected by the directed extends relationship may not have any cycles.

A class or trait inherits (as if they are copied) all the instance members of its transitive parents. However, since names may not be overloaded in Dafny, different members (that is, members with different type signatures) within the set of transitive parents and the class or trait itself must have different names.5 This restriction does mean that traits from different sources that coincidentally use the same name for different purposes cannot be combined by being part of the set of transitive parents for some new trait or class.

A declaration of member C.M in a class or trait overrides any other declarations of the same name (and signature) in a transitive parent. C.M is then called an override; a declaration that does not override anything is called an original declaration.

Static members of a trait may not be redeclared; thus, if there is a body it must be declared in the trait; the compiler will require a body, though the verifier will not.

Where traits within an extension hierarchy do declare instance members with the same name (and thus the same signature), some rules apply. Recall that, for methods, every declaration includes a specification; if no specification is given explicitly, a default specification applies. Instance method declarations in traits, however, need not have a body, as a body can be declared in an override.

For a given non-static method M,

The last restriction above is the current implementation. It effectively limits inheritance of a method M to a single “chain” of declarations and does not permit mixins.

Each of any method declarations explicitly or implicitly includes a specification. In simple cases, those syntactically separate specifications will be copies of each other (up to renaming to take account of differing formal parameter names). However they need not be. The rule is that the specifications of M in a given class or trait must be as strong as M’s specifications in a transitive parent. Here as strong as means that it must be permitted to call the subtype’s M in the context of the supertype’s M. Stated differently, where P and C are a parent trait and a child class or trait, respectively, then, under the precondition of P.M,

Non-static const and field declarations are also inherited from parent traits. These may not be redeclared in extending traits and classes. However, a trait need not initialize a const field with a value. The class that extends a trait that declares such a const field without an initializer can initialize the field in a constructor. If the declaring trait does give an initial value in the declaration, the extending class or trait may not either redeclare the field or give it a value in a constructor.

When names are inherited from multiple traits, they must be different. If two traits declare a common name (even with the same signature), they cannot both be extendees of the same class or trait.

14.3. Example of traits

As an example, the following trait represents movable geometric shapes: 

trait Shape
{
  function method Width(): real
    reads this
    decreases 1
  method Move(dx: real, dy: real)
    modifies this
  method MoveH(dx: real)
    modifies this
  {
    Move(dx, 0.0);
  }
}
``` <!-- %save Shape.tmp -->
Members `Width` and `Move` are _abstract_ (that is, body-less) and can
be implemented differently by different classes that extend the trait.
The implementation of method `MoveH` is given in the trait and thus
is used by all classes that extend `Shape`.  Here are two classes
that each extend `Shape`:
<!-- %check-verify %use Shape.tmp -->
```dafny
class UnitSquare extends Shape
{
  var x: real, y: real
  function method Width(): real 
    decreases 0
  {  // note the empty reads clause
    1.0
  }
  method Move(dx: real, dy: real)
    modifies this
  {
    x, y := x + dx, y + dy;
  }
}

class LowerRightTriangle extends Shape
{
  var xNW: real, yNW: real, xSE: real, ySE: real
  function method Width(): real
    reads this
    decreases 0
  {
    xSE - xNW
  }
  method Move(dx: real, dy: real)
    modifies this
  {
    xNW, yNW, xSE, ySE := xNW + dx, yNW + dy, xSE + dx, ySE + dy;
  }
}
``` <!-- %save UnitSquare.tmp -->
Note that the classes can declare additional members, that they supply
implementations for the abstract members of the trait,
that they repeat the member signatures, and that they are responsible
for providing their own member specifications that both strengthen the
corresponding specification in the trait and are satisfied by the
provided body.
Finally, here is some code that creates two class instances and uses
them together as shapes:
<!-- %check-verify %use UnitSquare.tmp -->
```dafny
method m() {
  var myShapes: seq<Shape>;
  var A := new UnitSquare;
  myShapes := [A];
  var tri := new LowerRightTriangle;
  // myShapes contains two Shape values, of different classes
  myShapes := myShapes + [tri];
  // move shape 1 to the right by the width of shape 0
  myShapes[1].MoveH(myShapes[0].Width());
}

15. Array types

ArrayType_ = arrayToken [ GenericInstantiation ]

Dafny supports mutable fixed-length array types of any positive dimension. Array types are (heap-based) reference types.

arrayToken is a kind of reserved token, such as array, array2, array3, an so on (but not array1). The suffix giving the element type can be omitted if the element type can be inferred, though in that case it is likely that the arrayToken itself is also inferrable and can be omitted.

15.1. One-dimensional arrays

A one-dimensional array of n T elements may be initialized by any expression that returns a value of the desired type. Commonly, array allocation expressions are used. Some examples are shown here: 

type T(0)
method m(n: nat) {
  var a := new T[n];
  var b: array<int> := new int[8];
  var c: array := new T[9];
}

The initial values of the array elements are arbitrary values of type T. A one-dimensional array value can also be assigned using an ordered list of expressions enclosed in square brackets, as follows: 

a := new T[] [t1, t2, t3, t4];

The initialization can also use an expression that returns a function of type nat -> T: 

a := new int[5](i => i*i);

In fact, the initializer can simply be a function name for the right type of function: 

a := new int[5](Square);

The length of an array is retrieved using the immutable Length member. For example, the array allocated with a := new T[n]; satisfies: 

a.Length == n

Once an array is allocated, its length cannot be changed.

For any integer-based numeric i in the range 0 <= i < a.Length, the array selection expression a[i] retrieves element i (that is, the element preceded by i elements in the array). The element stored at i can be changed to a value t using the array update statement: 

a[i] := t;

Caveat: The type of the array created by new T[n] is array<T>. A mistake that is simple to make and that can lead to befuddlement is to write array<T> instead of T after new. For example, consider the following: 

type T(0)
method m(n: nat) {
  var a := new array<T>;
  var b := new array<T>[n];
  var c := new array<T>(n);  // resolution error
  var d := new array(n);  // resolution error
}

The first statement allocates an array of type array<T>, but of unknown length. The second allocates an array of type array<array<T>> of length n, that is, an array that holds n values of type array<T>. The third statement allocates an array of type array<T> and then attempts to invoke an anonymous constructor on this array, passing argument n. Since array has no constructors, let alone an anonymous constructor, this statement gives rise to an error. If the type-parameter list is omitted for a type that expects type parameters, Dafny will attempt to fill these in, so as long as the array type parameter can be inferred, it is okay to leave off the “<T>” in the fourth statement above. However, as with the third statement, array has no anonymous constructor, so an error message is generated.

15.2. Converting arrays to sequences

One-dimensional arrays support operations that convert a stretch of consecutive elements into a sequence. For any array a of type array<T>, integer-based numerics lo and hi satisfying 0 <= lo <= hi <= a.Length, the following operations each yields a seq<T>:

expression description
a[lo..hi] subarray conversion to sequence
a[lo..] drop
a[..hi] take
a[..] array conversion to sequence

The expression a[lo..hi] takes the first hi elements of the array, then drops the first lo elements thereof and returns what remains as a sequence, with length hi - lo. The other operations are special instances of the first. If lo is omitted, it defaults to 0 and if hi is omitted, it defaults to a.Length. In the last operation, both lo and hi have been omitted, thus a[..] returns the sequence consisting of all the array elements of a.

The subarray operations are especially useful in specifications. For example, the loop invariant of a binary search algorithm that uses variables lo and hi to delimit the subarray where the search key may still be found can be expressed as follows: 

key !in a[..lo] && key !in a[hi..]

Another use is to say that a certain range of array elements have not been changed since the beginning of a method: 

a[lo..hi] == old(a[lo..hi])

or since the beginning of a loop: 

ghost var prevElements := a[..];
while // ...
  invariant a[lo..hi] == prevElements[lo..hi]
{
  // ...
}

Note that the type of prevElements in this example is seq<T>, if a has type array<T>.

A final example of the subarray operation lies in expressing that an array’s elements are a permutation of the array’s elements at the beginning of a method, as would be done in most sorting algorithms. Here, the subarray operation is combined with the sequence-to-multiset conversion: 

multiset(a[..]) == multiset(old(a[..]))

15.3. Multi-dimensional arrays

An array of 2 or more dimensions is mostly like a one-dimensional array, except that new takes more length arguments (one for each dimension), and the array selection expression and the array update statement take more indices. For example: 

matrix := new T[m, n];
matrix[i, j], matrix[x, y] := matrix[x, y], matrix[i, j];

create a 2-dimensional array whose dimensions have lengths m and n, respectively, and then swaps the elements at i,j and x,y. The type of matrix is array2<T>, and similarly for higher-dimensional arrays (array3<T>, array4<T>, etc.). Note, however, that there is no type array0<T>, and what could have been array1<T> is actually named just array<T>. (Accordingly, array0 and array1 are just normal identifiers, not type names.)

The new operation above requires m and n to be non-negative integer-based numerics. These lengths can be retrieved using the immutable fields Length0 and Length1. For example, the following holds for the array created above: 

matrix.Length0 == m && matrix.Length1 == n

Higher-dimensional arrays are similar (Length0, Length1, Length2, …). The array selection expression and array update statement require that the indices are in bounds. For example, the swap statement above is well-formed only if: 

0 <= i < matrix.Length0 && 0 <= j < matrix.Length1 &&
0 <= x < matrix.Length0 && 0 <= y < matrix.Length1

In contrast to one-dimensional arrays, there is no operation to convert stretches of elements from a multi-dimensional array to a sequence.

There is however syntax to create a multi-dimensional array value using a function: see Section 21.16.

16. Iterator types

IteratorDecl = "iterator" { Attribute } IteratorName
  ( [ GenericParameters ]
    Formals(allowGhostKeyword: true, allowNewKeyword: false, allowOlderKeyword: false)
    [ "yields" Formals(allowGhostKeyword: true, allowNewKeyword: false, allowOlderKeyword: false) ]
  | ellipsis
  )
  IteratorSpec
  [ BlockStmt ]

See Section 5.5 for a description of IteratorSpec.

An iterator provides a programming abstraction for writing code that iteratively returns elements. These CLU-style iterators are co-routines in the sense that they keep track of their own program counter and control can be transferred into and out of the iterator body.

An iterator is declared as follows: 

iterator Iter<T>(_in-params_) yields (_yield-params_)
  _specification_
{
  _body_
}

where T is a list of type parameters (as usual, if there are no type parameters, “<T>” is omitted). This declaration gives rise to a reference type with the same name, Iter<T>. In the signature, in-parameters and yield-parameters are the iterator’s analog of a method’s in-parameters and out-parameters. The difference is that the out-parameters of a method are returned to a caller just once, whereas the yield-parameters of an iterator are returned each time the iterator body performs a yield. The body consists of statements, like in a method body, but with the availability also of yield statements.

From the perspective of an iterator client, the iterator declaration can be understood as generating a class Iter<T> with various members, a simplified version of which is described next.

The Iter<T> class contains an anonymous constructor whose parameters are the iterator’s in-parameters: 

predicate Valid()
constructor (_in-params_)
  modifies this
  ensures Valid()

An iterator is created using new and this anonymous constructor. For example, an iterator willing to return ten consecutive integers from start can be declared as follows: 

iterator Gen(start: int) yields (x: int)
  yield ensures |xs| <= 10 && x == start + |xs| - 1
{
  var i := 0;
  while i < 10 invariant |xs| == i {
    x := start + i;
    yield;
    i := i + 1;
  }
}
``` <-- %save Gen.tmp -->
An instance of this iterator is created using
<!-- %no-check -->
```dafny
iter := new Gen(30);

It is used like this: 

method Main() {
  var i := new Gen(30);
  while true
    invariant i.Valid() && fresh(i._new)
    decreases 10 - |i.xs|
  {
    var m := i.MoveNext();
    if (!m) {break; }
    print i.x;
  }
}

The predicate Valid() says when the iterator is in a state where one can attempt to compute more elements. It is a postcondition of the constructor and occurs in the specification of the MoveNext member: 

method MoveNext() returns (more: bool)
  requires Valid()
  modifies this
  ensures more ==> Valid()

Note that the iterator remains valid as long as MoveNext returns true. Once MoveNext returns false, the MoveNext method can no longer be called. Note, the client is under no obligation to keep calling MoveNext until it returns false, and the body of the iterator is allowed to keep returning elements forever.

The in-parameters of the iterator are stored in immutable fields of the iterator class. To illustrate in terms of the example above, the iterator class Gen contains the following field: 

const start: int

The yield-parameters also result in members of the iterator class: 

var x: int

These fields are set by the MoveNext method. If MoveNext returns true, the latest yield values are available in these fields and the client can read them from there.

To aid in writing specifications, the iterator class also contains ghost members that keep the history of values returned by MoveNext. The names of these ghost fields follow the names of the yield-parameters with an “s” appended to the name (to suggest plural). Name checking rules make sure these names do not give rise to ambiguities. The iterator class for Gen above thus contains: 

ghost var xs: seq<int>

These history fields are changed automatically by MoveNext, but are not assignable by user code.

Finally, the iterator class contains some special fields for use in specifications. In particular, the iterator specification is recorded in the following immutable fields: 

ghost var _reads: set<object>
ghost var _modifies: set<object>
ghost var _decreases0: T0
ghost var _decreases1: T1
// ...

where there is a _decreases(i): T(i) field for each component of the iterator’s decreases clause.6 In addition, there is a field: 

ghost var _new: set<object>;

to which any objects allocated on behalf of the iterator body are added. The iterator body is allowed to remove elements from the _new set, but cannot by assignment to _new add any elements.

Note, in the precondition of the iterator, which is to hold upon construction of the iterator, the in-parameters are indeed in-parameters, not fields of this.

It is regrettably tricky to use iterators. The language really ought to have a foreach statement to make this easier. Here is an example showing a definition and use of an iterator.

iterator Iter<T(0)>(s: set<T>) yields (x: T)
  yield ensures x in s && x !in xs[..|xs|-1];
  ensures s == set z | z in xs;
{
  var r := s;
  while (r != {})
    invariant r !! set z | z in xs
    invariant s == r + set z | z in xs;
  {
    var y :| y in r;
    assert y !in xs;
    r, x := r - {y}, y;
    assert y !in xs;
    yield;
    assert y == xs[|xs|-1]; // a lemma to help prove loop invariant
  }
}

method UseIterToCopy<T(0)>(s: set<T>) returns (t: set<T>)
  ensures s == t;
{
  t := {};
  var m := new Iter(s);
  while (true)
    invariant m.Valid() && fresh(m._new);
    invariant t == set z | z in m.xs;
    decreases s - t;
  {
    var more := m.MoveNext();
    if (!more) { break; }
    t := t + {m.x};
  }
}

The design of iterators is under discussion and may change.

async method AM<T>(\(_in-params_\)) returns (\(_out-params_\))

also gives rise to an async-task type AM<T> (outside the enclosing class, the name of the type needs the qualification C.AM<T>). The async-task type is a reference type and can be understood as a class with various members, a simplified version of which is described next.

Each in-parameter x of type X of the asynchronous method gives rise to a immutable ghost field of the async-task type: 

ghost var x: X;

Each out-parameter y of type Y gives rise to a field 

var y: Y;

These fields are changed automatically by the time the asynchronous method is successfully awaited, but are not assignable by user code.

The async-task type also gets a number of special fields that are used to keep track of dependencies, outstanding tasks, newly allocated objects, etc. These fields will be described in more detail as the design of asynchronous methods evolves.

–>

17. Arrow types

ArrowType_ = ( DomainType_ "~>" Type
             | DomainType_ "-->" Type
             | DomainType_ "->" Type
             )

Functions are first-class values in Dafny. The types of function values are called arrow types (aka, function types). Arrow types have the form (TT) ~> U where TT is a (possibly empty) comma-delimited list of types and U is a type. TT is called the function’s domain type(s) and U is its range type. For example, the type of a function 

function F(x: int, arr: array<bool>): real
  requires x < 1000
  reads arr

is (int, array<bool>) ~> real.

As seen in the example above, the functions that are values of a type (TT) ~> U can have a precondition (as indicated by the requires clause) and can read values in the heap (as indicated by the reads clause). As described in Section 11.3.3, the subset type (TT) --> U denotes partial (but heap-independent) functions and the subset type (TT) -> U denotes total functions.

A function declared without a reads clause is known by the type checker to be a partial function. For example, the type of 

function F(x: int, b: bool): real
  requires x < 1000

is (int, bool) --> real. Similarly, a function declared with neither a reads clause nor a requires clause is known by the type checker to be a total function. For example, the type of 

function F(x: int, b: bool): real

is (int, bool) -> real. In addition to functions declared by name, Dafny also supports anonymous functions by means of lambda expressions (see Section 21.13).

To simplify the appearance of the basic case where a function’s domain consists of a list of exactly one non-function, non-tuple type, the parentheses around the domain type can be dropped in this case. For example, you may write just T -> U for a total arrow type. This innocent simplification requires additional explanation in the case where that one type is a tuple type, since tuple types are also written with enclosing parentheses. If the function takes a single argument that is a tuple, an additional set of parentheses is needed. For example, the function 

function G(pair: (int, bool)): real

has type ((int, bool)) -> real. Note the necessary double parentheses. Similarly, a function that takes no arguments is different from one that takes a 0-tuple as an argument. For instance, the functions 

function NoArgs(): real
function Z(unit: ()): real

have types () -> real and (()) -> real, respectively.

The function arrows are right associative. For example, A -> B -> C means A -> (B -> C), whereas the other association requires explicit parentheses: (A -> B) -> C. As another example, A -> B --> C ~> D means A -> (B --> (C ~> D)).

Note that the receiver parameter of a named function is not part of the type. Rather, it is used when looking up the function and can then be thought of as being captured into the function definition. For example, suppose function F above is declared in a class C and that c references an object of type C; then, the following is type correct: 

var f: (int, bool) -> real := c.F;

whereas it would have been incorrect to have written something like: 

var f': (C, int, bool) -> real := F;  // not correct

The arrow types themselves do not divide its parameters into ghost versus non-ghost. Instead, a function used as a first-class value is considered to be ghost if either the function or any of its arguments is ghost. The following example program illustrates: 

function method F(x: int, ghost y: int): int
{
  x
}

method Example() {
  ghost var f: (int, int) -> int;
  var g: (int, int) -> int;
  var h: (int) -> int;
  var x: int;
  f := F;
  x := F(20, 30);
  g := F; // error: tries to assign ghost to non-ghost
  h := F; // error: wrong arity (and also tries to assign ghost to non-ghost)
}

In addition to its type signature, each function value has three properties, described next.

Every function implicitly takes the heap as an argument. No function ever depends on the entire heap, however. A property of the function is its declared upper bound on the set of heap locations it depends on for a given input. This lets the verifier figure out that certain heap modifications have no effect on the value returned by a certain function. For a function f: T ~> U and a value t of type T, the dependency set is denoted f.reads(t) and has type set<object>.

The second property of functions stems from the fact that every function is potentially partial. In other words, a property of a function is its precondition. For a function f: T ~> U, the precondition of f for a parameter value t of type T is denoted f.requires(t) and has type bool.

The third property of a function is more obvious—the function’s body. For a function f: T ~> U, the value that the function yields for an input t of type T is denoted f(t) and has type U.

Note that f.reads and f.requires are themselves functions. Suppose f has type T ~> U and t has type T. Then, f.reads is a function of type T ~> set<object?> whose reads and requires properties are: 

f.reads.reads(t) == f.reads(t)
f.reads.requires(t) == true

f.requires is a function of type T ~> bool whose reads and requires properties are: 

f.requires.reads(t) == f.reads(t)
f.requires.requires(t) == true

In these examples, if f instead had type T --> U or T -> U, then the type of f.reads is T -> set<object?> and the type of f.requires is T -> bool.

Dafny also supports anonymous functions by means of lambda expressions. See Section 21.13.

18. Tuple types

TupleType = "(" [ [ "ghost" ] Type { "," [ "ghost" ] Type } ] ")"

Dafny builds in record types that correspond to tuples and gives these a convenient special syntax, namely parentheses. For example, for what might have been declared as 

datatype Pair<T,U> = Pair(0: T, 1: U)

Dafny provides the type (T, U) and the constructor (t, u), as if the datatype’s name were “” (i.e., an empty string) and its type arguments are given in round parentheses, and as if the constructor name were the empty string. Note that the destructor names are 0 and 1, which are legal identifier names for members. For example, showing the use of a tuple destructor, here is a property that holds of 2-tuples (that is, pairs): 

method m(){
  assert (5, true).1 == true;
}

Dafny declares n-tuples where n is 0 or 2 or more. There are no 1-tuples, since parentheses around a single type or a single value have no semantic meaning. The 0-tuple type, (), is often known as the unit type and its single value, also written (), is known as unit.

The ghost modifier can be used to mark tuple components as being used for specification only: 

const pair: (int, ghost int) := (1, ghost 2)

19. Algebraic Datatypes

DatatypeDecl =
  ( "datatype" | "codatatype" )
  { Attribute }
  DatatypeName [ GenericParameters ]
  "=" [ ellipsis ]
      [ "|" ] DatatypeMemberDecl
      { "|" DatatypeMemberDecl }
      [ TypeMembers ]

DatatypeMemberDecl =
  { Attribute } DatatypeMemberName [ FormalsOptionalIds ]

Dafny offers two kinds of algebraic datatypes, those defined inductively (with datatype) and those defined coinductively (with codatatype). The salient property of every datatype is that each value of the type uniquely identifies one of the datatype’s constructors and each constructor is injective in its parameters.

19.1. Inductive datatypes

The values of inductive datatypes can be seen as finite trees where the leaves are values of basic types, numeric types, reference types, coinductive datatypes, or arrow types. Indeed, values of inductive datatypes can be compared using Dafny’s well-founded < ordering.

An inductive datatype is declared as follows: 

datatype D<T> = _Ctors_

where Ctors is a nonempty |-separated list of (datatype) constructors for the datatype. Each constructor has the form: 

C(_params_)

where params is a comma-delimited list of types, optionally preceded by a name for the parameter and a colon, and optionally preceded by the keyword ghost. If a constructor has no parameters, the parentheses after the constructor name may be omitted. If no constructor takes a parameter, the type is usually called an enumeration; for example: 

datatype Friends = Agnes | Agatha | Jermaine | Jack

For every constructor C, Dafny defines a discriminator C?, which is a member that returns true if and only if the datatype value has been constructed using C. For every named parameter p of a constructor C, Dafny defines a destructor p, which is a member that returns the p parameter from the C call used to construct the datatype value; its use requires that C? holds. For example, for the standard List type 

datatype List<T> = Nil | Cons(head: T, tail: List<T>)
``` <!-- %save List.tmp -->
the following holds:
<!-- %check-verify %use List.tmp -->
```dafny
method m() {
  assert Cons(5, Nil).Cons? && Cons(5, Nil).head == 5;
}

Note that the expression 

Cons(5, Nil).tail.head

is not well-formed, since Cons(5, Nil).tail does not necessarily satisfy Cons?.

A constructor can have the same name as the enclosing datatype; this is especially useful for single-constructor datatypes, which are often called record types. For example, a record type for black-and-white pixels might be represented as follows: 

datatype Pixel = Pixel(x: int, y: int, on: bool)

To call a constructor, it is usually necessary only to mention the name of the constructor, but if this is ambiguous, it is always possible to qualify the name of constructor by the name of the datatype. For example, Cons(5, Nil) above can be written 

List.Cons(5, List.Nil)

As an alternative to calling a datatype constructor explicitly, a datatype value can be constructed as a change in one parameter from a given datatype value using the datatype update expression. For any d whose type is a datatype that includes a constructor C that has a parameter (destructor) named f of type T, and any expression t of type T, 

d.(f := t)

constructs a value like d but whose f parameter is t. The operation requires that d satisfies C?. For example, the following equality holds: 

method m(){
  assert Cons(4, Nil).(tail := Cons(3, Nil)) == Cons(4, Cons(3, Nil));
}

The datatype update expression also accepts multiple field names, provided these are distinct. For example, a node of some inductive datatype for trees may be updated as follows:

node.(left := L, right := R)

The operator < is defined for two operands of the same datataype. It means is properly contained in. For example, in the code 

datatype X = T(t: X) | I(i: int)
method comp() {
  var x := T(I(0));
  var y := I(0);
  var z := I(1);
  assert x.t < x;
  assert y < x;
  assert !(x < x);
  assert z < x; // FAILS
}

x is a datatype value that holds a T variant, which holds a I variant, which holds an integer 0. The value x.t is a portion of the datatype structure denoted by x, so x.t < x is true. Datatype values are immutable mathematical values, so the value of y is identical to the value of x.t, so y < x is true also, even though y is constructed from the ground up, rather than as a portion of x. However, z is different than either y or x.t and consequently z < x is not provable. Furthermore, < does not include ==, so x < x is false.

Note that only < is defined; not <= or > or >=.

Also, < is underspecified. With the above code, one can prove neither z < x nor !(z < x) and neither z < y nor !(z < y). In each pair, though, one or the other is true, so (z < x) || !(z < x) is provable.

19.2. Coinductive datatypes

Whereas Dafny insists that there is a way to construct every inductive datatype value from the ground up, Dafny also supports coinductive datatypes, whose constructors are evaluated lazily, and hence the language allows infinite structures. A coinductive datatype is declared using the keyword codatatype; other than that, it is declared and used like an inductive datatype.

For example, 

codatatype IList<T> = Nil | Cons(head: T, tail: IList<T>)
codatatype Stream<T> = More(head: T, tail: Stream<T>)
codatatype Tree<T> = Node(left: Tree<T>, value: T, right: Tree<T>)

declare possibly infinite lists (that is, lists that can be either finite or infinite), infinite streams (that is, lists that are always infinite), and infinite binary trees (that is, trees where every branch goes on forever), respectively.

The paper Co-induction Simply, by Leino and Moskal[@LEINO:Dafny:Coinduction], explains Dafny’s implementation and verification of coinductive types. We capture the key features from that paper in this section but the reader is referred to that paper for more complete details and to supply bibliographic references that are omitted here.

19.3. Coinduction

Mathematical induction is a cornerstone of programming and program verification. It arises in data definitions (e.g., some algebraic data structures can be described using induction), it underlies program semantics (e.g., it explains how to reason about finite iteration and recursion), and it is used in proofs (e.g., supporting lemmas about data structures use inductive proofs). Whereas induction deals with finite things (data, behavior, etc.), its dual, coinduction, deals with possibly infinite things. Coinduction, too, is important in programming and program verification: it arises in data definitions (e.g., lazy data structures), semantics (e.g., concurrency), and proofs (e.g., showing refinement in a coinductive big-step semantics). It is thus desirable to have good support for both induction and coinduction in a system for constructing and reasoning about programs.

Co-datatypes and co-recursive functions make it possible to use lazily evaluated data structures (like in Haskell or Agda). Greatest predicates, defined by greatest fix-points, let programs state properties of such data structures (as can also be done in, for example, Coq). For the purpose of writing coinductive proofs in the language, we introduce greatest and least lemmas. A greatest lemma invokes the coinduction hypothesis much like an inductive proof invokes the induction hypothesis. Underneath the hood, our coinductive proofs are actually approached via induction: greatest and least lemmas provide a syntactic veneer around this approach.

The following example gives a taste of how the coinductive features in Dafny come together to give straightforward definitions of infinite matters. 

// infinite streams
codatatype IStream<T> = ICons(head: T, tail: IStream<T>)

// pointwise product of streams
function Mult(a: IStream<int>, b: IStream<int>): IStream<int>
{ ICons(a.head * b.head, Mult(a.tail, b.tail)) }

// lexicographic order on streams
greatest predicate Below(a: IStream<int>, b: IStream<int>)
{ a.head <= b.head &&
  ((a.head == b.head) ==> Below(a.tail, b.tail))
}

// a stream is Below its Square
greatest lemma Theorem_BelowSquare(a: IStream<int>)
  ensures Below(a, Mult(a, a))
{ assert a.head <= Mult(a, a).head;
  if a.head == Mult(a, a).head {
    Theorem_BelowSquare(a.tail);
  }
}

// an incorrect property and a bogus proof attempt
greatest lemma NotATheorem_SquareBelow(a: IStream<int>)
  ensures Below(Mult(a, a), a); // ERROR
{
  NotATheorem_SquareBelow(a);
}

The example defines a type IStream of infinite streams, with constructor ICons and destructors head and tail. Function Mult performs pointwise multiplication on infinite streams of integers, defined using a co-recursive call (which is evaluated lazily). Greatest predicate Below is defined as a greatest fix-point, which intuitively means that the co-predicate will take on the value true if the recursion goes on forever without determining a different value. The greatest lemma states the theorem Below(a, Mult(a, a)). Its body gives the proof, where the recursive invocation of the co-lemma corresponds to an invocation of the coinduction hypothesis.

The proof of the theorem stated by the first co-lemma lends itself to the following intuitive reading: To prove that a is below Mult(a, a), check that their heads are ordered and, if the heads are equal, also prove that the tails are ordered. The second co-lemma states a property that does not always hold; the verifier is not fooled by the bogus proof attempt and instead reports the property as unproved.

We argue that these definitions in Dafny are simple enough to level the playing field between induction (which is familiar) and coinduction (which, despite being the dual of induction, is often perceived as eerily mysterious). Moreover, the automation provided by our SMT-based verifier reduces the tedium in writing coinductive proofs. For example, it verifies Theorem_BelowSquare from the program text given above—no additional lemmas or tactics are needed. In fact, as a consequence of the automatic-induction heuristic in Dafny, the verifier will automatically verify Theorem_BelowSquare even given an empty body.

Just like there are restrictions on when an inductive hypothesis can be invoked, there are restrictions on how a coinductive hypothesis can be used. These are, of course, taken into consideration by Dafny’s verifier. For example, as illustrated by the second greatest lemma above, invoking the coinductive hypothesis in an attempt to obtain the entire proof goal is futile. (We explain how this works in the section about greatest lemmas) Our initial experience with coinduction in Dafny shows it to provide an intuitive, low-overhead user experience that compares favorably to even the best of today’s interactive proof assistants for coinduction. In addition, the coinductive features and verification support in Dafny have other potential benefits. The features are a stepping stone for verifying functional lazy programs with Dafny. Coinductive features have also shown to be useful in defining language semantics, as needed to verify the correctness of a compiler, so this opens the possibility that such verifications can benefit from SMT automation.

19.3.1. Well-Founded Function/Method Definitions

The Dafny programming language supports functions and methods. A function in Dafny is a mathematical function (i.e., it is well-defined, deterministic, and pure), whereas a method is a body of statements that can mutate the state of the program. A function is defined by its given body, which is an expression. To ensure that function definitions are mathematically consistent, Dafny insists that recursive calls be well-founded, enforced as follows: Dafny computes the call graph of functions. The strongly connected components within it are clusters of mutually recursive definitions; the clusters are arranged in a DAG. This stratifies the functions so that a call from one cluster in the DAG to a lower cluster is allowed arbitrarily. For an intra-cluster call, Dafny prescribes a proof obligation that is taken through the program verifier’s reasoning engine. Semantically, each function activation is labeled by a rank—a lexicographic tuple determined by evaluating the function’s decreases clause upon invocation of the function. The proof obligation for an intra-cluster call is thus that the rank of the callee is strictly less (in a language-defined well-founded relation) than the rank of the caller. Because these well-founded checks correspond to proving termination of executable code, we will often refer to them as “termination checks”. The same process applies to methods.

Lemmas in Dafny are commonly introduced by declaring a method, stating the property of the lemma in the postcondition (keyword ensures) of the method, perhaps restricting the domain of the lemma by also giving a precondition (keyword requires), and using the lemma by invoking the method. Lemmas are stated, used, and proved as methods, but since they have no use at run time, such lemma methods are typically declared as ghost, meaning that they are not compiled into code. The keyword lemma introduces such a method. Control flow statements correspond to proof techniques—case splits are introduced with if statements, recursion and loops are used for induction, and method calls for structuring the proof. Additionally, the statement: 

forall x | P(x) { Lemma(x); }

is used to invoke Lemma(x) on all x for which P(x) holds. If Lemma(x) ensures Q(x), then the forall statement establishes 

forall x :: P(x) ==> Q(x).

19.3.2. Defining Coinductive Datatypes

Each value of an inductive datatype is finite, in the sense that it can be constructed by a finite number of calls to datatype constructors. In contrast, values of a coinductive datatype, or co-datatype for short, can be infinite. For example, a co-datatype can be used to represent infinite trees.

Syntactically, the declaration of a co-datatype in Dafny looks like that of a datatype, giving prominence to the constructors (following Coq). The following example defines a co-datatype Stream of possibly infinite lists.

codatatype Stream<T> = SNil | SCons(head: T, tail: Stream)
function Up(n: int): Stream<int> { SCons(n, Up(n+1)) }
function FivesUp(n: int): Stream<int>
  decreases 4 - (n - 1) % 5
{
  if (n % 5 == 0) then
    SCons(n, FivesUp(n+1))
  else
    FivesUp(n+1)
}
``` <!-- %save Stream.tmp -->

`Stream` is a coinductive datatype whose values are possibly infinite
lists. Function `Up` returns a stream consisting of all integers upwards
of `n` and `FivesUp` returns a stream consisting of all multiples of 5
upwards of `n` . The self-call in `Up` and the first self-call in `FivesUp`
sit in productive positions and are therefore classified as co-recursive
calls, exempt from termination checks. The second self-call in `FivesUp` is
not in a productive position and is therefore subject to termination
checking; in particular, each recursive call must decrease the rank
defined by the `decreases` clause.

Analogous to the common finite list datatype, `Stream` declares two
constructors, `SNil` and `SCons`. Values can be destructed using match
expressions and statements. In addition, like for inductive datatypes,
each constructor `C` automatically gives rise to a discriminator `C?` and
each parameter of a constructor can be named in order to introduce a
corresponding destructor. For example, if `xs` is the stream
`SCons(x, ys)`, then `xs.SCons?` and `xs.head == x` hold. In contrast
to datatype declarations, there is no grounding check for
co-datatypes—since a codatatype admits infinite values, the type is
nevertheless inhabited.

### 19.3.3. Creating Values of Co-datatypes
To define values of co-datatypes, one could imagine a “co-function”
language feature: the body of a “co-function” could include possibly
never-ending self-calls that are interpreted by a greatest fix-point
semantics (akin to a **CoFixpoint** in Coq). Dafny uses a different design:
it offers only functions (not “co-functions”), but it classifies each
intra-cluster call as either _recursive_ or _co-recursive_. Recursive calls
are subject to termination checks. Co-recursive calls may be
never-ending, which is what is needed to define infinite values of a
co-datatype. For example, function `Up(n)` in the preceding example is defined as the
stream of numbers from `n` upward: it returns a stream that starts with `n`
and continues as the co-recursive call `Up(n + 1)`.

To ensure that co-recursive calls give rise to mathematically consistent definitions,
they must occur only in productive positions. This says that it must be possible to determine
each successive piece of a co-datatype value after a finite amount of work. This
condition is satisfied if every co-recursive call is syntactically guarded by a constructor
of a co-datatype, which is the criterion Dafny uses to classify intra-cluster calls as being
either co-recursive or recursive. Calls that are classified as co-recursive are exempt from
termination checks.

A consequence of the productivity checks and termination checks is that, even in the
absence of talking about least or greatest fix-points of self-calling functions, all functions
in Dafny are deterministic. Since there cannot be multiple fix-points,
the language allows one function to be involved in both recursive and co-recursive calls,
as we illustrate by the function `FivesUp`.

### 19.3.4. Greatest predicates {#sec-copredicates}
Determining properties of co-datatype values may require an infinite
number of observations. To that end, Dafny provides _greatest predicates_
which are function declarations that use the `greatest predicate` keyword phrase.
Self-calls to a greatest predicate need not terminate. Instead, the value
defined is the greatest fix-point of the given recurrence equations.
Continuing the preceding example, the following code defines a
greatest predicate that holds for exactly those streams whose payload consists
solely of positive integers. The greatest predicate definition implicitly also
gives rise to a corresponding prefix predicate, `Pos#`. The syntax for
calling a prefix predicate sets apart the argument that specifies the
prefix length, as shown in the last line; for this figure, we took the
liberty of making up a coordinating syntax for the signature of the
automatically generated prefix predicate (which is not part of
Dafny syntax).

<!-- %check-resolve %use Stream.tmp -->
```dafny
greatest predicate Pos[nat](s: Stream<int>)
{
  match s
  case SNil => true
  case SCons(x, rest) => x > 0 && Pos(rest)
}
``` <!-- %save Pos.tmp -->
The following code is automatically generated by the Dafny compiler:
<!-- %no-check -->
```dafny
predicate Pos#[_k: nat](s: Stream<int>)
  decreases _k
{ if _k == 0 then true else
  match s
  case SNil => true
  case SCons(x, rest) => x > 0 && Pos#[_k-1](rest)
}

Some restrictions apply. To guarantee that the greatest fix-point always exists, the (implicit functor defining the) greatest predicate must be monotonic. This is enforced by a syntactic restriction on the form of the body of greatest predicates: after conversion to negation normal form (i.e., pushing negations down to the atoms), intra-cluster calls of greatest predicates must appear only in positive positions—that is, they must appear as atoms and must not be negated. Additionally, to guarantee soundness later on, we require that they appear in continous positions—that is, in negation normal form, when they appear under existential quantification, the quantification needs to be limited to a finite range7. Since the evaluation of a greatest predicate might not terminate, greatest predicates are always ghost. There is also a restriction on the call graph that a cluster containing a greatest predicate must contain only greatest predicates, no other kinds of functions.

extreme predicates and lemmas, one in which _k has type nat and one in which it has type ORDINAL (the default). The continuous restriction applies only when _k is nat. Also, higher-order function support in Dafny is rather modest and typical reasoning patterns do not involve them, so this restriction is not as limiting as it would have been in, e.g., Coq.

A greatest predicate declaration of P defines not just a greatest predicate, but also a corresponding prefix predicate P#. A prefix predicate is a finite unrolling of a co-predicate. The prefix predicate is constructed from the co-predicate by

For example, for greatest predicate Pos, the definition of the prefix predicate Pos# is as suggested above. Syntactically, the prefix-length argument passed to a prefix predicate to indicate how many times to unroll the definition is written in square brackets, as in Pos#[k](s). In the Dafny grammar this is called a HashCall. The definition of Pos# is available only at clusters strictly higher than that of Pos; that is, Pos and Pos# must not be in the same cluster. In other words, the definition of Pos cannot depend on Pos#.

19.3.4.1. Co-Equality

Equality between two values of a co-datatype is a built-in co-predicate. It has the usual equality syntax s == t, and the corresponding prefix equality is written s ==#[k] t. And similarly for s != t and s !=#[k] t.

19.3.5. Coinductive Proofs

From what we have said so far, a program can make use of properties of co-datatypes. For example, a method that declares Pos(s) as a precondition can rely on the stream s containing only positive integers. In this section, we consider how such properties are established in the first place.

19.3.5.1. Properties About Prefix Predicates

Among other possible strategies for establishing coinductive properties we take the time-honored approach of reducing coinduction to induction. More precisely, Dafny passes to the SMT solver an assumption D(P) for every greatest predicate P, where:

D(P) = forall x • P(x) <==> forall k • P#[k](x)

In other words, a greatest predicate is true iff its corresponding prefix predicate is true for all finite unrollings.

In Sec. 4 of the paper [Co-induction Simply] a soundness theorem of such assumptions is given, provided the greatest predicates meet the continous restrictions. An example proof of Pos(Up(n)) for every n > 0 is shown here:

lemma UpPosLemma(n: int)
  requires n > 0
  ensures Pos(Up(n))
{
  forall k | 0 <= k { UpPosLemmaK(k, n); }
}

lemma UpPosLemmaK(k: nat, n: int)
  requires n > 0
  ensures Pos#[k](Up(n))
  decreases k
{
  if k != 0 {
    // this establishes Pos#[k-1](Up(n).tail)
    UpPosLemmaK(k-1, n+1);
  }
}

The lemma UpPosLemma proves Pos(Up(n)) for every n > 0. We first show Pos#[k](Up(n )), for n > 0 and an arbitrary k, and then use the forall statement to show forall k • Pos#[k](Up(n)). Finally, the axiom D(Pos) is used (automatically) to establish the greatest predicate.

19.3.5.2. Greatest lemmas

As we just showed, with help of the D axiom we can now prove a greatest predicate by inductively proving that the corresponding prefix predicate holds for all prefix lengths k. In this section, we introduce greatest lemma declarations, which bring about two benefits. The first benefit is that greatest lemmas are syntactic sugar and reduce the tedium of having to write explicit quantifications over k. The second benefit is that, in simple cases, the bodies of greatest lemmas can be understood as coinductive proofs directly. As an example consider the following greatest lemma.

greatest lemma UpPosLemma(n: int)
  requires n > 0
  ensures Pos(Up(n))
{
  UpPosLemma(n+1);
}

This greatest lemma can be understood as follows: UpPosLemma invokes itself co-recursively to obtain the proof for Pos(Up(n).tail) (since Up(n).tail equals Up(n+1)). The proof glue needed to then conclude Pos(Up(n)) is provided automatically, thanks to the power of the SMT-based verifier.

19.3.5.3. Prefix Lemmas

To understand why the above UpPosLemma greatest lemma code is a sound proof, let us now describe the details of the desugaring of greatest lemmas. In analogy to how a greatest predicate declaration defines both a greatest predicate and a prefix predicate, a greatest lemma declaration defines both a greatest lemma and prefix lemma. In the call graph, the cluster containing a greatest lemma must contain only greatest lemmas and prefix lemmas, no other methods or function. By decree, a greatest lemma and its corresponding prefix lemma are always placed in the same cluster. Both greatest lemmas and prefix lemmas are always ghost code.

The prefix lemma is constructed from the greatest lemma by

Note that this rewriting removes all co-recursive calls of greatest lemmas, replacing them with recursive calls to prefix lemmas. These recursive calls are, as usual, checked to be terminating. We allow the pre-declared identifier _k to appear in the original body of the greatest lemma.8

We can now think of the body of the greatest lemma as being replaced by a forall call, for every k , to the prefix lemma. By construction, this new body will establish the greatest lemma’s declared postcondition (on account of the D axiom, and remembering that only the positive continuous occurrences of greatest predicates in the greatest lemma’s postcondition are rewritten), so there is no reason for the program verifier to check it.

The actual desugaring of our greatest lemma UpPosLemma is in fact the previous code for the UpPosLemma lemma except that UpPosLemmaK is named UpPosLemma# and modulo a minor syntactic difference in how the k argument is passed.

In the recursive call of the prefix lemma, there is a proof obligation that the prefixlength argument _k - 1 is a natural number. Conveniently, this follows from the fact that the body has been wrapped in an if _k != 0 statement. This also means that the postcondition must hold trivially when _k == 0, or else a postcondition violation will be reported. This is an appropriate design for our desugaring, because greatest lemmas are expected to be used to establish greatest predicates, whose corresponding prefix predicates hold trivially when _k = 0. (To prove other predicates, use an ordinary lemma, not a greatest lemma.)

It is interesting to compare the intuitive understanding of the coinductive proof in using a greatest lemma with the inductive proof in using a lemma. Whereas the inductive proof is performing proofs for deeper and deeper equalities, the greatest lemma can be understood as producing the infinite proof on demand.

20. Statements

Stmt = { "label" LabelName ":" } NonLabeledStmt
NonLabeledStmt =
  ( AssertStmt | AssumeStmt | BlockStmt | BreakStmt
  | CalcStmt | ExpectStmt | ForallStmt | IfStmt
  | MatchStmt | ModifyStmt
  | PrintStmt | ReturnStmt | RevealStmt
  | UpdateStmt | UpdateFailureStmt
  | VarDeclStatement | WhileStmt | ForLoopStmt | YieldStmt
  )

Many of Dafny’s statements are similar to those in traditional programming languages, but a number of them are significantly different. This grammar production shows the different kinds of Dafny statements. They are described in subsequent sections.

Statements typically end with either a semicolon (;) or a closing curly brace (‘}’).

20.1. Labeled Statement

Stmt = { "label" LabelName ":" } NonLabeledStmt

A labeled statement is just the keyword label followed by an identifier which is the label, followed by a colon and a statement. The label may be referenced in a break or continue statement within the labeled statement (see Section 20.2). That is, the break or continue that mentions the label must be enclosed in the labeled statement. The label may also be used in an old expression (Section 21.25). In this case, the label must have been encountered during the control flow en route to the old expression. We say in this case that the (program point of the) label dominates the (program point of the) use of the label.

A statement can be given several labels. It makes no difference which of these labels is used to reference the statement—they are synonyms of each other. The labels must be distinct from each other, and are not allowed to be the same as any previous enclosing or dominating label.

20.2. Break and Continue Statements

BreakStmt =
  ( "break" LabelName ";"
  | "continue" LabelName ";"
  | { "break" } "break" ";"
  | { "break" } "continue" ";"
  )

Break and continue statements provide a means to transfer control in a way different than the usual nested control structures. There are two forms of each of these statements: with and without a label.

If a label is used, the break or continue statement must be enclosed in a statement with that label. The enclosing statement is called the target of the break or continue.

A break statement transfers control to the point immediately following the target statement. For example, such a break statement can be used to exit a sequence of statements in a block statement before reaching the end of the block.

For example, 

label L: {
  var n := ReadNext();
  if n < 0 {
    break L;
  }
  DoSomething(n);
}

is equivalent to 

{
  var n := ReadNext();
  if 0 <= n {
    DoSomething(n);
  }
}

If no label is specified and the statement lists n occurrences of break, then the statement must be enclosed in at least n levels of loop statements. Control continues after exiting n enclosing loops. For example,

method m() {
  for i := 0 to 10 {
    for j := 0 to 10 {
      label X: {
        for k := 0 to 10 {
          if j + k == 15 {
            break break;
          }
        }
      }
    }
    // control continues here after the "break break", exiting two loops
  }
}

Note that a non-labeled break pays attention only to loop, not to labeled statements. For example, the labeled block X in the previous example does not play a role in determining the target statement of the break break;.

For a continue statement, the target statement must be a loop statement. The continue statement transfers control to the point immediately before the closing curly-brace of the loop body.

For example, 

method m() {
  for i := 0 to 100 {
    if i == 17 {
      continue;
    }
    DoSomething(i);
  }
}
method DoSomething(i:int){}

is equivalent to 

method m() {
  for i := 0 to 100 {
    if i != 17 {
      DoSomething(i);
    }
  }
}
method DoSomething(i:int){}

The same effect can also be obtained by wrapping the loop body in a labeled block statement and then using break with a label, but that usually makes for a more cluttered program: 

method m() {
  for i := 0 to 100 {
    label LoopBody: {
      if i == 17 {
        break LoopBody;
      }
      DoSomething(i);
    }
  }
}
method DoSomething(i:int){}

Stated differently, continue has the effect of ending the current loop iteration, after which control continues with any remaining iterations. This is most natural for for loops. For a while loop, be careful to make progress toward termination before a continue statement. For example, the following program snippet shows an easy mistake to make (the verifier will complain that the loop may not terminate):

method m() {
  var i := 0;
  while i < 100 {
    if i == 17 {
      continue; // error: this would cause an infinite loop
    }
    DoSomething(i);
    i := i + 1;
  }
}
method DoSomething(i:int){}

The continue statement can give a label, provided the label is a label of a loop. For example,

method m() {
  label Outer:
  for i := 0 to 100 {
    for j := 0 to 100 {
      if i + j == 19 {
        continue Outer;
      }
      WorkIt(i, j);
    }
    PostProcess(i);
    // the "continue Outer" statement above transfers control to here
  }
}
method WorkIt(i:int, j:int){}
method PostProcess(i:int){}

If a non-labeled continue statement lists n occurrences of break before the continue keyword, then the statement must be enclosed in at least n + 1 levels of loop statements. The effect is to break out of the n most closely enclosing loops and then continue the iterations of the next loop. That is, n occurrences of break followed by one more break; will break out of n levels of loops and then do a break, whereas n occurrences of break followed by continue; will break out of n levels of loops and then do a continue.

For example, the WorkIt example above can equivalently be written without labels as 

method m() {
  for i := 0 to 100 {
    for j := 0 to 100 {
      if i + j == 19 {
        break continue;
      }
      WorkIt(i, j);
    }
    PostProcess(i);
    // the "break continue" statement above transfers control to here
  }
}
method WorkIt(i:int, j:int){}
method PostProcess(i:int){}

Note that a loop invariant is checked on entry to a loop and at the closing curly-brace of the loop body. It is not checked at break statements. It also isn’t checked at continue statements per se, but the loop invariant is checked as usual at the closing curly-brace that the continue statement jumps to. This checking ensures that the loop invariant holds at the very top of every iteration. Commonly, the only exit out of a loop happens when the loop guard evaluates to false. Since no state is changed between the top of an iteration (where the loop invariant is known to hold) and the evaluation of the loop guard, one can also rely on the loop invariant to hold immediately following the loop. But the loop invariant may not hold immediately following a loop if a loop iteration changes the program state and then exits the loop with a break statement.

For example, the following program verifies: 

method m() {
  var i := 0;
  while i < 10
    invariant 0 <= i <= 10
  {
    if P(i) {
      i := i + 200;
      break;
    }
    i := i + 1;
  }
  assert i == 10 || 200 <= i < 210;
}
predicate method P(i:int)

To explain the example, the loop invariant 0 <= i <= 10 is known to hold at the very top of each iteration, that is, just before the loop guard i < 10 is evaluated. If the loop guard evaluates to false, then the negated guard condition (10 <= i) and the invariant hold, so i == 10 will hold immediately after the loop. If the loop guard evaluates to true (that is, i < 10 holds), then the loop body is entered. If the test P(i) then evaluates to true, the loop adds 200 to i and breaks out of the loop, so on such a path, 200 <= i < 210 is known to hold immediately after the loop. This is summarized in the assert statement in the example. So, remember, a loop invariant holds at the very top of every iteration, not necessarily immediately after the loop.

20.3. Block Statement

BlockStmt = "{" { Stmt } "}"

A block statement is just a sequence of statements enclosed by curly braces. Local variables declared in the block end their scope at the end of the block.

20.4. Return Statement

ReturnStmt = "return" [ Rhs { "," Rhs } ] ";"

A return statement can only be used in a method. It is used to terminate the execution of the method.

To return a value from a method, the value is assigned to one of the named out-parameters sometime before a return statement. In fact, the out-parameters act very much like local variables, and can be assigned to more than once. Return statements are used when one wants to return before reaching the end of the body block of the method.

Return statements can be just the return keyword (where the current values of the out-parameters are used), or they can take a list of expressions to return. If a list is given, the number of expressions given must be the same as the number of named out-parameters. These expressions are evaluated, then they are assigned to the out-parameters, and then the method terminates.

20.5. Yield Statement

YieldStmt = "yield" [ Rhs { "," Rhs } ] ";"

A yield statement can only be used in an iterator. See Section 16 for more details about iterators.

The body of an iterator is a co-routine. It is used to yield control to its caller, signaling that a new set of values for the iterator’s yield (out-)parameters (if any) are available. Values are assigned to the yield parameters at or before a yield statement. In fact, the yield parameters act very much like local variables, and can be assigned to more than once. Yield statements are used when one wants to return new yield parameter values to the caller. Yield statements can be just the yield keyword (where the current values of the yield parameters are used), or they can take a list of expressions to yield. If a list is given, the number of expressions given must be the same as the number of named iterator out-parameters. These expressions are then evaluated, then they are assigned to the yield parameters, and then the iterator yields.

20.6. Update and Call Statements

UpdateStmt =
    Lhs
    ( {Attribute} ";"
    |
     { "," Lhs }
     ( ":=" Rhs { "," Rhs }
     | ":|" [ "assume" ]
               Expression(allowLemma: false, allowLambda: true)
     )
     ";"
    )

If more than one left-hand side is used, these must denote different l-values, unless the corresponding right-hand sides also denote the same value.

The update statement serves several logical purposes.

1) The form

Lhs {Attribute} ";"

is assumed to be a call to a method with no out-parameters.

2) The form

    Lhs { , Lhs } ":=" Rhs ";"

can occur in the UpdateStmt grammar when there is a single Rhs that takes the special form of a Lhs that is a call. This is the only case where the number of left-hand sides can be different than the number of right-hand sides in the UpdateStmt. In that case the number of left-hand sides must match the number of out-parameters of the method that is called or there must be just one Lhs to the left of the :=, which then is assigned a tuple of the out-parameters. Note that the result of a method call is not allowed to be used as an argument of another method call, as if it were an expression.

3) This is the typical parallel-assignment form, in which no call is involved:

    Lhs { , Lhs } ":=" Rhs { "," Rhs } ";"

This UpdateStmt is a parallel assignment of right-hand-side values to the left-hand sides. For example, x,y := y,x swaps the values of x and y. If more than one left-hand side is used, these must denote different l-values, unless the corresponding right-hand sides also denote the same value. There must be an equal number of left-hand sides and right-hand sides in this case. Of course, the most common case will have only one Rhs and one Lhs.

4) The form

  Lhs { "," Lhs } :| [ "assume" ] Expression<false,false>

using “:|” assigns some values to the left-hand side variables such that the boolean expression on the right hand side is satisfied. This can be used to make a choice as in the following example where we choose an element in a set. The given boolean expression need not constrain the LHS values uniquely.

method Sum(X: set<int>) returns (s: int)
{
  s := 0; var Y := X;
  while Y != {}
    decreases Y
  {
    var y: int;
    y :| y in Y;
    s, Y := s + y, Y - {y};
  }
}

Dafny will report an error if it cannot prove that values exist that satisfy the condition.

In addition, as the choice is arbitrary, assignment statements using :| may be non-deterministic when executed.

Note that the form

    Lhs ":"

is diagnosed as a label in which the user forgot the label keyword.

20.7. Update with Failure Statement (:-)

UpdateFailureStmt  =
    [ Lhs { "," Lhs } ]
    ":-"
    [ "expect"  | "assert" | "assume" ]
    Expression(allowLemma: false, allowLambda: false)
    { "," Rhs }
    ";"

A :-9 statement is an alternate form of the := statement that allows for abrupt return if a failure is detected. This is a language feature somewhat analogous to exceptions in other languages.

An update-with-failure statement uses failure-compatible types. A failure-compatible type is a type that has the following members (each with no in-parameters and one out-parameter):

A failure-compatible type with an Extract member is called value-carrying.

To use this form of update,

The following subsections show various uses and alternatives.

20.7.1. Failure compatible types

A simple failure-compatible type is the following: 

datatype Status =
| Success
| Failure(error: string)
{
  predicate method IsFailure() { this.Failure?  }
  function method PropagateFailure(): Status
    requires IsFailure()
  {
    Failure(this.error)
  }
}
``` <!-- %save Status.tmp -->

A commonly used alternative that carries some value information is something like this generic type:
<!-- %check-resolve -->
```dafny
datatype Outcome<T> =
| Success(value: T)
| Failure(error: string)
{
  predicate method IsFailure() {
    this.Failure?
  }
  function method PropagateFailure<U>(): Outcome<U>
    requires IsFailure()
  {
    Failure(this.error) // this is Outcome<U>.Failure(...)
  }
  function method Extract(): T
    requires !IsFailure()
  {
    this.value
  }
}
``` <!-- %save Outcome.tmp -->


### 20.7.2. Simple status return with no other outputs

The simplest use of this failure-return style of programming is to have a method call that just returns a non-value-carrying `Status` value:
<!-- %check-resolve %use Status.tmp -->
```dafny
method Callee(i: int) returns (r: Status)
{
  if i < 0 { return Failure("negative"); }
  return Success;
}

method Caller(i: int) returns (rr: Status)
{
  :- Callee(i);
  ...
}

Note that there is no LHS to the :- statement. If Callee returns Failure, then the caller immediately returns, not executing any statements following the call of Callee. The value returned by Caller (the value of rr in the code above) is the result of PropagateFailure applied to the value returned by Callee, which is often just the same value. If Callee does not return Failure (that is, returns a value for which IsFailure() is false) then that return value is forgotten and execution proceeds normally with the statements following the call of Callee in the body of Caller.

The desugaring of the :- Callee(i); statement is 

var tmp;
tmp := Callee(i);
if tmp.IsFailure() {
  rr := tmp.PropagateFailure();
  return;
}

In this and subsequent examples of desugaring, the tmp variable is a new, unique variable, unused elsewhere in the calling member.

20.7.3. Status return with additional outputs

The example in the previous subsection affects the program only through side effects or the status return itself. It may well be convenient to have additional out-parameters, as is allowed for := updates; these out-parameters behave just as for :=. Here is an example:

method Callee(i: int) returns (r: Status, v: int, w: int)
{
  if i < 0 { return Failure("negative"), 0, 0; }
  return Success, i+i, i*i;
}

method Caller(i: int) returns (rr: Status, k: int)
{
  var j: int;
  j, k :- Callee(i);
  k := k + k;
  ...
}

Here Callee has two outputs in addition to the Status output. The LHS of the :- statement accordingly has two l-values to receive those outputs. The recipients of those outputs may be any sort of l-values; here they are a local variable and an out-parameter of the caller. Those outputs are assigned in the :- call regardless of the Status value:

The desugaring of the j, k :- Callee(i); statement is 

var tmp;
tmp, j, k := Callee(i);
if tmp.IsFailure() {
  rr := tmp.PropagateFailure();
  return;
}

20.7.4. Failure-returns with additional data

The failure-compatible return value can carry additional data as shown in the Outcome<T> example above. In this case there is a (first) LHS l-value to receive this additional data.

method Callee(i: int) returns (r: Outcome<nat>, v: int)
{
  if i < 0 { return Failure("negative"), i+i; }
  return Success(i), i+i;
}

method Caller(i: int) returns (rr: Outcome<int>, k: int)
{
  var j: int;
  j, k :- Callee(i);
  k := k + k;
  ...
}

Suppose Caller is called with an argument of 10. Then Callee is called with argument 10 and returns r and v of Outcome<nat>.Success(10) and 20. Here r.IsFailure() is false, so control proceeds normally. The j is assigned the result of r.Extract(), which will be 10, and k is assigned 20. Control flow proceeds to the next line, where k now gets the value 40.

Suppose instead that Caller is called with an argument of -1. Then Callee is called with the value -1 and returns r and v with values Outcome<nat>.Failure("negative") and -2. k is assigned the value of v (-2). But r.IsFailure() is true, so control proceeds directly to return from Caller. The first out-parameter of Caller (rr) gets the value of r.PropagateFailure(), which is Outcome<int>.Failure("negative"); k already has the value -2. The rest of the body of Caller is skipped. In this example, the first out-parameter of Caller has a failure-compatible type so the exceptional return will propagate up the call stack. It will keep propagating up the call stack as long as there are callers with this first special output type and calls that use :- and the return value keeps having IsFailure() true.

The desugaring of the j, k :- Callee(i); statement in this example is 

var tmp;
tmp, k := Callee(i);
if tmp.IsFailure() {
  rr := tmp.PropagateFailure();
  return;
}
j := tmp.Extract();

20.7.5. RHS with expression list

Instead of a failure-returning method call on the RHS of the statement, the RHS can instead be a list of expressions. As for a := statement, in this form, the expressions on the left and right sides of :- must correspond, just omitting a LHS l-value for the first RHS expression if its type is not value-carrying. The semantics is very similar to that in the previous subsection.

A RHS with a method call cannot be mixed with a RHS containing multiple expressions.

For example, the desugaring of 

method m(r: Status) returns (rr: Status) {
  var k;
  k :- r, 7;
  ...
}

is 

var k;
var tmp;
tmp, k := r, 7;
if tmp.IsFailure() {
  rr := tmp.PropagateFailure();
  return;
}

20.7.6. Failure with initialized declaration.

The :- syntax can also be used in initialization, as in 

var s :- M();

This is equivalent to 

var s;
s :- M();

with the semantics as described above.

20.7.7. Keyword alternative

In any of the above described uses of :-, the :- token may be followed immediately by the keyword expect, assert or assume.

In each of these cases, there is no abrupt return from the caller. Thus there is no evaluation of PropagateFailure. Consequently the first out-parameter of the caller need not match the return type of PropagateFailure; indeed, the failure-compatible type returned by the callee need not have a PropagateFailure member.

The equivalent desugaring replaces 

if tmp.IsFailure() {
  rr := tmp.PropagateFailure();
  return;
}

with 

expect !tmp.IsFailure(), tmp;

or 

assert !tmp.IsFailure();

or 

assume !tmp.IsFailure();

There is a grammatical nuance that the user should be aware of. The keywords assert, assume, and expect can start an expression. For example, assert P; E can be an expression. However, in e :- assert P; E; the assert is parsed as the keyword associated with :-. To have the assert considered part of the expression use parentheses: e :- (assert P; E);.

20.7.8. Key points

There are several points to note.

It is important to note the connection between the failure-compatible types used in the caller and callee, if they both use them. They do not have to be the same type, but they must be closely related, as it must be possible for the callee’s PropagateFailure to return a value of the caller’s failure-compatible type. In practice this means that one such failure-compatible type should be used for an entire program. If a Dafny program uses a library shared by multiple programs, the library should supply such a type and it should be used by all the client programs (and, effectively, all Dafny libraries). It is also the case that it is inconvenient to mix types such as Outcome and Status above within the same program. If there is a mix of failure-compatible types, then the program will need to use := statements and code for explicit handling of failure values.

20.7.9. Failure returns and exceptions

The :- mechanism is like the exceptions used in other programming languages, with some similarities and differences.

20.8. Variable Declaration Statement

VarDeclStatement =
  [ "ghost" ] "var" { Attribute }
  (
    LocalIdentTypeOptional
    { "," { Attribute } LocalIdentTypeOptional }
    [ ":="
      Rhs { "," Rhs }
    | ":-"
      [ "expect" | "assert" | "assume" ]
      Expression(allowLemma: false, allowLambda: false)
      { "," Rhs }
    | { Attribute }
      ":|"
      [ "assume" ] Expression(allowLemma: false, allowLambda: true)
    ]
  |
    CasePatternLocal
    ( ":=" | { Attribute } ":|" )
    Expression(allowLemma: false, allowLambda: true)
  )
  ";"

CasePatternLocal = ( [ Ident ] "(" CasePatternLocsl { "," CasePatternLocal } ")"
                   | LocalIdentTypeOptional
                   )

A VarDeclStatement is used to declare one or more local variables in a method or function. The type of each local variable must be given unless its type can be inferred, either from a given initial value, or from other uses of the variable. If initial values are given, the number of values must match the number of variables declared.

The scope of the declared variable extends to the end of the block in which it is declared. However, be aware that if a simple variable declaration is followed by an expression (rather than a subsequent statement) then the var begins a Let Expression and the scope of the introduced variables is only to the end of the expression. In this case, though, the var is in an expression context, not a statement context.

Note that the type of each variable must be given individually. The following code

var x, y : int;

does not declare both x and y to be of type int. Rather it will give an error explaining that the type of x is underspecified if it cannot be inferred from uses of x.

What follows the LocalIdentTypeOptional optionally combines the variable declarations with an update statement (cf. Section 20.6). If the RHS is a call, then any variable receiving the value of a formal ghost out-parameter will automatically be declared as ghost, even if the ghost keyword is not part of the variable declaration statement.

The left-hand side can also contain a tuple of patterns that will be matched against the right-hand-side. For example:

function returnsTuple() : (int, int)
{
    (5, 10)
}

function usesTuple() : int
{
    var (x, y) := returnsTuple();
    x + y
}

The assignment with failure operator :- returns from the method if the value evaluates to a failure value of a failure-compatible type (see Section 20.7).

20.9. Guards

Guard = ( "*"
        | "(" "*" ")"
        | Expression(allowLemma: true, allowLambda: true)
        )

Guards are used in if and while statements as boolean expressions. Guards take two forms.

The first and most common form is just a boolean expression.

The second form is either * or (*). These have the same meaning. An unspecified boolean value is returned. The value returned may be different each time it is executed.

20.10. Binding Guards

BindingGuard(allowLambda) =
  IdentTypeOptional { "," IdentTypeOptional }
  { Attribute }
  ":|"
  Expression(allowLemma: true, allowLambda)

IfStmts can also take a BindingGuard. It checks if there exist values for the given variables that satisfy the given expression. If so, it binds some satisfying values to the variables and proceeds into the “then” branch; otherwise it proceeds with the “else” branch, where the bound variables are not in scope.

In other words, the statement

if x :| P { S } else { T }

has the same meaning as

if exists x :: P { var x :| P; S } else { T }

The identifiers bound by BindingGuard are ghost variables and cannot be assigned to non-ghost variables. They are only used in specification contexts.

Here is an example:

predicate P(n: int)
{
  n % 2 == 0
}

method M1() returns (ghost y: int)
    requires exists x :: P(x)
    ensures P(y)
{
  if x : int :| P(x) {
      y := x;
  }
}

20.11. If Statement

IfStmt = "if"
  ( AlternativeBlock(allowBindingGuards: true)
  |
    ( BindingGuard(allowLambda: true)
    | Guard
    )
    BlockStmt [ "else" ( IfStmt | BlockStmt ) ]
  )

AlternativeBlock(allowBindingGuards) =
  ( { AlternativeBlockCase(allowBindingGuards) }
  | "{" { AlternativeBlockCase(allowBindingGuards) } "}"
  )

AlternativeBlockCase(allowBindingGuards) =
      { "case"
      (
        BindingGuard(allowLambda: false) // permitted iff allowBindingGuards == true
      | Expression(allowLemma: true, allowLambda: false)
      ) "=>" { Stmt } } .

The simplest form of an if statement uses a guard that is a boolean expression. For example,

  if x < 0 {
    x := -x;
  }

Unlike match statements, if statements do not have to be exhaustive: omitting the else block is the same as including an empty else block. To ensure that an if statement is exhaustive, use the if-case statement documented below.

If the guard is an asterisk then a non-deterministic choice is made:

  if * {
    print "True";
  } else {
    print "False";
  }

The if-case statement using the AlternativeBlock form is similar to the if ... fi construct used in the book “A Discipline of Programming” by Edsger W. Dijkstra. It is used for a multi-branch if.

For example: 

method m(x: int, y: int) returns (max: int) 
{
  if {
    case x <= y => max := y;
    case y <= x => max := x;
  }
}

In this form, the expressions following the case keyword are called guards. The statement is evaluated by evaluating the guards in an undetermined order until one is found that is true and the statements to the right of => for that guard are executed. The statement requires at least one of the guards to evaluate to true (that is, if-case statements must be exhaustive: the guards must cover all cases).

The form that used ... (a refinement feature) as the guard is deprecated.

20.12. While Statement

WhileStmt =
  "while"
  ( LoopSpec
    AlternativeBlock(allowBindingGuards: false)
  | Guard
    LoopSpec
    ( BlockStmt
    | /* go body-less */
    )
  )

Loops need loop specifications (LoopSpec in the grammar) in order for Dafny to prove that they obey expected behavior. In some cases Dafny can infer the loop specifications by analyzing the code, so the loop specifications need not always be explicit. These specifications are described in Section 5.6 and Section 20.14.

The general loop statement in Dafny is the familiar while statement. It has two general forms.

The first form is similar to a while loop in a C-like language. For example:

method m(){
  var i := 0;
  while i < 5 {
    i := i + 1;
  }
}

In this form, the condition following the while is one of these:

method m(n: int){
  var r := n;
  while
    decreases if 0 <= r then r else -r;
  {
    case r < 0 =>
      r := r + 1;
    case 0 < r =>
      r := r - 1;
  }
}

For this form, the guards are evaluated in some undetermined order until one is found that is true, in which case the corresponding statements are executed and the while statement is repeated. If none of the guards evaluates to true, then the loop execution is terminated.

20.13. For Loops

ForLoopStmt =
  "for" IdentTypeOptional ":="
    Expression(allowLemma: false, allowLambda: false)
    ( "to" | "downto" )
    ( Expression(allowLemma: false, allowLambda: false)
    | "*"
    )
    LoopSpec
    ( BlockStmt
    | /* go body-less */
    )
  )

The for statement provides a convenient way to write some common loops.

The statement introduces a local variable IdentTypeOptional, which is called the loop index. The loop index is in scope in the LoopSpec and BlockStmt, but not after the for loop. Assignments to the loop index are not allowed. The type of the loop index can typically be inferred, so it need not be given explicitly. If the identifier is not used, it can be written as _, as illustrated in this repeat-20-times loop: 

for _ := 0 to 20 {
  Body
}

There are four basic variations of the for loop: 

for i: T := lo to hi
  LoopSpec
{ Body }

for i: T := hi downto lo
  LoopSpec
{ Body }

for i: T := lo to *
  LoopSpec
{ Body }

for i: T := hi downto *
  LoopSpec
{ Body }

Semantically, they are defined as the following respective while loops: 

{
  var _lo, _hi := lo, hi;
  assert _lo <= _hi && forall _i: int :: _lo <= _i <= _hi ==> _i is T;
  var i := _lo;
  while i != _hi
    invariant _lo <= i <= _hi
    LoopSpec
    decreases _hi - i
  {
    Body
    i := i + 1;
  }
}

{
  var _lo, _hi := lo, hi;
  assert _lo <= _hi && forall _i: int :: _lo <= _i <= _hi ==> _i is T;
  var i := _hi;
  while i != lo
    invariant _lo <= i <= _hi
    LoopSpec
    decreases i - _lo
  {
    i := i - 1;
    Body
  }
}

{
  var _lo := lo;
  assert forall _i: int :: _lo <= _i ==> _i is T;
  var i := _lo;
  while true
    invariant _lo <= i
    LoopSpec
  {
    Body
    i := i + 1;
  }
}

{
  var _hi := hi;
  assert forall _i: int :: _i <= _hi ==> _i is T;
  var i := _hi;
  while true
    invariant i <= _hi
    LoopSpec
  {
    i := i - 1;
    Body
  }
}

Note that expressions lo and hi are evaluated just once, before the loop iterations start.

Also, note in all variations that the values of i in the body are the values from lo to, but not including, hi. This makes it convenient to write common loops, including these:

for i := 0 to a.Length {
  Process(a[i]);
}
for i := a.Length downto 0 {
  Process(a[i]);
}

Nevertheless, hi must be a legal value for the type of the index variable, since that is how the index variable is used in the invariant.

If the end-expression is not *, then no explicit decreases is allowed, since such a loop is already known to terminate. If the end-expression is *, then the absence of an explicit decreases clause makes it default to decreases *. So, if the end-expression is * and no explicit decreases clause is given, the loop is allowed only in methods that are declared with decreases *.

The directions to or downto are contextual keywords. That is, these two words are part of the syntax of the for loop, but they are not reserved keywords elsewhere.

Just like for while loops, the body of a for-loop may be omitted during verification. This suppresses attempts to check assertions (like invariants) that would occur at the end of the loop. Eventually, however a body must be provided; the compiler will not compile a method containing a body-less for-loop.

20.14. Loop Specifications

For some simple loops, such as those mentioned previously, Dafny can figure out what the loop is doing without more help. However, in general the user must provide more information in order to help Dafny prove the effect of the loop. This information is provided by a LoopSpec. A LoopSpec provides information about invariants, termination, and what the loop modifies. For additional tutorial information see [@KoenigLeino:MOD2011] or the online Dafny tutorial.

20.14.1. Loop invariants {sec-loop-invariants}

Loops present a problem for specification-based reasoning. There is no way to know in advance how many times the code will go around the loop and a tool cannot reason about every one of a possibly unbounded sequence of unrollings. In order to consider all paths through a program, specification-based program verification tools require loop invariants, which are another kind of annotation.

A loop invariant is an expression that holds just prior to the loop test, that is, upon entering a loop and after every execution of the loop body. It captures something that is invariant, i.e. does not change, about every step of the loop. Now, obviously we are going to want to change variables, etc. each time around the loop, or we wouldn’t need the loop. Like pre- and postconditions, an invariant is a property that is preserved for each execution of the loop, expressed using the same boolean expressions we have seen. For example,

var i := 0;
while i < n
  invariant 0 <= i
{
  i := i + 1;
}

When you specify an invariant, Dafny proves two things: the invariant holds upon entering the loop, and it is preserved by the loop. By preserved, we mean that assuming that the invariant holds at the beginning of the loop (just prior to the loop test), we must show that executing the loop body once makes the invariant hold again. Dafny can only know upon analyzing the loop body what the invariants say, in addition to the loop guard (the loop condition). Just as Dafny will not discover properties of a method on its own, it will not know that any but the most basic properties of a loop are preserved unless it is told via an invariant.

20.14.2. Loop termination

Dafny proves that code terminates, i.e. does not loop forever, by using decreases annotations. For many things, Dafny is able to guess the right annotations, but sometimes it needs to be made explicit. There are two places Dafny proves termination: loops and recursion. Both of these situations require either an explicit annotation or a correct guess by Dafny.

A decreases annotation, as its name suggests, gives Dafny an expression that decreases with every loop iteration or recursive call. There are two conditions that Dafny needs to verify when using a decreases expression:

That is, the expression must strictly decrease in a well-founded ordering (cf. Section 24.7).

Many times, an integral value (natural or plain integer) is the quantity that decreases, but other values can be used as well. In the case of integers, the bound is assumed to be zero. For each loop iteration the decreases expression at the end of the loop body must be strictly smaller than the value at the beginning of the loop body (after the loop test). For integers, the well-founded relation between x and X is x < X && 0 <= X. Thus if the decreases value (X) is negative at the loop test, it must exit the loop, since there is no permitted value for x to have at the end of the loop body.

For example, the following is a proper use of decreases on a loop:

method m(n: nat){
  var i := n;
  while 0 < i
    invariant 0 <= i
    decreases i
  {
    i := i - 1;
  }
}

Here Dafny has all the ingredients it needs to prove termination. The variable i becomes smaller each loop iteration, and is bounded below by zero. When i becomes 0, the lower bound of the well-founded order, control flow exits the loop.

This is fine, except the loop is backwards from most loops, which tend to count up instead of down. In this case, what decreases is not the counter itself, but rather the distance between the counter and the upper bound. A simple trick for dealing with this situation is given below:

method m(m: nat, n: int) {
  assume m <= n;
  var i := m;
  while i < n
    invariant 0 <= i <= n
    decreases n - i
  {
    i := i + 1;
  }
}

This is actually Dafny’s guess for this situation, as it sees i < n and assumes that n - i is the quantity that decreases. The upper bound of the loop invariant implies that 0 <= n – i, and gives Dafny a lower bound on the quantity. This also works when the bound n is not constant, such as in the binary search algorithm, where two quantities approach each other, and neither is fixed.

If the decreases clause of a loop specifies *, then no termination check will be performed. Use of this feature is sound only with respect to partial correctness.

20.14.3. Loop framing

The specification of a loop also includes framing, which says what the loop modifies. The loop frame includes both local variables and locations in the heap.

For local variables, the Dafny verifier performs a syntactic scan of the loop body to find every local variable or out-parameter that occurs as a left-hand side of an assignment. These variables are called syntactic assignment targets of the loop, or syntactic loop targets for short. Any local variable or out-parameter that is not a syntactic assignment target is known by the verifier to remain unchanged by the loop.

The heap may or may not be a syntactic loop target. It is when the loop body syntactically contains a statement that can modify a heap location. This includes calls to compiled methods, even if such a method has an empty modifies clause, since a compiled method is always allowed to allocate new objects and change their values in the heap.

If the heap is not a syntactic loop target, then the verifier knows the heap remains unchanged by the loop. If the heap is a syntactic loop target, then the loop’s effective modifies clause determines what is allowed to be modified by iterations of the loop body.

A loop can use modifies clauses to declare the effective modifies clause of the loop. If a loop does not explicitly declare any modifies clause, then the effective modifies clause of the loop is the effective modifies clause of the most tightly enclosing loop or, if there is no enclosing loop, the modifies clause of the enclosing method.

In most cases, there is no need to give an explicit modifies clause for a loop. The one case where it is sometimes needed is if a loop modifies less than is allowed by the enclosing method. Here are two simple methods that illustrate this case:

class Cell {
  var data: int
}

method M0(c: Cell, d: Cell)
  requires c != d
  modifies c, d
  ensures c.data == d.data == 100
{
  c.data, d.data := 100, 0;
  var i := 0;
  while i < 100
    invariant d.data == i
    // Needs "invariant c.data == 100" or "modifies d" to verify
  {
    d.data := d.data + 1;
    i := i + 1;
  }
}

method M1(c: Cell)
  modifies c
  ensures c.data == 100
{
  c.data := 100;
  var i := 0;
  while i < 100
    // Needs "invariant c.data == 100" or "modifies {}" to verify
  {
    var tmp := new Cell;
    tmp.data := i;
    i := i + 1;
  }
}

In M0, the effective modifies clause of the loop is modifies c, d. Therefore, the method’s postcondition c.data == 100 is not provable. To remedy the situation, the loop needs to be declared either with invariant c.data == 100 or with modifies d.

Similarly, the effective modifies clause of the loop in M1 is modifies c. Therefore, the method’s postcondition c.data == 100 is not provable. To remedy the situation, the loop needs to be declared either with invariant c.data == 100 or with modifies {}.

When a loop has an explicit modifies clause, there is, at the top of every iteration, a proof obligation that

20.14.4. Body-less methods, functions, loops, and aggregate statements

Methods (including lemmas), functions, loops, and forall statements are ordinarily declared with a body, that is, a curly-braces pair that contains (for methods, loops, and forall) a list of statements or (for a function) an expression. In each case, Dafny syntactically allows these constructs to be given without a body. This is to allow programmers to temporarily postpone the development of the implementation of the method, function, loop, or aggregate statement.

If a method has no body, there is no difference for callers of the method. Callers still reason about the call in terms of the method’s specification. But without a body, the verifier has no method implementation to check against the specification, so the verifier is silently happy. The compiler, on the other hand, will complain if it encounters a body-less method, because the compiler is supposed to generate code for the method, but it isn’t clever enough to do that by itself without a given method body. If the method implementation is provided by code written outside of Dafny, the method can be marked with an {:extern} annotation, in which case the compiler will no longer complain about the absence of a method body; the verifier will not object either, even though there is now no proof that the Dafny specifications are satisfied by the external implementation.

A lemma is a special kind of method. Callers are therefore unaffected by the absence of a body, and the verifier is silently happy with not having a proof to check against the lemma specification. Despite a lemma being ghost, it is still the compiler that checks for, and complains about, body-less lemmas. A body-less lemma is an unproven lemma, which is often known as an axiom. If you intend to use a lemma as an axiom, omit its body and add the attribute {:axiom}, which causes the compiler to suppress its complaint about the lack of a body.

Similarly, calls to a body-less function use only the specification of the function. The verifier is silently happy, but the compiler complains (whether or not the function is ghost). As for methods and lemmas, the {:extern} and {:axiom} attributes can be used to suppress the compiler’s complaint.

By supplying a body for a method or function, the verifier will in effect show the feasibility of the specification of the method or function. By supplying an {:extern} or {:axiom} attribute, you are taking that responsibility into your own hands. Common mistakes include forgetting to provide an appropriate modifies or reads clause in the specification, or forgetting that the results of functions in Dafny (unlike in most other languages) must be deterministic.

Just like methods and functions have two sides, callers and implementations, loops also have two sides. One side (analogous to callers) is the context that uses the loop. That context treats the loop in the same way regardless of whether or not the loop has a body. The other side is the loop body, that is, the implementation of each loop iteration. The verifier checks that the loop body maintains the loop invariant and that the iterations will eventually terminate, but if there is no loop body, the verifier is silently happy. This allows you to temporarily postpone the authoring of the loop body until after you’ve made sure that the loop specification is what you need in the context of the loop.

There is one thing that works differently for body-less loops than for loops with bodies. It is the computation of syntactic loop targets, which become part of the loop frame (see Section 20.14.3). For a body-less loop, the local variables computed as part of the loop frame are the mutable variables that occur free in the loop specification. The heap is considered a part of the loop frame if it is used for mutable fields in the loop specification or if the loop has an explicit modifies clause. The IDE will display the computed loop frame in hover text.

For example, consider

class Cell {
  var data: int
  const K: int
}

method BodylessLoop(n: nat, c: Cell)
  requires c.K == 8
  modifies c
{
  c.data := 5;
  var a, b := n, n;
  for i := 0 to n
    invariant c.K < 10
    invariant a <= n
    invariant c.data < 10
  assert a == n;
  assert b == n;
  assert c.data == 5;
}

The loop specification mentions local variable a, and thus a is considered part of the loop frame. Since what the loop invariant says about a is not strong enough to prove the assertion a == n that follows the loop, the verifier complains about that assertion.

Local variable b is not mentioned in the loop specification, and thus b is not included in the loop frame. Since in-parameter n is immutable, it is not included in the loop frame, either, despite being mentioned in the loop specification. For these reasons, the assertion b == n is provable after the loop.

Because the loop specification mentions the mutable field data, the heap becomes part of the loop frame. Since the loop invariant is not strong enough to prove the assertion c.data == 5 that follows the loop, the verifier complains about that assertion. On the other hand, had c.data < 10 not been mentioned in the loop specification, the assertion would be verified, since field K is then the only field mentioned in the loop specification and K is immutable.

Finally, the aggregate statement (forall) can also be given without a body. Such a statement claims that the given ensures clause holds true for all values of the bound variables that satisfy the given range constraint. If the statement has no body, the program is in effect omitting the proof, much like a body-less lemma is omitting the proof of the claim made by the lemma specification. As with the other body-less constructs above, the verifier is silently happy with a body-less forall statement, but the compiler will complain.

20.15. Match Statement

MatchStmt =
  "match"
  Expression(allowLemma: true, allowLambda: true)
  ( "{" { CaseStmt } "}"
  | { CaseStmt }
  )

CaseStmt = "case" ExtendedPattern "=>" { Stmt }

[ ExtendedPattern is defined in Section 21.33.]

The match statement is used to do case analysis on a value of an inductive or coinductive datatype (which includes the built-in tuple types), a base type, or newtype. The expression after the match keyword is called the selector. The expression is evaluated and then matched against each clause in order until a matching clause is found.

The process of matching the selector expression against the CaseBinding_s is the same as for match expressions and is described in Section 21.33.

The code below shows an example of a match statement.

datatype Tree = Empty | Node(left: Tree, data: int, right: Tree)

// Return the sum of the data in a tree.
method Sum(x: Tree) returns (r: int)
{
  match x {
    case Empty => r := 0;
    case Node(t1, d, t2) =>
      var v1 := Sum(t1);
      var v2 := Sum(t2);
      r := v1 + d + v2;
  }
}

Note that the Sum method is recursive yet has no decreases annotation. In this case it is not needed because Dafny is able to deduce that t1 and t2 are smaller (structurally) than x. If Tree had been coinductive this would not have been possible since x might have been infinite.

20.16. Assert Statement

AssertStmt =
    "assert"
    { Attribute }
    [ LabelName ":" ]
    Expression(allowLemma: false, allowLambda: true)
    ( ";"
    | "by" BlockStmt
    )

Assert statements are used to express logical proposition that are expected to be true. Dafny will attempt to prove that the assertion is true and give an error if the assertion cannot be proven. Once the assertion is proved, its truth may aid in proving subsequent deductions. Thus if Dafny is having a difficult time verifying a method, the user may help by inserting assertions that Dafny can prove, and whose truth may aid in the larger verification effort, much as lemmas might be used in mathematical proofs.

Assert statements are ignored by the compiler.

Using ... as the argument of the statement is deprecated.

In the by form of the assert statement, there is an additional block of statements that provide the Dafny verifier with additional proof steps. Those statements are often a sequence of lemmas, calc statements, reveal statements or other assert statements, combined with ghost control flow, ghost variable declarations and ghost update statements of variables declared in the by block. The intent is that those statements be evaluated in support of proving the assert statement. For that purpose, they could be simply inserted before the assert statement. But by using the by block, the statements in the block are discarded after the assertion is proved. As a result, the statements in the block do not clutter or confuse the solver in performing subsequent proofs of assertions later in the program. Furthermore, by isolating the statements in the by block their purpose – to assist in proving the given assertion – is manifest in the structure of the code.

Examples of this form of assert are given in the section of the reveal statement and in Different Styles of Proof

20.17. Assume Statement

AssumeStmt =
    "assume"
    { Attribute }
    ( Expression(allowLemma: false, allowLambda: true)
    )
    ";"

The assume statement lets the user specify a logical proposition that Dafny may assume to be true without proof. If in fact the proposition is not true this may lead to invalid conclusions.

An assume statement would ordinarily be used as part of a larger verification effort where verification of some other part of the program required the proposition. By using the assume statement the other verification can proceed. Then when that is completed the user would come back and replace the assume with assert.

An assume statement cannot be compiled. In fact, the compiler will complain if it finds an assume anywhere where it has not been replaced through a refinement step.

Using ... as the argument of the statement is deprecated.

20.18. Expect Statement

ExpectStmt =
    "expect"
    { Attribute }
    ( Expression(allowLemma: false, allowLambda: true)
    )
    [ "," Expression(allowLemma: false, allowLambda: true) ]
    ";"

The expect statement states a boolean expression that is (a) assumed to be true by the verifier and (b) checked to be true at run-time. That is, the compiler inserts into the run-time executable a check that the given expression is true; if the expression is false, then the execution of the program halts immediately. If a second argument is given, it may be a value of any type. That value is converted to a string (just like the print statement) and the string is included in the message emitted by the program when it halts; otherwise a default message is emitted.

Because the expect expression and optional second argument are compiled, they cannot be ghost expressions.

assume statements are ignored at run-time. The expect statement behaves like assume for the verifier, but also inserts a run-time check that the assumption is indeed correct (for the test cases used at run-time).

Here are a few use-cases for the expect statement.

A) To check the specifications of external methods.

Consider an external method Random that takes a nat as input and returns a nat value that is less than the input. Such a method could be specified as 

method {:extern} Random(n: nat) returns (r: nat)
  ensures r < n

But because there is no body for Random (only the external non-dafny implementation), it cannot be verified that Random actually satisfies this specification.

To mitigate this situation somewhat, we can define a wrapper function, Random', that calls Random but in which we can put some run-time checks: 

method {:extern} Random(n: nat) returns (r: nat)

method Random'(n: nat) returns (r: nat)
  ensures r < n
{
  r := Random(n);
  expect r < n;
}

Here we can verify that Random' satisfies its own specification, relying on the unverified specification of Random. But we are also checking at run-time that any input-output pairs for Random encountered during execution do satisfy the specification, as they are checked by the expect statement.

Note, in this example, two problems still remain. One problem is that the out-parameter of the extern Random has type nat, but there is no check that the value returned really is non-negative. It would be better to declare the out-parameter of Random to be int and to include 0 <= r in the condition checked by the expect statement in Random'. The other problem is that Random surely will need n to be strictly positive. This can be fixed by adding requires n != 0 to Random' and Random.

B) Run-time testing

Verification and run-time testing are complementary and both have their role in assuring that software does what is intended. Dafny can produce executables and these can be instrumented with unit tests. Annotating a method with the {:test} attribute indicates to the compiler that it should produce target code that is correspondingly annotated to mark the method as a unit test (e.g., an XUnit test) in the target language. Alternatively, the /runAllTests option will produce a main method that invokes all methods with the {:test} attribute, and hence does not depend on any testing framework in the target language. Within such methods one might use expect statements (as well as print statements) to insert checks that the target program is behaving as expected.

C) Compiler tests

If one wants to assure that compiled code is behaving at run-time consistently with the statically verified code, one can use paired assert/expect statements with the same expression: 

assert _P_;
expect _P_;

The verifier will check that P is always true at the given point in a program (at the assert statement).

At run-time, the compiler will insert checks that the same predicate, in the expect statement, is true. Any difference identifies a compiler bug. Note that the expect must be after the assert. If the expect is first, then the verifier will interpret the expect like an assume, in which case the assert will be proved trivially and potential unsoundness will be hidden.

Using ... as the argument of the statement is deprecated.

20.19. Print Statement

PrintStmt =
    "print"
    Expression(allowLemma: false, allowLambda: true)
    { "," Expression(allowLemma: false, allowLambda: true) }
    ";"

The print statement is used to print the values of a comma-separated list of expressions to the console. The generated code uses target-language-specific idioms to perform this printing. The expressions may of course include strings that are used for captions. There is no implicit new line added, so to add a new line you should include "\n" as part of one of the expressions. Dafny automatically creates implementations of methods that convert values to strings for all Dafny data types. For example,

datatype Tree = Empty | Node(left: Tree, data: int, right: Tree)
method Main()
{
  var x : Tree := Node(Node(Empty, 1, Empty), 2, Empty);
  print "x=", x, "\n";
}

produces this output:

x=Tree.Node(Tree.Node(Tree.Empty, 1, Tree.Empty), 2, Tree.Empty)

Note that Dafny does not have method overriding and there is no mechanism to override the built-in value->string conversion. Nor is there a way to explicitly invoke this conversion. One can always write an explicit function to convert a data value to a string and then call it explicitly in a print statement or elsewhere.

By default, Dafny does not keep track of print effects, but this can be changed using the -trackPrintEffects command line flag. print statements are allowed only in non-ghost contexts and not in expressions, with one exception. The exception is that a function-by-method may contain print statements, whose effect may be observed as part of the run-time evaluation of such functions.

The verifier checks that each expression is well-defined, but otherwise ignores the print statement.

Note: print writes to standard output. To improve compatibility with native code and external libraries, the process of encoding Dafny strings passed to print into standard-output byte strings is left to the runtime of the language that the Dafny code is compiled to (some language runtimes use UTF-8 in all cases; others obey the current locale or console encoding).

In most cases, the standard-output encoding can be set before running the compiled program using language-specific flags or environment variables (e.g. -Dfile.encoding= for Java). This is in fact how dafny run operates: it uses language-specific flags and variables to enforce UTF-8 output regardless of the target language (but note that the C++ and Go backends currently have limited support for UTF-16 surrogates).

20.20. Reveal Statement

RevealStmt =
    "reveal"
    Expression(allowLemma: false, allowLambda: true)
    { "," Expression(allowLemma: false, allowLambda: true) }
    ";"

The reveal statement makes available to the solver information that is otherwise not visible, as described in the following subsections.

20.20.1. Revealing assertions

If an assert statement has an expression label, then a proof of that assertion is attempted, but the assertion itself is not used subsequently. For example, consider 

method m(i: int) {
  assert x: i == 0; // Fails
  assert i == 0; // Fails also because the x: makes the first assertion opaque
}

The first assertion fails. Without the label x:, the second would succeed because after a failing assertion, the assertion is assumed in the context of the rest of the program. But with the label, the first assertion is hidden from the rest of the program. That assertion can be revealed by adding a reveal statement:

method m(i: int) {
  assert x: i == 0; // Fails
  reveal x;
  assert i == 0; // Now succeeds
}

or 

method m(i: int) {
  assert x: i == 0; // Fails
  assert i == 0 by { reveal x; } // Now succeeds
}

At the point of the reveal statement, the labeled assertion is made visible and can be used in proving the second assertion. In this example there is no point to labeling an assertion and then immediately revealing it. More useful are the cases where the reveal is in an assert-by block or much later in the method body.

20.20.2. Revealing preconditions

In the same way as assertions, preconditions can be labeled. Within the body of a method, a precondition is an assumption; if the precondition is labeled then that assumption is not visible in the body of the method. A reveal statement naming the label of the precondition then makes the assumption visible.

Here is a toy example: 

method m(x: int, y: int) returns (z: int)
  requires L: 0 < y
  ensures z == x+y
  ensures x < z
{
  z := x + y;
}

The above method will not verify. In particular, the second postcondition cannot be proved. However, if we add a reveal L; statement in the body of the method, then the precondition is visible and both postconditions can be proved.

One could also use this style: 

method m(x: int, y: int) returns (z: int)
  requires L: 0 < y
  ensures z == x+y
  ensures x < z
{
  z := x + y;
  assert x < z by { reveal L; }
}

The reason to possibly hide a precondition is the same as the reason to hide assertions: sometimes less information is better for the solver as it helps the solver focus attention on relevant information.

Section 7 of http://leino.science/papers/krml276.html provides an extended illustration of this technique to make all the dependencies of an assert explicit.

20.20.3. Revealing function bodies

Normally function bodies are transparent and available for constructing proofs of assertions that use those functions. However, sometimes it is helpful to mark a function {:opaque} and treat it as an uninterpreted function, whose properties are just its specifications. This action limits the information available to the logical reasoning engine and may make a proof possible where there might be information overload otherwise.

But then there may be specific instances where the definition of that opaque function is needed. In that situation, the body of the function can be revealed using the reveal statement. Here is an example: 

function {:opaque} f(i: int): int { i + 1 }

method m(i: int) {
  assert f(i) == i + 1;
}

Without the {:opaque} attribute, the assertion is valid; with the attribute it cannot be proved because the body if the function is not visible. However if a reveal f(); statement is inserted before the assertion, the proof succeeds. Note that the pseudo-function-call in the reveal statement is written without arguments.

20.21. Forall Statement

ForallStmt =
  "forall"
  ( "(" [ QuantifierDomain ] ")"
  | [ QuantifierDomain ]
  )
  { EnsuresClause(allowLambda: true) }
  [ BlockStmt ]

The forall statement executes the body simultaneously for all quantified values in the specified quantifier domain. See Section 2.6.5 for more details on quantifier domains.

There are several variant uses of the forall statement and there are a number of restrictions. In particular, a forall statement can be classified as one of the following:

An assign forall statement performs simultaneous assignment. The left-hand sides must denote different l-values, unless the corresponding right-hand sides also coincide.

The following is an excerpt of an example given by Leino in Developing Verified Programs with Dafny. When the buffer holding the queue needs to be resized, the forall statement is used to simultaneously copy the old contents into the new buffer.

class SimpleQueue<Data(0)>
{
  ghost var Contents: seq<Data>;
  var a: array<Data>  // Buffer holding contents of queue.
  var m: int          // Index head of queue.
  var n: int          // Index just past end of queue
   
  method Enqueue(d: Data)
    requires a.Length > 0;
    requires 0 <= m <= n <= a.Length;
    modifies this, this.a;
    ensures Contents == old(Contents) + [d]
  {
    if n == a.Length {
      var b := a;
      if m == 0 { b := new Data[2 * a.Length]; }
      forall i | 0 <= i < n - m {
      	b[i] := a[m + i];
      }
      a, m, n := b, 0, n - m;
    }
    a[n], n, Contents := d, n + 1, Contents + [d];
  }
}

Here is an example of a call forall statement and the callee. This is contained in the CloudMake-ConsistentBuilds.dfy test in the Dafny repository.

method m() {
  forall cmd', deps', e' |
       Hash(Loc(cmd', deps', e')) == Hash(Loc(cmd, deps, e)) {
    HashProperty(cmd', deps', e', cmd, deps, e);
  }
}

lemma HashProperty(cmd: Expression, deps: Expression, ext: string,
    cmd': Expression, deps': Expression, ext': string)
  requires Hash(Loc(cmd, deps, ext)) == Hash(Loc(cmd', deps', ext'))
  ensures cmd == cmd' && deps == deps' && ext == ext'

The following example of a proof forall statement comes from the same file:

forall p | p in DomSt(stCombinedC.st) && p in DomSt(stExecC.st)
  ensures GetSt(p, stCombinedC.st) == GetSt(p, stExecC.st)
{
  assert DomSt(stCombinedC.st) <= DomSt(stExecC.st);
  assert stCombinedC.st == Restrict(DomSt(stCombinedC.st),
                                               stExecC.st);
}

More generally, the statement 

forall x | P(x) { Lemma(x); }

is used to invoke Lemma(x) on all x for which P(x) holds. If Lemma(x) ensures Q(x), then the forall statement establishes 

forall x :: P(x) ==> Q(x).

The forall statement is also used extensively in the de-sugared forms of co-predicates and co-lemmas. See datatypes.

20.22. Modify Statement

ModifyStmt =
  "modify"
  { Attribute }
  FrameExpression(allowLemma: false, allowLambda: true)
  { "," FrameExpression(allowLemma: false, allowLambda: true) }
  ";"

The effect of the modify statement is to say that some undetermined modifications have been made to any or all of the memory locations specified by the frame expressions. In the following example, a value is assigned to field x followed by a modify statement that may modify any field in the object. After that we can no longer prove that the field x still has the value we assigned to it.

class MyClass {
  var x: int
  method N()
    modifies this
  {
    x := 18;
    modify this;
    assert x == 18;  // error: cannot conclude this here
  }
}

Using ... as the argument of the statement is deprecated.

The form of the modify statement which includes a block statement is also deprecated.

20.23. Calc Statement

CalcStmt = "calc" { Attribute } [ CalcOp ] "{" CalcBody_ "}"

CalcBody_ = { CalcLine_ [ CalcOp ] Hints_ }

CalcLine_ = Expression(allowLemma: false, allowLambda: true) ";"

Hints_ = { ( BlockStmt | CalcStmt ) }

CalcOp =
  ( "==" [ "#" "["
           Expression(allowLemma: true, allowLambda: true) "]" ]
  | "<" | ">"
  | "!=" | "<=" | ">="
  | "<==>" | "==>" | "<=="
  )

The calc statement supports calculational proofs using a language feature called program-oriented calculations (poC). This feature was introduced and explained in the [Verified Calculations] paper by Leino and Polikarpova[@LEINO:Dafny:Calc]. Please see that paper for a more complete explanation of the calc statement. We here mention only the highlights.

Calculational proofs are proofs by stepwise formula manipulation as is taught in elementary algebra. The typical example is to prove an equality by starting with a left-hand-side and through a series of transformations morph it into the desired right-hand-side.

Non-syntactic rules further restrict hints to only ghost and side-effect free statements, as well as imposing a constraint that only chain-compatible operators can be used together in a calculation. The notion of chain-compatibility is quite intuitive for the operators supported by poC; for example, it is clear that “<” and “>” cannot be used within the same calculation, as there would be no relation to conclude between the first and the last line. See the paper for a more formal treatment of chain-compatibility.

Note that we allow a single occurrence of the intransitive operator “!=” to appear in a chain of equalities (that is, “!=” is chain-compatible with equality but not with any other operator, including itself). Calculations with fewer than two lines are allowed, but have no effect. If a step operator is omitted, it defaults to the calculation-wide operator, defined after the calc keyword. If that operator is omitted, it defaults to equality.

Here is an example using calc statements to prove an elementary algebraic identity. As it turns out, Dafny is able to prove this without the calc statements, but the example illustrates the syntax.

lemma docalc(x : int, y: int)
  ensures (x + y) * (x + y) == x * x + 2 * x * y + y * y
{
  calc {
    (x + y