return statement

 

C++

Language

Standard library headers

Concepts

Utilities library

Strings library

Containers library

Algorithms library

Iterators library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

Filesystem library (C++17)

Technical Specifications

 

C++ language

 

Statements

Labels

label : statement

Expression statements

expression ;

Compound statements

{ statement... }

Selection statements

if

switch

Iteration statements

while

do-while

for

range for(C++11)

Jump statements

break

continue

return

goto

Declaration statements

declaration ;

Try blocks

try compound-statement handler-sequence

Transactional memory

syncronized, atomic_commit, etc(TM TS)

 

Terminates current function and returns specified value to the caller function.

Syntax

attr(optional) return expression(optional) ;	(1)
attr(optional) return braced-init-list ;	(2)	(since C++11)

attr(C++11)	-	optional sequence of any number of attributes
expression	-	expression, convertible to the function return type
braced-init-list	-	brace-enclosed list of initializers and other braced-init-lists

Explanation

1) Evaluates the expression, terminates the current function and returns the result of the expression to the caller, after implicit conversion to the function return type. The expression is optional in functions whose return type is (possibly cv-qualified) void, in constructors and in destructors.

2) Uses copy-list-initialization to construct the return value of the function.

Notes

If control reaches the end of a function with the return type void (possibly cv-qualified), end of a constructor, end of a destructor, or the end of a function-try-block for a function with the return type (possibly cv-qualified) void without encountering a return statement, return; is executed.

If control reaches the end of the main function, return 0; is executed.

Flowing off the end of a value-returning function (except main) without a return statement is undefined behavior.

In a function returning void, the return statement with expression can be used, if the expression type is void.

Returning by value may involve construction and copy/move of a temporary object, unless copy elision is used.

If expression is an lvalue expression and the conditions for copy elision are met, or would be met, except that expression names a function parameter, then overload resolution to select the constructor to use for initialization of the returned value is performed twice: first as if expression were an rvalue expression (thus it may select the move constructor or a copy constructor taking reference to const), and if no suitable conversion is available, overload resolution is performed the second time, with lvalue expression (so it may select the copy constructor taking a reference to non-const). The above rule applies even if the function return type is different from the type of expression (copy elision requires same type)

(since C++11)

The copy-initialization of the temporary that is the result of evaluating a function call is sequenced-before the destruction of all temporaries at the end of expression, which, in turn, is sequenced-before the destruction of local variables of the block enclosing the return statement.

(since C++14)

Keywords

return

Example

Run this code

#include <iostream>
#include <string>
#include <utility>
 
void fa(int i)
{
    if (i == 2)
         return;
    std::cout << i << '\n';
} // implied return;
 
int fb(int i)
{
    if (i > 4)
         return 4;
    std::cout << i << '\n';
    return 2;
}
 
std::pair<std::string, int> fc(const char* p, int x)
{
    return {p, x};
}
 
void fd()
{
    return fa(10); // fa(10) is a void expression
}
 
int main()
{
    fa(2); // returns, does nothing when i==2
    fa(1); // prints its argument, then returns
    int i = fb(5); // prints its argument, returns 2
    i = fb(i); // prints its argument, returns 4
    std::cout << i << '\n'
              << fc("Hello", 7).second << '\n';
    fd();
}

Output:

1
4
2
7
10

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DR	Applied to	Behavior as published	Correct behavior
CWG 1579	C++11	return by converting move constructor was not allowed	converting move constructor look up enabled
CWG 1885	C++14	sequencing of the destruction of atomatic variables was not explicit	sequencing rules added

See also

C documentation for return statement