Apache C++ Standard Library Reference Guide

## Function Objects

Library: General utilities

- Local Index
- Summary
- Synopsis
- Description
- Interface
- Example
- See Also
- Standards Conformance

### Local Index

No Entries

### Summary

Objects with an `operator()` defined. They are used as arguments to templatized algorithms, in place of pointers to functions.

### Synopsis

    #include <functional>

### Description

Function objects are objects with an `operator()` defined. They are important for the effective use of the standard library's generic algorithms, because the interface for each algorithmic template can accept either an object with an `operator()` defined, or a pointer to a function. The C++ Standard Library includes both a standard set of function objects, and a pair of classes that you can use as the base for creating your own function objects.

Function objects that take one argument are called unary function objects. Unary function objects must include the typedefs `argument_type` and `result_type`. Similarly, function objects that take two arguments are called binary function objects and, as such, must include the typedefs `first_argument_type`, `second_argument_type`, and `result_type`.

The classes unary_function and binary_function make the task of creating templatized function objects easier. The necessary typedefs for a unary or binary function object are included by inheriting from the appropriate function object class.

The function objects in the C++ Standard Library are listed below, together with a brief description of their operation. This Reference Guide also includes an alphabetic entry for each function.

#### Table 19: C++ Standard Library function objects and their operations

Name | Operation
`arithmetic functions`
`plus` | `addition x + y`
`minus` | `subtraction x - y`
`multiplies` | `multiplication x * y`
`divides` | `division x / y`
`modulus` | `remainder x % y`
`negate` | `negation - x`
`comparison functions`
`equal_to` | `equality test x == y`
`not_equal_to` | `inequality test x != y`
`greater` | `greater comparison x > y`
`less` | `less-than comparison x < y`
`greater_equal` | `greater than or equal comparison x >= y`
`less_equal` | `less than or equal comparison x <= y`
`logical functions`
`logical_and` | `logical conjunction x && y`
`logical_or` | `logical disjunction x || y`
`logical_not` | `logical negation ! x`

### Interface

    namespace std  {

      template <class Arg, class Result>
      struct unary_function{
           typedef Arg argument_type;
           typedef Result result_type;
      };

      template <class Arg1, class Arg2, class Result>
      struct binary_function{
           typedef Arg1 first_argument_type;
           typedef Arg2 second_argument_type;
           typedef Result result_type;
      };

      // Arithmetic Operations

      template<class T>
      struct plus : binary_function<T, T, T> {
          T operator() (const T&, const T&) const;
      };

      template <class T>
      struct minus : binary_function<T, T, T> {
              T operator() (const T&, const T&) const;
      };

      template <class T>
      struct multiplies : binary_function<T, T, T> {
            T operator() (const T&, const T&) const;
      };

      template <class T>
      struct divides : binary_function<T, T, T> {
              T operator() (const T&, const T&) const;
      };

      template <class T>
      struct modulus : binary_function<T, T, T> {
              T operator() (const T&, const T&) const;
      };

      template <class T>
      struct negate : unary_function<T, T> {
              T operator() (const T&) const;
      };

      // Comparisons

      template <class T>
      struct equal_to : binary_function<T, T, bool> {
               bool operator() (const T&, const T&) const;
      };

      template <class T>
      struct not_equal_to : binary_function<T, T, bool> {
              bool operator() (const T&, const T&) const;
      };

      template <class T>
      struct greater : binary_function<T, T, bool> {
              bool operator() (const T&, const T&) const;
      };

      template <class T>
      struct less : binary_function<T, T, bool> {
              bool operator() (const T&, const T&) const;
      };

      template <class T>
      struct greater_equal : binary_function<T, T, bool> {
              bool operator() (const T&, const T&) const;
      };

      template <class T>
      struct less_equal : binary_function<T, T, bool> {
              bool operator() (const T&, const T&) const;
      };

      // Logical Comparisons

      template <class T>
      struct logical_and : binary_function<T, T, bool> {
              bool operator() (const T&, const T&) const;
      };

      template <class T>
      struct logical_or : binary_function<T, T, bool> {
               bool operator() (const T&, const T&) const;
      };

      template <class T>
      struct logical_not : unary_function<T, T, bool> {
              bool operator() (const T&, const T&) const;
      };
    }

### Example

    //
    // funct_ob.cpp
    //

    #include <algorithm>
    #include <deque>
    #include <functional>
    #include <iostream>
    #include <vector>

    // Create a new function object from unary_function.
    template <class Arg, class Result>
    struct factorial: public std::unary_function<Arg, Result>
    {
        Result operator() (const Arg &arg) {
            Result a = 1;
            for (Arg i = 2; i <= arg; i++)
                a *= i;
            return a;
        }
    };

    int main ()
    {
        // Typedefs for convenience.
        typedef std::deque<int, std::allocator<int> >    deque;
        typedef std::vector<long, std::allocator<long> > vector;

        // Initialize a deque with an array of integers.
        deque::value_type arr[] = { 1, 2, 3, 4, 5, 6, 7 };
        deque d (arr, arr + sizeof arr / sizeof *arr);

        // Create an empty vector to store the factorials.
        vector v;

        // Transform the numbers in the deque to their
        // factorials and store in the vector.
        std::transform(d.begin(), d.end(),
                       std::back_inserter(v),
                       factorial<deque::value_type,
                                 vector::value_type>());

        // Create an iterator to output deque elements.
        std::ostream_iterator<deque::value_type, char,
                std::char_traits<char> > outd(std::cout, " ");

        // Print the results.
        std::cout << "The following numbers: \n     ";
        std::copy(d.begin(), d.end(), outd);

        // Create an iterator to output vector elements.
        std::ostream_iterator<vector::value_type, char,
                 std::char_traits<char> > outv(std::cout, " ");

        std::cout << std::endl;
        std::cout << "\nHave the factorials: \n     ";
        std::copy (v.begin(), v.end(), outv);
        std::cout << std::endl;

        return 0;
    }

    Program Output:

    The following numbers:
         1 2 3 4 5 6 7

    Have the factorials:
         1 2 6 24 120 720 5040

### See Also

binary_function, unary_function

### Standards Conformance

ISO/IEC 14882:1998 -- International Standard for Information Systems -- Programming Language C++, Section 20.3