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 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)
2022.07.31 | http://cppreference.com |