std::function(3)

NAME
std::function - std::function

Synopsis
   Defined in header <functional>
   template< class > (since C++11)
   class function; /* undefined */
   template< class R, class... Args > (since C++11)
   class function<R(Args...)>;
   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 T if sizeof...(Args)==1 and T is the
   C++20) first and only type in Args...
   first_argument_type(deprecated in T1 if sizeof...(Args)==2 and T1 is the
   C++17)(removed in C++20) first of the two types in Args...
   second_argument_type(deprecated in T2 if sizeof...(Args)==2 and T2 is the
   C++17)(removed in C++20) 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 assigns a new target
   (removed in C++17) (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) specializes the std::swap algorithm
   (C++11) (function template)
   operator== compares a std::function with nullptr
   operator!= (function template)
   (removed in C++20)

Helper classes
   std::uses_allocator<std::function> specializes the std::uses_allocator type trait
   (C++11) (until C++17) (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 (until C++23)
   expression will always return a prvalue. Hence, the resulting
   reference will usually bind to a temporary whose lifetime ends when
   std::function::operator() returns.
   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 (since C++23)
   because binding the returned referenced to a temporary object is
   forbidden.
 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;

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