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:

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.

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.

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 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.

Example

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 a certain 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 = std::pow(10.0, static_cast<FltT>(digits));
    FltT z = x * y;
    return (z < 0 ? std::ceil(z - 0.5) : std::floor(z + 0.5)) / y;
  }
};
...
// Copy seq to seq2, rounding off to two decimal places.
std::transform(seq.begin(  ), seq.end(  ), seq2.begin(  ),
  std::bind2nd(roundoff<double>(  ), 2));

See Also

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

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.

See Also

unary_negate class template, not2 function template

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 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 threshold—in other words, where the threshold is less than or equal to the data point. Here is one way to do this:

std::cout
  << std::count_if(data.begin(  ), data.end(  ),
       std::bind1st(std::less_equal<double>(  ), threshold))
  << '\n';

See Also

bind2nd function template, binder1st class template

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 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 threshold. Here is one way to do this:

std::cout << std::count_if(data.begin(  ), data.end(  ),
             std::bind2nd(std::greater<double>(  ), threshold)) << '\n';

See Also

bind1st function template, binder2nd class template

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.

See Also

bind1st function template, binder2nd class template

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.

See Also

bind2nd function template, binder1st class template

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 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.

See Also

const_mem_fun_t class template, const_mem_fun1_ref_t class template, mem_fun_ref function template, mem_fun_ref_t class template

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 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.

See Also

const_mem_fun_ref_t class template, const_mem_fun1_t class template, mem_fun function template, mem_fun_t class template

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 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.

See Also

const_mem_fun_ref_t class template, const_mem_fun1_t class template, mem_fun_ref function template, mem_fun1_ref_t class template

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 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.

See Also

const_mem_fun_t class template, const_mem_fun1_ref_t class template, mem_fun function template, mem_fun1_t class template

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 in which operator( ) returns x / y.

See Also

binary_function class template, minus class template, modulus class template, multiplies class template, negate class template, plus class template

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 in which operator( ) returns x == y.

See Also

binary_function class template, greater class template, greater_equal class template, less class template, less_equal class template, not_equal_to class template

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 in which operator( ) returns x > y.

See Also

binary_function class template, equal_to class template, greater_equal class template, less class template, less_equal class template, not_equal_to class template

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 in which operator( ) returns x >= y.

See Also

binary_function class template, equal_to class template, greater class template, less class template, less_equal class template, not_equal_to class template

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 in which operator( ) returns x < y.

See Also

binary_function class template, equal_to class template, greater class template, greater_equal class template, less_equal class template, not_equal_to class template

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 in which operator( ) returns x <= y.

See Also

binary_function class template, equal_to class template, greater class template, greater_equal class template, less class template, not_equal_to class template

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 in which operator( ) returns x && y. Note that no short-circuiting occurs because both arguments must be evaluated before operator( ) can be called.

See Also

logical_not class template, logical_or class template

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 in which operator( ) returns !x.

See Also

logical_and class template, logical_or class template, not1 function template, not2 function template

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 in which operator( ) returns x || y. Note that no short-circuiting occurs because both arguments must be evaluated before operator( ) can be called.

See Also

logical_and class template, logical_not class template

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 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

class Employee {
public:
  int         sales(  )      const { return sales_; }
  std::string name(  )       const { return name_; }
  bool        gets_bonus(  ) const { return sales(  ) > bonus; }
...
};
   
std::list<Employee*> empptrs;
// Fill empptrs with pointers to Employee objects.
...
// Remove the employees who will NOT receive bonuses.
std::list<Employee*>::iterator last = 
  std::remove_if(empptrs.begin(  ), empptrs.end(  ),
                 std::not1(std::mem_fun(&Employee::gets_bonus)));

See Also

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

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 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

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 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(  ));

See Also

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

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.

See Also

const_mem_fun_ref_t class template, mem_fun_ref function template, mem_fun_t class template, mem_fun1_ref_t class template

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.

See Also

const_mem_fun_t class template, mem_fun function template, mem_fun_ref_t class template, mem_fun1_t class template

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.

See Also

const_mem_fun1_ref_t class template, mem_fun_ref function template, mem_fun_ref_t class template, mem_fun1_t class template

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.

See Also

const_mem_fun1_t class template, mem_fun function template, mem_fun_t class template, mem_fun1_ref_t class template

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 in which operator( ) returns x - y.

See Also

binary_function class template, divides class template, modulus class template, multiplies class template, negate class template, plus class template

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 in which operator( ) returns x % y.

See Also

binary_function class template, divides class template, minus class template, multiplies class template, negate class template, plus class template

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 in which operator( ) returns x * y.

See Also

binary_function class template, divides class template, minus class template, modulus class template, negate class template, plus class template

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( ) returns -x.

See Also

divides class template, minus class template, modulus class template, multiplies class template, plus class template, unary_function class template

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. See Example 13-11 earlier in this section.

See Also

logical_not class template, not2 function template, unary_negate class template

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.

See Also

binary_negate class template, logical_not class template, not1 function template

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 in which operator( ) returns x != y.

See Also

binary_function class template, equal_to class template, greater class template, greater_equal class template, less class template, less_equal class template

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 in which operator( ) returns x + y.

See Also

binary_function class template, divides class template, minus class template, modulus class template, multiplies class template, negate class template

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, 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.

See Also

pointer_to_unary_function class template, ptr_fun function template

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, 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.

See Also

pointer_to_binary_function class template, ptr_fun function template

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 your own power function instead, as shown in Example 13-13.

Example

Example 13-13. Wrapping the pow function in a function object

std::vector<double> a, b, c;
double power(double x, double y)
{
  return std::pow(x, y);
}
...
std::transform(a.begin(), a.end(  ), b.begin(  ), c.begin(  ),
               std::ptr_fun(power));

See Also

mem_fun function template, mem_fun_ref function template, pointer_to_binary_function class template, pointer_to_unary_function class template

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.

See Also

binary_negate class template, not1 function template

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.

See Also

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