| Home | Libraries | People | FAQ | More

## Tutorial

This section explains how to use this library.

### Overloading

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).

### 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 `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`.

[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``, ...)`. Unfortunately, it is not possible to support polymorphic function objects (see http://lists.boost.org/Archives/boost/2012/03/191744.php).

[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.