Share via


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  

See Also

mem_fn Function
reference_wrapper Class