## 9.3 Calling functions

All function arguments are mandatory—there are no default values.

### Functions as expressions

Functions with non-void return types are called just like any other built-in function in Stan—they are applied to appropriately typed arguments to produce an expression, which has a value when executed.

### Functions as statements

Functions with void return types may be applied to arguments and used as statements. These act like sampling statements or print statements. Such uses are only appropriate for functions that act through side effects, such as incrementing the log probability accumulator, printing, or raising exceptions.

### Resolving overloads

Overloaded functions alongside type promotion can result in situations where there are multiple valid interpretations of a function call. Stan requires that there be a unique signature which minimizes the number of promotions required.

Consider the following two overloaded functions

```
real foo(int a, real b);
real foo(real a, int b);
```

These functions do **not** have a unique minimum when called with two integer arguments
`foo(1,2)`

, and therefore cannot be called as such.

Promotion of integers to complex numbers is considered as two separate
promotions, one from `int`

to `real`

and a second from `real`

to `complex`

.
Consider the following functions with `real`

and `complex`

signatures

```
real bar(real x);
real bar(complex z);
```

A call `bar(5)`

with an integer argument will be resolved to `bar(real)`

because
it only requires a single promotion, whereas the promotion to a complex number
requires two promotions.

### Argument promotion

The rules for calling functions work the same way as assignment as far as promotion goes. This means that we can promote arguments to the type expected by function arguments. For example, the following will work.

```
real foo(real x) { return ... };
...int a = 5;
real b = foo(a); // a promoted to type real
```

In addition to promoting `int`

to `real`

, Stan also promotes `real`

to
`complex`

, and by transitivity, `int`

to `complex`

. This also works
for containers, so an array of `int`

may be assigned to an array of
`real`

of the same shape. And we can also promote `vector`

to
`complex_vector`

and similarly for row vectors and matrices.

### Probability functions in sampling statements

Functions whose name ends in `_lpdf`

or `_lpmf`

(density
and mass functions) may be used as probability functions and may be
used in place of parameterized distributions on the right-hand-side of
sampling statements.

### Restrictions on placement

Functions of certain types are restricted on scope of usage.
Functions whose names end in `_lp`

assume access to the log
probability accumulator and are only available in the transformed
parameter and model blocks.

Functions whose names end in `_rng`

assume access to the random number generator and may only be used
within the generated quantities block, transformed data block, and
within user-defined functions ending in `_rng`

.

Functions whose names end in `_lpdf`

and `_lpmf`

can be used anywhere.
However, `_lupdf`

and `_lupmf`

functions can only be used in the model
block or user-defined probability functions.

See the section on function bodies for more information on these special types of function.