std::function

 

C++

Compiler support

Freestanding and hosted

Language

Standard library

Standard library headers

Named requirements

Feature test macros(C++20)

Language support library

Concepts library(C++20)

Diagnostics library

Memory management library

Metaprogramming library(C++11)

General utilities library

Containers library

Iterators library

Ranges library(C++20)

Algorithms library

Strings library

Text processing library

Numerics library

Date and time library

Input/output library

Filesystem library(C++17)

Concurrency support library(C++11)

Execution control library(C++26)

Technical specifications

Symbols index

External libraries

 

Utilities library

Language support Type support (basic types, RTTI) Library feature-test macros(C++20) Program utilities Variadic functions initializer_list (C++11) is_constant_evaluated (C++20) is_within_lifetime (C++26) source_location (C++20) Coroutine support(C++20) Contract support(C++26) Three-way comparison three_way_comparablethree_way_comparable_with (C++20)(C++20) strong_ordering (C++20) weak_ordering (C++20) partial_ordering (C++20) common_comparison_category (C++20) compare_three_way_result (C++20) compare_three_way (C++20) strong_order (C++20) weak_order (C++20) partial_order (C++20) compare_strong_order_fallback (C++20) compare_weak_order_fallback (C++20) compare_partial_order_fallback (C++20)   is_eqis_ltis_lteq (C++20)(C++20)(C++20)   is_neqis_gtis_gteq (C++20)(C++20)(C++20)

General utilities Function objects Bit manipulation(C++20) bitset hash (C++11) Relational operators(deprecated in C++20) rel_ops::operator!=rel_ops::operator>    rel_ops::operator<=rel_ops::operator>= Integer comparison functions cmp_equalcmp_lesscmp_less_than (C++20)(C++20)(C++20)   cmp_not_equalcmp_greatercmp_greater_than (C++20)(C++20)(C++20) in_range (C++20) Swap and type operations swap ranges::swap (C++20) exchange (C++14) declval (C++11) to_underlying (C++23) forward (C++11) forward_like (C++23) move (C++11) move_if_noexcept (C++11) as_const (C++17) Common vocabulary types pair tuple (C++11) optional (C++17) any (C++17) variant (C++17) tuple_size (C++11) tuple_element (C++11) apply (C++17) make_from_tuple (C++17) expected (C++23)

 

Function objects

Function wrappers function (C++11) move_only_function (C++23) copyable_function (C++26) function_ref (C++26) mem_fn (C++11) bad_function_call (C++11)	Partial function application bind_frontbind_back (C++20)(C++23) bind (C++11) is_bind_expression (C++11) is_placeholder (C++11) _1, _2, _3, ... (C++11)
Function invocation invokeinvoke_r (C++17)(C++23) Identity function object identity (C++20)	Reference wrappers reference_wrapper (C++11) refcref (C++11)(C++11) unwrap_referenceunwrap_ref_decay (C++20)(C++20)
Operator wrappers plus minus negate multiplies divides modulus bit_and bit_or bit_not (C++14)   bit_xor equal_to not_equal_to greater less greater_equal less_equal logical_and logical_or logical_not	Transparent operator wrappers plus<> (C++14) minus<> (C++14) negate<> (C++14) multiplies<> (C++14)   divides<> (C++14) modulus<> (C++14) bit_and<> (C++14) bit_or<> (C++14) bit_not<> (C++14) bit_xor<> (C++14) equal_to<> (C++14) not_equal_to<> (C++14) greater<> (C++14) less<> (C++14) greater_equal<> (C++14) less_equal<> (C++14) logical_and<> (C++14) logical_or<> (C++14) logical_not<> (C++14)
Negators not_fn (C++17) Searchers default_searcher (C++17) boyer_moore_searcher (C++17) boyer_moore_horspool_searcher (C++17)	Constrained comparators ranges::equal_to (C++20) ranges::not_equal_to (C++20) ranges::greater (C++20) ranges::less (C++20) ranges::greater_equal (C++20) ranges::less_equal (C++20) compare_three_way (C++20)
Old binders and adaptors
unary_function (until C++17*) binary_function (until C++17*) ptr_fun (until C++17*) pointer_to_unary_function (until C++17*) pointer_to_binary_function (until C++17*)   mem_fun (until C++17*) mem_fun_tmem_fun1_tconst_mem_fun_tconst_mem_fun1_t (until C++17*)(until C++17*)(until C++17*)(until C++17*) not1 (until C++20*) not2 (until C++20*)	binder1stbinder2nd (until C++17*)(until C++17*) bind1stbind2nd (until C++17*)(until C++17*) mem_fun_ref (until C++17*) mem_fun_ref_tmem_fun1_ref_tconst_mem_fun_ref_tconst_mem_fun1_ref_t (until C++17*)(until C++17*)(until C++17*)(until C++17*) unary_negate (until C++20*) binary_negate (until C++20*)

 

std::function

Member functions

function::function

function::~function

function::operator=

function::swap

function::assign (until C++17)

function::operator bool

function::operator()

function::target_type

function::target

Non-member functions

operator==operator!= (until C++20)

swap(std::function)

Helper classes

uses_allocator<std::function> (until C++17)

Deduction guides(C++17)

 

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 CopyConstructibleCallabletarget -- 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 emptystd::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)

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<constint&()> F([]{return42;});// Error since C++23: can't bind// the returned reference to a temporaryint x = F();// Undefined behavior until C++23: the result of F() is a dangling reference   std::function<int&()> G([]()->int&{staticint i{0x2A};return i;});// OK   std::function<constint&()> H([i{052}]->constint&{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 objectusing 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 callsreturn 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