|
1 | 1 | --- |
2 | 2 | title: "return Statement (C)" |
3 | | -ms.date: "11/04/2016" |
| 3 | +description: "The C language return statement ends function execution and optionally returns a value to the caller." |
| 4 | +ms.date: "06/10/2020" |
4 | 5 | helpviewer_keywords: ["( ) parentheses in return statements"] |
5 | 6 | ms.assetid: 18cd82cf-f899-4b28-83ad-4eff353ddcb4 |
6 | 7 | --- |
7 | 8 | # return Statement (C) |
8 | 9 |
|
9 | | -The `return` statement terminates the execution of a function and returns control to the calling function. Execution resumes in the calling function at the point immediately following the call. A `return` statement can also return a value to the calling function. See [Return Type](../c-language/return-type.md) for more information. |
| 10 | +A **`return`** statement ends the execution of a function, and returns control to the calling function. Execution resumes in the calling function at the point immediately following the call. A **`return`** statement can return a value to the calling function. For more information, see [Return type](../c-language/return-type.md). |
10 | 11 |
|
11 | 12 | ## Syntax |
12 | 13 |
|
13 | | -*jump-statement*:<br/> |
14 | | - **return** *expression*<sub>opt</sub> **;** |
| 14 | +> *jump-statement*:\ |
| 15 | +> **`return`** *expression*​<sub>opt</sub> **`;`** |
15 | 16 |
|
16 | | -The value of *expression*, if present, is returned to the calling function. If *expression* is omitted, the return value of the function is undefined. The expression, if present, is evaluated and then converted to the type returned by the function. If the function was declared with return type `void`, a `return` statement containing an expression generates a warning and the expression is not evaluated. |
| 17 | +The value of *expression*, if present, is returned to the calling function. If *expression* is omitted, the return value of the function is undefined. The expression, if present, is evaluated and then converted to the type returned by the function. When a **`return`** statement contains an expression in functions that have a **`void`** return type, the compiler generates a warning, and the expression isn't evaluated. |
17 | 18 |
|
18 | | -If no `return` statement appears in a function definition, control automatically returns to the calling function after the last statement of the called function is executed. In this case, the return value of the called function is undefined. If a return value is not required, declare the function to have `void` return type; otherwise, the default return type is `int`. |
| 19 | +If no **`return`** statement appears in a function definition, control automatically returns to the calling function after the last statement of the called function is executed. In this case, the return value of the called function is undefined. If the function has a return type other than **`void`**, it's a serious bug, and the compiler prints a warning diagnostic message. If the function has a **`void`** return type, this behavior is okay, but may be considered poor style. Use a plain **`return`** statement to make your intent clear. |
19 | 20 |
|
20 | | -Many programmers use parentheses to enclose the *expression* argument of the `return` statement. However, C does not require the parentheses. |
| 21 | +As a good engineering practice, always specify a return type for your functions. If a return value isn't required, declare the function to have **`void`** return type. If a return type isn't specified, the C compiler assumes a default return type of **`int`**. |
21 | 22 |
|
22 | | -This example demonstrates the `return` statement: |
| 23 | +Many programmers use parentheses to enclose the *expression* argument of the **`return`** statement. However, C doesn't require the parentheses. |
| 24 | + |
| 25 | +The compiler may issue a warning diagnostic message about unreachable code if it finds any statements placed after the **`return`** statement. |
| 26 | + |
| 27 | +In a **`main`** function, the **`return`** statement and expression are optional. What happens to the returned value, if one is specified, depends on the implementation. **Microsoft-specific**: The Microsoft C implementation returns the expression value to the process that invoked the program, such as *`cmd.exe`*. If no **`return`** expression is supplied, the Microsoft C runtime returns a value that indicates success (0) or failure (a non-zero value). |
| 28 | + |
| 29 | +## Example |
| 30 | + |
| 31 | +This example is one program in several parts. It demonstrates the **`return`** statement, and how it's used both to end function execution, and optionally, to return a value. |
23 | 32 |
|
24 | 33 | ```C |
25 | | -#include <limits.h> |
26 | | -#include <stdio.h> |
| 34 | +// C_return_statement.c |
| 35 | +// Compile using: cl /W4 C_return_statement.c |
| 36 | +#include <limits.h> // for INT_MAX |
| 37 | +#include <stdio.h> // for printf |
| 38 | + |
| 39 | +long long square( int value ) |
| 40 | +{ |
| 41 | + // Cast one operand to long long to force the |
| 42 | + // expression to be evaluated as type long long. |
| 43 | + // Note that parentheses around the return expression |
| 44 | + // are allowed, but not required here. |
| 45 | + return ( value * (long long) value ); |
| 46 | +} |
| 47 | +``` |
27 | 48 |
|
28 | | -void draw( int i, long long ll ); |
29 | | -long long sq( int s ); |
| 49 | +The `square` function returns the square of its argument, in a wider type to prevent an arithmetic error. **Microsoft-specific**: In the Microsoft C implementation, the **`long long`** type is large enough to hold the product of two **`int`** values without overflow. |
30 | 50 |
|
31 | | -int main() |
| 51 | +The parentheses around the **`return`** expression in `square` are evaluated as part of the expression, and aren't required by the **`return`** statement. |
| 52 | +
|
| 53 | +```C |
| 54 | +double ratio( int numerator, int denominator ) |
32 | 55 | { |
33 | | - long long y; |
34 | | - int x = INT_MAX; |
| 56 | + // Cast one operand to double to force floating-point |
| 57 | + // division. Otherwise, integer division is used, |
| 58 | + // then the result is converted to the return type. |
| 59 | + return numerator / (double) denominator; |
| 60 | +} |
| 61 | +``` |
| 62 | + |
| 63 | +The `ratio` function returns the ratio of its two **`int`** arguments as a floating-point **`double`** value. The **`return`** expression is forced to use a floating-point operation by casting one of the operands to **`double`**. Otherwise, the integer division operator would be used, and the fractional part would be lost. |
35 | 64 |
|
36 | | - y = sq( x ); |
37 | | - draw( x, y ); |
38 | | - return x; |
| 65 | +```C |
| 66 | +void report_square( void ) |
| 67 | +{ |
| 68 | + int value = INT_MAX; |
| 69 | + long long squared = 0LL; |
| 70 | + squared = square( value ); |
| 71 | + printf( "value = %d, squared = %lld\n", value, squared ); |
| 72 | + return; // Use an empty expression to return void. |
39 | 73 | } |
| 74 | +``` |
| 75 | +
|
| 76 | +The `report_square` function calls `square` with a parameter value of `INT_MAX`, the largest signed integer value that fits in an **`int`**. The **`long long`** result is stored in `squared`, then printed. The `report_square` function has a **`void`** return type, so it doesn't have an expression in its **`return`** statement. |
40 | 77 |
|
41 | | -long long sq( int s ) |
| 78 | +```C |
| 79 | +void report_ratio( int top, int bottom ) |
42 | 80 | { |
43 | | - // Note that parentheses around the return expression |
44 | | - // are allowed but not required here. |
45 | | - return( s * (long long)s ); |
| 81 | + double fraction = ratio( top, bottom ); |
| 82 | + printf( "%d / %d = %.16f\n", top, bottom, fraction ); |
| 83 | + // It's okay to have no return statement for functions |
| 84 | + // that have void return types. |
46 | 85 | } |
| 86 | +``` |
| 87 | + |
| 88 | +The `report_ratio` function calls `ratio` with parameter values of `1` and `INT_MAX`. The **`double`** result is stored in `fraction`, then printed. The `report_ratio` function has a **`void`** return type, so it doesn't need to explicitly return a value. Execution of `report_ratio` "falls off the bottom" and returns no value to the caller. |
47 | 89 |
|
48 | | -void draw( int i, long long ll ) |
| 90 | +```C |
| 91 | +int main() |
49 | 92 | { |
50 | | - printf( "i = %d, ll = %lld\n", i, ll ); |
51 | | - return; |
| 93 | + int n = 1; |
| 94 | + int x = INT_MAX; |
| 95 | + |
| 96 | + report_square(); |
| 97 | + report_ratio( n, x ); |
| 98 | + |
| 99 | + return 0; |
52 | 100 | } |
53 | 101 | ``` |
54 | 102 |
|
55 | | -In this example, the `main` function calls two functions: `sq` and `draw`. The `sq` function returns the value of `x * x` to `main`, where the return value is assigned to `y`. The parentheses around the return expression in `sq` are evaluated as part of the expression, and are not required by the return statement. Since the return expression is evaluated before it is converted to the return type, `sq` forces the expression type to be the return type with a cast to prevent a possible integer overflow, which could lead to unexpected results. The `draw` function is declared as a `void` function. It prints the values of its parameters and then the empty return statement ends the function and does not return a value. An attempt to assign the return value of `draw` would cause a diagnostic message to be issued. The `main` function then returns the value of `x` to the operating system. |
| 103 | +The **`main`** function calls two functions: `report_square` and `report_ratio`. As `report_square` takes no parameters and returns **`void`**, we don't assign its result to a variable. Likewise, `report_ratio` returns **`void`**, so we don't save its return value, either. After each of these function calls, execution continues at the next statement. Then **`main`** returns a value of `0` (typically used to report success) to end the program. |
| 104 | + |
| 105 | +To compile the example, create a source code file named *`C_return_statement.c`*. Then, copy all the example code, in the order shown. Save the file, and compile it in a Developer command prompt window by using the command: |
| 106 | + |
| 107 | +**`cl /W4 C_return_statement.c`** |
56 | 108 |
|
57 | | -The output of the example looks like this: |
| 109 | +Then, to run the example code, enter **`C_return_statement.exe`** at the command prompt. The output of the example looks like this: |
58 | 110 |
|
59 | 111 | ```Output |
60 | | -i = 2147483647, ll = 4611686014132420609 |
| 112 | +value = 2147483647, squared = 4611686014132420609 |
| 113 | +1 / 2147483647 = 0.0000000004656613 |
61 | 114 | ``` |
62 | 115 |
|
63 | 116 | ## See also |
|
0 commit comments