Declaring functions

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.

The type of the function being declared is composed from the return type (provided by the decl-specifier-seq of the declaration syntax) and the function declarator.

(see Declarations for the other forms of the declarator syntax).

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
};

The return type of a function cannot be a function type or an array type (but can be a pointer or reference to those).

int x = 1;
auto f() { return x; } // return type is int
const auto& f() { return x; } // return type is const int&

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))

auto f(bool val)
{
    if(val) return 123; // deduces return type int
    else    return 3.14f; // deduces return type float: error
}

auto f() {} // returns void
auto g() { return f(); } // returns void
auto* x() {} // error: cannot deduce auto* from void

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
}

auto func () { return {1, 2, 3}; }  // error

struct F
{
    virtual auto f() { return 2; } // error
};

auto f();               // declared, not yet defined
auto f() { return 42; } // defined, return type is int
int f();                // error, cannot use the deduced type
decltype(auto) f();     // error, different kind of deduction
auto f();               // re-declared, OK
 
template<typename T>
struct A { friend T frf(T); };
auto frf(int i) { return i; } // not a friend of A<int>

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

template<typename T> auto g(T t) { return t; } // #1
template auto g(int);      // OK, return type is int
//template char g(char);   // error, no matching template
 
template<> auto g(double); // OK, forward declaration with unknown return type
template<typename T> T g(T t) { return t; } // OK, not equivalent to #1
template char g(char);     // OK, now there is a matching template
template auto g(float);    // still matches #1
// void h() { return g(42); } // error, ambiguous

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

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.

int f(int a, int *p, int (*(*x)(double))[3]);

int f(int a = 7, int *p = nullptr, int (*(*x)(double))[3] = nullptr);

int f(int, int *, int (*(*)(double))[3]);

int f(int = 7, int * = nullptr, int (*(*)(double))[3] = nullptr);

int printf(const char* fmt, ...);

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 C++11), and it has virtually no effect.

void f(auto (auto::*)(auto)); // #1
template<typename T, typename U, typename V> void f(T (U::*)(V)); // same as #1
 
void g1(const C1*, C2&); // #2 (assuming C1 and C2 are concepts
template<C1 T, C2 U> void g1(const T*, U&); // same as #2

Parameter names declared in function declarations are usually for only self-documenting purposes. They are used (but remain optional) in function definitions.

The type of each function parameter in the parameter list is determined according to the following rules:

Because of these rules, the following function declarations declare exactly the same function:

int f(char s[3]);
int f(char[]);
int f(char* s);
int f(char* const);
int f(char* volatile s);

The following declarations also declare exactly the same function.

int f(int());
int f(int (*g)());

The comma before the ellipsis parameter that indicates variadic arguments is optional, 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 is used is the implementation of std::is_function.

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:

where function-body is one of the following.

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.

The parameter types, as well as the return type of a function cannot be incomplete class types, except for deleted functions (since C++11). The completeness check is made in the context of the function body, which allows member functions to return the class in which they are defined (or its enclosing class), even if it's 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
}

struct sometype
{
    void* operator new(std::size_t) = delete;
    void* operator new[](std::size_t) = delete;
};
sometype* p = new sometype; // error, attempts to call deleted sometype::operator new

struct sometype { sometype(); };
sometype::sometype() = delete; // error: must be deleted on the first declaration

static const char __func__[] = "function-name";

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

Example 1: non-member functions

#include <iostream>
#include <string>
 
// declaration in namespace(file) scope
// (the definition is provided later)
int f1();
 
// simple function with a default argument, returning nothing
void f0(const std::string& arg = "world")
{
    std::cout << "Hello, " << arg << '\n';
}
 
// function returning a pointer to f0
auto fp11() -> void(*)(const std::string&)
{
    return f0;
}
 
// function returning a pointer to f0, pre-C++11 style
void (*fp03())(const std::string&)
{
    return f0;
}
 
int main()
{
    f0();
    fp11()("test");
    fp03()("again");
    int f2(std::string); // declaration in function scope
    std::cout << f2("bad12") << '\n';
}
 
// simple non-member function returning int
int f1()
{
    return 42;
}
 
// 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;
}

Hello, world
Hello, test
Hello, again
stoi() failed!
0

Defect reports

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