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 commonly used with the standard algorithms.
For example, to copy a sequence of numbers, adding a fixed amount, say 42, to each value, one could use the following expression:
std::transform(src.begin(), src.end(), dst.begin(), std::bind2nd(std::plus<int>(), 42))
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.
Function objects are defined for C++ operators, for binding function arguments, and for adapting functions, member functions, etc., as function objects.
Base class for binary functionals
template <typename Arg1, typename Arg2, typename Result> struct binary_function { typedef Arg1 first_argument_type; typedef Arg2 second_argument_type; typedef Result result_type; };
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 return type. 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.
Example 13-10: Functional to round off a floating point number.
// Functional for a binary function that rounds off // a floating point number (of type FltT) to some number // of decimal places (supplied as an unsigned). template<typename FltT> struct roundoff : std::binary_function<FltT,unsigned,FltT> { FltT operator()(FltT x, unsigned digits) const { FltT y = pow(10.0, digits); FltT z = x * y; return (z < 0 ? ceil(z - 0.5) : floor(z + 0.5)) / y; } }; ... // Copy seq to seq2, rounding off to 2 decimal places. std::transform(seq.begin(), seq.end(), seq2.begin(), std::bind2nd(roundoff<double>(), 2));
binary_negate class template, const_mem_fun1_ref_t class template, const_mem_fun1_t class template, mem_fun1_ref_t class template, mem_fun1_t class template, pointer_to_binary_function class template, unary_function class template
Logical negation of a binary predicate
template <typename P> class binary_negate : public binary_function<typename P::first_argument_type, typename P::second_argument_type, bool> { public: explicit binary_negate(const P& predicate); bool operator()(const typename P::first_argument_type& x, const typename P::second_argument_type& y) const; };
The binary_negate
class template is a binary functional that returns the logical negation of another binary functional. That is, operator()
returns !predicate(x,
y)
.The simplest way to use binary_negate
is to use the not2
function template.
unary_negate class template, not2 function template
Create a binder1st function object
template <typename Operation, typename T> binder1st<Operation> bind1st(const Operation& op, const T& x);
The bind1st
function is a convenient way to construct a binder1st
object. Use bind1st
when you have a binary function and you always want to supply the same value as the first argument to the function.
For example, suppose you have have a container of data points, and you want to count the number of points that exceed a threshold, in other words, where the threshold is less than or equal to the data point. Example 13-11 shows one way to do this.
Example 13-11: Binding a threshold to the less functional
std::cout << std::count_if(data.begin(), data.end(), std::bind1st(std::less_equal<double>(), threshold)) << '\n';
bind2nd function template, binder1st class template
Create a binder2nd function object
template <typename Operation, typename T> binder2nd<Operation> bind2nd(const Operation& op, const T& x);
The bind2nd
function is a convenient way to construct a binder2nd
object. Use bind2nd
when you have a binary function and you always want to supply the same value as the first argument to the function.
For example, suppose you have have a container of data points, and you want to count the number of points that exceed a threshold. Example 13-12 shows one way to do this.
Example 13-12: Binding a threshold to the greater functional
std::cout << std::count_if(data.begin(), data.end(), std::bind2nd(std::greater<double>(), threshold)) << '\n';
bind1st function template, binder2nd class template
Bind a value to the first argument of a binary function
template <typename Operation> class binder1st : public unary_function< typename Operation::second_argument_type, typename Operation::result_type> { protected: Operation op; typename Operation::first_argument_type value; public: binder1st(const Operation& x, const typename Operation::first_argument_type& y); typename Operation::result_type operator() (const typename Operation::second_argument_type& x)const; };
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.
bind1st function template, binder2nd class template
Bind a value to the second argument of a binary function
template <typename Operation> class binder2nd : public unary_function< typename Operation::first_argument_type, typename Operation::result_type> { protected: Operation op; typename Operation::second_argument_type value; public: binder2nd(const Operation& x, const typename Operation::second_argument_type& y); typename Operation::result_type operator() (const typename Operation::first_argument_type& x) const; };
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.
bind2nd function template, binder1st class template
Call a member function of a constant reference object
template <typename Rtn, typename T> class const_mem_fun_ref_t : public unary_function<T, Rtn> { public: explicit const_mem_fun_ref_t(Rtn (T::*p)() const); Rtn operator()(const T& p) const; };
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 const
reference to the object.
See the mem_fun_ref
function template for an easier way to construct and use the const_mem_fun_ref_t
class template.
const_mem_fun_t class template, const_mem_fun1_ref_t class template, mem_fun_ref function template, mem_fun_ref_t class template
Call a member function of a constant object
template <class Rtn, class T> class const_mem_fun_t : public unary_function<T*, Rtn> { public: explicit const_mem_fun_t(Rtn (T::*p)() const); Rtn operator()(const T* p) const; };
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 const
pointer to the object.
See the mem_fun
function template for an easier way to construct and use the const_mem_fun_t
class template.
const_mem_fun_ref_t class template, const_mem_fun1_t class template, mem_fun function template, mem_fun_t class template
Call a member function of a constant reference object, with an argument
template <typename Rtn, typename T, typename Arg> class const_mem_fun1_ref_t : public binary_function<T, Arg, Rtn> { public: explicit const_mem_fun1_ref_t(Rtn (T::*p)(Arg) const); Rtn operator()(const T& p, Arg x) const; };
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 const
reference to the object.
See the mem_fun_ref
function template for an easier way to construct and use the const_mem_fun1_ref_t
class template.
const_mem_fun_ref_t class template, const_mem_fun1_t class template, mem_fun_ref function template, mem_fun1_ref_t class template
Call a member function of a constant object, with an argument
template <typename Rtn, typename T, typename Arg> class const_mem_fun1_t: public binary_function<T*, Arg, Rtn> { public: explicit const_mem_fun1_t(Rtn (T::*p)(Arg) const); Rtn operator()(const T* p, Arg x) const; };
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 const
pointer to the object.
See the mem_fun
function template for an easier way to construct and use the const_mem_fun1_t
class template.
const_mem_fun_t class template, const_mem_fun1_ref_t class template, mem_fun function template, mem_fun1_t class template
Binary functional to divide
template <typename T> struct divides : binary_function<T, T, T> { T operator()(const T& x, const T& y) const; };
The divides
class template is a binary functional where operator()
returns x
/
y
.
binary_function class template, minus class template, modulus class template, multiplies class template, negate class template, plus class template
Binary functional to compare for equality
template <typename T> struct equal_to : binary_function<T, T, bool> { bool operator()(const T& x, const T& y) const; };
The equal_to
class template is a binary functional where operator()
returns x
==
y
.
binary_function class template, reater class template, greater_equal class template, less class template, less_equal class template, not_equal_to class template
Binary functional to compare for greater than
template <typename T> struct greater : binary_function<T, T, bool> { bool operator()(const T& x, const T& y) const; };
The greater
class template is a binary functional where operator()
returns x
>
y
.
binary_function class template, equal_to class template, greater_equal class template, less class template, less_equal class template, not_equal_to class template
Binary functional to compare for greater than or equal
template <typename T> struct greater_equal : binary_function<T, T, bool> { bool operator()(const T& x, const T& y) const; };
The greater_equal
class template is a binary functional where operator()
returns x
>=
y
.
binary_function class template, equal_to class template, greater class template, less class template, less_equal class template, not_equal_to class template
Binary functional to compare for less than
template <typename T> struct less : binary_function<T, T, bool> { bool operator()(const T& x, const T& y) const; };
The less
class template is a binary functional where operator()
returns x
<
y
.
binary_function class template, equal_to class template, greater class template, greater_equal class template, less_equal class template, not_equal_to class template
Binary functional to compare for less than or equal
template <typename T> struct less_equal : binary_function<T, T, bool> { bool operator()(const T& x, const T& y) const; };
The less_equal
class template is a binary functional where operator()
returns x
<=
y
.
binary_function class template, equal_to class template, greater class template, greater_equal class template, less class template, not_equal_to class template
Binary functional for logical conjunction
template <typename T> struct logical_and : binary_function<T, T, bool> { bool operator()(const T& x, const T& y) const; };
The logical_and
class template is a binary functional where operator()
returns x
&&
y
. Note that no short-circuiting occurs because both arguments must be evaluated before operator()
can be called.
logical_not class template, logical_or class template
Binary functional for logical negation
template <typename T> struct logical_not : unary_function<T, bool> { bool operator()(const T& x) const; };
The logical_not
class template is a unary functional where operator()
returns !x
.
logical_and class template, logical_or class template, not1 function template, not2 function template
Binary functional for logical disjunction
template <typename T> struct logical_or : binary_function<T, T, bool> { bool operator()(const T& x, const T& y) const; };
The logical_or
class template is a binary functional where operator()
returns x
||
y
. Note that no short-circuiting occurs because both arguments must be evaluated before operator()
can be called.
logical_and class template, logical_not class template
Create a function object to call a member function
template<typename Rtn, typename T> const_mem_fun_t<Rtn,T> mem_fun(Rtn (T::*f)() const); template<typename Rtn, typename T, typename Arg> const_mem_fun1_t<Rtn,T,Arg> mem_fun(Rtn (T::*f)(Arg) const); template<typename Rtn, typename T> mem_fun_t<Rtn,T> mem_fun(Rtn (T::*f)()); template<typename Rtn, typename T, typename Arg> mem_fun1_t<Rtn,T,Arg> mem_fun(Rtn (T::*f)(Arg));
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 an pointer to T
(or a derived class). 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
function is usually the simplest way to create a function object that wraps a member function. In normal use, the compiler infers 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, false
if the employee is unlucky. Example 13-13 shows how to remove all the unlucky employees from the container.
Example 13-13: Wrapping a member function as a function object
class Employee { public: int sales() const { return sales_; } std::string name() const { return name_; } bool gets_bonus() const { return sales() > bonus; } ... }; std::list<Employee*> emps; // Fill emps with pointers to Employee objects... // Erase the employees who will NOT receive bonuses. // The call to remove_if rearranges emps; the call to // erase removes the unlucky employees from the list. emps.erase( std::remove_if(emps.begin(), emps.end(), std::not1(std::mem_fun(Employee::gets_bonus))), emps.end());
const_mem_fun_t class template, const_mem_fun1_t class template, mem_fun_ref function template, mem_fun_t class template, mem_fun1_t class template, ptr_fun function template
Create a function object to call a member function of a reference object
template<typename Rtn, typename T> const_mem_fun_ref_t<Rtn,T> mem_fun_ref(Rtn (T::*f)() const); template<typename Rtn, typename T, typename Arg> const_mem_fun1_ref_t<Rtn,T,Arg> mem_fun_ref(Rtn (T::*f)(Arg) const); template<typename Rtn, typename T> mem_fun_ref_t<Rtn,T> mem_fun_ref(Rtn (T::*f)()); template<typename Rtn, typename T, typename Arg> mem_fun1_ref_t<Rtn,T,A> mem_fun_ref(Rtn (T::*f)(Arg));
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 infers the template parameters.
Suppose you have an Employee
class and a container of Employee
objects. 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, false
if the employee is unlucky. Example 13-14 shows how to remove all the unlucky employees from the container.
Example 13-14: Wrapping a member function as a function object
class Employee { public: int sales() const { return sales_; } std::string name() const { return name_; } bool gets_bonus() const { return sales() > bonus; } ... }; std::list<Employee> emps; // Fill emps with pointers to Employee objects... // Erase the employees who will NOT receive bonuses. // The call to remove_if rearranges emps; the call to // erase removes the unlucky employees from the list. emps.erase( std::remove_if(emps.begin(), emps.end(), std::not1(std::mem_fun_ref(Employee::gets_bonus))), emps.end());
const_mem_fun_ref_t class template, const_mem_fun1_ref_t class template, mem_fun function template, mem_fun_ref_t class template, mem_fun1_ref_t class template, ptr_fun function template
Call a member function of a reference object
template <typename Rtn, typename T> class mem_fun_ref_t : public unary_function<T, Rtn> { public: explicit mem_fun_ref_t(Rtn (T::*p)()); Rtn operator()(T& p) const; };
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.
const_mem_fun_ref_t class template, mem_fun_ref function template, mem_fun_t class template, mem_fun1_ref_t class template
Call a member function of a constant object
template <class Rtn, class T> class mem_fun_t : public unary_function<T*, Rtn> { public: explicit mem_fun_t(Rtn (T::*p)() const); Rtn operator()(const T* p) const; };
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.
const_mem_fun_t class template, mem_fun function template, mem_fun_ref_t class template, mem_fun1_t class template
Call a member function of a constant reference object, with an argument
template <typename Rtn, typename T, typename Arg> class mem_fun1_ref_t : public binary_function<T, Arg, Rtn> { public: explicit mem_fun1_ref_t(Rtn (T::*p)(Arg) const); Rtn operator()(const T& p, Arg x) const; };
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.
const_mem_fun1_ref_t class template, mem_fun_ref function template, mem_fun_ref_t class template, mem_fun1_t class template
Call a member function of an object, with an argument
template <typename Rtn, typename T, typename Arg> class mem_fun1_t: public binary_function<T*, Arg, Rtn> { public: explicit mem_fun1_t(Rtn (T::*p)(Arg)); Rtn operator()(T* p, Arg x) const; };
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.
const_mem_fun1_t class template, mem_fun function template, mem_fun_t class template, mem_fun1_ref_t class template
Binary functional for subtraction
template <typename T> struct minus : binary_function<T, T, T> { T operator()(const T& x, const T& y) const; };
The minus
class template is a binary functional where operator()
returns x
-
y
.
binary_function class template, divides class template, modulus class template, multiplies class template, negate class template, plus class template
Binary functional for modulus (remainder)
template <typename T> struct modulus : binary_function<T, T, T> { T operator()(const T& x, const T& y) const; };
The modulus
class template is a binary functional where operator()
returns x
%
y
.
binary_function class template, divides class template, minus class template, multiplies class template, negate class template, plus class template
Binary functional for multiplication
template <typename T> struct multiplies : binary_function<T, T, T> { T operator()(const T& x, const T& y) const; };
The multiplies
class template is a binary functional where operator()
returns x
*
y
.
binary_function class template, divides class template, minus class template, modulus class template, negate class template, plus class template
Unary functional for arithmetic negation
template <typename T> struct negate : unary_function<T,T> { T operator()(const T& x) const; };
The negate
class template is a unary functional that performs arithmetic negation, that is, operator()
return -x
.
divides class template, minus class template, modulus class template, multiplies class template, plus class template, unary_function class template
Return a unary_negate object
template <typename Predicate> unary_negate<Predicate> not1(const Predicate& pred);
The not1
function template is a convenient way to construct a unary_negate
function object that performs the logical negation of pred
. For an example of its use, see Example 13-XX, earlier in this section.
logical_not class template, not2 function template, unary_negate class template
Return a binary_negate object
template <typename Predicate> binary_negate<Predicate> not2(const Predicate& pred);
The not2
function template is a convenient way to construct a binary_negate
function object that performs the logical negation of pred
.
binary_negate class template, logical_not class template, not1 function template
Binary functional for inequality
template <typename T> struct not_equal_to : binary_function<T, T, bool> { bool operator()(const T& x, const T& y) const; };
The not_equal_to
class template is a binary functional where operator()
returns x
!=
y
.
binary_function class template, equal_to class template, greater class template, greater_equal class template, less class template, less_equal class template
Binary functional for addition
template <typename T> struct plus : binary_function<T, T, T> { T operator()(const T& x, const T& y) const; };
The plus
class template is a binary functional where operator()
returns x
+
y
.
binary_function class template, divides class template, minus class template, modulus class template, multiplies class template, negate class template
Functional for a pointer to a binary function
template <class Arg1, class Arg2, class Rtn> class pointer_to_binary_function : public binary_function<Arg1,Arg2,Rtn> { public: explicit pointer_to_binary_function(Rtn (*f)(Arg1, Arg2)); Rtn operator()(Arg1 x, Arg2 y) const; };
The pointer_to_binary_function
class template is a function object that wraps a pointer to a function, where the function is an ordinary (non-member) function that takes two arguments. The ptr_fun
function template is the most convenient way to create a pointer_to_binary_function
object.
pointer_to_unary_function class template, ptr_fun function template
Functional for a pointer to a unary function
template <typename Arg, typename Rtn> class pointer_to_unary_function : public unary_function<Arg, Rtn> { public: explicit pointer_to_unary_function(Result (*f)(Arg)); Rtn operator()(Arg x) const; };
The pointer_to_unary_function
class template is a function object that wraps a pointer to a function, where the function is an ordinary (non-member) function that takes one argument. The ptr_fun
function template is the most convenient way to create a pointer_to_unary_function
object.
pointer_to_binary_function class template, ptr_fun function template
Create a pointer to function object
template <typename Arg1, typename Arg2, typename Rtn> pointer_to_binary_function<Arg1,Arg2,Rtn> ptr_fun(Rtn (*f)(Arg1, Arg2)); template <typename Arg, typename Rtn> pointer_to_unary_function<Arg, Rtn> ptr_fun(Rtn (*f)(Arg));
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 the std::pow
function instead, as shown in Example 13-15.
Example 13-15: Wrapping the pow function in a function object.
std::vector<double> a, b, c; ... std::transform(a.begin(), a.end(), b.begin(), c.begin(), std::ptr_fun(std::pow));
mem_fun function template, mem_fun_ref function template, pointer_to_binary_function class template, pointer_to_unary_function class template
Logical negation of a unary predicate
template <typename P> class unary_negate : public unary_function<typename P::argument_type,bool> { public: explicit unary_negate(const P& predicate); bool operator()(const typename P::argument_type& x) const; };
The unary_negate
class template is a binary functional that returns the logical negation of another unary functional. That is, operator()
returns !predicate(x)
. The simplest way to use unary_negate
is to use the not1
function template.
binary_negate class template, not1 function template
Base class for unary functionals
template <typename Arg, typename Result> struct unary_function { typedef Arg argument_type; typedef Result result_type; };
The unary_function
template is a base class for all the function classes that represent unary operations. It provides standard names for the argument and result types.
binary_function class template, binder1st class template, binder2nd class template, const_mem_fun_ref_t class template, const_mem_fun_t class template, mem_fun_ref_t class template, mem_fun_t class template, negate class template, pointer_to_unary_function class template, unary_negate class template