src/doc/reference/src/items/functions.md

   1 # Functions
   2
   3 A _function_ consists of a [block], along with a name and a set of parameters.
   4 Other than a name, all these are optional. Functions are declared with the
   5 keyword `fn`. Functions may declare a set of *input* [*variables*][variables]
   6 as parameters, through which the caller passes arguments into the function, and
   7 the *output* [*type*][type] of the value the function will return to its caller
   8 on completion.
   9
  10 When referred to, a _function_ yields a first-class *value* of the
  11 corresponding zero-sized [*function item type*], which
  12 when called evaluates to a direct call to the function.
  13
  14 For example, this is a simple function:
  15 ```rust
  16 fn answer_to_life_the_universe_and_everything() -> i32 {
  17     return 42;
  18 }
  19 ```
  20
  21 As with `let` bindings, function arguments are irrefutable patterns, so any
  22 pattern that is valid in a let binding is also valid as an argument:
  23
  24 ```rust
  25 fn first((value, _): (i32, i32)) -> i32 { value }
  26 ```
  27
  28 The block of a function is conceptually wrapped in a block that binds the
  29 argument patterns and then `return`s the value of the function's block. This
  30 means that the tail expression of the block, if evaluated, ends up being
  31 returned to the caller. As usual, an explicit return expression within
  32 the body of the function will short-cut that implicit return, if reached.
  33
  34 For example, the function above behaves as if it was written as:
  35
  36 ```rust,ignore
  37 // argument_0 is the actual first argument passed from the caller
  38 let (value, _) = argument_0;
  39 return {
  40     value
  41 };
  42 ```
  43
  44 ## Generic functions
  45
  46 A _generic function_ allows one or more _parameterized types_ to appear in its
  47 signature. Each type parameter must be explicitly declared in an
  48 angle-bracket-enclosed and comma-separated list, following the function name.
  49
  50 ```rust
  51 // foo is generic over A and B
  52
  53 fn foo<A, B>(x: A, y: B) {
  54 # }
  55 ```
  56
  57 Inside the function signature and body, the name of the type parameter can be
  58 used as a type name. [Trait] bounds can be specified for type
  59 parameters to allow methods with that trait to be called on values of that
  60 type. This is specified using the `where` syntax:
  61
  62 ```rust
  63 # use std::fmt::Debug;
  64 fn foo<T>(x: T) where T: Debug {
  65 # }
  66 ```
  67
  68 When a generic function is referenced, its type is instantiated based on the
  69 context of the reference. For example, calling the `foo` function here:
  70
  71 ```rust
  72 use std::fmt::Debug;
  73
  74 fn foo<T>(x: &[T]) where T: Debug {
  75     // details elided
  76 }
  77
  78 foo(&[1, 2]);
  79 ```
  80
  81 will instantiate type parameter `T` with `i32`.
  82
  83 The type parameters can also be explicitly supplied in a trailing [path]
  84 component after the function name. This might be necessary if there is not
  85 sufficient context to determine the type parameters. For example,
  86 `mem::size_of::<u32>() == 4`.
  87
  88 ## Extern functions
  89
  90 Extern functions are part of Rust's foreign function interface, providing the
  91 opposite functionality to [external blocks]. Whereas external
  92 blocks allow Rust code to call foreign code, extern functions with bodies
  93 defined in Rust code _can be called by foreign code_. They are defined in the
  94 same way as any other Rust function, except that they have the `extern`
  95 modifier.
  96
  97 ```rust
  98 // Declares an extern fn, the ABI defaults to "C"
  99 extern fn new_i32() -> i32 { 0 }
 100
 101 // Declares an extern fn with "stdcall" ABI
 102 # #[cfg(target_arch = "x86_64")]
 103 extern "stdcall" fn new_i32_stdcall() -> i32 { 0 }
 104 ```
 105
 106 Unlike normal functions, extern fns have type `extern "ABI" fn()`. This is the
 107 same type as the functions declared in an extern block.
 108
 109 ```rust
 110 # extern fn new_i32() -> i32 { 0 }
 111 let fptr: extern "C" fn() -> i32 = new_i32;
 112 ```
 113
 114 As non-Rust calling conventions do not support unwinding, unwinding past the end
 115 of an extern function will cause the process to abort. In LLVM, this is
 116 implemented by executing an illegal instruction.
 117
 118 [external blocks]: items/external-blocks.html
 119 [path]: paths.html
 120 [block]: expressions/block-expr.html
 121 [variables]: variables.html
 122 [type]: types.html
 123 [*function item type*]: types.html#function-item-types
 124 [Trait]: items/traits.html