Functions and Function Objects

Example <ospace/osstd/ examples/func0.cpp>

#include <iostream>
#include <set>

void
main()
  {
  set< int, less< int > > s;
  s.insert( 1 );
  s.insert( 42 );
  s.insert( 3 );

  set< int, less< int > >::iterator p;
  for ( p = s.begin(); p != s.end(); ++p ) // Display contents.
    cout << *p << "\n";
  }

1
3
42

Predicates

Predicates trigger actions and always return true or false . A unary predicate takes a single argument. A binary predicate takes two arguments. For example, the count_if() algorithm counts all of the values in a sequence satisfying a user-supplied unary predicate. The following example passes the address of the regular C function bigger() to count_if() , which in turn uses bigger() to count the numbers in a sequence that are greater than three.

#include <iostream>
#include <algorithm>
#include <vector>

bool
bigger( int i )
  {
  return i > 3;
  }

void
main()
  {
  vector< int > v;
  v.push_back( 4 );
  v.push_back( 1 );
  v.push_back( 5 );

  int n = 0;
  count_if( v.begin(), v.end(), bigger, n );
  cout << "Number greater than 3 = " << n << "\n";
  }

number greater than 3 = 2

#include <iostream>
#include <algorithm>
#include <functional>

bool input[ 7 ] = { 1, 0, 0, 1, 1, 1, 1 };

void
main()
  {
  int n = 0;
  count_if( input, input + 7, logical_not< bool >(), n );
  cout << "count = " << n << "\n";
  }

count = 2

Comparators

Comparators are binary functions that order elements and always return true or false . When a comparator returns true , it generally means the first parameter is ordered before the second parameter. For example, with one variation of sort() you can specify a function that controls the sorting order.

In the following example, bigger_than() tells sort() to place x to the left of y if x is greater than y .

#include <iostream>
#include <algorithm>
#include <vector>

bool
bigger_than( int x, int y )
  {
  return x > y;
  }

void
main()
  {
  vector< int >  v;
  v.push_back( 4 );
  v.push_back( 1 );
  v.push_back( 5 );

  sort( v.begin(), v.end(), bigger_than );

  vector< int >::iterator i;
  for ( i = v.begin(); i != v.end(); ++i )
      cout << *i << "\n";
  }

5
4
1

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

void
main()
  {
  vector< int > v;
  v.push_back( 4 );
  v.push_back( 1 );
  v.push_back( 5 );

  sort( v.begin(), v.end(), greater< int >() );

  vector< int >::iterator i;
  for ( i = v.begin(); i != v.end(); ++i )
    cout << *i << "\n";
  }

5
4
1

greater< int > g; // Construct a greater function object.
sort( v.begin(), v.end(), g ); // Call with function object.

Pointer Based Comparators

STL containers often contain pointers to objects or strings. STL does not contain function objects for comparing these two kinds of items properly, so Helper<ToolKit> includes a variety of non-standard comparators and functions for solving this problem. Consult the Foundations User Guide and Reference Manual for more information about Helper<ToolKit>.

General Functions

Many algorithms use a general function to apply a mathematical operation to every element in a collection. For example, the transform() algorithm applies a unary function to every item in a collection and stores the result into another collection.

The following example uses a negate object to negate every element in a collection.

#include <iostream>
#include <algorithm>
#include <functional>

int array[] = { 1, 5, 2, 3 };
int result[ 4 ];

void
main()
  {
  transform( array, array + 4, result, negate< int >() );

  for ( int i = 0; i < 4; ++i )
    cout << result[ i ] << " ";
  cout << "\n";
  }

-1 -5 -2 -3

Function Adapters

Several function objects have an associated adapter function that simplifies the syntax of creating instances.

The following example collects even numbers from a container using a function object that tests whether a number is odd. Notice that the function object unary_negate takes a unary predicate and returns the complement. A unary predicate is a function that takes one argument. In this case, the unary_negate turns odd(x) into !odd(x) .

#include <iostream>
#include <algorithm>
#include <functional>

int array[ 3 ] = { 1, 2, 3 };

class odd : public unary_function< int, bool >
  {
  public:
    odd() {}
    bool operator()( const int& n ) const { return ( n % 2 ) == 1; }
  };

void
main()
  {
  int* p = find_if( array, array + 3, unary_negate< odd >( odd() ) );

  if ( p != array + 3 )
    cout << *p << "\n";
  }

2

#include <iostream>
#include <algorithm>
#include <functional>

int array[ 3 ] = { 1, 2, 3 };

class odd : public unary_function< int, bool >
  {
  public:
    odd() {}
    bool operator()( const int& n ) const { return ( n % 2 ) == 1; }
  };

void
main()
  {
  int* p = find_if( array, array + 3, not1( odd() ) );
  if ( p != array + 3 )
    cout << *p << "\n";
  }

2

List of Function Objects

Following is a complete list of all the standard STL function objects, with the argument count and synopsis of operation for each.

Function	# args	Operation	Adapter
binary_negate	2	!P(x, y)	not2
binder1st	1	P(V,x)	bind1st
binder2nd	1	P(x,V)	bind2nd
divides	2	x / y
equal_to	2	x == y
greater	2	x > y
greater_equal	2	x >= y
less	2	x < y
less_equal	2	x <= y
logical_and	2	x && y
logical_not	1	!x
logical_or	2	x || y
minus	2	x - y
modulus	2	x % y
negate	1	-x
not_equal_to	2	x != y
plus	2	x + y
pointer_to_binary_function	2	P(x, y)	ptr_fun
pointer_to_unary_function	1	P(x)	ptr_fun
times	2	x * x
unary_negate	1	!P(x)	not1