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