C++ Reference ยท Keywords and Statements
The return statement
Reference for C++ return: returning values, void and braced lists, copy elision (RVO), returning references, dangling locals and falling off main.
return ends the current function and, in a non-void function, gives the caller a value. The value initializes the function's return object, converting if needed. Local variables are destroyed on the way out, in reverse order of construction.
How the value is delivered matters for performance and safety. Returning a local object by value is normally free thanks to copy elision (and the implicit move rule when elision is not possible). Returning a reference or pointer to a local variable is the classic way to create a dangling reference.
int square(int x) { return x * x; }
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
Syntax
return; // only in void functions, constructors, destructors return expression; return braced-init-list;
| Part | Description |
|---|---|
expression |
Converted to the function's return type by copy-initialization. In a function returning auto or decltype(auto) it determines the type. |
braced-init-list |
Initializes the return object by list-initialization, as in return {1, 2};. |
return; |
Used when the return type is void (a return f(); where f returns void is also allowed). |
Usage notes
- Flowing off the end of a non-
voidfunction (other thanmain) is undefined behavior if the value is used. Compilers warn with-Wreturn-type; treat it as an error. mainis special: reaching its end acts asreturn 0;.- Do not return a reference or pointer to a local variable or a by-value parameter; the object is gone when the caller sees it.
- Do not write
return std::move(local);for a local variable of the return type. It disables copy elision and gains nothing. Return the name directly. - A prvalue return (
return T{};) never copies or moves since C++17. Returning a named local may be elided (NRVO) but is not guaranteed; otherwise the compiler tries a move first. - Different return statements in an
autofunction must deduce to the same type:return 1;andreturn 2.0;do not compile together. - Returning
constvalues (const int f()) only blocks moving and brings no benefit. - Returning a struct,
std::pairorstd::tupleis a clean way to give several results; unpack them with structured bindings. [[nodiscard]]on the function warns when callers ignore the returned value.- A function that never returns can be marked
[[noreturn]].