|
+Home | +Libraries | +People | +FAQ | +More | +
++ Boost.FunctionTypes uses tag types to encode properties that are not types + per se, such as calling convention or whether a function is variadic or cv- + qualified. +
++ These tags can be used to determine whether one property of a type has a particular + value. +
++is_function<int(...), variadic>::value // == true +is_function<int() , variadic>::value // == false ++
+ A compound property tag describes a combination of possible values of different
+ properties. The type components<F>, where F
+ is a callable builtin type, is a compound property tag that describes F.
+ The tag class template can be used to combine property tags.
+
+tag<non_const,default_cc> // combination of two properties ++
+ When several values for the same property are specified in tag's
+ argument list, only the rightmost one is used; others are ignored.
+
+tag<components<F>, default_cc> // overrides F's calling convention property ++
+ When compound property tag is specified to analyse a type, all of its component + properties must match. +
++is_member_function_pointer< F, tag<const_qualified,default_cc> >::value +// true for +// F = void(a_class::*)() const +// false for +// F = void(a_class::*)() +// F = void(__fastcall a_class::*)() const ++
+ Default values are selected for properties not specified by the tag in the + context of type synthesis. +
++// given S = mpl::vector<int,a_class const &> + +member_function_pointer<S>::type // is int (a_class::*)() const +// note: the cv-qualification is picked based on the class type, +// a nonvariadic signature and the default calling convention +// are used + +member_function_pointer<S,non_const>::type // is int (a_class::*)() +// no const qualification, as explicitly specified by the tag type ++
| + | Copyright © 2004 -2007 Tobias Schwinger | +
+ |
+Home | +Libraries | +People | +FAQ | +More | +
++ Thanks go to the following people for supporting the development of this library + in one or the other way: +
+| + | Copyright © 2004 -2007 Tobias Schwinger | +
+ |
+Home | +Libraries | +People | +FAQ | +More | +
++ Boost.FunctionTypes provides functionality to classify, decompose and synthesize + function, function pointer, function reference and pointer to member types. +
++ We collectively refer to these types as callable builtin + types. +
++ In particular, the library can be used to: +
++ The library is designed to work well with other Boost libraries and uses well-accepted + concepts introduced by Boost and TR1. +
+
+ Templates that encapsulate boolean or numeric properties define a static member
+ constant called value.
+
+is_function_pointer< bool(*)(int) >::value // == true + +function_arity< bool(*)(int) >::value // == 1 ++
+ Templates that encapsulate properties that are single types contain a type
+ member called type.
+
+function_type< mpl::vector<bool,int> >::type // is bool(int) + +result_type< bool(&)(int) >::type // is bool ++
+ Templates that encapsulate properties that are type lists model an MPL-compatible + type sequence. +
++parameter_types< bool(int) > // models an MPL sequence ++
| + | Copyright © 2004 -2007 Tobias Schwinger | +
+ |
+Home | +Libraries | +People | +FAQ | +More | +
++ The library does not define the required members of class templates in case + of an error. This technique causes the compiler to stop displaying diagnostics + in client code, at the point where the error actually is, instead of tracing + template instantiations into the implementation of the library. +
++ The library's components have limited error conditions, so problematic input + can be spotted easily. +
+
+ MPL provides algorithms on Sequences, so transformations (such as turning by-value
+ parameter types into const references for optimized forwarding or computing
+ a signature to specialize boost::function
+ after applying boost::bind)
+ can be expressed more easily. The MPL Sequence concept is compatible with several
+ other Boost libraries (most importantly Fusion),
+ so another reason is interoperability.
+
+ Despite their syntax, pointer to member object types can be seen as dereferencing + functionals. +
+
+ This-pointer, this-reference or just
+ the object (or maybe even a smart pointer to the object) plus adjustments of
+ cv-qualification - all these cases have their place, somewhere and there is
+ no single best answer.
+
+ Special treatment of the class type within the sequence can significantly complicate
+ client code. A custom ClassTransform argument allows the
+ client to adjust the class type before the sequence is formed and then treat
+ all parameters uniformly.
+
+ Let's consider the alternatives. +
++ The first one is just using more templates so every property has to be asked + for explicitly. This approach results in more complicated client code if more + than one propery has to be checked and in a exponentially larger library interface. +
++ The second alternative is having the client pass in bit patterns via non-type + template parameters. The logic has to be performed by the client and there + are much more error conditions. Further, class templates with non-type template + parameters do not work within MPL lambda expressions and can cause problems + with older compilers. +
++ Yes, but it isn't immediately obvious as the set of possible MPL sequences + isn't inherently disjoint from the set of callable builtin types. +
++ However, any attempt to make a builtin type work as an MPL sequence is a bad + idea, because builtin types are accessible before the headers that make the + type a sequence have been included, which can easily violate the ODR. +
+this parameter count for the function arity
+ of member functions?
+ + It was found preferable that the following condition holds: +
++mpl::size< parameter_types<T> >::value == function_arity<T>::value ++
+ A cv-qualified pointer is still a pointer. It usually doesn't matter and even + if it does, it's a job for Boost.TypeTraits. +
+| + | Copyright © 2004 -2007 Tobias Schwinger | +
+ |
+Home | +Libraries | +People | +FAQ | +More | +
+| + | Copyright © 2004 -2007 Tobias Schwinger | +
+ |
+Home | +Libraries | +People | +FAQ | +More | +
++template<typename T, typename Tag = null_tag> +struct is_function; ++
+ Header +
++#include <boost/function_types/is_function.hpp> ++
+
T+ Type to analyze +
Tag+ Further properties required for a positive result +
is_function<T,Tag>+ Predicate value as MPL + - Integral + Constant +
is_function<T,Tag>::value+ Constant boolean value +
+ Determines whether a given type is a function, possibly with additional + properties as specified by a property tag. +
++template<typename T, typename Tag = null_tag> +struct is_function_pointer; ++
+ Header +
++#include <boost/function_types/is_function_pointer.hpp> ++
+
T+ Type to analyze +
Tag+ Further properties required for a positive result +
is_function_pointer<T,Tag>+ Predicate value MPL - + Integral + Constant +
is_function_pointer<T,Tag>::value+ Constant boolean value +
+ Determines whether a given type is a function pointer, possibly with additional + properties as specified by a property tag. +
++template<typename T, typename Tag = null_tag> +struct is_function_reference; ++
+ Header +
++#include <boost/function_types/is_function_reference.hpp> ++
+
T+ Type to analyze +
Tag+ Further properties required for a positive result +
is_function_reference<T,Tag>+ Predicate value MPL - + Integral + Constant +
is_function_reference<T,Tag>::value+ Constant boolean value +
+ Determines whether a given type is a function reference, possibly with + additional properties as specified by a property tag. +
++template<typename T, typename Tag = null_tag> +struct is_member_pointer; ++
+ Header +
++#include <boost/function_types/is_member_pointer.hpp> ++
+
T+ Type to analyze +
Tag+ Further properties required for a positive result +
is_member_pointer<T,Tag>+ Predicate value MPL - + Integral + Constant +
is_member_pointer<T,Tag>::value+ Constant boolean value +
+ Determines whether a given type is a pointer to member (object or function) + type, possibly with additional properties as specified by a property tag. +
++template<typename T> +struct is_member_object_pointer; ++
+ Header +
++#include <boost/function_types/is_member_object_pointer.hpp> ++
+
T+ Type to analyze +
is_member_object_pointer<T>+ Predicate value MPL - + Integral + Constant +
is_member_object_pointer<T>::value+ Constant boolean value +
+ Determines whether a given type is a pointer to member object type. +
++template<typename T, typename Tag = null_tag> +struct is_member_function_pointer; ++
+ Header +
++#include <boost/function_types/is_member_function_pointer.hpp> ++
+
T+ Type to analyze +
Tag+ Further properties required for a positive result +
is_member_function_pointer<T,Tag>+ Predicate value MPL - + Integral + Constant +
is_member_function_pointer<T,Tag>::value+ Constant boolean value +
+ Determines whether a given type is a member function pointer, possibly + with additional properties as specified by a property tag. +
++template<typename T, typename Tag = null_tag> +struct is_callable_builtin; ++
+ Header +
++#include <boost/function_types/is_callable_builtin.hpp> ++
+
T+ Type to analyze +
Tag+ Further properties required for a positive result +
is_callable_builtin<T,Tag>+ Predicate value as MPL + - Integral + Constant +
is_callable_builtin<T,Tag>::value+ Constant boolean value +
+ Determines whether a given type is a callable builtin, possibly with additional + properties as specified by a property tag. +
++template<typename T, typename Tag = null_tag> +struct is_nonmember_callable_builtin; ++
+ Header +
++#include <boost/function_types/is_nonmember_callable_builtin.hpp> ++
+
T+ Type to analyze +
Tag+ Further properties required for a positive result +
is_nonmember_callable_builtin<T,Tag>+ Predicate value as MPL + - Integral + Constant +
is_nonmember_callable_builtin<T,Tag>::value+ Constant boolean value +
+ Determines whether a given type is a callable builtin that is not a member + function pointer, possibly with additional properties as specified by a + property tag. +
+| + | Copyright © 2004 -2007 Tobias Schwinger | +
+ |
+Home | +Libraries | +People | +FAQ | +More | +
++template<typename F> +struct result_type; ++
+ Header +
++#include <boost/function_types/result_type.hpp> ++
+
F+ Type to analyze +
result_type<F>::type
+ Result type of F
+
+ Extracts the result type of a callable, builtin type. +
+
+ If F is no callable, builtin type, any attempt to access
+ the type member results in a compile error.
+
+template<typename F, class ClassTransform = add_reference<_> > +struct parameter_types; ++
+ Header +
++#include <boost/function_types/parameter_types.hpp> ++
+
F+ Type to analyze +
ClassTransform
+ MPL - Lambda
+ Expression to transform the class type if F
+ is a member function pointer
+
parameter_types<F,ClassTransform>+ MPL - Front + / Back + Extensible + Random + Access Sequence of parameter types +
+ Extracts the parameter types of a callable, builtin type. +
+
+ If F is no callable, builtin type, any attempt to access
+ the sequence results in a compile error.
+
+template<typename F> +struct function_arity; ++
+ Header +
++#include <boost/function_types/function_arity.hpp> ++
+
F+ Callable builtin type +
function_arity<F>+ Function arity as MPL + - Integral + Constant +
function_arity<F>::value+ Constant value of the function arity +
+ Extracts the function arity, that is the number of parameters. The hidden
+ this of member function pointers counts, in other words
+ the arity value is always greater than or equal to one if F
+ is a member function pointer.
+
+ If F is no callable, builtin type, any attempt to access
+ the value results in a compile error.
+
+template<typename T, class ClassTransform = add_reference<_> > +struct components; ++
+ Header +
++#include <boost/function_types/components.hpp> ++
+
T+ Type to analyze +
ClassTransform
+ MPL - Lambda
+ Expression to transform the class type if T
+ is a member function pointer
+
components<T,ClassTransform>+ MPL - Front + / Back + Extensible + Random + Access Sequence of all component types and property tag +
components<T,ClassTransform>::types+ Decorated MPL Sequence, exposed for optimization +
+ Extracts all properties of a callable builtin type, that is the result
+ type, followed by the parameter types (including the type of this
+ for member function pointers).
+
+ If T is no callable builtin type, the component types
+ are an empty sequence and the Tag's meaning is equivalent to the null_tag.
+
| + | Copyright © 2004 -2007 Tobias Schwinger | +
+ |
+Home | +Libraries | +People | +FAQ | +More | +
++ Expands to a numeric value that describes the maximum function arity supported + by the library. +
++ Defaults to 20 if not explicitly defined by the user before inclusion of + the first library header. +
+
+ The following macros do not need to be defined, unless
+ to configure the library to work with a compiler and/or calling convention
+ not covered by the auto-detection mechanism in boost/function_types/config/compiler.hpp.
+
+ Expands to a sequence
+ of ternary tuples
+ (these data types are defined in the documentation
+ of the Boost Preprocessor library). Each sequence element describes
+ one calling convention specifier. The first element in each tuple is the
+ macro suffix for BOOST_FT_CC_*,
+ the second element is the name of the tag that describes the calling convention
+ and the third is the name of the specifier. The specifier is allowed to
+ be an empty string, so the third tuple element is either BOOST_PP_EMPTY
+ or BOOST_PP_IDENTITY(name).
+
+ Define this macro to extend the set of possible names for custom calling + conventions. The macro expands to nothing by default. +
+
+ The following names are predefined by the library and must not occur in
+ the definition of BOOST_FT_CC_NAMES:
+
+#define BOOST_FT_BUILTIN_CC_NAMES \ + (( IMPLICIT , implicit_cc , BOOST_PP_EMPTY ))\ + (( CDECL , cdecl_cc , BOOST_PP_IDENTITY(__cdecl ) ))\ + (( STDCALL , stdcall_cc , BOOST_PP_IDENTITY(__stdcall ) ))\ + (( PASCAL , pascal_cc , BOOST_PP_IDENTITY(pascal ) ))\ + (( FASTCALL , fastcall_cc , BOOST_PP_IDENTITY(__fastcall) ))\ + (( CLRCALL , clrcall_cc , BOOST_PP_IDENTITY(__clrcall ) ))\ + (( THISCALL , thiscall_cc , BOOST_PP_IDENTITY(__thiscall) ))\ + (( IMPLICIT_THISCALL , thiscall_cc , BOOST_PP_EMPTY )) +// Don't get confused by the last line, here (thiscall can't be specified +// explicitly prior to MSVC 8). ++
+ Enables a specific calling convention. * dentoes the macro suffix, as defined
+ by BOOST_FT_CC_NAMES
+ or BOOST_FT_BUILTIN_CC_NAMES.
+
+ The macro expands to a list of restrictions, separated by the |
+ character. Possible items are:
+
+ If no such macro is defined for a particular calling convention, it is + disabled. Example: +
++#define BOOST_FT_CC_STDCALL non_variadic|callable_builtin +// enables stdcall calling convention for all non-variadic, +// callable, builtin types ++
+ Defining this macro causes the following macros to be defined, if not defined + already: +
++#define BOOST_FT_CC_CDECL BOOST_FT_COMMON_X86_CCs +#define BOOST_FT_CC_STDCALL non_variadic|BOOST_FT_COMMON_X86_CCs +#define BOOST_FT_CC_FASTCALL non_variadic|BOOST_FT_COMMON_X86_CCs ++
+ This macro allows to change the syntax of callable builtin types. It is + useful to handle the compiler specific placement of the calling convention + specifier. +
++ The default definition is as follows: +
++#define BOOST_FT_SYNTAX(result,lparen,cc_spec,type_mod,name,rparen) \ + result() lparen() cc_spec() type_mod() name() rparen() ++
+ Set to void for compilers that insist on a void
+ parameter for nullary function types, empty by default.
+
+ Disables support for cv-qualified function types. Cv-qualified function
+ types are illegal by the current standard version, but there is a pending
+ defect report on that issue. It defaults to 1 until
+ the standard changes, setting this macro to 0 may not
+ work.
+
+ The following macros are useful for testing when changing + the source code of the library. +
++ Makes the compiler preprocess as much as possible of the library code (rather + than loading already-preprocessed header files) if defined. +
++ Makes the compiler preprocess the loop over possible names for custom calling + conventions (rather than loading an already-preprocessed header file) if + defined. +
+
+ This macro is defined automatically if BOOST_FT_CC_NAMES
+ has been defined.
+
| + | Copyright © 2004 -2007 Tobias Schwinger | +
+ |
+Home | +Libraries | +People | +FAQ | +More | +
++template<typename Types, typename Tag = null_tag> +struct function_type; ++
+ Header +
++#include <boost/function_types/function_type.hpp> ++
+
Types+ Component types in form of an MPL + - Forward + Sequence or another callable, builtin type +
Tag+ Further properties +
function_type<Types,Tag>::type+ Synthesized type +
+ Synthesizes a function type from given properties. +
+
+ If the template parameters do not describe a valid type, any attempt to
+ access the type member will result in a compile error.
+
+template<typename Types, typename Tag = null_tag> +struct function_pointer; ++
+ Header +
++#include <boost/function_types/function_pointer.hpp> ++
+
Types+ Component types in form of an MPL + - Forward + Sequence or another callable, builtin type +
Tag+ Further properties +
function_pointer<Types,Tag>::type+ Synthesized type +
+ Synthesizes a function pointer type from given properties. +
+
+ If the template parameters do not describe a valid type, any attempt to
+ access the type member will result in a compile error.
+
+template<typename Types, typename Tag = null_tag> +struct function_reference; ++
+ Header +
++#include <boost/function_types/function_reference.hpp> ++
+
Types+ Component types in form of an MPL + - Forward + Sequence or another callable, builtin type +
Tag+ Further properties +
function_reference<Types,Tag>::type+ Synthesized type +
+ Synthesizes a function reference type from given properties. +
+
+ If the template parameters do not describe a valid type, any attempt to
+ access the type member will result in a compile error.
+
+template<typename Types, typename Tag = null_tag> +struct member_function_pointer; ++
+ Header +
++#include <boost/function_types/member_function_pointer.hpp> ++
+
Types+ Component types in form of an MPL + - Forward + Sequence or another callable, builtin type +
Tag+ Further properties +
member_function_pointer<Types,Tag>::type+ Synthesized type +
+ Synthesizes a member function pointer type from given properties. +
++ An optional reference or possibly cv-qualified pointer is removed from + the second type in the sequence to determine the the class type. The cv-qualification + of the resulting type applies to the member function, unless otherwise + explicitly specified by the property tag. +
+
+ If the template parameters do not describe a valid type, any attempt to
+ access the type member will result in a compile error.
+
| + | Copyright © 2004 -2007 Tobias Schwinger | +
+ |
+Home | +Libraries | +People | +FAQ | +More | +
++typedef unspecified variadic; ++
+ Header +
++#include <boost/function_types/property_tags.hpp> ++
+ States that a function type takes a variable number of arguments through
+ an ellipsis parameter (such as printf).
+
+typedef unspecified non_variadic; ++
+ Header +
++#include <boost/function_types/property_tags.hpp> ++
+ States that a function type does not have an ellipsis parameter. +
++typedef unspecified default_cc; ++
+ Header +
++#include <boost/function_types/property_tags.hpp> ++
+ States that a function type encodes the default calling convention. +
++typedef unspecified const_qualified; ++
+ Header +
++#include <boost/function_types/property_tags.hpp> ++
+ States that a function type is const qualified. +
++typedef unspecified non_const; ++
+ Header +
++#include <boost/function_types/property_tags.hpp> ++
+ States that a function type is not const qualified. +
++typedef unspecified volatile_qualified; ++
+ Header +
++#include <boost/function_types/property_tags.hpp> ++
+ States that a function type is volatile qualified. +
++typedef unspecified non_volatile; ++
+ Header +
++#include <boost/function_types/property_tags.hpp> ++
+ States that a function type is not volatile qualified. +
++typedef unspecified non_cv; ++
+ Header +
++#include <boost/function_types/property_tags.hpp> ++
+ States that a function type is neither const nor volatile qualified. Equivalent
+ to __tag<__non_const,__non_volatile>,
+ but involves fewer template instantiations when evaluated.
+
+typedef unspecified const_non_volatile; ++
+ Header +
++#include <boost/function_types/property_tags.hpp> ++
+ States that a function type is const but not volatile qualified. Equivalent
+ to __tag<__const_qualified,__non_volatile>,
+ but involves fewer template instantiations when evaluated.
+
+typedef unspecified volatile_non_const; ++
+ Header +
++#include <boost/function_types/property_tags.hpp> ++
+ States that a function type is volatile but not const qualified. Equivalent
+ to __tag<__volatile_qualified,__non_const>,
+ but involves fewer template instantiations when evaluated.
+
+typedef unspecified cv_qualified; ++
+ Header +
++#include <boost/function_types/property_tags.hpp> ++
+ States that a function type is both const and volatile qualified. Equivalent
+ to __tag<__const_qualified,__volatile_qualified>,
+ but involves fewer template instantiations when evaluated.
+
+typedef unspecified null_tag; ++
+ Header +
++#include <boost/function_types/property_tags.hpp> ++
+ States nothing. +
++template<class Tag1, class Tag2, + class Tag3 = null_tag, class Tag4 = null_tag> +struct tag; ++
+ Header +
++#include <boost/function_types/property_tags.hpp> ++
+
TagN+ Property tag +
tag<Tag1,Tag2...>+ Compound property tag +
+ Combination of up to four property tags. If the arguments describe different + values for the same property the value of the rightmost argument is used. +
+| + | Copyright © 2004 -2007 Tobias Schwinger | +
+ |
+Home | +Libraries | +People | +FAQ | +More | +
+
+ Generic libraries that accept callable arguments are common in C++. Accepting
+ a callable argument of builin type often involves a lot of repetitive code
+ because the accepting function is overloaded for different function arities.
+ Further, member functions may have const/volatile-qualifiers,
+ a function may take a variable number of (additional, POD-typed) arguments
+ (such as printf) and several C++ implementations encode
+ a calling convention with each function's type to allow calls across language
+ or (sub-)system boundaries.
+
+template<typename R> +void accept_function(R(* func)()); + +template<typename R> +void accept_function(R(& func)()); + +template<typename R, typename C> +void accept_function(R(C::* func)()); + +template<typename R, typename C> +void accept_function(R(C::* func)() const); + +template<typename R, typename C> +void accept_function(R(C::* func)() volatile); + +template<typename R, typename C> +void accept_function(R(C::* func)() const volatile); + +template<typename R> +void accept_function(R(* func)(...)); + +template<typename R> +void accept_function(R(& func)(...)); + +template<typename R, typename C> +void accept_function(R(C::* func)(...)); + +template<typename R, typename C> +void accept_function(R(C::* func)(...) const); + +template<typename R, typename C> +void accept_function(R(C::* func)(...) volatile); + +template<typename R, typename C> +void accept_function(R(C::* func)(...) const volatile); + +// ... + +// needs to be repeated for every additional function parameter +// times the number of possible calling conventions ++
+ The "overloading approach" obviously does not scale well: There might + be several functions that accept callable arguments in one library and client + code might end up using several libraries that use this pattern. On the developer + side, library developers spend their time solving the same problem, working + around the same portability issues, and apply similar optimizations to keep + the compilation time down. +
++ Using Boost.FunctionTypes it is possible to write a single function template + instead: +
++template<typename F> +void accept_function(F f) +{ + // ... use Boost.FunctionTypes to analyse F +} ++
+ The combination with a tuples library that provides an invoker component, such + as Boost.Fusion, allows to + build flexible callback facilities that are entirely free of repetitive code + as shown by the interpreter + example. +
+
+ When taking the address of an overloaded function or function template, the
+ type of the function must be known from the context the expression is used
+ in. The code below shows three examples for choosing the float(float)
+ overload of std::abs.
+
+float (*ptr_absf)(float) = & std::abs; + + +void foo(float(*func)(float)); + +void bar() +{ + foo(& std::abs); +} + + +std::transform(b, e, o, static_cast<float(*)(float)>(& std::abs)); ++
+ The library's type synthesis capabilities can be used to automate overload + selection and instantiation of function templates. Given an overloaded function + template +
++template<typename R, typename T0> +R overloaded(T0); + +template<typename R, typename T0, typename T1> +R overloaded(T0,T1); + +template<typename R. typename T0, typename T1, typename T2> +R overloaded(T0,T1,T2); ++
+ we can pick any of the three overloads and instantiate the template with template + arguments from a type sequence in a single expression: +
++static_cast<function_pointer<Seq>::type>(& overloaded) ++
+ This technique can be occasionally more flexible than template argument deduction + from a function call because the exact types from the sequence are used to + specialize the template (including possibly cv-qualified reference types and + the result type). It is applied twice in the interface + example. +
++ Another interersting property of callable, builtin types is that they can be + valid types for non-type template parameters. This way, a function can be pinpointed + at compile time, allowing the compiler to eliminate the call by inlining. The + fast_mem_fn example + exploits this characteristic and implements a potentially inlining version + of boost::mem_fn limited to + member functions that are known at compile time. +
+| + | Copyright © 2004 -2007 Tobias Schwinger | +
+ |
+Home | +Libraries | +People | +FAQ | +More | +
Copyright © 2004 -2007 Tobias Schwinger
+ 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
+Last revised: November 05, 2007 at 18:24:58 +0100 |
++ |