return
statementGeneral topics | ||||||||||||||||
Flow control | ||||||||||||||||
Conditional execution statements | ||||||||||||||||
Iteration statements (loops) | ||||||||||||||||
Jump statements | ||||||||||||||||
| ||||||||||||||||
Functions | ||||||||||||||||
Function declaration | ||||||||||||||||
Lambda function expression | ||||||||||||||||
inline specifier | ||||||||||||||||
Dynamic exception specifications(until C++17*) | ||||||||||||||||
noexcept specifier(C++11) | ||||||||||||||||
Exceptions | ||||||||||||||||
Namespaces | ||||||||||||||||
Types | ||||||||||||||||
Specifiers | ||||||||||||||||
| ||||||||||||||||
Storage duration specifiers | ||||||||||||||||
Initialization | ||||||||||||||||
Expressions | ||||||||||||||||
Alternative representations | ||||||||||||||||
Literals | ||||||||||||||||
Boolean -Integer -Floating-point | ||||||||||||||||
Character -String -nullptr(C++11) | ||||||||||||||||
User-defined(C++11) | ||||||||||||||||
Utilities | ||||||||||||||||
Attributes(C++11) | ||||||||||||||||
Types | ||||||||||||||||
typedef declaration | ||||||||||||||||
Type alias declaration(C++11) | ||||||||||||||||
Casts | ||||||||||||||||
Memory allocation | ||||||||||||||||
Classes | ||||||||||||||||
Class-specific function properties | ||||||||||||||||
| ||||||||||||||||
Special member functions | ||||||||||||||||
Templates | ||||||||||||||||
Miscellaneous | ||||||||||||||||
Terminates the current function and returns the specified value (if any) to the caller.
Contents |
attr (optional)return expression (optional); | (1) | ||||||||
attr (optional)return braced-init-list; | (2) | (since C++11) | |||||||
attr (optional)co_return expression (optional); | (3) | (since C++20) | |||||||
attr (optional)co_return braced-init-list; | (4) | (since C++20) | |||||||
attr | - | (since C++11) sequence of any number ofattributes |
expression | - | expression, convertible to the function return type |
braced-init-list | - | brace-enclosed initializer list |
Theexpressionorbraced-init-list(since C++11) (if any) is known as theoperand of thereturn statement.
There is asequence point between the copy-initialization of the result of the function call and the destruction of all temporaries at the end ofexpression. | (until C++11) |
The copy-initialization of the result of the function call issequenced-before the destruction of all temporaries at the end ofexpression, which, in turn, issequenced-before the destruction of local variables of the block enclosing thereturn statement. | (since C++11) |
If the return type of the function is a reference type and areturn statement(1,2) binds the returned reference to the result of atemporary expression, the program is ill-formed. | (since C++26) |
If control reaches the end of
without encountering areturn statement,return; is executed.
If control reaches the end of themain
function,return0; is executed.
Flowing off the end of a value-returning function, except themain
function and specificcoroutines(since C++20), without areturn statement is undefined behavior.
In a function returning (possibly cv-qualified)void, thereturn statement withexpression can be used, if the expression type is (possibly cv-qualified)void.
If the return type of a function is specified as aplaceholder type, it will bededuced from the return value. Ifdecltype(auto) is used, the type deduction treats anexpression that can be anentity as anentity. | (since C++14) |
Returning by value may involve construction and copy/move of a temporary object, unlesscopy elision is used. Specifically, the conditions for copy/move are as follows:
Automatic move from local variables and parametersTheexpression ismove-eligible if it is a (possibly parenthesized)identifier expression that names a variable of automatic storage duration whose type is
| (since C++11) |
| (since C++20) |
and that variable is declared
of the innermost enclosing function or lambda expression. | (since C++11) |
If theexpression is move-eligible,overload resolution to select the constructor to use for initialization of the returned value or, forco_return, to select the overload ofpromise.return_value()(since C++20) is performedtwice :
| (since C++11) (until C++23) |
| (since C++11) (until C++20) |
| (since C++11) (until C++23) |
If theexpression is move-eligible, it is treated as an xvalue (thus overload resolution may select themove constructor). | (since C++23) |
Guaranteed copy elisionIfexpression is a prvalue, the result object is initialized directly by that expression. This does not involve a copy or move constructor when the types match (seecopy elision). | (since C++17) |
Feature-test macro | Value | Std | Feature |
---|---|---|---|
__cpp_implicit_move | 202207L | (C++23) | Simplerimplicit move |
#include <iostream>#include <string>#include <utility> void fa(int i){if(i==2)return;std::cout<<"fa("<< i<<")\n";}// implied return; int fb(int i){if(i>4)return4;std::cout<<"fb("<< i<<")\n";return2;} std::pair<std::string,int> fc(constchar* p,int x){return{p, x};} void fd(){return fa(10);// fa(10) is a void expression} int main(){ fa(1);// prints its argument, then returns fa(2);// does nothing when i == 2, just returns int i= fb(5);// returns 4 i= fb(i);// prints its argument, returns 2std::cout<<"i = "<< i<<'\n'<<"fc(~).second = "<< fc("Hello",7).second<<'\n'; fd();} struct MoveOnly{ MoveOnly()=default; MoveOnly(MoveOnly&&)=default;}; MoveOnly move_11(MoveOnly arg){return arg;// OK. implicit move} MoveOnly move_11(MoveOnly&& arg){return arg;// OK since C++20. implicit move} MoveOnly&& move_23(MoveOnly&& arg){return arg;// OK since C++23. implicit move}
Output:
fa(1)fb(4)i = 2fc(~).second = 7fa(10)
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
DR | Applied to | Behavior as published | Correct behavior |
---|---|---|---|
CWG 1541 | C++98 | expression could not be omitted if the return type is cv-qualifiedvoid | it can be omitted |
CWG 1579 | C++11 | return by converting move constructor was not allowed | converting move constructor lookup enabled |
CWG 1885 | C++98 | sequencing of the destruction of automatic variables was not explicit | sequencing rules added |
C documentation for return statement |