|  | Home | Libraries | People | FAQ | More | 
This section explains how to use this library.
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`.
[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.