Difference between revisions of "cpp/utility/functional/function"
0xDEADBEEF (Talk | contribs) m (Redirected page to enwiki:Rust (programming language)) |
m (~ added link to std::copyable_function) |
||
(2 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
− | # | + | {{cpp/title|function}} |
+ | {{cpp/utility/functional/function/navbar}} | ||
+ | {{dcl begin}} | ||
+ | {{dcl header|functional}} | ||
+ | {{dcl|since=c++11| | ||
+ | template< class > | ||
+ | class function; /* undefined */ | ||
+ | }} | ||
+ | {{dcl|since=c++11| | ||
+ | template< class R, class... Args > | ||
+ | class function<R(Args...)>; | ||
+ | }} | ||
+ | {{dcl end}} | ||
+ | |||
+ | Class template {{tt|std::function}} is a general-purpose polymorphic function wrapper. Instances of {{tt|std::function}} can store, copy, and invoke any {{named req|CopyConstructible}} {{named req|Callable}} ''target'' -- functions (via pointers thereto), [[cpp/language/lambda|lambda expressions]], [[cpp/utility/functional/bind|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 {{tt|std::function}}. If a {{tt|std::function}} contains no target, it is called ''empty''. Invoking the ''target'' of an ''empty'' {{tt|std::function}} results in {{lc|std::bad_function_call}} exception being thrown. | ||
+ | |||
+ | {{tt|std::function}} satisfies the requirements of {{named req|CopyConstructible}} and {{named req|CopyAssignable}}. | ||
+ | |||
+ | ===Member types=== | ||
+ | {{dsc begin}} | ||
+ | {{dsc hitem|Type|Definition}} | ||
+ | {{dsc|{{tt|result_type}}|{{tt|R}}}} | ||
+ | {{dsc|{{tt|argument_type}}<br>{{mark|deprecated in C++17}}{{mark until c++20|removed=yes}}|{{tt|T}} if {{c|1=sizeof...(Args)==1}} and {{tt|T}} is the first and only type in {{tt|Args...}}}} | ||
+ | {{dsc|{{tt|first_argument_type}}<br>{{mark|deprecated in C++17}}{{mark until c++20|removed=yes}}|{{tt|T1}} if {{c|1=sizeof...(Args)==2}} and {{tt|T1}} is the first of the two types in {{tt|Args...}} }} | ||
+ | {{dsc|{{tt|second_argument_type}}<br>{{mark|deprecated in C++17}}{{mark until c++20|removed=yes}}|{{tt|T2}} if {{c|1=sizeof...(Args)==2}} and {{tt|T2}} is the second of the two types in {{tt|Args...}}}} | ||
+ | {{dsc end}} | ||
+ | |||
+ | ===Member functions=== | ||
+ | {{dsc begin}} | ||
+ | {{dsc inc|cpp/utility/functional/function/dsc constructor}} | ||
+ | {{dsc inc|cpp/utility/functional/function/dsc destructor}} | ||
+ | {{dsc inc|cpp/utility/functional/function/dsc operator{{=}}}} | ||
+ | {{dsc inc|cpp/utility/functional/function/dsc swap}} | ||
+ | {{dsc inc|cpp/utility/functional/function/dsc assign}} | ||
+ | {{dsc inc|cpp/utility/functional/function/dsc operator_bool}} | ||
+ | {{dsc inc|cpp/utility/functional/function/dsc operator()}} | ||
+ | |||
+ | {{dsc h2|Target access}} | ||
+ | {{dsc inc|cpp/utility/functional/function/dsc target_type}} | ||
+ | {{dsc inc|cpp/utility/functional/function/dsc target}} | ||
+ | {{dsc end}} | ||
+ | |||
+ | ===Non-member functions=== | ||
+ | {{dsc begin}} | ||
+ | {{dsc inc|cpp/utility/functional/function/dsc swap2}} | ||
+ | {{dsc inc|cpp/utility/functional/function/dsc operator_cmp}} | ||
+ | {{dsc end}} | ||
+ | |||
+ | ===Helper classes=== | ||
+ | {{dsc begin}} | ||
+ | {{dsc inc|cpp/utility/functional/function/dsc uses_allocator}} | ||
+ | {{dsc end}} | ||
+ | |||
+ | ===[[cpp/utility/functional/function/deduction_guides|Deduction guides]]{{mark since c++17}}=== | ||
+ | |||
+ | ===Notes=== | ||
+ | {{rrev multi | ||
+ | |rev1= | ||
+ | Care should be taken when a {{tt|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 {{rlt|operator()|std::function::operator()}} returns. | ||
+ | |since2=c++23|rev2= | ||
+ | If a {{tt|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. | ||
+ | }} | ||
+ | |||
+ | {{source|1= | ||
+ | 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=== | ||
+ | {{example | ||
+ | |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'; | ||
+ | } | ||
+ | |p = true|output= | ||
+ | -9 | ||
+ | 42 | ||
+ | 31337 | ||
+ | 314160 | ||
+ | 314160 | ||
+ | num_: 314159 | ||
+ | 314161 | ||
+ | 314162 | ||
+ | 18 | ||
+ | 5! = 120; 6! = 720; 7! = 5040; | ||
+ | }} | ||
+ | |||
+ | ===See also=== | ||
+ | {{dsc begin}} | ||
+ | {{dsc inc|cpp/utility/functional/dsc move_only_function}} | ||
+ | {{dsc inc|cpp/utility/functional/dsc copyable_function}} | ||
+ | {{dsc inc|cpp/utility/functional/dsc bad_function_call}} | ||
+ | {{dsc inc|cpp/utility/functional/dsc mem_fn}} | ||
+ | {{dsc|'''{{ltt|cpp/language/typeid|typeid}}'''|queries information of a type, returning a {{tt|std::type_info}} object representing the type}} | ||
+ | {{dsc end}} | ||
+ | |||
+ | {{langlinks|de|es|fr|it|ja|pt|ru|zh}} |
Latest revision as of 19:37, 4 July 2024
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.
Contents |
[edit] 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...
|
[edit] 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) | |
(removed in C++17) |
assigns a new target (public member function) |
checks if a 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) |
[edit] Non-member functions
(C++11) |
specializes the std::swap algorithm (function template) |
(removed in C++20) |
compares a std::function with nullptr (function template) |
[edit] Helper classes
(C++11) (until C++17) |
specializes the std::uses_allocator type trait (class template specialization) |
[edit] Deduction guides(since C++17)
[edit] Notes
Care should be taken when a |
(until C++23) |
If a |
(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
[edit] 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); 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;
[edit] See also
(C++23) |
move-only wrapper of any callable object that supports qualifiers in a given call signature (class template) |
(C++26) |
copyable wrapper of any copy constructible callable object that supports qualifiers in a given call signature (class template) |
(C++11) |
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) |
typeid | queries information of a type, returning a std::type_info object representing the type
|