function_types.qbk

Boost provides free peer-reviewed portable C++ source libraries. We emphasize libraries that work

[library Boost.FunctionTypes
  [quickbook 1.3]
  [version 2.5]
  [authors [Schwinger, Tobias]]
  [copyright 2004-2007 Tobias Schwinger]
  [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])
  ]
  [purpose Meta-programming support library]
  [category template]
  [category generic]
  [last-revision $Date: 2008-03-17 17:42:41 -0400 (Mon, 17 Mar 2008) $]
]

[def __unspecified__ /unspecified/]

[def __mpl__ [@../../../mpl/index.html MPL]]
[def __mpl_integral_constant__ __mpl__ - [@../../../mpl/doc/refmanual/integral-constant.html Integral Constant]]
[def __mpl_fwd_seq__ __mpl__ - [@../../../mpl/doc/refmanual/forward-sequence.html Forward Sequence]]
[def __mpl_fb_ext_ra_seq__ __mpl__ - [@../../../mpl/doc/refmanual/front-extensible-sequence.html Front] / [@../../../mpl/doc/refmanual/back-extensible-sequence.html Back ][@../../../mpl/doc/refmanual/extensible-sequence.html Extensible ][@../../../mpl/doc/refmanual/random-access-sequence.html Random Access Sequence]]
[def __mpl_lambda_expression__  __mpl__ - [@../../../mpl/doc/refmanual/lambda-expression.html Lambda Expression]]

[def __is_function [link boost_functiontypes.reference.classification.is_function is_function]]
[def __is_function_pointer [link boost_functiontypes.reference.classification.is_function_pointer is_function_pointer]]
[def __is_function_reference [link boost_functiontypes.reference.classification.is_function_reference is_function_reference]]
[def __is_member_function_pointer [link boost_functiontypes.reference.classification.is_member_function_pointer is_member_function_pointer]]
[def __is_callable_builtin [link boost_functiontypes.reference.classification.is_callable_builtin is_callable_builtin]]
[def __is_nonmember_callable_builtin [link boost_functiontypes.reference.classification.is_nonmember_callable_builtin is_nonmember_callable_builtin]]

[def __components [link boost_functiontypes.reference.decomposition.components components]]
[def __parameter_types [link boost_functiontypes.reference.decomposition.parameter_types parameter_types]]
[def __function_arity [link boost_functiontypes.reference.decomposition.function_arity function_arity]]
[def __result_type [link boost_functiontypes.reference.decomposition.result_type result_type]]

[def __function_type [link boost_functiontypes.reference.synthesis.function_type function_type]]
[def __function_pointer [link boost_functiontypes.reference.synthesis.function_pointer function_pointer]]
[def __function_reference [link boost_functiontypes.reference.synthesis.function_reference function_reference]
[def __member_function_pointer [link boost_functiontypes.reference.synthesis.member_function_pointer member_function_pointer]]

[def __null_tag [link boost_functiontypes.reference.tag_types.null_tag null_tag]]

[/ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ]

[section:introduction Introduction]

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:

* test whether a type is a specific callable, builtin type,
* extract all component properties from callable, builtin types, and
* create callable, builtin types from specified properties.

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

[endsect]

[section:use_cases Use Cases]

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 [@../../../fusion/index.html Boost.Fusion], allows to build flexible callback 
facilities that are entirely free of repetitive code as shown by the 
[@../../../function_types/example/interpreter.hpp 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 
[@../../../function_types/example/interface.hpp 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 [@../../../function_types/example/fast_mem_fn.hpp fast_mem_fn example]
exploits this characteristic and implements a potentially inlining version of 
[@../../../bind/mem_fn.html boost::mem_fn]
limited to member functions that are known at compile time. 

[endsect]


[/ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ]
[section:about_tag_types About Tag Types]

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

[endsect]


[/ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ]

[section:reference Reference]


[section:classification Class templates for type classification]

[section:is_function is_function]

  template<typename T, typename Tag = __null_tag>
  struct is_function;

[*Header]

  #include <boost/function_types/is_function.hpp>

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

[endsect]


[section:is_function_pointer is_function_pointer]

  template<typename T, typename Tag = __null_tag>
  struct is_function_pointer;

[*Header]

  #include <boost/function_types/is_function_pointer.hpp>

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

[endsect]


[section:is_function_reference is_function_reference]

  template<typename T, typename Tag = __null_tag>
  struct is_function_reference;

[*Header]

  #include <boost/function_types/is_function_reference.hpp>

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

[endsect]


[section:is_member_pointer is_member_pointer]

  template<typename T, typename Tag = __null_tag>
  struct is_member_pointer;

[*Header]

  #include <boost/function_types/is_member_pointer.hpp>

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

[endsect]


[section:is_member_object_pointer is_member_object_pointer]

  template<typename T>
  struct is_member_object_pointer;

[*Header]

  #include <boost/function_types/is_member_object_pointer.hpp>

[variablelist
  [[[^T]][Type to analyze]]
  [[[^is_member_object_pointer<T>]][Predicate value __mpl_integral_constant__]]
  [[[^is_member_object_pointer<T>::value]][Constant boolean value]]
]