function Class
The latest version of this topic can be found at function Class.
Wrapper for a callable object.
Syntax
template <class Fty>
class function // Fty of type Ret(T1, T2, ..., TN)
: public unary_function<T1, Ret> // when Fty is Ret(T1)
: public binary_function<T1, T2, Ret> // when Fty is Ret(T1, T2)
{
public:
typedef Ret result_type;
function();
function(nullptr_t);
function(const function& right);
template <class Fty2>
function(Fty2 fn);
template <class Fty2, class Alloc>
function (reference_wrapper<Fty2>, const Alloc& _Ax);
template <class Fty2, class Alloc>
void assign(Fty2, const Alloc& _Ax);
template <class Fty2, class Alloc>
void assign(reference_wrapper<Fty2>, const Alloc& _Ax);
function& operator=(nullptr_t);
function& operator=(const function&);
template <class Fty2>
function& operator=(Fty2);
template <class Fty2>
function& operator=(reference_wrapper<Fty2>);
void swap(function&);
explicit operator bool() const;
result_type operator()(T1, T2, ....., TN) const;
const std::type_info& target_type() const;
template <class Fty2>
Fty2 *target();
template <class Fty2>
const Fty2 *target() const;
template <class Fty2>
void operator==(const Fty2&) const = delete;
template <class Fty2>
void operator!=(const Fty2&) const = delete;
};
Parameters
Fty
The function type to wrap.
_Ax
The allocator function.
Remarks
The template class is a call wrapper whose call signature is Ret(T1, T2, ..., TN). You use it to enclose a variety of callable objects in a uniform wrapper.
Some member functions take an operand that names the desired target object. You can specify such an operand in several ways:
fn -- the callable object fn; after the call the function object holds a copy of fn
fnref -- the callable object named by fnref.get(); after the call the function object holds a reference to fnref.get()
right -- the callable object, if any, held by the function object right
npc -- a null pointer; after the call the function object is empty
In all cases, INVOKE(f, t1, t2, ..., tN), where f is the callable object and t1, t2, ..., tN are lvalues of types T1, T2, ..., TN respectively, must be well-formed and, if Ret is not void, convertible to Ret.
An empty function object does not hold a callable object or a reference to a callable object.
Constructors
| function::function | Constructs a wrapper that either is empty or stores a callable object of arbitrary type with a fixed signature. |
Typedefs
| function::result_type | The return type of the stored callable object. |
Member Functions
| function::assign | Assigns a callable object to this function object. |
| function::swap | Swap two callable objects. |
| function::target | Tests if stored callable object is callable as specified. |
| function::target_type | Gets type information on the callable object. |
Operators
| function::operator unspecified | Tests if stored callable object exists. |
| function::operator() | Calls a callable object. |
| function::operator= | Replaces the stored callable object. |
Requirements
Header: <functional>
Namespace: std
function::assign
Assigns a callable object to this function object.
template <class Fx, class Alloc>
void assign(
Fx _Func,
const Alloc& _Ax);
template <class Fx, class Alloc>
void assign(
reference_wrapper<Fx> _Fnref,
const Alloc& _Ax);
Parameters
_Func
A callable object.
_Fnref
A reference wrapper that contains a callable object.
_Ax
An allocator object.
Remarks
The member functions each replace the callable object held by *this with the callable object passed as the operand. Both allocate storage with the allocator object _Ax.
function::function
Constructs a wrapper that either is empty or stores a callable object of arbitrary type with a fixed signature.
function
();
function
(nullptr_t npc);
function
(const function& right);
template <class Fx>
function
(Fx _Func);
template <class Fx>
function
(reference_wrapper<Fx> _Fnref);
template <class Fx, class Alloc>
function
(
Fx _Func,
const Alloc& _Ax);
template <class Fx, class Alloc>
function
(
reference_wrapper<Fx> _Fnref,
const Alloc& _Ax);
Parameters
right
The function object to copy.
Fx
The type of the callable object.
_Func
The callable object to wrap.
Alloc
The allocator type.
_Ax
The allocator.
_Fnref
The callable object reference to wrap.
Remarks
The first two constructors construct an empty function object. The next three constructors construct a function object that holds the callable object passed as the operand. The last two constructors allocate storage with the allocator object _Ax.
Example
// std_tr1__functional__function_function.cpp
// compile with: /EHsc
#include <functional>
#include <iostream>
#include <vector>
int square(int val)
{
return val * val;
}
class multiply_by
{
public:
explicit multiply_by(const int n) : m_n(n) { }
int operator()(const int x) const
{
return m_n * x;
}
private:
int m_n;
};
int main()
{
typedef std::vector< std::function<int (int)> > vf_t;
vf_t v;
v.push_back(square);
v.push_back(std::negate<int>());
v.push_back(multiply_by(3));
for (vf_t::const_iterator i = v.begin(); i != v.end(); ++i)
{
std::cout << (*i)(10) << std::endl;
}
std::function<int (int)> f = v[0];
std::function<int (int)> g;
if (f) {
std::cout << "f is non-empty (correct)." << std::endl;
} else {
std::cout << "f is empty (can't happen)." << std::endl;
}
if (g) {
std::cout << "g is non-empty (can't happen)." << std::endl;
} else {
std::cout << "g is empty (correct)." << std::endl;
}
return 0;
}
100
-10
30
f is non-empty (correct).
g is empty (correct).
function::operator unspecified
Tests if stored callable object exists.
operator unspecified();
Remarks
The operator returns a value that is convertible to bool with a true value only if the object is not empty. You use it to test whether the object is empty.
Example
// std_tr1__functional__function_operator_bool.cpp
// compile with: /EHsc
#include <functional>
#include <iostream>
int neg(int val)
{
return (-val);
}
int main()
{
std::function<int (int)> fn0;
std::cout << std::boolalpha << "not empty == " << (bool)fn0 << std::endl;
std::function<int (int)> fn1(neg);
std::cout << std::boolalpha << "not empty == " << (bool)fn1 << std::endl;
return (0);
}
not empty == false
not empty == true
function::operator()
Calls a callable object.
result_type operator()(T1 t1,
T2 t2, ...,
TN tN);
Parameters
TN
The type of the Nth call argument.
tN
The Nth call argument.
Remarks
The member function returns INVOKE(fn, t1, t2, ..., tN, Ret), where fn is the target object stored in *this. You use it to call the wrapped callable object.
Example
// std_tr1__functional__function_operator_call.cpp
// compile with: /EHsc
#include <functional>
#include <iostream>
int neg(int val)
{
return (-val);
}
int main()
{
std::function<int (int)> fn1(neg);
std::cout << std::boolalpha << "empty == " << !fn1 << std::endl;
std::cout << "val == " << fn1(3) << std::endl;
return (0);
}
empty == false
val == -3
function::operator=
Replaces the stored callable object.
function& operator=(null_ptr_type npc);
function& operator=(const function& right);
template <class Fty>
function& operator=(Fty fn);
template <class Fty>
function& operator=(reference_wrapper<Fty> fnref);
Parameters
npc
A null pointer constant.
right
The function object to copy.
fn
The callable object to wrap.
fnref
The callable object reference to wrap.
Remarks
The operators each replace the callable object held by *this with the callable object passed as the operand.
Example
// std_tr1__functional__function_operator_as.cpp
// compile with: /EHsc
#include <functional>
#include <iostream>
int neg(int val)
{
return (-val);
}
int main()
{
std::function<int (int)> fn0(neg);
std::cout << std::boolalpha << "empty == " << !fn0 << std::endl;
std::cout << "val == " << fn0(3) << std::endl;
std::function<int (int)> fn1;
fn1 = 0;
std::cout << std::boolalpha << "empty == " << !fn1 << std::endl;
fn1 = neg;
std::cout << std::boolalpha << "empty == " << !fn1 << std::endl;
std::cout << "val == " << fn1(3) << std::endl;
fn1 = fn0;
std::cout << std::boolalpha << "empty == " << !fn1 << std::endl;
std::cout << "val == " << fn1(3) << std::endl;
fn1 = std::cref(fn1);
std::cout << std::boolalpha << "empty == " << !fn1 << std::endl;
std::cout << "val == " << fn1(3) << std::endl;
return (0);
}
empty == false
val == -3
empty == true
empty == false
val == -3
empty == false
val == -3
empty == false
val == -3
function::result_type
The return type of the stored callable object.
typedef Ret result_type;
Remarks
The typedef is a synonym for the type Ret in the template's call signature. You use it to determine the return type of the wrapped callable object.
Example
// std_tr1__functional__function_result_type.cpp
// compile with: /EHsc
#include <functional>
#include <iostream>
int neg(int val)
{
return (-val);
}
int main()
{
std::function<int (int)> fn1(neg);
std::cout << std::boolalpha << "empty == " << !fn1 << std::endl;
std::function<int (int)>::result_type val = fn1(3);
std::cout << "val == " << val << std::endl;
return (0);
}
empty == false
val == -3
function::swap
Swap two callable objects.
void swap(function& right);
Parameters
right
The function object to swap with.
Remarks
The member function swaps the target objects between *this and right. It does so in constant time and throws no exceptions.
Example
// std_tr1__functional__function_swap.cpp
// compile with: /EHsc
#include <functional>
#include <iostream>
int neg(int val)
{
return (-val);
}
int main()
{
std::function<int (int)> fn0(neg);
std::cout << std::boolalpha << "empty == " << !fn0 << std::endl;
std::cout << "val == " << fn0(3) << std::endl;
std::function<int (int)> fn1;
std::cout << std::boolalpha << "empty == " << !fn1 << std::endl;
std::cout << std::endl;
fn0.swap(fn1);
std::cout << std::boolalpha << "empty == " << !fn0 << std::endl;
std::cout << std::boolalpha << "empty == " << !fn1 << std::endl;
std::cout << "val == " << fn1(3) << std::endl;
return (0);
}
empty == false
val == -3
empty == true
empty == true
empty == false
val == -3
function::target
Tests if stored callable object is callable as specified.
template <class Fty2>
Fty2 *target();
template <class Fty2>
const Fty2 *target() const;
Parameters
Fty2
The target callable object type to test.
Remarks
The type Fty2 must be callable for the argument types T1, T2, ..., TN and the return type Ret. If target_type() == typeid(Fty2), the member template function returns the address of the target object; otherwise, it returns 0.
A type Fty2 is callable for the argument types T1, T2, ..., TN and the return type Ret if, for lvalues fn, t1, t2, ..., tN of types Fty2, T1, T2, ..., TN, respectively, INVOKE(fn, t1, t2, ..., tN) is well-formed and, if Ret is not void, convertible to Ret.
Example
// std_tr1__functional__function_target.cpp
// compile with: /EHsc
#include <functional>
#include <iostream>
int neg(int val)
{
return (-val);
}
int main()
{
typedef int (*Myfun)(int);
std::function<int (int)> fn0(neg);
std::cout << std::boolalpha << "empty == " << !fn0 << std::endl;
std::cout << "no target == " << (fn0.target<Myfun>() == 0) << std::endl;
Myfun *fptr = fn0.target<Myfun>();
std::cout << "val == " << (*fptr)(3) << std::endl;
std::function<int (int)> fn1;
std::cout << std::boolalpha << "empty == " << !fn1 << std::endl;
std::cout << "no target == " << (fn1.target<Myfun>() == 0) << std::endl;
return (0);
}
empty == false
no target == false
val == -3
empty == true
no target == true
function::target_type
Gets type information on the callable object.
const std::type_info& target_type() const;
Remarks
The member function returns typeid(void) if *this is empty, otherwise it returns typeid(T), where T is the type of the target object.
Example
// std_tr1__functional__function_target_type.cpp
// compile with: /EHsc
#include <functional>
#include <iostream>
int neg(int val)
{
return (-val);
}
int main()
{
std::function<int (int)> fn0(neg);
std::cout << std::boolalpha << "empty == " << !fn0 << std::endl;
std::cout << "type == " << fn0.target_type().name() << std::endl;
std::function<int (int)> fn1;
std::cout << std::boolalpha << "empty == " << !fn1 << std::endl;
std::cout << "type == " << fn1.target_type().name() << std::endl;
return (0);
}
empty == false
type == int (__cdecl*)(int)
empty == true
type == void