home | help 
std::function(3)	       C++ Standard Libary		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	CopyCon-
     structible
	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 Copy-
     Assignable.

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 reference to a temporary object is
	forbidden.

      std::function<const int&()> F([] { return 42; }); //  Error  since  C++23:
     can't bind
							//  the  returned refer-
     ence 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  re-
     cursive 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  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 mem-
     ber
	(C++11) 	   (function template)
	typeid		    queries  information  of   a   type,   returning   a
     std::type_info object
			   representing the type

http://cppreference.com 	   2024.06.10			std::function(3)
home | help