# std::function

From cppreference.com
< cpp‎ | utility‎ | functional

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 (via pointers thereto), 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 reference 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) << ";  ";
        std::cout << '\n';
    }

Possible output:

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

### See also

move_only_function (C++23) | move-only wrapper of any callable object that supports qualifiers in a given call signature (class template)
copyable_function (C++26) | copyable wrapper of any copy constructible callable object that supports qualifiers in a given call signature (class template)
function_ref (C++26) | non-owning wrapper of any callable object (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)
`typeid` | queries information of a type, returning a std::type_info object representing the type

Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/utility/functional/function&oldid=178280"