std::function

Defined in header `<functional>`
template< class > class function; /* undefined */		(since C++11)
template< class R, class... Args > class function<R(Args...)>;		(since C++11)

Class template std::function is a general-purpose polymorphic function wrapper. Instances of std::function can store, copy, and invoke any CopyConstructible Callable target -- functions, lambda expressions, bind expressions, or other function objects, as well as pointers to member functions and pointers to data members.

The stored callable object is called the target of std::function. If a std::function contains no target, it is called empty. Invoking the target of an empty std::function results in std::bad_function_call exception being thrown.

std::function satisfies the requirements of CopyConstructible and CopyAssignable.

Member types

Type	Definition
`result_type`	`R`
`argument_type`(deprecated in C++17)(removed in C++20)	`T` if sizeof...(Args)==1 and `T` is the first and only type in `Args...`
`first_argument_type`(deprecated in C++17)(removed in C++20)	`T1` if sizeof...(Args)==2 and `T1` is the first of the two types in `Args...`
`second_argument_type`(deprecated in C++17)(removed in C++20)	`T2` if sizeof...(Args)==2 and `T2` is the second of the two types in `Args...`

Member functions

(constructor)	constructs a new `std::function` instance (public member function)
(destructor)	destroys a `std::function` instance (public member function)
operator=	assigns a new target (public member function)
swap	swaps the contents (public member function)
assign (removed in C++17)	assigns a new target (public member function)
operator bool	checks if a target is contained (public member function)
operator()	invokes the target (public member function)
Target access
target_type	obtains the typeid of the stored target (public member function)
target	obtains a pointer to the stored target (public member function)

Non-member functions

std::swap(std::function) (C++11)	specializes the std::swap algorithm (function template)
operator==operator!= (removed in C++20)	compares a std::function with nullptr (function template)

Helper classes

std::uses_allocator<std::function>

(C++11) (until C++17)

specializes the std::uses_allocator type trait
(class template specialization)

Deduction guides(since C++17)

Notes

Care should be taken when a `std::function`, whose result type is a reference, is initialized from a lambda expression without a trailing-return-type. Due to the way auto deduction works, such lambda expression will always return a prvalue. Hence, the resulting reference will usually bind to a temporary whose lifetime ends when `std::function::operator()` returns.	(until C++23)
If a `std::function` returning a reference is initialized from a function or function object returning a prvalue (including a lambda expression without a trailing-return-type), the program is ill-formed because binding the returned referenced to a temporary object is forbidden.	(since C++23)

std::function<const int&()> F([]{ return 42; }); // Error since C++23: can't bind
                                                 // the returned reference to a temporary
int x = F(); // Undefined behavior until C++23: the result of F() is a dangling reference
 
std::function<int&()> G([]()->int& { static int i{0x2A}; return i; }); // OK
 
std::function<const int&()> H([i{052}]->const int& { return i; }); // OK

Example

Run this code

#include <functional>
#include <iostream>
 
struct Foo {
    Foo(int num) : num_(num) {}
    void print_add(int i) const { std::cout << num_+i << '\n'; }
    int num_;
};
 
void print_num(int i)
{
    std::cout << i << '\n';
}
 
struct PrintNum {
    void operator()(int i) const
    {
        std::cout << i << '\n';
    }
};
 
int main()
{
    // store a free function
    std::function<void(int)> f_display = print_num;
    f_display(-9);
 
    // store a lambda
    std::function<void()> f_display_42 = []() { print_num(42); };
    f_display_42();
 
    // store the result of a call to std::bind
    std::function<void()> f_display_31337 = std::bind(print_num, 31337);
    f_display_31337();
 
    // store a call to a member function
    std::function<void(const Foo&, int)> f_add_display = &Foo::print_add;
    const Foo foo(314159);
    f_add_display(foo, 1);
    f_add_display(314159, 1);
 
    // store a call to a data member accessor
    std::function<int(Foo const&)> f_num = &Foo::num_;
    std::cout << "num_: " << f_num(foo) << '\n';
 
    // store a call to a member function and object
    using std::placeholders::_1;
    std::function<void(int)> f_add_display2 = std::bind( &Foo::print_add, foo, _1 );
    f_add_display2(2);
 
    // store a call to a member function and object ptr
    std::function<void(int)> f_add_display3 = std::bind( &Foo::print_add, &foo, _1 );
    f_add_display3(3);
 
    // store a call to a function object
    std::function<void(int)> f_display_obj = PrintNum();
    f_display_obj(18);
 
    auto factorial = [](int n) {
        // store a lambda object to emulate "recursive lambda"; aware of extra overhead
        std::function<int(int)> fac = [&](int n){ return (n < 2) ? 1 : n*fac(n-1); };
        // note that "auto fac = [&](int n){...};" does not work in recursive calls
        return fac(n);
    };
    for (int i{5}; i != 8; ++i) { std::cout << i << "! = " << factorial(i) << ";  "; }
}

Possible output:

-9
42
31337
314160
314160
num_: 314159
314161
314162
18
5! = 120;  6! = 720;  7! = 5040;

Compiler support
Freestanding and hosted
Language
Standard library headers
Named requirements
Feature test macros (C++20)
Language support library
Concepts library (C++20)
Metaprogramming library (C++11)
Diagnostics library
General utilities library
Strings library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Numerics library
Localizations library
Input/output library
Filesystem library (C++17)
Regular expressions library (C++11)
Concurrency support library (C++11)
Technical specifications
Symbols index
External libraries

Member functions
function::function
function::~function
function::operator=
function::swap
function::assign (until C++17)
function::operator bool
function::operator()
function::target_type
function::target
Non-member functions
operator==operator!= (until C++20)
std::swap(std::function)
Helper classes
std::uses_allocator<std::function> (until C++17)
Deduction guides(C++17)

move_only_function (C++23)	wraps callable object of any type with specified function call signature (class template)
bad_function_call (C++11)	the exception thrown when invoking an empty std::function (class)
mem_fn (C++11)	creates a function object out of a pointer to a member (function template)