`<functional>`

Article
05/20/2022

Defines C++ Standard Library 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.

Requirements

Header: <functional>

Namespace: std

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 C++ Standard Library. 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. Function objects and their adaptors allow the C++ Standard Library to upgrade existing applications and help integrate the library into the C++ programming environment.

The implementation of the function objects in <functional> includes transparent operator functors, which are specializations of standard function objects and take no template parameters, and perform perfect forwarding of the function arguments and perfect return of the result. These template specializations do not require that you specify argument types when you invoke arithmetic, comparison, logical, and bitwise operator functors. You can overload arithmetic, comparison, logical, or bitwise operators for your own types, or for heterogeneous combinations of types, and then use the transparent operator functors as function arguments. For example, if your type MyType implements operator<, you can call sort(my_collection.begin(), my_collection.end(), less<>()) instead of explicitly specifying the type sort(my_collection.begin(), my_collection.end(), less<MyType>()).

The following features are added in C++11, C++14 and C++17:

A call signature is the name of a return type followed by a parenthesized comma-separated list of zero or more argument types.
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 callable object is an object of a callable type.
A call wrapper type is a type that holds a callable object and supports a call operation that forwards to that object.
A call wrapper is an object of a call wrapper type.
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 N == 1 and f is a pointer to member data of a 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 N == 1 and f is a pointer to member data of a 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 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 move constructor and a copy constructor. A simple call wrapper is a call wrapper that has an assignment operator and whose copy constructor, move constructor, and assignment operator do not throw exceptions. A forwarding call wrapper is a call wrapper that can be called by using an arbitrary argument list and that delivers the arguments to the wrapped callable object as references. All rvalue arguments are delivered as rvalue references, and lvalue arguments are delivered as lvalue references.

Members

Classes

Name	Description
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 class template providing a member function that negates the return value of a specified binary function. (Deprecated in C++17.)
binder1st	A class template 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. (Deprecated in C++11, removed in C++17.)
binder2nd	A class template 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. (Deprecated in C++11, removed in C++17.)
boyer_moore_horspool_searcher
boyer_moore_searcher
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. (Deprecated in C++11, removed in C++17.)
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. (Deprecated in C++11, removed in C++17.)
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. (Deprecated in C++11, removed in C++17.)
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. (Deprecated in C++11, removed in C++17.)
default_searcher
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. (Deprecated in C++11, removed in C++17.)
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. (Deprecated in C++11, removed in C++17.)
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. (Deprecated in C++11, removed in C++17.)
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. (Deprecated in C++11, removed in C++17.)
pointer_to_binary_function	Converts a binary function pointer into an adaptable binary function. (Deprecated in C++11, removed in C++17.)
pointer_to_unary_function	Converts a unary function pointer into an adaptable unary function. (Deprecated in C++11, removed in C++17.)
reference_wrapper	A class that wraps a reference.
unary_negate	A class template providing a member function that negates the return value of a specified unary function. (Deprecated in C++17.)

Functions

Name	Description
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. (Deprecated in C++11, removed in C++17.)
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. (Deprecated in C++11, removed in C++17.)
bit_and	Returns the bitwise AND (binary `operator&`) of the two parameters.
bit_not	Returns the bitwise complement (`operator~`) of the parameter. (Added in C++14.)
bit_or	Returns the bitwise OR (`operator\|`) of the two parameters.
bit_xor	Returns the bitwise XOR (`operator^`) of the two parameters.
cref	Constructs a const `reference_wrapper` from an argument.
invoke
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. (Deprecated in C++11, removed in C++17.)
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. (Deprecated in C++17.)
not2	Returns the complement of a binary predicate. (Deprecated in C++17.)
not_fn	Returns the complement of the result of its function object. (Added in C++17.)
ptr_fun	A helper template function used to convert unary and binary function pointers, respectively, into unary and binary adaptable functions. (Deprecated in C++11, removed in C++17.)
ref	Constructs a `reference_wrapper` from an argument.
swap	Swaps two `function` objects.

Structs

Name	Description
binary_function	An empty base class that defines types that may be inherited by derived class that provides a binary function object. (Deprecated in C++11, removed in C++17.)
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. (Deprecated in C++11, removed in C++17.)

Objects

Name	Description
_1.._M	Placeholders for replaceable arguments.

Operators

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