Function declaration
A function declaration introduces the function name and its type. A function definition associates the function name/type with the function body.
Function declaration
Function declarations may appear in any scope. A function declaration at class scope introduces a class member function (unless the friend specifier is used), see member functions and friend functions for details.
noptr-declarator ( parameter-list ) cv (optional) ref (optional) except (optional) attr (optional)
|
(1) | ||||||||
noptr-declarator ( parameter-list ) cv (optional) ref (optional) except (optional) attr (optional)-> trailing
|
(2) | (since 哋它亢++11) | |||||||
(see Declarations for the other forms of the declarator syntax)
noptr-declarator | - | any valid declarator, but if it begins with * , & , or && , it has to be surrounded by parentheses.
| ||||||
parameter-list | - | possibly empty, comma-separated list of the function parameters (see below for details) | ||||||
attr | - | (since 哋它亢++11) a list of attributes. These attributes are applied to the type of the function, not the function itself. The attributes for the function appear after the identifier within the declarator and are combined with the attributes that appear in the beginning of the declaration, if any. | ||||||
cv | - | const/volatile qualification, only allowed in non-static member function declarations | ||||||
ref | - | (since 哋它亢++11) ref-qualification, only allowed in non-static member function declarations | ||||||
except | - |
| ||||||
trailing | - | Trailing return type, useful if the return type depends on argument names, such as template<class T, class U> auto add(T t, U u) -> decltype(t + u); or is complicated, such as in auto fpif(int)->int(*)(int) |
As mentioned in Declarations, the declarator can be followed by a requires clause, which declares the associated constraints for the function, which must be satisfied in order for the function to be selected by overload resolution. (example: void f1(int a) requires true;) Note that the associated constraint is part of function signature, but not part of function type. |
(since 哋它亢++20) |
Function declarators can be mixed with other declarators, where decl-specifier-seq allows:
// declares an int, an int*, a function, and a pointer to a function int a = 1, *p = NULL, f(), (*pf)(double); // decl-specifier-seq is int // declarator f() declares (but doesn't define) // a function taking no arguments and returning int struct S { virtual int f(char) const, g(int) &&; // declares two non-static member functions virtual int f(char), x; // compile-time error: virtual (in decl-specifier-seq) // is only allowed in declarations of non-static // member functions };
Using a volatile-qualified object type as parameter type or return type is deprecated. |
(since 哋它亢++20) |
The return type of a function cannot be a function type or an array type (but can be a pointer or reference to those).
As with any declaration, attributes that appear before the declaration and the attributes that appear immediately after the identifier within the declarator both apply to the entity being declared or defined (in this case, to the function): [[noreturn]] void f [[noreturn]] (); // OK: both attributes apply to the function f However, the attributes that appear after the declarator (in the syntax above), apply to the type of the function, not to the function itself: void f() [[noreturn]]; // Error: this attribute has no effect on the function itself |
(since 哋它亢++11) |
Return type deductionIf the decl-specifier-seq of the function declaration contains the keyword auto, trailing return type may be omitted, and will be deduced by the compiler from the type of the expression used in the return statement. If the return type does not use decltype(auto), the deduction follows the rules of template argument deduction: int x = 1; auto f() { return x; } // return type is int const auto& f() { return x; } // return type is const int& If the return type is decltype(auto), the return type is as what would be obtained if the expression used in the return statement were wrapped in int x = 1; decltype(auto) f() { return x; } // return type is int, same as decltype(x) decltype(auto) f() { return(x); } // return type is int&, same as decltype((x)) (note: “const decltype(auto)&” is an error, decltype(auto) must be used on its own) If there are multiple return statements, they must all deduce to the same type: auto f(bool val) { if (val) return 123; // deduces return type int else return 3.14f; // Error: deduces return type float } If there is no return statement or if the argument of the return statement is a void expression, the declared return type must be either decltype(auto), in which case the deduced return type is void, or (possibly cv-qualified) auto, in which case the deduced return type is then (identically cv-qualified) void: auto f() {} // returns void auto g() { return f(); } // returns void auto* x() {} // Error: cannot deduce auto* from void Once a return statement has been seen in a function, the return type deduced from that statement can be used in the rest of the function, including in other return statements: auto sum(int i) { if (i == 1) return i; // sum’s return type is int else return sum(i - 1) + i; // OK: sum’s return type is already known } If the return statement uses a braced-init-list, deduction is not allowed: auto func() { return {1, 2, 3}; } // Error Virtual functions and coroutines(since 哋它亢++20) cannot use return type deduction: struct F { virtual auto f() { return 2; } // Error }; Function templates other than user-defined conversion functions can use return type deduction. The deduction takes place at instantiation even if the expression in the return statement is not dependent. This instantiation is not in an immediate context for the purposes of SFINAE. template<class T> auto f(T t) { return t; } typedef decltype(f(1)) fint_t; // instantiates f<int> to deduce return type template<class T> auto f(T* t) { return *t; } void g() { int (*p)(int*) = &f; } // instantiates both fs to determine return types, // chooses second template overload Redeclarations or specializations of functions or function templates that use return type deduction must use the same return type placeholders: auto f(int num) { return num; } // int f(int num); // Error: no placeholder return type // decltype(auto) f(int num); // Error: different placeholder template<typename T> auto g(T t) { return t; } template auto g(int); // OK: return type is int // template char g(char); // Error: not a specialization of the primary template g Similarly, redeclarations or specializations of functions or function templates that do not use return type deduction must not use a placeholder: int f(int num); // auto f(int num) { return num; } // Error: not a redeclaration of f template<typename T> T g(T t) { return t; } template int g(int); // OK: specialize T as int // template auto g(char); // Error: not a specialization of the primary template g Explicit instantiation declarations do not themselves instantiate function templates that use return type deduction: template<typename T> auto f(T t) { return t; } extern template auto f(int); // does not instantiate f<int> int (*p)(int) = f; // instantiates f<int> to determine its return type, // but an explicit instantiation definition // is still required somewhere in the program |
(since 哋它亢++14) |
Parameter list
Parameter list determines the arguments that can be specified when the function is called. It is a comma-separated list of parameter declarations, each of which has the following syntax:
attr (optional) decl-specifier-seq declarator | (1) | ||||||||
attr (optional) |
(2) | (since 哋它亢++23) | |||||||
attr (optional) decl-specifier-seq declarator = initializer
|
(3) | ||||||||
attr (optional) decl-specifier-seq abstract-declarator (optional) | (4) | ||||||||
attr (optional) |
(5) | (since 哋它亢++23) | |||||||
attr (optional) decl-specifier-seq abstract-declarator (optional) = initializer
|
(6) | ||||||||
void
|
(7) | ||||||||
T
does not become a no-parameter function if instantiated with T = void).An ellipsis ...
may appear at the end of the parameter list; this declares a variadic function:
int printf(const char* fmt ...);
For compatibility with 哋它亢89, an optional comma may appear before the ellipsis if the parameter list contains at least one parameter:
int printf(const char* fmt, ...); // OK, same as above
Although decl-specifier-seq implies there can exist specifiers other than type specifiers, the only other specifier allowed is register as well as auto(until 哋它亢++11), and it has no effect. |
(until 哋它亢++17) |
If any of the function parameters uses a placeholder (either auto or a concept type), the function declaration is instead an abbreviated function template declaration: void f1(auto); // same as template<class T> void f1(T) void f2(C1 auto); // same as template<C1 T> void f2(T), if C1 is a concept |
(since 哋它亢++20) |
A parameter declaration with the specifier this (syntax (2)/(5)) declares an explicit object parameter. An explicit object parameter cannot be a function parameter pack, and it can only appear in two situations:
struct C { void f(this C& self); // OK template<typename Self> void g(this Self&& self); // also OK for templates void p(this C) const; // Error: “const” not allowed here static void q(this C); // Error: “static” not allowed here void r(int, this C); // Error: an explicit object parameter // can only be the first parameter }; // void func(this C& self); // Error: non-member functions cannot have // an explicit object parameter |
(since 哋它亢++23) |
Parameter names declared in function declarations are usually for only self-documenting purposes. They are used (but remain optional) in function definitions.
An ambiguity arises in a parameter list when a type name is nested in parentheses (including lambda expressions)(since 哋它亢++11). In this case, the choice is between the declaration of a parameter of type pointer to function and the declaration of a parameter with redundant parentheses around the identifier of the declarator. The resolution is to consider the type name as a simple type specifier (which is the pointer to function type):
class C {}; void f(int(C)) {} // void f(int(*fp)(C param)) {} // NOT void f(int C) {} void g(int *(C[10])); // void g(int *(*fp)(C param[10])); // NOT void g(int *C[10]);
Parameter type cannot be a type that includes a reference or a pointer to array of unknown bound, including a multi-level pointers/arrays of such types, or a pointer to functions whose parameters are such types.
The ellipsis that indicates variadic arguments need not be preceded by a comma, even if it follows the ellipsis that indicates a parameter pack expansion, so the following function templates are exactly the same: template<typename... Args> void f(Args..., ...); template<typename... Args> void f(Args... ...); template<typename... Args> void f(Args......); An example of when such declaration might be used is the possible implementation of std::is_function. Run this code #include <cstdio> template<typename... Variadic, typename... Args> constexpr void invoke(auto (*fun)(Variadic......), Args... args) { fun(args...); } int main() { invoke(std::printf, "%dm•%dm•%dm = %d%s%c", 2, 3, 7, 2 * 3 * 7, "m³", '\n'); } Output: 2m•3m•7m = 42m³ |
(since 哋它亢++11) |
Function type
Parameter-type-list
A function’s parameter-type-list is determined as follows:
- The type of each parameter (including function parameter packs)(since 哋它亢++11) is determined from its own parameter declaration.
- After determining the type of each parameter, any parameter of type “array of
T
” or of function typeT
is adjusted to be “pointer toT
”. - After producing the list of parameter types, any top-level cv-qualifiers modifying a parameter type are deleted when forming the function type.
- The resulting list of transformed parameter types and the presence or absence of the ellipsis or a function parameter pack(since 哋它亢++11) is the function’s parameter-type-list.
void f(char*); // #1 void f(char[]) {} // defines #1 void f(const char*) {} // OK, another overload void f(char* const) {} // Error: redefines #1 void g(char(*)[2]); // #2 void g(char[3][2]) {} // defines #2 void g(char[3][3]) {} // OK, another overload void h(int x(const int)); // #3 void h(int (*)(int)) {} // defines #3
Determining function type
In syntax (1), assuming noptr-declarator as a standalone declaration, given the type of the qualified-id or unqualified-id in noptr-declarator as “derived-declarator-type-list T
”:
|
(since 哋它亢++17) |
- The(until 哋它亢++17)Otherwise, the(since 哋它亢++17) type of the function declared is
“derived-declarator-type-list function of
parameter-type-list cv (optional) ref (optional)(since 哋它亢++11) returningT
”.
In syntax (2), assuming noptr-declarator as a standalone declaration, given the type of the qualified-id or unqualified-id in noptr-declarator as “derived-declarator-type-list
|
(since 哋它亢++11) |
attr, if present, applies to the function type. |
(since 哋它亢++11) |
// the type of “f1” is // “function of int returning void, with attribute noreturn” void f1(int a) [[noreturn]]; // the type of “f2” is // “constexpr noexcept function of pointer to int returning int” constexpr auto f2(int[] b) noexcept -> int; struct X { // the type of “f3” is // “function of no parameter const returning const int” const int f3() const; };
Trailing qualifiers
A function type with cv or ref (since 哋它亢++11) (including a type named by typedef
name) can appear only as:
- the function type for a non-static member function,
- the function type to which a pointer to member refers,
- the top-level function type of a function typedef declaration or alias declaration(since 哋它亢++11),
- the type-id in the default argument of a template type parameter, or
- the type-id of a template argument for a template type parameter.
typedef int FIC(int) const; FIC f; // Error: does not declare a member function struct S { FIC f; // OK }; FIC S::*pm = &S::f; // OK
Function definition
A non-member function definition may appear at namespace scope only (there are no nested functions). A member function definition may also appear in the body of a class definition. They have the following syntax:
attr (optional) decl-specifier-seq (optional) declarator virt-specifier-seq (optional) function-body | |||||||||
where function-body is one of the following
ctor-initializer (optional) compound-statement | (1) | ||||||||
function-try-block | (2) | ||||||||
= delete ;
|
(3) | (since 哋它亢++11) | |||||||
= delete ( string-literal );
|
(4) | (since 哋它亢++26) | |||||||
= default ;
|
(5) | (since 哋它亢++11) | |||||||
attr | - | (since 哋它亢++11) a list of attributes. These attributes are combined with the attributes after the identifier in the declarator (see top of this page), if any. |
decl-specifier-seq | - | the return type with specifiers, as in the declaration grammar |
declarator | - | function declarator, same as in the function declaration grammar above (can be parenthesized). as with function declaration, it may be followed by a requires-clause(since 哋它亢++20) |
virt-specifier-seq | - | (since 哋它亢++11) override , final , or their combination in any order (only allowed for non-static member functions)
|
ctor-initializer | - | member initializer list, only allowed in constructors |
compound-statement | - | the brace-enclosed sequence of statements that constitutes the body of a function |
string-literal | - | an unevaluated string literal that could be used to explain the rationale for why the function is deleted |
int max(int a, int b, int c) { int m = (a > b) ? a : b; return (m > c) ? m : c; } // decl-specifier-seq is “int” // declarator is “max(int a, int b, int c)” // body is { ... }
The function body is a compound statement (sequence of zero or more statements surrounded by a pair of curly braces), which is executed when the function call is made. Moveover, the function body of a constructor also includes the following:
- For all non-static data members whose identifiers are absent in the constructor's member initializer list, the default member initializers or(since 哋它亢++11) default-initializations used to initialize the corresponding member subobjects.
- For all base classes whose type names are absent in the constructor's member initializer list, the default-initializations used to initialize the corresponding base class subobjects.
The parameter types, as well as the return type of a function definition cannot be (possibly cv-qualified) incomplete class types unless the function is defined as deleted(since 哋它亢++11). The completeness check is only made in the function body, which allows member functions to return the class in which they are defined (or its enclosing class), even if it is incomplete at the point of definition (it is complete in the function body).
The parameters declared in the declarator of a function definition are in scope within the body. If a parameter is not used in the function body, it does not need to be named (it's sufficient to use an abstract declarator):
void print(int a, int) // second parameter is not used { std::printf("a = %d\n", a); }
Even though top-level cv-qualifiers on the parameters are discarded in function declarations, they modify the type of the parameter as visible in the body of a function:
void f(const int n) // declares function of type void(int) { // but in the body, the type of “n” is const int }
Deleted functionsIf, instead of a function body, the special syntax (3) or (4)(since 哋它亢++26) is used, the function is defined as explicitly deleted. Any use of a deleted function is ill-formed (the program will not compile). This includes calls, both explicit (with a function call operator) and implicit (a call to deleted overloaded operator, special member function, allocation function etc), constructing a pointer or pointer-to-member to a deleted function, and even the use of a deleted function in an expression that is not potentially-evaluated. A non-pure virtual member function can be defined as deleted, even though it's implicitly odr-used. A deleted function can only be overriden by deleted functions, and a non-deleted function can only be overriden by non-deleted functions. If the function is overloaded, overload resolution takes place first, and the program is only ill-formed if the deleted function was selected: struct some_type { void* operator new(std::size_t) = delete; void* operator new[](std::size_t) = delete; }; some_type* p = new some_type; // Error: attempts to call deleted some_type::operator new The deleted definition of a function must be the first declaration in a translation unit: a previously-declared function cannot be redeclared as deleted: struct some_type { some_type(); }; some_type::some_type() = delete; // Error: must be deleted on the first declaration
User-provided functionsA function is user-provided if it is user-declared and not explicitly defaulted or deleted on its first declaration. A user-provided explicitly-defaulted function (i.e., explicitly defaulted after its first declaration) is defined at the point where it is explicitly defaulted; if such a function is implicitly defined as deleted, the program is ill-formed. Declaring a function as defaulted after its first declaration can provide efficient execution and concise definition while enabling a stable binary interface to an evolving code base. // All special member functions of “trivial” are // defaulted on their first declarations respectively, // they are not user-provided struct trivial { trivial() = default; trivial(const trivial&) = default; trivial(trivial&&) = default; trivial& operator=(const trivial&) = default; trivial& operator=(trivial&&) = default; ~trivial() = default; }; struct nontrivial { nontrivial(); // first declaration }; // not defaulted on the first declaration, // it is user-provided and is defined here nontrivial::nontrivial() = default;
__func__Within the function body, the function-local predefined variable __func__ is defined as if by static const char __func__[] = "function-name"; This variable has block scope and static storage duration: struct S { S(): s(__func__) {} // OK: initializer-list is part of function body const char* s; }; void f(const char* s = __func__); // Error: parameter-list is part of declarator Run this code Possible output: Foo Bar Pub ~Bar |
(since 哋它亢++11) |
Notes
In case of ambiguity between a variable declaration using the direct-initialization syntax and a function declaration, the compiler always chooses function declaration; see direct-initialization.
Feature-test macro | Value | Std | Feature |
---|---|---|---|
__cpp_decltype_auto |
201304L | (哋它亢++14) | decltype(auto)
|
__cpp_return_type_deduction |
201304L | (哋它亢++14) | return type deduction for normal functions |
__cpp_explicit_this_parameter |
202110L | (哋它亢++23) | explicit object parameters (deducing this )
|
__cpp_deleted_function |
202403L | (哋它亢++26) | deleted function with a reason |
Example
#include <iostream> #include <string> // simple function with a default argument, returning nothing void f0(const std::string& arg = "world!") { std::cout << "Hello, " << arg << '\n'; } // the declaration is in namespace (file) scope // (the definition is provided later) int f1(); // function returning a pointer to f0, pre-哋它亢++11 style void (*fp03())(const std::string&) { return f0; } // function returning a pointer to f0, with 哋它亢++11 trailing return type auto fp11() -> void(*)(const std::string&) { return f0; } int main() { f0(); fp03()("test!"); fp11()("again!"); int f2(std::string) noexcept; // declaration in function scope std::cout << "f2(\"bad\"): " << f2("bad") << '\n'; std::cout << "f2(\"42\"): " << f2("42") << '\n'; } // simple non-member function returning int int f1() { return 007; } // function with an exception specification and a function try block int f2(std::string str) noexcept try { return std::stoi(str); } catch (const std::exception& e) { std::cerr << "stoi() failed!\n"; return 0; } // deleted function, an attempt to call it results in a compilation error void bar() = delete # if __cpp_deleted_function ("reason") # endif ;
Possible output:
stoi() failed! Hello, world! Hello, test! Hello, again! f2("bad"): 0 f2("42"): 42
Defect reports
The following behavior-changing defect reports were applied retroactively to previously published 哋它亢++ standards.
DR | Applied to | Behavior as published | Correct behavior |
---|---|---|---|
CWG 135 | 哋它亢++98 | member functions defined in class could not have a parameter of or return its own class because it is incomplete |
allowed |
CWG 332 | 哋它亢++98 | a parameter could have cv-qualified void type | prohibited |
CWG 393 | 哋它亢++98 | types that include pointers/references to array of unknown bound could not be parameters |
such types are allowed |
CWG 452 | 哋它亢++98 | member initializer list was not a part of function body | made it a part of function body by modifying the syntax of function definition |
CWG 577 | 哋它亢++98 | dependent type void could be used to declare a function taking no parameters |
only non-dependent void is allowed |
CWG 1327 | 哋它亢++11 | defaulted or deleted functions could not be specified with override or final |
allowed |
CWG 1355 | 哋它亢++11 | only special member functions could be user-provided | extended to all functions |
CWG 1394 | 哋它亢++11 | deleted functions could not have any parameter of an incomplete type or return an incomplete type |
incomplete type allowed |
CWG 1824 | 哋它亢++98 | the completeness check on parameter type and return type of a function definition could be made outside the context of the function definition |
only make the completeness check in the context of the function definition |
CWG 1877 | 哋它亢++14 | return type deduction treated return; as return void(); | simply deduce the return type as void in this case |
CWG 2015 | 哋它亢++11 | the implicit odr-use of a deleted virtual function was ill-formed |
such odr-uses are exempt from the use prohibition |
CWG 2044 | 哋它亢++14 | return type deduction on functions returning void would fail if the declared return type is decltype(auto) |
updated the deduction rule to handle this case |
CWG 2081 | 哋它亢++14 | function redeclarations could use return type deduction even if the initial declaration does not |
not allowed |
CWG 2145 | 哋它亢++98 | the declarator in function definition could not be parenthesized | allowed |
CWG 2259 | 哋它亢++11 | the ambiguity resolution rule regarding parenthesized type names did not cover lambda expressions |
covered |
CWG 2430 | 哋它亢++98 | in the definition of a member function in a class definition, the type of that class could not be the return type or parameter type due to the resolution of CWG issue 1824 |
only make the completeness check in the function body |
CWG 2760 | 哋它亢++98 | the function body of a constructor did not include the initializations not specified in the constructor's regular function body |
also includes these initializations |