diff --git a/include/boost/functional/overloaded_function.hpp b/include/boost/functional/overloaded_function.hpp new file mode 100644 index 0000000..83fe4b3 --- /dev/null +++ b/include/boost/functional/overloaded_function.hpp @@ -0,0 +1,311 @@ + +// Copyright (C) 2009-2012 Lorenzo Caminiti +// Distributed under the Boost Software License, Version 1.0 +// (see accompanying file LICENSE_1_0.txt or a copy at +// http://www.boost.org/LICENSE_1_0.txt) +// Home at http://www.boost.org/libs/functional/overloaded_function + +#ifndef DOXYGEN // Doxygen documentation only. + +#if !BOOST_PP_IS_ITERATING +# ifndef BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_HPP_ +# define BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_HPP_ + +# include +# include +# include +# include +# include +# include +# include +# include +# include +# include +# include +# include +# include +# include +# include +# include +# include +# include + +#define BOOST_FUNCTIONAL_f_type(z, n, unused) \ + BOOST_PP_CAT(F, n) + +#define BOOST_FUNCTIONAL_f_arg(z, n, unused) \ + BOOST_PP_CAT(f, n) + +#define BOOST_FUNCTIONAL_f_tparam(z, n, unused) \ + typename BOOST_FUNCTIONAL_f_type(z, n, ~) \ + +#define BOOST_FUNCTIONAL_f_tparam_dflt(z, n, is_tspec) \ + BOOST_FUNCTIONAL_f_tparam(z, n, ~) \ + /* overload requires at least 2 functors so F0 and F1 not optional */ \ + BOOST_PP_EXPR_IIF(BOOST_PP_AND(BOOST_PP_NOT(is_tspec), \ + BOOST_PP_GREATER(n, 1)), \ + = void \ + ) + +#define BOOST_FUNCTIONAL_f_arg_decl(z, n, unused) \ + BOOST_FUNCTIONAL_f_type(z, n, ~) /* no qualifier to deduce tparam */ \ + BOOST_FUNCTIONAL_f_arg(z, n, ~) + +#define BOOST_FUNCTIONAL_g_type(z, n, unused) \ + BOOST_PP_CAT(G, n) + +#define BOOST_FUNCTIONAL_g_arg(z, n, unused) \ + BOOST_PP_CAT(g, n) + +#define BOOST_FUNCTIONAL_g_tparam(z, n, unused) \ + typename BOOST_FUNCTIONAL_g_type(z, n, ~) + +#define BOOST_FUNCTIONAL_g_arg_decl(z, n, unused) \ + BOOST_FUNCTIONAL_g_type(z, n, ~) /* no qualifier to deduce tparam */ \ + BOOST_FUNCTIONAL_g_arg(z, n, ~) + +#define BOOST_FUNCTIONAL_base(z, n, unused) \ + ::boost::overloaded_function_detail::base< \ + BOOST_FUNCTIONAL_f_type(z, n, ~) \ + > + +#define BOOST_FUNCTIONAL_inherit(z, n, unused) \ + public BOOST_FUNCTIONAL_base(z, n, ~) + +#define BOOST_FUNCTIONAL_base_init(z, n, unused) \ + BOOST_FUNCTIONAL_base(z, n, ~)(BOOST_FUNCTIONAL_g_arg(z, n, ~)) + +#define BOOST_FUNCTIONAL_using_operator_call(z, n, unused) \ + using BOOST_FUNCTIONAL_base(z, n, ~)::operator(); + +#define BOOST_FUNCTIONAL_function_type(z, n, unused) \ + typename ::boost::overloaded_function_detail::function_type< \ + BOOST_FUNCTIONAL_f_type(z, n, ~) \ + >::type + +# define BOOST_PP_ITERATION_PARAMS_1 \ + /* at least 2 func to overload so start from 2 to MAX */ \ + /* (cannot iterate [0, MAX-2) because error on Sun) */ \ + (3, (2, BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_OVERLOAD_MAX, \ + "boost/functional/overloaded_function.hpp")) +# include BOOST_PP_ITERATE() // Iterate over function arity. + +#undef BOOST_FUNCTIONAL_f_type +#undef BOOST_FUNCTIONAL_f_arg +#undef BOOST_FUNCTIONAL_f_tparam +#undef BOOST_FUNCTIONAL_f_arg_decl +#undef BOOST_FUNCTIONAL_f_tparam_dflt +#undef BOOST_FUNCTIONAL_g_type +#undef BOOST_FUNCTIONAL_g_arg +#undef BOOST_FUNCTIONAL_g_tparam +#undef BOOST_FUNCTIONAL_g_arg_decl +#undef BOOST_FUNCTIONAL_base +#undef BOOST_FUNCTIONAL_inherit +#undef BOOST_FUNCTIONAL_base_init +#undef BOOST_FUNCTIONAL_using_operator_call +#undef BOOST_FUNCTIONAL_function_type + +# endif // #include guard + +#elif BOOST_PP_ITERATION_DEPTH() == 1 +# define BOOST_FUNCTIONAL_overloads \ + /* iterate as OVERLOADS, OVERLOADS-1, OVERLOADS-2, ... */ \ + /* (add 2 because iteration started from 2 to MAX) */ \ + BOOST_PP_ADD(2, BOOST_PP_SUB( \ + BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_OVERLOAD_MAX, \ + BOOST_PP_FRAME_ITERATION(1))) +# define BOOST_FUNCTIONAL_is_tspec \ + /* if template specialization */ \ + BOOST_PP_LESS(BOOST_FUNCTIONAL_overloads, \ + BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_OVERLOAD_MAX) + +// For type-of emulation: This must be included at this pp iteration level. +# include BOOST_TYPEOF_INCREMENT_REGISTRATION_GROUP() + +namespace boost { + +template< + BOOST_PP_ENUM(BOOST_FUNCTIONAL_overloads, BOOST_FUNCTIONAL_f_tparam_dflt, + BOOST_FUNCTIONAL_is_tspec) +> +class overloaded_function + // Template specialization. + BOOST_PP_EXPR_IIF(BOOST_PP_EXPAND(BOOST_FUNCTIONAL_is_tspec), <) + BOOST_PP_IIF(BOOST_FUNCTIONAL_is_tspec, + BOOST_PP_ENUM + , + BOOST_PP_TUPLE_EAT(3) + )(BOOST_FUNCTIONAL_overloads, BOOST_FUNCTIONAL_f_type, ~) + BOOST_PP_EXPR_IIF(BOOST_PP_EXPAND(BOOST_FUNCTIONAL_is_tspec), >) + // Bases (overloads >= 2 so always at least 2 bases). + : BOOST_PP_ENUM(BOOST_FUNCTIONAL_overloads, + BOOST_FUNCTIONAL_inherit, ~) +{ +public: + template< + BOOST_PP_ENUM(BOOST_FUNCTIONAL_overloads, BOOST_FUNCTIONAL_g_tparam, ~) + > /* implicit */ inline overloaded_function( + BOOST_PP_ENUM(BOOST_FUNCTIONAL_overloads, + BOOST_FUNCTIONAL_g_arg_decl, ~)) + // Overloads >= 2 so always at least 2 bases to initialize. + : BOOST_PP_ENUM(BOOST_FUNCTIONAL_overloads, + BOOST_FUNCTIONAL_base_init, ~) + {} + + BOOST_PP_REPEAT(BOOST_FUNCTIONAL_overloads, + BOOST_FUNCTIONAL_using_operator_call, ~) +}; + +template< + BOOST_PP_ENUM(BOOST_FUNCTIONAL_overloads, BOOST_FUNCTIONAL_f_tparam, ~) +> +overloaded_function< + BOOST_PP_ENUM(BOOST_FUNCTIONAL_overloads, BOOST_FUNCTIONAL_function_type, ~) +> make_overloaded_function( + BOOST_PP_ENUM(BOOST_FUNCTIONAL_overloads, BOOST_FUNCTIONAL_f_arg_decl, ~) +) { + return overloaded_function< + BOOST_PP_ENUM(BOOST_FUNCTIONAL_overloads, + BOOST_FUNCTIONAL_function_type, ~) + >(BOOST_PP_ENUM(BOOST_FUNCTIONAL_overloads, BOOST_FUNCTIONAL_f_arg, ~)); +} + +} // namespace + +// For type-of emulation: Register overloaded function type (for _AUTO, etc). +BOOST_TYPEOF_REGISTER_TEMPLATE(boost::overloaded_function, + BOOST_FUNCTIONAL_overloads) + +# undef BOOST_FUNCTIONAL_overloads +# undef BOOST_FUNCTIONAL_is_tspec +#endif // iteration + +// DOCUMENTATION // + +#else // DOXYGEN + +/** @file +@brief Overload distinct function pointers, function references, and +monomorphic function objects into a single function object. +*/ + +namespace boost { + +/** +@brief Function object to overload functions with distinct signatures. + +This function object aggregates together calls to functions of all the +specified function types F1, F2, etc which must have distinct +function signatures from one another. + +@Params +@Param{Fi, +Each function type must be specified using the following syntax (which is +Boost.Function's preferred syntax): +@code + result_type (argument1_type\, argumgnet2_type\, ...) +@endcode +} +@EndParams + +In some cases, the @RefFunc{make_overloaded_function} function template can be +useful to construct an overloaded function object without explicitly +specifying the function types. + +At least two distinct function types must be specified (because there is +nothing to overload between one or zero functions). +The maximum number of functions to overload is given by the +@RefMacro{BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_OVERLOAD_MAX} +configuration macro. +The maximum number of function parameters for each of the specified function +types is given by the +@RefMacro{BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_ARITY_MAX} +configuration macro. + +@See @RefSect{tutorial, Tutorial} section, @RefFunc{make_overloaded_function}, +@RefMacro{BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_OVERLOAD_MAX}, +@RefMacro{BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_ARITY_MAX}, +Boost.Function. +*/ +template +class overloaded_function { +public: + /** + @brief Construct the overloaded function object. + + Any function pointer, function reference, and monomorphic function object + that can be converted to a boost::function function object can be + specified as parameter. + + @Note Unfortunately, it is not possible to support polymorphic function + objects (as explained here). + */ + overloaded_function(const boost::function&, + const boost::function&, ...); + + /** + @brief Call operator matching the signature of the function type specified + as 1st template parameter. + + This will in turn invoke the call operator of the 1st function passed to + the constructor. + */ + typename boost::function_traits::result_type operator()( + typename boost::function_traits::arg1_type, + typename boost::function_traits::arg2_type, + ...) const; + + /** + @brief Call operator matching the signature of the function type specified + as 2nd template parameter. + + This will in turn invoke the call operator of the 2nd function passed to + the constructor. + + @Note Similar call operators are present for all specified function types + F1, F2, etc (even if not exhaustively listed by this + documentation). + */ + typename boost::function_traits::result_type operator()( + typename boost::function_traits::arg1_type, + typename boost::function_traits::arg2_type, + ...) const; +}; + +/** +@brief Make an overloaded function object without explicitly specifying the +function types. + +This function template creates and returns an @RefClass{overloaded_function} +object that overloads all the specified functions f1, f2, etc. + +The function types are internally determined from the template parameter types +so they do not need to be explicitly specified. +Therefore, this function template usually has a more concise syntax when +compared with @RefClass{overloaded_function}. +This is especially useful when the explicit type of the returned +@RefClass{overloaded_function} object does not need to be known (e.g., when +used with Boost.Typeof's BOOST_AUTO, C++11 auto, or when the +overloaded function object is handled using a function template parameter, see +the @RefSect{tutorial, Tutorial} section). + +The maximum number of functions to overload is given by the +@RefMacro{BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_OVERLOAD_MAX} +configuration macro. + +@Note In this documentation, __function_type__ is a placeholder for a +symbol that is specific to the implementation of this library. + +@See @RefSect{tutorial, Tutorial} section, @RefClass{overloaded_function}, +@RefMacro{BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_OVERLOAD_MAX}. +*/ +template +overloaded_function< + __function_type__, __function_type__, ... +> make_overloaded_function(F1 f1, F2 f2, ...); + +} // namespace + +#endif // DOXYGEN + diff --git a/include/boost/functional/overloaded_function/config.hpp b/include/boost/functional/overloaded_function/config.hpp new file mode 100644 index 0000000..2f5d9e1 --- /dev/null +++ b/include/boost/functional/overloaded_function/config.hpp @@ -0,0 +1,50 @@ + +// Copyright (C) 2009-2012 Lorenzo Caminiti +// Distributed under the Boost Software License, Version 1.0 +// (see accompanying file LICENSE_1_0.txt or a copy at +// http://www.boost.org/LICENSE_1_0.txt) +// Home at http://www.boost.org/libs/functional/overloaded_function + +#ifndef BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_HPP_ +#define BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_HPP_ + +/** @file +@brief Change the compile-time configuration of this library. +*/ + +/** +@brief Specify the maximum number of arguments of the functions being +overloaded. + +If this macro is left undefined by the user, it has a default value of 5 +(increasing this number might increase compilation time). +When specified by the user, this macro must be a non-negative integer number. + +@See @RefSect{getting_started, Getting Started}, +@RefClass{boost::overloaded_function}. +*/ +#ifndef BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_ARITY_MAX +# define BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_ARITY_MAX 5 +#endif + +/** +@brief Specify the maximum number of functions that can be overloaded. + +If this macro is left undefined by the user, it has a default value of 5 +(increasing this number might increase compilation time). +When defined by the user, this macro must be an integer number greater or +equal than 2 (because at least two distinct functions need to be specified in +order to define an overload). + +@See @RefSect{getting_started, Getting Started}, +@RefClass{boost::overloaded_function}. +*/ +#ifndef BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_OVERLOAD_MAX +# define BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_OVERLOAD_MAX 5 +#endif +#if BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_OVERLOAD_MAX < 2 +# error "maximum overload macro cannot be less than 2" +#endif + +#endif // #include guard + diff --git a/include/boost/functional/overloaded_function/detail/base.hpp b/include/boost/functional/overloaded_function/detail/base.hpp new file mode 100644 index 0000000..8fd9a0a --- /dev/null +++ b/include/boost/functional/overloaded_function/detail/base.hpp @@ -0,0 +1,86 @@ + +// Copyright (C) 2009-2012 Lorenzo Caminiti +// Distributed under the Boost Software License, Version 1.0 +// (see accompanying file LICENSE_1_0.txt or a copy at +// http://www.boost.org/LICENSE_1_0.txt) +// Home at http://www.boost.org/libs/functional/overloaded_function + +#if !BOOST_PP_IS_ITERATING +# ifndef BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_DETAIL_BASE_HPP_ +# define BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_DETAIL_BASE_HPP_ + +# include +# include +# include +# include +# include +# include + +#define BOOST_FUNCTIONAL_DETAIL_arg_type(z, n, unused) \ + BOOST_PP_CAT(A, n) + +#define BOOST_FUNCTIONAL_DETAIL_arg_name(z, n, unused) \ + BOOST_PP_CAT(a, n) + +#define BOOST_FUNCTIONAL_DETAIL_arg_tparam(z, n, unused) \ + typename BOOST_FUNCTIONAL_DETAIL_arg_type(z, n, unused) + +#define BOOST_FUNCTIONAL_DETAIL_arg(z, n, unused) \ + BOOST_FUNCTIONAL_DETAIL_arg_type(z, n, unused) \ + BOOST_FUNCTIONAL_DETAIL_arg_name(z, n, unused) + +#define BOOST_FUNCTIONAL_DETAIL_f \ + R (BOOST_PP_ENUM(BOOST_FUNCTIONAL_DETAIL_arity, \ + BOOST_FUNCTIONAL_DETAIL_arg_type, ~)) + +// Do not use namespace ::detail because overloaded_function is already a class. +namespace boost { namespace overloaded_function_detail { + +template +class base {}; // Empty template cannot be used directly (only its spec). + +# define BOOST_PP_ITERATION_PARAMS_1 \ + (3, (0, BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_ARITY_MAX, \ + "boost/functional/overloaded_function/detail/base.hpp")) +# include BOOST_PP_ITERATE() // Iterate over funciton arity. + +} } // namespace + +#undef BOOST_FUNCTIONAL_DETAIL_arg_type +#undef BOOST_FUNCTIONAL_DETAIL_arg_name +#undef BOOST_FUNCTIONAL_DETAIL_arg_tparam +#undef BOOST_FUNCTIONAL_DETAIL_arg +#undef BOOST_FUNCTIONAL_DETAIL_f + +# endif // #include guard + +#elif BOOST_PP_ITERATION_DEPTH() == 1 +# define BOOST_FUNCTIONAL_DETAIL_arity BOOST_PP_FRAME_ITERATION(1) + +template< + typename R + BOOST_PP_COMMA_IF(BOOST_FUNCTIONAL_DETAIL_arity) + BOOST_PP_ENUM(BOOST_FUNCTIONAL_DETAIL_arity, + BOOST_FUNCTIONAL_DETAIL_arg_tparam, ~) +> +class base< BOOST_FUNCTIONAL_DETAIL_f > { +public: + /* implicit */ inline base( + // This requires specified type to be implicitly convertible to + // a boost::function<> functor. + boost::function< BOOST_FUNCTIONAL_DETAIL_f > const& f): f_(f) + {} + + inline R operator()(BOOST_PP_ENUM(BOOST_FUNCTIONAL_DETAIL_arity, + BOOST_FUNCTIONAL_DETAIL_arg, ~)) const { + return f_(BOOST_PP_ENUM(BOOST_FUNCTIONAL_DETAIL_arity, + BOOST_FUNCTIONAL_DETAIL_arg_name, ~)); + } + +private: + boost::function< BOOST_FUNCTIONAL_DETAIL_f > const f_; +}; + +# undef BOOST_FUNCTIONAL_DETAIL_arity +#endif // iteration + diff --git a/include/boost/functional/overloaded_function/detail/function_type.hpp b/include/boost/functional/overloaded_function/detail/function_type.hpp new file mode 100644 index 0000000..0c28607 --- /dev/null +++ b/include/boost/functional/overloaded_function/detail/function_type.hpp @@ -0,0 +1,85 @@ + +// Copyright (C) 2009-2012 Lorenzo Caminiti +// Distributed under the Boost Software License, Version 1.0 +// (see accompanying file LICENSE_1_0.txt or a copy at +// http://www.boost.org/LICENSE_1_0.txt) +// Home at http://www.boost.org/libs/functional/overloaded_function + +#ifndef BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_DETAIL_FUNCTION_TYPE_HPP_ +#define BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_DETAIL_FUNCTION_TYPE_HPP_ + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +// Do not use namespace ::detail because overloaded_function is already a class. +namespace boost { namespace overloaded_function_detail { + +// Requires: F is a monomorphic functor (i.e., has non-template `operator()`). +// Returns: F's function type `result_type (arg1_type, arg2_type, ...)`. +// It does not assume F typedef result_type, arg1_type, ... but needs typeof. +template +class functor_type { + // NOTE: clang does not accept extra parenthesis `&(...)`. + typedef BOOST_TYPEOF_TPL(&F::operator()) call_ptr; +public: + typedef + typename boost::function_types::function_type< + typename boost::mpl::push_front< + typename boost::mpl::pop_front< // Remove functor type (1st). + typename boost::function_types::parameter_types< + call_ptr>::type + >::type + , typename boost::function_types::result_type::type + >::type + >::type + type; +}; + +// NOTE: When using boost::function in Boost.Typeof emulation mode, the user +// has to register boost::functionN instead of boost::function in oder to +// do TYPEOF(F::operator()). That is confusing, so boost::function is handled +// separately so it does not require any Boost.Typeof registration at all. +template +struct functor_type< boost::function > { + typedef F type; +}; + +// Requires: F is a function type, pointer, reference, or monomorphic functor. +// Returns: F's function type `result_type (arg1_type, arg2_type, ...)`. +template +struct function_type { + typedef + typename boost::mpl::if_, + boost::mpl::identity + , + typename boost::mpl::if_, + boost::remove_pointer + , + typename boost::mpl::if_, + boost::remove_reference + , // Else, requires that F is a functor. + functor_type + >::type + >::type + >::type + ::type type; +}; + +} } // namespace + +#endif // #include guard + diff --git a/overloaded_function/doc/Jamfile.v2 b/overloaded_function/doc/Jamfile.v2 new file mode 100644 index 0000000..1cfbc8e --- /dev/null +++ b/overloaded_function/doc/Jamfile.v2 @@ -0,0 +1,30 @@ + +# Copyright (C) 2009-2012 Lorenzo Caminiti +# Distributed under the Boost Software License, Version 1.0 +# (see accompanying file LICENSE_1_0.txt or a copy at +# http://www.boost.org/LICENSE_1_0.txt) +# Home at http://www.boost.org/libs/functional/overloaded_function + +import quickbook ; +using boostbook ; + +doxygen reference + : ../../../../boost/functional/overloaded_function.hpp + ../../../../boost/functional/overloaded_function/config.hpp + : "Reference" + PREDEFINED="DOXYGEN" + QUIET=YES + WARN_IF_UNDOCUMENTED=NO + HIDE_UNDOC_MEMBERS=YES + HIDE_UNDOC_CLASSES=YES + ALIASES=" Params=\"Parameters: \" Param{2}=\"\" EndParams=\"
\\1\\2
\" Returns=\"Returns:\" Note=\"Note:\" Warning=\"Warning:\" See=\"See:\" RefSect{2}=\"\\xmlonly\\2\\endxmlonly\" RefClass{1}=\"\\xmlonly\\1\\endxmlonly\" RefFunc{1}=\"\\xmlonly\\1\\endxmlonly\" RefMacro{1}=\"\\xmlonly\\1\\endxmlonly\" " + ; + +xml qbk : overloaded_function.qbk : reference ; + +boostbook doc : qbk + : boost.root=../../../../.. + boost.defaults=Boost + pdf:boost.url.prefix=http://www.boost.org/doc/libs/release/libs/functional/overloaded_function/doc/html + ; + diff --git a/overloaded_function/doc/html/BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_ARITY_MAX.html b/overloaded_function/doc/html/BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_ARITY_MAX.html new file mode 100644 index 0000000..b59ac5a --- /dev/null +++ b/overloaded_function/doc/html/BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_ARITY_MAX.html @@ -0,0 +1,54 @@ + + + +Macro BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_ARITY_MAX + + + + + + + + + + + + + + + +
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
+
+
+PrevUpHomeNext +
+
+
+
+

Macro BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_ARITY_MAX

+

BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_ARITY_MAX — Specify the maximum number of arguments of the functions being overloaded.

+
+

Synopsis

+
// In header: <boost/functional/overloaded_function/config.hpp>
+
+BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_ARITY_MAX
+
+

Description

+

If this macro is left undefined by the user, it has a default value of 5 (increasing this number might increase compilation time). When specified by the user, this macro must be a non-negative integer number.

+

See: Getting Started, boost::overloaded_function.

+
+
+ + + +
Copyright © 2011, 2012 Lorenzo Caminiti

+ Distributed under the Boost Software License, Version 1.0 (see accompanying + file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +

+
+
+
+PrevUpHomeNext +
+ + diff --git a/overloaded_function/doc/html/BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_OVERLOAD_MAX.html b/overloaded_function/doc/html/BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_OVERLOAD_MAX.html new file mode 100644 index 0000000..9db47e1 --- /dev/null +++ b/overloaded_function/doc/html/BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_OVERLOAD_MAX.html @@ -0,0 +1,54 @@ + + + +Macro BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_OVERLOAD_MAX + + + + + + + + + + + + + + + +
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
+
+
+PrevUpHomeNext +
+
+
+
+

Macro BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_OVERLOAD_MAX

+

BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_OVERLOAD_MAX — Specify the maximum number of functions that can be overloaded.

+
+

Synopsis

+
// In header: <boost/functional/overloaded_function/config.hpp>
+
+BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_OVERLOAD_MAX
+
+

Description

+

If this macro is left undefined by the user, it has a default value of 5 (increasing this number might increase compilation time). When defined by the user, this macro must be an integer number greater or equal than 2 (because at least two distinct functions need to be specified in order to define an overload).

+

See: Getting Started, boost::overloaded_function.

+
+
+ + + +
Copyright © 2011, 2012 Lorenzo Caminiti

+ Distributed under the Boost Software License, Version 1.0 (see accompanying + file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +

+
+
+
+PrevUpHomeNext +
+ + diff --git a/overloaded_function/doc/html/boost/make_overloaded_function.html b/overloaded_function/doc/html/boost/make_overloaded_function.html new file mode 100644 index 0000000..998264b --- /dev/null +++ b/overloaded_function/doc/html/boost/make_overloaded_function.html @@ -0,0 +1,60 @@ + + + +Function template make_overloaded_function + + + + + + + + + + + + + + + +
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
+
+
+PrevUpHomeNext +
+
+
+
+

Function template make_overloaded_function

+

boost::make_overloaded_function — Make an overloaded function object without explicitly specifying the function types.

+
+

Synopsis

+
// In header: <boost/functional/overloaded_function.hpp>
+
+
+template<typename F1, typename F2, ... > 
+  overloaded_function< __function_type__< F1 >, __function_type__< F2 >,...> 
+  make_overloaded_function(F1 f1, F2 f2, ...);
+
+

Description

+

This function template creates and returns an overloaded_function object that overloads all the specified functions f1, f2, etc.

+

The function types are internally determined from the template parameter types so they do not need to be explicitly specified. Therefore, this function template usually has a more concise syntax when compared with overloaded_function. This is especially useful when the explicit type of the returned overloaded_function object does not need to be known (e.g., when used with Boost.Typeof's BOOST_AUTO, C++11 auto, or when the overloaded function object is handled using a function template parameter, see the Tutorial section).

+

The maximum number of functions to overload is given by the BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_OVERLOAD_MAX configuration macro.

+

Note: In this documentation, __function_type__ is a placeholder for a symbol that is specific to the implementation of this library.

+

See: Tutorial section, overloaded_function, BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_OVERLOAD_MAX.

+
+
+ + + +
Copyright © 2011, 2012 Lorenzo Caminiti

+ Distributed under the Boost Software License, Version 1.0 (see accompanying + file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +

+
+
+
+PrevUpHomeNext +
+ + diff --git a/overloaded_function/doc/html/boost/overloaded_function.html b/overloaded_function/doc/html/boost/overloaded_function.html new file mode 100644 index 0000000..7421832 --- /dev/null +++ b/overloaded_function/doc/html/boost/overloaded_function.html @@ -0,0 +1,112 @@ + + + +Class template overloaded_function + + + + + + + + + + + + + + + +
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
+
+
+PrevUpHomeNext +
+
+
+
+

Class template overloaded_function

+

boost::overloaded_function — Function object to overload functions with distinct signatures.

+
+

Synopsis

+
// In header: <boost/functional/overloaded_function.hpp>
+
+template<typename F1, typename F2, ... > 
+class overloaded_function {
+public:
+  // construct/copy/destruct
+  overloaded_function(const boost::function< F1 > &, 
+                      const boost::function< F2 > &, ...);
+
+  // public member functions
+  boost::function_traits< F1 >::result_type 
+  operator()(typename boost::function_traits< F1 >::arg1_type, 
+             typename boost::function_traits< F1 >::arg2_type, ...) const;
+  boost::function_traits< F2 >::result_type 
+  operator()(typename boost::function_traits< F2 >::arg1_type, 
+             typename boost::function_traits< F2 >::arg2_type, ...) const;
+};
+
+

Description

+

This function object aggregates together calls to functions of all the specified function types F1, F2, etc which must have distinct function signatures from one another.

+

Parameters:

+
++++ + + + + +
FiEach function type must be specified using the following syntax (which is Boost.Function's preferred syntax): 
    result_type (argument1_type, argumgnet2_type, ...)
+
+

+

+

In some cases, the make_overloaded_function function template can be useful to construct an overloaded function object without explicitly specifying the function types.

+

At least two distinct function types must be specified (because there is nothing to overload between one or zero functions). The maximum number of functions to overload is given by the BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_OVERLOAD_MAX configuration macro. The maximum number of function parameters for each of the specified function types is given by the BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_ARITY_MAX configuration macro.

+

See: Tutorial section, make_overloaded_function, BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_OVERLOAD_MAX, BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_ARITY_MAX, Boost.Function.

+
+

+overloaded_function + public + construct/copy/destruct

+
  1. +
    overloaded_function(const boost::function< F1 > &, 
+                    const boost::function< F2 > &, ...);
    Construct the overloaded function object.

    Any function pointer, function reference, and monomorphic function object that can be converted to a boost::function function object can be specified as parameter.

    +

    Note: Unfortunately, it is not possible to support polymorphic function objects (as explained here).

    +
+
+
+

+overloaded_function public member functions

+
    +
  1. +
    boost::function_traits< F1 >::result_type 
+operator()(typename boost::function_traits< F1 >::arg1_type, 
+           typename boost::function_traits< F1 >::arg2_type, ...) const;
    Call operator matching the signature of the function type specified as 1st template parameter.

    This will in turn invoke the call operator of the 1st function passed to the constructor.

    +
    2. +
  2. +
    boost::function_traits< F2 >::result_type 
+operator()(typename boost::function_traits< F2 >::arg1_type, 
+           typename boost::function_traits< F2 >::arg2_type, ...) const;
    Call operator matching the signature of the function type specified as 2nd template parameter.

    This will in turn invoke the call operator of the 2nd function passed to the constructor.

    +

    Note: Similar call operators are present for all specified function types F1, F2, etc (even if not exhaustively listed by this documentation).

    +
    3. +
+
+
+
+ + + +
Copyright © 2011, 2012 Lorenzo Caminiti

+ Distributed under the Boost Software License, Version 1.0 (see accompanying + file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +

+
+
+
+PrevUpHomeNext +
+ + diff --git a/overloaded_function/doc/html/boost_functional_overloadedfunction/Acknowledgments.html b/overloaded_function/doc/html/boost_functional_overloadedfunction/Acknowledgments.html new file mode 100644 index 0000000..f03dd92 --- /dev/null +++ b/overloaded_function/doc/html/boost_functional_overloadedfunction/Acknowledgments.html @@ -0,0 +1,60 @@ + + + +Acknowledgments + + + + + + + + + + + + + + +
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
+
+
+PrevUpHome +
+
+
+

+ Many thanks to Mathias Gaunard for suggesting to implement boost::overloaded_function + and for some sample code. +

+

+ Thanks to John Bytheway for suggesting to implement boost::make_overloaded_function. +

+

+ Thanks to Nathan Ridge for suggestions on how to implement boost::make_overloaded_function. +

+

+ Thanks to Robert Stewart for commenting on the library name. +

+

+ Many thanks to the entire Boost community + and mailing list for providing valuable comments about this library and great + insights on the C++ programming language. +

+
+ + + +
Copyright © 2011, 2012 Lorenzo Caminiti

+ Distributed under the Boost Software License, Version 1.0 (see accompanying + file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +

+
+
+
+PrevUpHome +
+ + diff --git a/overloaded_function/doc/html/boost_functional_overloadedfunction/Getting_Started.html b/overloaded_function/doc/html/boost_functional_overloadedfunction/Getting_Started.html new file mode 100644 index 0000000..6ac82c8 --- /dev/null +++ b/overloaded_function/doc/html/boost_functional_overloadedfunction/Getting_Started.html @@ -0,0 +1,95 @@ + + + +Getting Started + + + + + + + + + + + + + + + +
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
+
+
+PrevUpHomeNext +
+
+
+
+
Compilers + and Platforms
+
Installation
+
+

+ This section explains how to setup a system to use this library. +

+
+
+

+ The authors originally developed and tested this library on: +

+
    +
  1. + GNU Compiler Collection (GCC) C++ 4.5.3 (with and without C++11 features + enabled -std=c++0x) + on Cygwin. +
    2. +
  2. + Miscrosoft Visual C++ (MSVC) 8.0 on Windows 7. +
    3. +
+

+ See the library regressions + test results for detailed information on supported compilers and + platforms. Check the library regression test Jamfile.v2 + for any special configuration that might be required for a specific compiler. +

+
+
+
+

+ This library is composed of header files only. Therefore there is no pre-compiled + object file which needs to be installed. Programmers can simply instruct + the compiler where to find the library header files (-I option on GCC, /I option on MSVC, etc) and compile code + using the library. +

+

+ The maximum number of functions to overload is given by the BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_OVERLOAD_MAX + configuration macro. The maximum number of function parameters for each of + the specified function type is given by the BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_ARITY_MAX + configuration macro. All configuration macros have appropriate default values + when they are left undefined. +

+
+
+ + + +
Copyright © 2011, 2012 Lorenzo Caminiti

+ Distributed under the Boost Software License, Version 1.0 (see accompanying + file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +

+
+
+
+PrevUpHomeNext +
+ + diff --git a/overloaded_function/doc/html/boost_functional_overloadedfunction/Tutorial.html b/overloaded_function/doc/html/boost_functional_overloadedfunction/Tutorial.html new file mode 100644 index 0000000..8211939 --- /dev/null +++ b/overloaded_function/doc/html/boost_functional_overloadedfunction/Tutorial.html @@ -0,0 +1,228 @@ + + + +Tutorial + + + + + + + + + + + + + + + +
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
+
+
+PrevUpHomeNext +
+
+
+
+
Overloading
+
Without + Function Types
+
+

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

+
+
+ + + +
Copyright © 2011, 2012 Lorenzo Caminiti

+ Distributed under the Boost Software License, Version 1.0 (see accompanying + file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +

+
+
+
+PrevUpHomeNext +
+ + diff --git a/overloaded_function/doc/html/index.html b/overloaded_function/doc/html/index.html new file mode 100644 index 0000000..c9f1f8d --- /dev/null +++ b/overloaded_function/doc/html/index.html @@ -0,0 +1,147 @@ + + + +Chapter 1. Boost.Functional/OverloadedFunction 1.0.0 + + + + + + + + + + + + + +
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
+
+
Next
+
+
+

+Chapter 1. Boost.Functional/OverloadedFunction 1.0.0

+

+Lorenzo Caminiti +

+

Copyright © 2011, 2012 Lorenzo Caminiti

+
+

+ Distributed under the Boost Software License, Version 1.0 (see accompanying + file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +

+
+
+
+

Table of Contents

+
+
Introduction
+
Getting + Started
+
+
Compilers + and Platforms
+
Installation
+
+
Tutorial
+
+
Overloading
+
Without + Function Types
+
+
Reference
+
+
Header <boost/functional/overloaded_function.hpp>
+
Header <boost/functional/overloaded_function/config.hpp>
+
+
Acknowledgments
+
+
+

+ This library allows to overload different functions into a single function object. +

+
+
+

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

+

+

+ Instead of calling them using their separate names (here BOOST_TEST + is equivalent to assert): + [1] +

+

+

+
BOOST_TEST(identity_s("abc") == "abc");
+BOOST_TEST(identity_i(123) == 123);
+BOOST_TEST(identity_d(1.23) == 1.23);
+
+

+

+

+ It is possible to use this library to create a single overloaded + function object (or functor) + named identity that aggregates + together the calls to the specific functions (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 the functions are called via a single overloaded function object + identity instead of using their + different names identity_s, + identity_i, and identity_d. +

+
+
+
+

[1] + In most of the examples presented in this documentation, the Boost.Detail/LightweightTest + (boost/detail/lightweight_test.hpp) macro BOOST_TEST is used to check correctness + conditions (conceptually similar to assert). + A failure of the checked condition does not abort the execution of the program, + it will instead make boost::report_errors + return a non-zero program exit code. Using Boost.Detail/LightweightTest allows + to add the examples to the library regression tests so to make sure that + they always compile and run correctly. +

+
+
+ + + +

Last revised: April 13, 2012 at 00:59:44 GMT

+
+
Next
+ + diff --git a/overloaded_function/doc/html/reference.html b/overloaded_function/doc/html/reference.html new file mode 100644 index 0000000..3fcf6f5 --- /dev/null +++ b/overloaded_function/doc/html/reference.html @@ -0,0 +1,66 @@ + + + +Reference + + + + + + + + + + + + + + + +
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
+
+
+PrevUpHomeNext +
+
+

+Reference

+
+
Header <boost/functional/overloaded_function.hpp>
+
Header <boost/functional/overloaded_function/config.hpp>
+
+
+
+

Overload distinct function pointers, function references, and monomorphic function objects into a single function object.

+
namespace boost {
+  template<typename F1, typename F2, ... > class overloaded_function;
+  template<typename F1, typename F2, ... > 
+    overloaded_function< __function_type__< F1 >, __function_type__< F2 >,...> 
+    make_overloaded_function(F1, F2, ...);
+}
+
+
+
+

Change the compile-time configuration of this library.

+
+
+BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_ARITY_MAX
+BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_OVERLOAD_MAX
+
+
+ + + +
Copyright © 2011, 2012 Lorenzo Caminiti

+ Distributed under the Boost Software License, Version 1.0 (see accompanying + file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +

+
+
+
+PrevUpHomeNext +
+ + diff --git a/overloaded_function/doc/overloaded_function.qbk b/overloaded_function/doc/overloaded_function.qbk new file mode 100644 index 0000000..6cf6964 --- /dev/null +++ b/overloaded_function/doc/overloaded_function.qbk @@ -0,0 +1,171 @@ + +[/ Copyright (C) 2009-2012 Lorenzo Caminiti ] +[/ Distributed under the Boost Software License, Version 1.0 ] +[/ (see accompanying file LICENSE_1_0.txt or a copy at ] +[/ http://www.boost.org/LICENSE_1_0.txt) ] +[/ Home at http://www.boost.org/libs/functional/overloaded_function ] + +[library Boost.Functional/OverloadedFunction + [quickbook 1.5] + [version 1.0.0] + [copyright 2011-2012 Lorenzo Caminiti] + [purpose overload functions with one function object] + [license + Distributed under the Boost Software License, Version 1.0 + (see accompanying file LICENSE_1_0.txt or copy at + [@http://www.boost.org/LICENSE_1_0.txt]) + ] + [authors [Caminiti lorcaminiti@gmail.com, Lorenzo]] + [category Function Objects and Higher-Order Programming] +] + +[def __Introduction__ [link functional_overloaded_function.introduction Introduction]] +[def __Getting_Started__ [link functional_overloaded_function.getting_started Getting Started]] +[def __Tutorial__ [link functional_overloaded_function.tutorial Tutorial]] +[def __Boost__ [@http://www.boost.org Boost]] +[def __Boost_Test__ [@http://www.boost.org/libs/test Boost.Test]] +[def __Boost_Function__ [@http://www.boost.org/libs/function Boost.Function]] +[def __Boost_Typeof__ [@http://www.boost.org/doc/libs/typeof Boost.Typeof]] + +[import ../test/identity.hpp] +[import ../test/functor.cpp] +[import ../test/make_decl.cpp] +[import ../test/make_call.cpp] + +This library allows to overload different functions into a single function object. + +[section Introduction] + +Consider the following functions which have distinct signatures: + +[identity_decls] + +Instead of calling them using their separate names (here `BOOST_TEST` is equivalent to `assert`): +[footnote +In most of the examples presented in this documentation, the Boost.Detail/LightweightTest (=boost/detail/lightweight_test.hpp=) macro `BOOST_TEST` is used to check correctness conditions (conceptually similar to `assert`). +A failure of the checked condition does not abort the execution of the program, it will instead make `boost::report_errors` return a non-zero program exit code. +Using Boost.Detail/LightweightTest allows to add the examples to the library regression tests so to make sure that they always compile and run correctly. +] + +[identity_calls] + +It is possible to use this library to create a single [@http://en.wikipedia.org/wiki/Function_overloading overloaded] function object (or [@http://en.wikipedia.org/wiki/Functor functor]) named `identity` that aggregates together the calls to the specific functions (see also [@../../test/functor.cpp =functor.cpp=] and [@../../test/identity.hpp =identity.hpp=]): + +[identity_functor] + +Note how the functions are called via a single overloaded function object `identity` instead of using their different names `identity_s`, `identity_i`, and `identity_d`. + +[endsect] + +[section Getting Started] + +This section explains how to setup a system to use this library. + +[section Compilers and Platforms] + +The authors originally developed and tested this library on: + +# GNU Compiler Collection (GCC) C++ 4.5.3 (with and without C++11 features enabled `-std=c++0x`) on Cygwin. +# Miscrosoft Visual C++ (MSVC) 8.0 on Windows 7. + +See the library [@http://www.boost.org/development/tests/release/developer/functional-overloaded_function.html regressions test results] for detailed information on supported compilers and platforms. +Check the library regression test [@../../test/Jamfile.v2 =Jamfile.v2=] for any special configuration that might be required for a specific compiler. + +[endsect] + +[section Installation] + +This library is composed of header files only. +Therefore there is no pre-compiled object file which needs to be installed. +Programmers can simply instruct the compiler where to find the library header files (`-I` option on GCC, `/I` option on MSVC, etc) and compile code using the library. + +The maximum number of functions to overload is given by the [macroref BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_OVERLOAD_MAX] configuration macro. +The maximum number of function parameters for each of the specified function type is given by the [macroref BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_ARITY_MAX] configuration macro. +All configuration macros have appropriate default values when they are left undefined. + +[endsect] + +[endsect] + +[section Tutorial] + +This section explains how to use this library. + +[section Overloading] + +Consider the following functions which have distinct signatures: + +[identity_decls] + +This library header [headerref boost/functional/overloaded_function.hpp] provides a [classref 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 [@../../test/functor.cpp =functor.cpp=] and [@../../test/identity.hpp =identity.hpp=]): + +[identity_functor] + +Note how each function type is passed as a template parameter of [classref 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 [@http://en.wikipedia.org/wiki/Polymorphism_(computer_science) monomorphic function] objects are passed to the [classref boost::overloaded_function] constructor matching the order of the specified template parameters. +[footnote +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]). +] +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). +[footnote +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. +] +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). + +[endsect] + +[section Without Function Types] + +For convenience, this library also provides the [funcref 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 [classref boost::overloaded_function] instantiation is returned by [funcref boost::make_overloaded_function]. + +The [funcref 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 [@../../test/make_decl.cpp =make_decl.cpp=] and [@../../test/identity.hpp =identity.hpp=]): + +[identity_make_decl] + +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 [classref boost::overloaded_function]. +Therefore, [funcref boost::make_overloaded_function] provides a more concise syntax in this context when compared with [classref boost::overloaded_function]. + +Another case where [funcref boost::make_overloaded_function] can be useful is when the overloaded function object is passed to a function template which can hold the specific [classref boost::overloaded_function] type using a template parameter. +For example (see also [@../../test/make_call.cpp =make_call.cpp=] and [@../../test/identity.hpp =identity.hpp=]): + +[identity_make_checks] +[identity_make_call] + +The library implementation of [funcref 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): + +[identity_typeof] + +[endsect] + +[endsect] + +[xinclude reference.xml] + +[section Acknowledgments] + +Many thanks to Mathias Gaunard for suggesting to implement [classref boost::overloaded_function] and for some sample code. + +Thanks to John Bytheway for suggesting to implement [funcref boost::make_overloaded_function]. + +Thanks to Nathan Ridge for suggestions on how to implement [funcref boost::make_overloaded_function]. + +Thanks to Robert Stewart for commenting on the library name. + +Many thanks to the entire __Boost__ community and mailing list for providing valuable comments about this library and great insights on the C++ programming language. + +[endsect] + diff --git a/overloaded_function/index.html b/overloaded_function/index.html new file mode 100644 index 0000000..00b3362 --- /dev/null +++ b/overloaded_function/index.html @@ -0,0 +1,15 @@ + + + + + + + Automatic redirection failed, click this + link  
+

© Copyright Lorenzo Caminiti, 2009-2012

+

Distributed under the Boost Software License, Version 1.0 (see + accompanying file + LICENSE_1_0.txt or a copy at + www.boost.org/LICENSE_1_0.txt)

+ + diff --git a/overloaded_function/test/Jamfile.v2 b/overloaded_function/test/Jamfile.v2 new file mode 100644 index 0000000..3871ee5 --- /dev/null +++ b/overloaded_function/test/Jamfile.v2 @@ -0,0 +1,16 @@ + +# Copyright (C) 2009-2012 Lorenzo Caminiti +# Distributed under the Boost Software License, Version 1.0 +# (see accompanying file LICENSE_1_0.txt or a copy at +# http://www.boost.org/LICENSE_1_0.txt) +# Home at http://www.boost.org/libs/functional/overloaded_function + +import testing ; + +# Sun does not automatically detect type-of emulation (force it). +project : requirements sun:BOOST_TYPEOF_EMULATION ; + +run functor.cpp ; +run make_decl.cpp ; +run make_call.cpp ; + diff --git a/overloaded_function/test/functor.cpp b/overloaded_function/test/functor.cpp new file mode 100644 index 0000000..86827fc --- /dev/null +++ b/overloaded_function/test/functor.cpp @@ -0,0 +1,34 @@ + +// Copyright (C) 2009-2012 Lorenzo Caminiti +// Distributed under the Boost Software License, Version 1.0 +// (see accompanying file LICENSE_1_0.txt or a copy at +// http://www.boost.org/LICENSE_1_0.txt) +// Home at http://www.boost.org/libs/functional/overloaded_function + +#include "identity.hpp" +#include +#include + +int main() { + //[identity_calls + BOOST_TEST(identity_s("abc") == "abc"); + BOOST_TEST(identity_i(123) == 123); + BOOST_TEST(identity_d(1.23) == 1.23); + //] + + //[identity_functor + 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); + //] + + return boost::report_errors(); +} + diff --git a/overloaded_function/test/identity.hpp b/overloaded_function/test/identity.hpp new file mode 100644 index 0000000..5134429 --- /dev/null +++ b/overloaded_function/test/identity.hpp @@ -0,0 +1,29 @@ + +// Copyright (C) 2009-2012 Lorenzo Caminiti +// Distributed under the Boost Software License, Version 1.0 +// (see accompanying file LICENSE_1_0.txt or a copy at +// http://www.boost.org/LICENSE_1_0.txt) +// Home at http://www.boost.org/libs/functional/overloaded_function + +#ifndef IDENTITY_HPP_ +#define IDENTITY_HPP_ + +//[identity_typeof +#include // No need to register `boost::function`. +//] +#include +#include + +//[identity_decls +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 identity_d = identity_d_impl; // Functor. +//] + +#endif // #include guard + diff --git a/overloaded_function/test/make_call.cpp b/overloaded_function/test/make_call.cpp new file mode 100644 index 0000000..e2abdde --- /dev/null +++ b/overloaded_function/test/make_call.cpp @@ -0,0 +1,27 @@ + +// Copyright (C) 2009-2012 Lorenzo Caminiti +// Distributed under the Boost Software License, Version 1.0 +// (see accompanying file LICENSE_1_0.txt or a copy at +// http://www.boost.org/LICENSE_1_0.txt) +// Home at http://www.boost.org/libs/functional/overloaded_function + +#include "identity.hpp" +#include +#include + +//[identity_make_checks +template +void check(F identity) { + BOOST_TEST(identity("abc") == "abc"); + BOOST_TEST(identity(123) == 123); + BOOST_TEST(identity(1.23) == 1.23); +} +//] + +int main() { + //[identity_make_call + check(boost::make_overloaded_function(identity_s, identity_i, identity_d)); + //] + return boost::report_errors(); +} + diff --git a/overloaded_function/test/make_decl.cpp b/overloaded_function/test/make_decl.cpp new file mode 100644 index 0000000..6f5cbdf --- /dev/null +++ b/overloaded_function/test/make_decl.cpp @@ -0,0 +1,24 @@ + +// Copyright (C) 2009-2012 Lorenzo Caminiti +// Distributed under the Boost Software License, Version 1.0 +// (see accompanying file LICENSE_1_0.txt or a copy at +// http://www.boost.org/LICENSE_1_0.txt) +// Home at http://www.boost.org/libs/functional/overloaded_function + +#include "identity.hpp" +#include +#include +#include + +int main() { + //[identity_make_decl + 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); + //] + return boost::report_errors(); +} +