Boost C++ Libraries

Consider the following functions which have distinct signatures:

const std::string& identity_s(const std::string& x) // Function (as pointer).
    { return x; }

int identity_i_impl(int x) { return x; }
int (&identity_i)(int) = identity_i_impl; // Function reference.

double identity_d_impl(double x) { return x; }
boost::function<double (double)> identity_d = identity_d_impl; // Functor.

This library header boost/functional/overloaded_function.hpp provides a boost::overloaded_function class template that creates a single overloaded function object that can be used to call the specified functions instead of using the separate function names (see also functor.cpp and identity.hpp):

boost::overloaded_function<
      const std::string& (const std::string&)
    , int (int)
    , double (double)
> identity(identity_s, identity_i, identity_d);

// All calls via single `identity` function.
BOOST_TEST(identity("abc") == "abc");
BOOST_TEST(identity(123) == 123);
BOOST_TEST(identity(1.23) == 1.23);

Note how each function type is passed as a template parameter of boost::overloaded_function using the following syntax (this is Boost.Function's preferred syntax):

result-type (argument1-type, argument2-type, ...)

Then the relative function pointers, function references, or monomorphic function objects are passed to the boost::overloaded_function constructor matching the order of the specified template parameters. ^[2] In the above example, identity_s is passed as a function pointer (the function address is automatically taken from the function name by the compiler), identity_i as a function reference, and identity_d as a function object.

All specified function types must have distinct parameters from one another (so the overloaded calls can be resolved by this library). ^[3] In order to create an overloaded function object, it is necessary to specify at least two function types (because there is nothing to overload between one or zero functions).

For convenience, this library also provides the boost::make_overloaded_function function template which allows to create the overloaded function object without explicitly specifying the function types. The function types are automatically deduced from the specified functions and the appropriate boost::overloaded_function instantiation is returned by boost::make_overloaded_function.

The boost::make_overloaded_function function template can be useful when used together with Boost.Typeof's BOOST_AUTO (or C++11 auto). For example (see also make_decl.cpp and identity.hpp):

BOOST_AUTO(identity, boost::make_overloaded_function(
        identity_s, identity_i, identity_d));

BOOST_TEST(identity("abc") == "abc");
BOOST_TEST(identity(123) == 123);
BOOST_TEST(identity(1.23) == 1.23);

Note how the overloaded function object identity has been created specifying only the functions identity_s, identity_i, identity_d and without specifying the function types const std::string& (const std::string&), int (int), and double (double) as required instead by boost::overloaded_function. Therefore, boost::make_overloaded_function provides a more concise syntax in this context when compared with boost::overloaded_function.

Another case where boost::make_overloaded_function can be useful is when the overloaded function object is passed to a function template which can hold the specific boost::overloaded_function type using a template parameter. For example (see also make_call.cpp and identity.hpp):

template<typename F>
void check(F identity) {
    BOOST_TEST(identity("abc") == "abc");
    BOOST_TEST(identity(123) == 123);
    BOOST_TEST(identity(1.23) == 1.23);
}

check(boost::make_overloaded_function(identity_s, identity_i, identity_d));

The library implementation of boost::make_overloaded_function uses Boost.Typeof to automatically deduce some of the function types. In order to compile code in Boost.Typeof emulation mode, all types should be properly registered using BOOST_TYPEOF_REGISTER_TYPE and BOOST_TYPEOF_REGISTER_TEMPLATE, or appropriate Boost.Typeof headers should be included (see Boost.Typeof for more information). For the above examples, it is sufficient to include the Boost.Typeof header that registers std::string (this library does not require to register boost::function for Boost.Typeof emulation):

#include <boost/typeof/std/string.hpp> // No need to register `boost::function`.