<functional>

Article
07/11/2012

Defines Standard Template Library (STL) functions that help construct function objects, also known as functors, and their binders. A function object is an object of a type that defines operator(). A function object can be a function pointer, but more typically, the object is used to store additional information that can be accessed during a function call.

#include <functional>

Remarks

Algorithms require two types of function objects: unary and binary. Unary function objects require one argument, and binary function objects require two arguments. A function object and function pointers can be passed as a predicate to an algorithm, but function objects are also adaptable and increase the scope, flexibility, and efficiency of the STL. If, for example, a value needed to be bound to a function before being passed to an algorithm, then a function pointer could not be used. Function adaptors convert function pointers into adaptable function objects that can be bound to a value. The header <functional> also contains member function adaptors that allow member functions to be called as adaptable function objects. Functions are adaptable if they have nested type declarations specifying their argument and return types. The C++ Standard requires that this adaptability is implemented by having all standard object classes inherit from the unary_function or binary_function base classes. Function objects and their adaptors allow the STL to upgrade existing applications and help integrate the STL into the C++ programming environment.

TR1 Extensions

The following features are added in the Visual C++ implementation of TR1:

A call signature is the name of a return type followed by a parenthesized comma-separated list of zero or more argument types.
A call wrapper is an object of a call wrapper type.
A call wrapper type is a type that holds a callable object and supports a call operation that forwards to that object.
A callable object is an object of a callable type.
A callable type is a pointer to function, a pointer to member function, a pointer to member data, or a class type whose objects can appear immediately to the left of a function call operator.
A target object is the callable object held by a call wrapper object.

The pseudo-function INVOKE(f, t1, t2, ..., tN) means one of the following things:

(t1.*f)(t2, ..., tN) when f is a pointer to member function of class T and t1 is an object of type T or a reference to an object of type T or a reference to an object of a type derived from T.
((*t1).*f)(t2, ..., tN) when f is a pointer to member function of class T and t1 is not one of the types described in the previous item.
t1.*f when f is a pointer to member data of class T and t1 is an object of type T or a reference to an object of type T or a reference to an object of a type derived from T.
(*t1).*f when f is a pointer to member data of class class T and t1 is not one of the types described in the previous item.
f(t1, t2, ..., tN) in all other cases.

The pseudo-function INVOKE(f, t1, t2, ..., tN, R) means INVOKE(f, t1, t2, ..., tN) implicitly converted to R.

If a call wrapper has a weak result type, the type of its member type result_type is based on the type T of the target object of the wrapper, as follows:

If T is a pointer to function, result_type is a synonym for the return type of T.
If T is a pointer to member function, result_type is a synonym for the return type of T.
If T is a pointer to data member, result_type is a synonym for the declared type of the data member.
If T is a class type that has a member type result_type, then result_type is a synonym for T::result_type.
Otherwise, there is no member result_type.

Every call wrapper has a copy constructor. A simple call wrapper is a call wrapper that has an assignment operator and whose copy constructor and assignment operator do not throw exceptions. A forwarding call wrapper is a call wrapper that can be called by using an argument list t1, t2, ..., tN, where each ti is an lvalue.

The call wrappers defined in this header support function call operators that have arguments of types T1, T2, ..., TN, where 0 <= N <= NMAX. In this implementation, the value of NMAX is 10.

Classes

bad_function_call	A class that describes an exception thrown to indicate that a call to operator() on a function object failed because the object was empty.
binary_negate	A template class providing a member function that negates the return value of a specified binary function.
binder1st	A template class providing a constructor that converts a binary function object into a unary function object by binding the first argument of the binary function to a specified value.
binder2nd	A template class providing a constructor that converts a binary function object into a unary function object by binding the second argument of the binary function to a specified value.
const_mem_fun_ref_t	An adapter class that allows a const member function that takes no arguments to be called as a unary function object when initialized with a reference argument.
const_mem_fun_t	An adapter class that allows a const member function that takes no arguments to be called as a unary function object when initialized with a pointer argument.
const_mem_fun1_ref_t	An adapter class that allows a const member function that takes a single argument to be called as a binary function object when initialized with a reference argument.
const_mem_fun1_t	An adapter class that allows a const member function that takes a single argument to be called as a binary function object when initialized with a pointer argument.
function	A class that wraps a callable object.
hash	A class that computes a hash code for a value.
is_bind_expression	A class that tests if a particular type is generated by calling bind.
is_placeholder	A class that tests if a particular type is a placeholder.
mem_fun_ref_t	An adapter class that allows a non_const member function that takes no arguments to be called as a unary function object when initialized with a reference argument.
mem_fun_t	An adapter class that allows a non_const member function that takes no arguments to be called as a unary function object when initialized with a pointer argument.
mem_fun1_ref_t	An adapter class that allows a non_const member function that takes a single argument to be called as a binary function object when initialized with a reference argument.
mem_fun1_t	An adapter class that allows a non_const member function that takes a single argument to be called as a binary function object when initialized with a pointer argument.
pointer_to_binary_function	Converts a binary function pointer into an adaptable binary function.
pointer_to_unary_function	Converts a unary function pointer into an adaptable unary function.
reference_wrapper	A class that wraps a reference.
result_of	A struct that holds the return type of a wrapped callable object.
unary_negate	A template class providing a member function that negates the return value of a specified unary function.

Functions

bind	Binds arguments to a callable object.
bind1st	A helper template function that creates an adaptor to convert a binary function object into a unary function object by binding the first argument of the binary function to a specified value.
bind2nd	A helper template function that creates an adaptor to convert a binary function object into a unary function object by binding the second argument of the binary function to a specified value.
bit_and	Returns the binary AND of the two parameters.
bit_or	Returns the binary OR of the two parameters.
bit_xor	Returns the binary XOR of the two parameters.
cref	Constructs a const reference_wrapper from an argument.
mem_fn	Generates a simple call wrapper.
mem_fun	Helper template functions used to construct function object adaptors for member functions when initialized with pointer arguments.
mem_fun_ref	A helper template function used to construct function object adaptors for member functions when initialized with reference arguments.
not1	Returns the complement of a unary predicate.
not2	Returns the complement of a binary predicate.
ptr_fun	A helper template function used to convert unary and binary function pointers, respectively, into unary and binary adaptable functions.
ref	Constructs a reference_wrapper from an argument.
swap	Swaps two function objects.

Structs

binary_function	An empty base class that defines types that may be inherited by derived class that provides a binary function object.
divides	The class provides a predefined function object that performs the arithmetic operation of division on elements of a specified value type.
equal_to	A binary predicate that tests whether a value of a specified type is equal to another value of that type.
greater	A binary predicate that tests whether a value of a specified type is greater than another value of that type.
greater_equal	A binary predicate that tests whether a value of a specified type is greater than or equal to another value of that type.
less	A binary predicate that tests whether a value of a specified type is less than another value of that type.
less_equal	A binary predicate that tests whether a value of a specified type is less than or equal to another value of that type.
logical_and	The class provides a predefined function object that performs the logical operation of conjunction on elements of a specified value type and tests for the truth or falsity of the result.
logical_not	The class provides a predefined function object that performs the logical operation of negation on elements of a specified value type and tests for the truth or falsity of the result.
logical_or	The class provides a predefined function object that performs the logical operation of disjunction on elements of a specified value type and tests for the truth or falsity of the result.
minus	The class provides a predefined function object that performs the arithmetic operation of subtraction on elements of a specified value type.
modulus	The class provides a predefined function object that performs the arithmetic operation of modulus on elements of a specified value type.
multiplies	The class provides a predefined function object that performs the arithmetic operation of multiplication on elements of a specified value type.
negate	The class provides a predefined function object that returns the negative of an element value.
not_equal_to	A binary predicate that tests whether a value of a specified type is not equal to another value of that type.
plus	The class provides a predefined function object that performs the arithmetic operation of addition on elements of a specified value type.
unary_function	An empty base class that defines types that may be inherited by derived class that provides a unary function object.

Objects

_1	Placeholders for replaceable arguments.

Operators

operator==	Disallows equality comparison of callable objects.
operator!=	Disallows inequality comparison of callable objects.

Share via

<functional>

Remarks

TR1 Extensions

Classes

Functions

Structs

Objects

Operators

See Also

Reference

Other Resources

Additional resources