# Functions
> **Syntax**\
> _Function_ :\
> _FunctionQualifiers_ `fn` [IDENTIFIER] [_Generics_]?\
> `(` _FunctionParameters_? `)`\
> _FunctionReturnType_? [_WhereClause_]?\
> [_BlockExpression_]
>
> _FunctionQualifiers_ :\
> _AsyncConstQualifiers_? `unsafe`? (`extern` _Abi_?)?
>
> _AsyncConstQualifiers_ :\
> `async` | `const`
>
> _Abi_ :\
> [STRING_LITERAL] | [RAW_STRING_LITERAL]
>
> _FunctionParameters_ :\
> _FunctionParam_ (`,` _FunctionParam_)\* `,`?
>
> _FunctionParam_ :\
> [_Pattern_] `:` [_Type_]
>
> _FunctionReturnType_ :\
> `->` [_Type_]
A _function_ consists of a [block], along with a name and a set of parameters.
Other than a name, all these are optional. Functions are declared with the
keyword `fn`. Functions may declare a set of *input* [*variables*][variables]
as parameters, through which the caller passes arguments into the function, and
the *output* [*type*][type] of the value the function will return to its caller
on completion.
When referred to, a _function_ yields a first-class *value* of the
corresponding zero-sized [*function item type*], which
when called evaluates to a direct call to the function.
For example, this is a simple function:
```rust
fn answer_to_life_the_universe_and_everything() -> i32 {
return 42;
}
```
As with `let` bindings, function arguments are irrefutable [patterns], so any
pattern that is valid in a let binding is also valid as an argument:
```rust
fn first((value, _): (i32, i32)) -> i32 { value }
```
The block of a function is conceptually wrapped in a block that binds the
argument patterns and then `return`s the value of the function's block. This
means that the tail expression of the block, if evaluated, ends up being
returned to the caller. As usual, an explicit return expression within
the body of the function will short-cut that implicit return, if reached.
For example, the function above behaves as if it was written as:
```rust,ignore
// argument_0 is the actual first argument passed from the caller
let (value, _) = argument_0;
return {
value
};
```
## Generic functions
A _generic function_ allows one or more _parameterized types_ to appear in its
signature. Each type parameter must be explicitly declared in an
angle-bracket-enclosed and comma-separated list, following the function name.
```rust
// foo is generic over A and B
fn foo(x: A, y: B) {
# }
```
Inside the function signature and body, the name of the type parameter can be
used as a type name. [Trait] bounds can be specified for type
parameters to allow methods with that trait to be called on values of that
type. This is specified using the `where` syntax:
```rust
# use std::fmt::Debug;
fn foo(x: T) where T: Debug {
# }
```
When a generic function is referenced, its type is instantiated based on the
context of the reference. For example, calling the `foo` function here:
```rust
use std::fmt::Debug;
fn foo(x: &[T]) where T: Debug {
// details elided
}
foo(&[1, 2]);
```
will instantiate type parameter `T` with `i32`.
The type parameters can also be explicitly supplied in a trailing [path]
component after the function name. This might be necessary if there is not
sufficient context to determine the type parameters. For example,
`mem::size_of::() == 4`.
## Extern function qualifier
The `extern` function qualifier allows providing function _definitions_ that can
be called with a particular ABI:
```rust,ignore
extern "ABI" fn foo() { ... }
```
These are often used in combination with [external block] items which provide
function _declarations_ that can be used to call functions without providing
their _definition_:
```rust,ignore
extern "ABI" {
fn foo(); /* no body */
}
unsafe { foo() }
```
When `"extern" Abi?*` is omitted from `FunctionQualifiers` in function items,
the ABI `"Rust"` is assigned. For example:
```rust
fn foo() {}
```
is equivalent to:
```rust
extern "Rust" fn foo() {}
```
Functions in Rust can be called by foreign code, and using an ABI that
differs from Rust allows, for example, to provide functions that can be
called from other programming languages like C:
```rust
// Declares a function with the "C" ABI
extern "C" fn new_i32() -> i32 { 0 }
// Declares a function with the "stdcall" ABI
# #[cfg(target_arch = "x86_64")]
extern "stdcall" fn new_i32_stdcall() -> i32 { 0 }
```
Just as with [external block], when the `extern` keyword is used and the `"ABI`
is omitted, the ABI used defaults to `"C"`. That is, this:
```rust
extern fn new_i32() -> i32 { 0 }
let fptr: extern fn() -> i32 = new_i32;
```
is equivalent to:
```rust
extern "C" fn new_i32() -> i32 { 0 }
let fptr: extern "C" fn() -> i32 = new_i32;
```
Functions with an ABI that differs from `"Rust"` do not support unwinding in the
exact same way that Rust does. Therefore, unwinding past the end of functions
with such ABIs causes the process to abort.
> **Note**: The LLVM backend of the `rustc` implementation
aborts the process by executing an illegal instruction.
## Const functions
Functions qualified with the `const` keyword are const functions. _Const
functions_ can be called from within [const context]s. When called from a const
context, the function is interpreted by the compiler at compile time. The
interpretation happens in the environment of the compilation target and not the
host. So `usize` is `32` bits if you are compiling against a `32` bit system,
irrelevant of whether you are building on a `64` bit or a `32` bit system.
If a const function is called outside a [const context], it is indistinguishable
from any other function. You can freely do anything with a const function that
you can do with a regular function.
Const functions have various restrictions to make sure that they can be
evaluated at compile-time. It is, for example, not possible to write a random
number generator as a const function. Calling a const function at compile-time
will always yield the same result as calling it at runtime, even when called
multiple times. There's one exception to this rule: if you are doing complex
floating point operations in extreme situations, then you might get (very
slightly) different results. It is advisable to not make array lengths and enum
discriminants depend on floating point computations.
Exhaustive list of permitted structures in const functions:
> **Note**: this list is more restrictive than what you can write in
> regular constants
* Type parameters where the parameters only have any [trait bounds]
of the following kind:
* lifetimes
* `Sized` or [`?Sized`]
This means that ``, ``, and ``
are all permitted.
This rule also applies to type parameters of impl blocks that
contain const methods
* Arithmetic and comparison operators on integers
* All boolean operators except for `&&` and `||` which are banned since
they are short-circuiting.
* Any kind of aggregate constructor (array, `struct`, `enum`, tuple, ...)
* Calls to other *safe* const functions (whether by function call or method call)
* Index expressions on arrays and slices
* Field accesses on structs and tuples
* Reading from constants (but not statics, not even taking a reference to a static)
* `&` and `*` (only dereferencing of references, not raw pointers)
* Casts except for raw pointer to integer casts
* `unsafe` blocks and `const unsafe fn` are allowed, but the body/block may only do
the following unsafe operations:
* calls to const unsafe functions
## Async functions
Functions may be qualified as async, and this can also be combined with the
`unsafe` qualifier:
```rust,edition2018
async fn regular_example() { }
async unsafe fn unsafe_example() { }
```
Async functions do no work when called: instead, they
capture their arguments into a future. When polled, that future will
execute the function's body.
An async function is roughly equivalent to a function
that returns [`impl Future`] and with an [`async move` block][async-blocks] as
its body:
```rust,edition2018
// Source
async fn example(x: &str) -> usize {
x.len()
}
```
is roughly equivalent to:
```rust,edition2018
# use std::future::Future;
// Desugared
fn example<'a>(x: &'a str) -> impl Future