Skip to content

32. Functions and declarations

A function is a name, a signature and a body: an expression in HQL that gives the result. A declaration is a name and a signature with no body: the result comes from a function written in Rust. A program calls both the same way, and the checker types a call from the signature alone, so nothing at the call says which of the two it reaches.

This chapter is about the second kind. Every function of the standard library that a program cannot write for itself, from abs to split, is a declaration, and Part V is about adding declarations of your own.

A function has a body

Chapter 4 declares functions. The body follows =, and its type is checked against the result the signature states:

fn double(n: Int) : Int = n * 2

double(21)
42

Everything double does is in the program. Removing the Rust that implements hql would leave the function exactly as it is written.

A declaration has none

The same signature without = is a declaration. It states what a call takes and gives, and nothing about how:

abs(-3)
3

abs is declared in the standard module math as fn abs(self: Int) : Int. The line has no body, because no HQL expression defines the absolute value of an Int without already having one. The result comes from a Rust function inside the hql binary.

A declaration is one half of a pair. The other half is the Rust function, and the pair is joined by an extension: the unit that implements the declarations of a package's modules. A declaration in a file that no extension implements is checked and binds no name:

fn area(side: Float) : Float

area(2.0f)
check error[unknown-name]: `area` is not bound
 --> <expression>:3:1
  |
3 | area(2.0f)
  | ^^^^^^^^^^

The declaration itself is accepted: its types exist and its name is free. The call is refused because a program has no extension, so nothing implements area.

Which one to write

A function A declaration
Written in HQL HQL for the signature, Rust for the result
Lives in a program or a module of a project a module of a package
Needs nothing beyond hql a Rust toolchain to build the package
Reaches what HQL expresses anything a Rust crate does
Changes take effect on the next run after the package is rebuilt

A function is the default. A declaration is for what HQL cannot express or should not repeat: a numeric routine a Rust crate already provides, a file format, a protocol, a computation whose speed matters.

The pages of this chapter

Page What it covers
Declarations the receiver, positional and named parameters, defaults, forms of one name, purity and shape
How the standard library is built a standard module's contract, the Rust beside it, and the check that joins them

What is next

Chapter 33 follows an import from the module it names to the package that provides it and the file the package's extension is loaded from.