src/doc/trpl/functions.md

   1 % Functions
   2
   3 You've already seen one function so far, the `main` function:
   4
   5 ```{rust}
   6 fn main() {
   7 }
   8 ```
   9
  10 This is the simplest possible function declaration. As we mentioned before,
  11 `fn` says "this is a function," followed by the name, some parentheses because
  12 this function takes no arguments, and then some curly braces to indicate the
  13 body. Here's a function named `foo`:
  14
  15 ```{rust}
  16 fn foo() {
  17 }
  18 ```
  19
  20 So, what about taking arguments? Here's a function that prints a number:
  21
  22 ```{rust}
  23 fn print_number(x: i32) {
  24     println!("x is: {}", x);
  25 }
  26 ```
  27
  28 Here's a complete program that uses `print_number`:
  29
  30 ```{rust}
  31 fn main() {
  32     print_number(5);
  33 }
  34
  35 fn print_number(x: i32) {
  36     println!("x is: {}", x);
  37 }
  38 ```
  39
  40 As you can see, function arguments work very similar to `let` declarations:
  41 you add a type to the argument name, after a colon.
  42
  43 Here's a complete program that adds two numbers together and prints them:
  44
  45 ```{rust}
  46 fn main() {
  47     print_sum(5, 6);
  48 }
  49
  50 fn print_sum(x: i32, y: i32) {
  51     println!("sum is: {}", x + y);
  52 }
  53 ```
  54
  55 You separate arguments with a comma, both when you call the function, as well
  56 as when you declare it.
  57
  58 Unlike `let`, you _must_ declare the types of function arguments. This does
  59 not work:
  60
  61 ```{ignore}
  62 fn print_sum(x, y) {
  63     println!("x is: {}", x + y);
  64 }
  65 ```
  66
  67 You get this error:
  68
  69 ```text
  70 hello.rs:5:18: 5:19 expected one of `!`, `:`, or `@`, found `)`
  71 hello.rs:5 fn print_number(x, y) {
  72 ```
  73
  74 This is a deliberate design decision. While full-program inference is possible,
  75 languages which have it, like Haskell, often suggest that documenting your
  76 types explicitly is a best-practice. We agree that forcing functions to declare
  77 types while allowing for inference inside of function bodies is a wonderful
  78 sweet spot between full inference and no inference.
  79
  80 What about returning a value? Here's a function that adds one to an integer:
  81
  82 ```{rust}
  83 fn add_one(x: i32) -> i32 {
  84     x + 1
  85 }
  86 ```
  87
  88 Rust functions return exactly one value, and you declare the type after an
  89 "arrow," which is a dash (`-`) followed by a greater-than sign (`>`).
  90
  91 You'll note the lack of a semicolon here. If we added it in:
  92
  93 ```{ignore}
  94 fn add_one(x: i32) -> i32 {
  95     x + 1;
  96 }
  97 ```
  98
  99 We would get an error:
 100
 101 ```text
 102 error: not all control paths return a value
 103 fn add_one(x: i32) -> i32 {
 104      x + 1;
 105 }
 106
 107 help: consider removing this semicolon:
 108      x + 1;
 109           ^
 110 ```
 111
 112 Remember our earlier discussions about semicolons and `()`? Our function claims
 113 to return an `i32`, but with a semicolon, it would return `()` instead. Rust
 114 realizes this probably isn't what we want, and suggests removing the semicolon.
 115
 116 This is very much like our `if` statement before: the result of the block
 117 (`{}`) is the value of the expression. Other expression-oriented languages,
 118 such as Ruby, work like this, but it's a bit unusual in the systems programming
 119 world. When people first learn about this, they usually assume that it
 120 introduces bugs. But because Rust's type system is so strong, and because unit
 121 is its own unique type, we have never seen an issue where adding or removing a
 122 semicolon in a return position would cause a bug.
 123
 124 But what about early returns? Rust does have a keyword for that, `return`:
 125
 126 ```{rust}
 127 fn foo(x: i32) -> i32 {
 128     if x < 5 { return x; }
 129
 130     x + 1
 131 }
 132 ```
 133
 134 Using a `return` as the last line of a function works, but is considered poor
 135 style:
 136
 137 ```{rust}
 138 fn foo(x: i32) -> i32 {
 139     if x < 5 { return x; }
 140
 141     return x + 1;
 142 }
 143 ```
 144
 145 The previous definition without `return` may look a bit strange if you haven't
 146 worked in an expression-based language before, but it becomes intutive over
 147 time. If this were production code, we wouldn't write it in that way anyway,
 148 we'd write this:
 149
 150 ```rust
 151 fn foo(x: i32) -> i32 {
 152     if x < 5 {
 153         x
 154     } else {
 155         x + 1
 156     }
 157 }
 158 ```
 159
 160 Because `if` is an expression, and it's the only expression in this function,
 161 the value will be the result of the `if`.
 162
 163 There are some additional ways to define functions, but they involve features
 164 that we haven't learned about yet, so let's just leave it at that for now.