std::function

From cppreference.com
< cpplrm; | utilitylrm; | functional
Function objects
Function wrappers
function
(C++11)
(C++11)
Bind
(C++11)
Function invocation
(C++17)
Identity function object
(C++20)
Reference wrappers
(C++11)(C++11)
Operator wrappers
Negators
(C++17)
Searchers
Old binders and adaptors
(until C++17)
(until C++17)
(until C++17)
(until C++17)
(until C++17)(until C++17)(until C++17)(until C++17)
(until C++20)
(until C++20)
(until C++17)(until C++17)
(until C++17)(until C++17)

(until C++17)
(until C++17)(until C++17)(until C++17)(until C++17)
(until C++20)
(until C++20)
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 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

constructs a new std::function instance
(public member function)
destroys a std::function instance
(public member function)
assigns a new target
(public member function)
swaps the contents
(public member function)
(until C++17)
assigns a new target
(public member function)
checks if a valid target is contained
(public member function)
invokes the target
(public member function)
Target access
obtains the typeid of the stored target
(public member function)
obtains a pointer to the stored target
(public member function)

Non-member functions

specializes the std::swap algorithm
(function template)
compares a std::function with nullptr
(function template)

Helper classes

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

Deduction guides(since C++17)

Example

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

Output:

-9
42
31337
314160
314160
num_: 314159
314161
314162
18

See also

the exception thrown when invoking an empty std::function
(class)
(C++11)
creates a function object out of a pointer to a member
(function template)