Apache C++ Standard Library Reference Guide

## bind1st(), bind2nd(), binder1st, binder2nd

Library: General utilities

    Function

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

### Local Index

No Entries

### Summary

Templatized utilities to bind values to function objects

### Synopsis

    #include <functional>

    namespace std {
      template <class Operation>
      class binder1st;

      template <class Operation, class T>
      binder1st<Operation> bind1st(const Operation&, const T&);

      template <class Operation>
      class binder2nd ;

      template <class Operation, class T>
      binder2nd<Operation> bind2nd(const Operation&, const T&);
    }

### Description

Because so many functions included in the C++ Standard Library take other functions as arguments, the library includes classes that let you build new function objects out of old ones. Both `bind1st()` and `bind2nd()` are functions that take as arguments a binary function object `f` and a value `x,` and return, respectively, classes binder1st and binder2nd. The underlying function object must be a subclass of binary_function.

Class binder1st binds the value to the first argument of the binary function, and binder2nd does the same thing for the second argument of the function. The resulting classes can be used in place of a unary predicate in other function calls.

For example, you could use the `count_if()` algorithm to count all elements in a vector that are less than or equal to 7, using the following:

    vector<int> v;
    int littleNums;

    count_if(v.begin, v.end, bind1st(greater<int>(),7),
             littleNums)

This function adds one to `littleNums` each time the element is greater than 7.

### Interface

    namespace std {

      // Class binder1st
      template <class Operation>
      class binder1st
         : public unary_function<typename
                                 Operation::second_argument_type,
                                 typename Operation::result_type>
      {
      public:

         binder1st(const Operation&,
                   const typename Operation::first_argument_type&);

         typename Operation::result_type
         operator() (const typename
                     Operation::second_argument_type&) const;
      };

      // Class binder2nd
      template <class Operation>
      class binder2nd
         : public unary_function<typename
                             Operation::first_argument_type,
                             typename Operation::result_type>
      {
      public:

         binder2nd(const Operation&,
                   const typename Operation::second_argument_type&);
         typename Operation::result_type
         operator()(const typename
                    Operation::first_argument_type&) const;
      };

      // Creator bind1st
      template <class Operation, class T>
      binder1st<Operation> bind1st(const Operation&, const T&);

      // Creator bind2nd
      template<class Operation, class T>
      binder2nd <Operation> bind2nd(const Operation&, const T&);
    }

### Example

    //
    // binders.cpp
    //

    #include <algorithm>   // for find_if
    #include <functional>  // for equal_to, bind1st, bind2nd
    #include <iostream>    // for cout
    #include <iterator>    // for ostream_iterator
    #include <vector>      // for vector

    int main ()
    {
        typedef std::vector<int>                  Vector;
        typedef std::equal_to<Vector::value_type> EqualTo;

        const Vector::value_type arr [] = { 1, 2, 3, 4, 5 };

        // Initialize a vector with the array elements.
        const Vector v1 (arr, arr + sizeof arr / sizeof *arr);

        // Value to look for.
        const Vector::value_type x (3);

        // Create an 'equal to 3' unary predicate by binding the value
        // 3 to the EqualTo binary predicate.
        const std::binder1st<EqualTo> equal_to_3 =
            std::bind1st (EqualTo (), x);

        // Now use this new predicate in a call to find_if.
        const Vector::const_iterator it1 =
            std::find_if (v1.begin (), v1.end (), equal_to_3);

        // Even better, construct the new predicate on the fly.
        const Vector::const_iterator it2 =
            std::find_if (v1.begin (), v1.end (), std::bind1st (EqualTo (), x));

        // And now the same thing using bind2nd.
        // Same result since EqualTo is commutative.
        const Vector::const_iterator it3 =
            std::find_if (v1.begin (), v1.end (), std::bind2nd (EqualTo (), x));

        // Use the same predicate to count the number of elements
        // equal to 3.
        const Vector::size_type n =
            std::count_if (v1.begin (), v1.end (), std::bind2nd (EqualTo (), x));

        // Output results.
        std::ostream_iterator<Vector::value_type> out (std::cout, " ");

        std::cout << "The vector { ";
        std::copy (v1.begin (), v1.end (), out);

        std::cout << "} contains " << n << " element equal to "
                  << x <<  " at offset " <<
                  it1 - v1.begin () << ".\n";

        // Exit with status of 0 on success, 1 on failure.
        const bool success = 1 == n && it1 == it2 && it1 == it2 && *it1 == x;

        return success ? 0 : 1;
    }

    Program Output:
    The vector { 1 2 3 4 5 } contains 1 element equal to 3 at offset 2.

### See Also

Function Objects

### Standards Conformance

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