src/doc/trpl/functions.md

   1 % Functions
   2
   3 Every Rust program has at least one function, 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 ```rust,ignore
  62 fn print_sum(x, y) {
  63     println!("sum is: {}", x + y);
  64 }
  65 ```
  66
  67 You get this error:
  68
  69 ```text
  70 expected one of `!`, `:`, or `@`, found `)`
  71 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 (`>`). The last
  90 line of a function determines what it returns. You’ll note the lack of a
  91 semicolon here. If we added it in:
  92
  93 ```rust,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 This reveals two interesting things about Rust: it is an expression-based
 113 language, and semicolons are different from semicolons in other ‘curly brace
 114 and semicolon’-based languages. These two things are related.
 115
 116 ## Expressions vs. Statements
 117
 118 Rust is primarily an expression-based language. There are only two kinds of
 119 statements, and everything else is an expression.
 120
 121 So what's the difference? Expressions return a value, and statements do not.
 122 That’s why we end up with ‘not all control paths return a value’ here: the
 123 statement `x + 1;` doesn’t return a value. There are two kinds of statements in
 124 Rust: ‘declaration statements’ and ‘expression statements’. Everything else is
 125 an expression. Let’s talk about declaration statements first.
 126
 127 In some languages, variable bindings can be written as expressions, not just
 128 statements. Like Ruby:
 129
 130 ```ruby
 131 x = y = 5
 132 ```
 133
 134 In Rust, however, using `let` to introduce a binding is _not_ an expression. The
 135 following will produce a compile-time error:
 136
 137 ```ignore
 138 let x = (let y = 5); // expected identifier, found keyword `let`
 139 ```
 140
 141 The compiler is telling us here that it was expecting to see the beginning of
 142 an expression, and a `let` can only begin a statement, not an expression.
 143
 144 Note that assigning to an already-bound variable (e.g. `y = 5`) is still an
 145 expression, although its value is not particularly useful. Unlike other
 146 languages where an assignment evaluates to the assigned value (e.g. `5` in the
 147 previous example), in Rust the value of an assignment is an empty tuple `()`:
 148
 149 ```
 150 let mut y = 5;
 151
 152 let x = (y = 6);  // x has the value `()`, not `6`
 153 ```
 154
 155 The second kind of statement in Rust is the *expression statement*. Its
 156 purpose is to turn any expression into a statement. In practical terms, Rust's
 157 grammar expects statements to follow other statements. This means that you use
 158 semicolons to separate expressions from each other. This means that Rust
 159 looks a lot like most other languages that require you to use semicolons
 160 at the end of every line, and you will see semicolons at the end of almost
 161 every line of Rust code you see.
 162
 163 What is this exception that makes us say "almost"? You saw it already, in this
 164 code:
 165
 166 ```rust
 167 fn add_one(x: i32) -> i32 {
 168     x + 1
 169 }
 170 ```
 171
 172 Our function claims to return an `i32`, but with a semicolon, it would return
 173 `()` instead. Rust realizes this probably isn’t what we want, and suggests
 174 removing the semicolon in the error we saw before.
 175
 176 ## Early returns
 177
 178 But what about early returns? Rust does have a keyword for that, `return`:
 179
 180 ```rust
 181 fn foo(x: i32) -> i32 {
 182     return x;
 183
 184     // we never run this code!
 185     x + 1
 186 }
 187 ```
 188
 189 Using a `return` as the last line of a function works, but is considered poor
 190 style:
 191
 192 ```rust
 193 fn foo(x: i32) -> i32 {
 194     return x + 1;
 195 }
 196 ```
 197
 198 The previous definition without `return` may look a bit strange if you haven’t
 199 worked in an expression-based language before, but it becomes intuitive over
 200 time.
 201
 202 ## Diverging functions
 203
 204 Rust has some special syntax for ‘diverging functions’, which are functions that
 205 do not return:
 206
 207 ```
 208 fn diverges() -> ! {
 209     panic!("This function never returns!");
 210 }
 211 ```
 212
 213 `panic!` is a macro, similar to `println!()` that we’ve already seen. Unlike
 214 `println!()`, `panic!()` causes the current thread of execution to crash with
 215 the given message.
 216
 217 Because this function will cause a crash, it will never return, and so it has
 218 the type ‘`!`’, which is read ‘diverges’. A diverging function can be used
 219 as any type:
 220
 221 ```should_panic
 222 # fn diverges() -> ! {
 223 #    panic!("This function never returns!");
 224 # }
 225 let x: i32 = diverges();
 226 let x: String = diverges();
 227 ```