Boost C++ Libraries

A function wrapper is defined simply by instantiating the function class template with the desired return type and argument types, formulated as a C++ function type. Any number of arguments may be supplied, up to some implementation-defined limit (10 is the default maximum). The following declares a function object wrapper f that takes two int parameters and returns a float:

boost::function<float (int x, int y)> f;

boost::function2<float, int, int> f;

By default, function object wrappers are empty, so we can create a function object to assign to f:

struct int_div { 
  float operator()(int x, int y) const { return ((float)x)/y; }; 
};

f = int_div();

Now we can use f to execute the underlying function object int_div:

std::cout << f(5, 3) << std::endl;

We are free to assign any compatible function object to f. If int_div had been declared to take two long operands, the implicit conversions would have been applied to the arguments without any user interference. The only limit on the types of arguments is that they be CopyConstructible, so we can even use references and arrays:

boost::function<void (int values[], int n, int& sum, float& avg)> sum_avg;

boost::function4<void, int*, int, int&, float&> sum_avg;

void do_sum_avg(int values[], int n, int& sum, float& avg)
{
  sum = 0;
  for (int i = 0; i < n; i++)
    sum += values[i];
  avg = (float)sum / n;
}

sum_avg = &do_sum_avg;

Invoking a function object wrapper that does not actually contain a function object is a precondition violation, much like trying to call through a null function pointer, and will throw a bad_function_call exception). We can check for an empty function object wrapper by using it in a boolean context (it evaluates true if the wrapper is not empty) or compare it against 0. For instance:

if (f)
  std::cout << f(5, 3) << std::endl;
else
  std::cout << "f has no target, so it is unsafe to call" << std::endl;

Alternatively, empty() method will return whether or not the wrapper is empty.

Finally, we can clear out a function target by assigning it to 0 or by calling the clear() member function, e.g.,

f = 0;

Free function pointers can be considered singleton function objects with const function call operators, and can therefore be directly used with the function object wrappers:

float mul_ints(int x, int y) { return ((float)x) * y; }

f = &mul_ints;

Note that the & isn't really necessary unless you happen to be using Microsoft Visual C++ version 6.

In many systems, callbacks often call to member functions of a particular object. This is often referred to as "argument binding", and is beyond the scope of Boost.Function. The use of member functions directly, however, is supported, so the following code is valid:

struct X {
  int foo(int);
};

boost::function<int (X*, int)> f;

f = &X::foo;
  
X x;
f(&x, 5);

boost::function2<int, X*, int> f;

f = &X::foo;
  
X x;
f(&x, 5);

Several libraries exist that support argument binding. Three such libraries are summarized below:

In some cases it is expensive (or semantically incorrect) to have Boost.Function clone a function object. In such cases, it is possible to request that Boost.Function keep only a reference to the actual function object. This is done using the ref and cref functions to wrap a reference to a function object:

stateful_type a_function_object;
boost::function<int (int)> f;
f = boost::ref(a_function_object);

boost::function<int (int)> f2(f);

stateful_type a_function_object;
boost::function1<int, int> f;
f = boost::ref(a_function_object);

boost::function1<int, int> f2(f);

Here, f will not make a copy of a_function_object, nor will f2 when it is targeted to f's reference to a_function_object. Additionally, when using references to function objects, Boost.Function will not throw exceptions during assignment or construction.

Function object wrappers can be compared via == or != against any function object that can be stored within the wrapper. If the function object wrapper contains a function object of that type, it will be compared against the given function object (which must be either be EqualityComparable or have an overloaded boost::function_equal). For instance:

int compute_with_X(X*, int);

f = &X::foo;
assert(f == &X::foo);
assert(&compute_with_X != f);

When comparing against an instance of reference_wrapper, the address of the object in the reference_wrapper is compared against the address of the object stored by the function object wrapper:

a_stateful_object so1, so2;
f = boost::ref(so1);
assert(f == boost::ref(so1));
assert(f == so1); // Only if a_stateful_object is EqualityComparable
assert(f != boost::ref(so2));