13.25 <functional>

The <functional> header defines several
functionals, or function
objects. A function object is an object that has an
operator( ), so it can be called using the same
syntax as a function. Function objects are most often used with the
standard algorithms.

For example, to copy a sequence of integers, adding a fixed amount
(42) to each value, you could use the following expression:

The result of combining bind2nd and
plus<int> is a function object that adds the
value 42 when it is applied to any integer. The
transform algorithm copies all the elements from
src to dst, applying the
functional argument to each element. See the detailed description of
bind2nd and plus in this
section for details.

The standard function objects are defined for C++ operators; for
binding function arguments; and for adapting functions, member
functions, etc., as function objects.

Boost defines functionals that extend and improve on those in the
standard library. See Appendix B for information
about Boost.

The binary_function template is a base-class
template for all the function classes that represent binary
operations. It provides standard names for the argument and result
types.

The base template has separate template parameters for each of the
argument types and the return type. Many of the predefined function
objects in this section use the same type for all three parameters,
but you can use different types when defining your own function
object, as shown in Example 13-10.

The binary_negate class template is a binary
functional that returns the logical negation of another binary
functionalthat is, operator( ) returns
!predicate(x, y). The simplest
way to use binary_negate is to use the
not2 function template.

The bind1st function is a convenient way to
construct a binder1st object. Use
bind1st when you have a binary function and always
want to supply the same value as the first argument to the function.

Example

Suppose you have a container of data points, and you want to count
the number of points that exceed a thresholdin other words,
where the threshold is less than or equal to the data point. Here is
one way to do this:

The binder1st class template is a unary functional
that binds a fixed value as the first argument to a binary function
object. The constructor initializes the op and
value data members with the x
and y arguments. The operator(
) member function returns op(value,
x).

See the bind1st function template for an easier
way to construct and use the binder1st class
template.

The binder2nd class template is a unary functional
that binds a fixed value as the second argument to a binary function
object. The constructor initializes the op and
value data members with the x
and y arguments. The operator(
) member function returns op(x,
value).

See the bind2nd function template for an easier
way to construct and use the binder2nd class
template.

The const_mem_fun_ref_t class template is a unary
functional that wraps a member function pointer. The
Rtn template parameter is the member
function's return type, and the T
template parameter is the class that declares the member function.
The argument to the constructor is a pointer to the member function,
which takes no arguments. The member function is called from
operator( ) using a reference to the
const object.

See the mem_fun_ref function template for an
easier way to construct and use the
const_mem_fun_ref_t class template.

The const_mem_fun_t class template is a unary
functional that wraps a member function pointer. The
Rtn template parameter is the member
function's return type, and the T
template parameter is the class that declares the member function.
The argument to the constructor is a pointer to the member function,
which takes no arguments. The member function is called from
operator( ) using a pointer to the
const object.

See the mem_fun function template for an easier
way to construct and use the const_mem_fun_t class
template.

The const_mem_fun1_ref_t class template is a
binary functional that wraps a member function pointer. The
Rtn template parameter is the member
function's return type, the T
template parameter is the class that declares the member function,
and the Arg template parameter is the type of the
member function's sole argument.

The argument to the constructor is a pointer to the member function.
The member function is called from operator( )
using a reference to the const object.

See the mem_fun_ref function template for an
easier way to construct and use the
const_mem_fun1_ref_t class template.

The const_mem_fun1_t class template is a binary
functional that wraps a member function pointer. The
Rtn template parameter is the member
function's return type, the T
template parameter is the class that declares the member function,
and the Arg template parameter is the type of the
member function's sole argument.

The argument to the constructor is a pointer to the member function.
The member function is called from operator( )
using a pointer to the const object.

See the mem_fun function template for an easier
way to construct and use the const_mem_fun1_t
class template.

The mem_fun function template takes a pointer to a
member function as an argument and returns a function object that can
call the member function. The function object must be applied to a
pointer to T (or a derived class). The
Rtn template parameter is the return type of the
member function, and the T template parameter is
the object that has the member function. The optional
Arg template parameter is the type of the argument
to the member function.

The mem_fun function is usually the simplest way
to create a function object that wraps a member function. In normal
use, the compiler deduces the template parameters.

Suppose you have an Employee class and a container
of Employee pointers. One of the member functions
of Employee is gets_bonus,
which returns a bool: true if
the employee is lucky and gets a bonus this year, and
false if the employee is unlucky. Example 13-11 shows how to remove all the unlucky employees
from the container.

Example

Example 13-11. Wrapping a member function called via a pointer as a function object

The mem_fun_ref function template takes a pointer
to a member function as an argument and returns a function object
that can call the member function. The function object must be
applied to an object of type T (or a derived
class). The object is passed by reference to the functional. The
Rtn template parameter is the return type of the
member function; the T template parameter is the
object that has the member function. The optional
Arg template parameter is the type of the argument
to the member function.

The mem_fun_ref function is usually the simplest
way to create a function object that wraps a member function. In
normal use, the compiler deduces the template parameters.

Suppose you have an Employee class and a container
of Employee objects. As in Example 13-11, one of the member functions of
Employee is gets_bonus, which
returns a bool: true if the
employee is lucky and gets a bonus this year, or
false if the employee is unlucky. Example 13-12 shows how to remove all the unlucky employees
from the container.

Example

Example 13-12. Wrapping a member function called via a reference as a function object

The mem_fun_ref_t class template is a unary
functional that wraps a member function pointer. The
Rtn template parameter is the member
function's return type, and the T
template parameter is the class that declares the member function.
The argument to the constructor is a pointer to the member function,
which takes no arguments. The member function is called from
operator( ) using a reference to the object.

See the mem_fun_ref function template for an
easier way to construct and use the mem_fun_ref_t
class template.

The mem_fun_t class template is a unary functional
that wraps a member function pointer. The Rtn
template parameter is the member function's return
type, and the T template parameter is the class
that declares the member function. The argument to the constructor is
a pointer to the member function, which takes no arguments. The
member function is called from operator( ) using a
pointer to the object.

See the mem_fun function template for an easier
way to construct and use the mem_fun_t class
template.

The mem_fun1_ref_t class template is a binary
functional that wraps a member function pointer. The
Rtn template parameter is the member
function's return type, the T
template parameter is the class that declares the member function,
and the Arg template parameter is the type of the
member function's sole argument.

The argument to the constructor is a pointer to the member function.
The member function is called from operator( )
using a const reference to the object.

See the mem_fun_ref function template for an
easier way to construct and use the mem_fun1_ref_t
class template.

The mem_fun1_t class template is a binary
functional that wraps a member function pointer. The
Rtn template parameter is the member
function's return type, the T
template parameter is the class that declares the member function,
and the Arg template parameter is the type of the
member function's sole argument.

The argument to the constructor is a pointer to the member function.
The member function is called from operator( )
using a pointer to the object.

See the mem_fun function template for an easier
way to construct and use the mem_fun1_t class
template.

The pointer_to_binary_function class template is a
function object that wraps a pointer to a function, in which the
function is an ordinary (nonmember) function that takes two
arguments. The ptr_fun function template is the
most convenient way to create a
pointer_to_binary_function object.

The pointer_to_unary_function class template is a
function object that wraps a pointer to a function, in which the
function is an ordinary (nonmember) function that takes one argument.
The ptr_fun function template is the most
convenient way to create a
pointer_to_unary_function object.

The ptr_fun function template creates a function
object from a pointer to a function. The resulting function object
has an operator( ) that calls the function.
Functions of one and two arguments are supported.

For example, suppose you have two numeric vectors,
a and b, and you want to raise
each element of a to the power of the
corresponding element in b, saving the result in a
third vector, c. There is no predefined power
function object, so you can use ptr_fun and your
own power function instead, as shown in Example 13-13.

The unary_negate class template is a binary
functional that returns the logical negation of another unary
functionalthat is, operator( ) returns
!predicate(x). The simplest way to use
unary_negate is to use the not1
function template.