Tutorial

Overloading
Without Function Types

This section explains how to use this library.

Overloading

Consider the following functions with distinct signatures:

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

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 identity.cpp):

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_CHECK( identity("abc") == "abc" );
BOOST_CHECK( identity(123) == 123 );
BOOST_CHECK( identity(1.23) == 1.23 );

Note how function types in the following format are passed as template parameters to boost::overloaded_function (this is the format of 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 function pointer (the function address is automatically taken from the function name by compiler), identity_i as function reference, and identity_d as 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).

Without Function Types

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 identity.cpp):

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

BOOST_CHECK( identity("abc") == "abc" );
BOOST_CHECK( identity(123) == 123 );
BOOST_CHECK( 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 hide the specific boost::overloaded_function type using a template parameter. For example (see also identity.cpp):

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

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

^[2] Function pointers are of the form result-type (*)(argument1-type, ...) (the C++ compiler is usually able to automatically promote a function name to a function pointer in a context where a function pointer is expected even if the function name is not prefixed by &). Function references are of the form result-type (&)(argument1-type, ...). Function types are of the form result-type (argument1-type, ...) (note how they lack of both * and & when compared to function pointers and function references). Finally, monomorphic function objects are instances of classes with a non-template call operator of the form result-type operator()(argument1-type, ...).

^[3] Note that in C++ the function result type is not used for overload resolution (to avoid making the overload resolution context dependent). Therefore, at least one of the function parameters must be distinct for each specified function type.