functional.qbk

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

[/==============================================================================
    Copyright (C) 2001-2007 Joel de Guzman, Dan Marsden, Tobias Schwinger

    Use, modification and distribution is subject to 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)
===============================================================================/]
[section Functional]

Components to call functions and function objects and to make Fusion code
callable through a function object interface.

/functional.hpp>

[heading Fused and unfused forms]

What is a function call?

    f (a,b,c)

It is a name and a tuple written next to each other, left-to-right.

Although the C++ syntax does not allow to replace [^(a,b,c)] with some Fusion
__sequence__, introducing yet another function provides a solution:

   invoke(f,my_sequence)

Alternatively it is possible to apply a simple transformation to [^f] in order
to achieve the same effect:

   f tuple <=> ``f'`` (tuple)

Now, [^f'] is an unary function that takes the arguments to `f` as a tuple;
[^f'] is the /fused/ form of `f`.
Reading the above equivalence right-to-left to get the inverse transformation,
`f` is the /unfused/ form of [^f'].

[heading Calling functions and function objects]

Having generic C++ code call back arbitrary functions provided by the client
used to be a heavily repetitive task, as different functions can differ in
arity, invocation syntax and other properties that might be part of the type.
Transporting arguments as Fusion sequences and factoring out the invocation
makes Fusion algorithms applicable to function arguments and also reduces
the problem to one invocation syntax and a fixed arity (instead of an arbitrary
number of arbitrary arguments times several syntactic variants times additional
properties).

Transforming an unfused function into its fused counterpart allows n-ary
calls from an algorithm that invokes an unary __poly_func_obj__ with
__sequence__ arguments.

The library provides several function templates to invoke different kinds of
functions and adapters to transform them into fused form, respectively.
Every variant has a corresponding generator function template that returns
an adapter instance for the given argument.

[heading Making Fusion code callable through a function object interface]

Transforming a fused function into its unfused counterpart allows to create
function objects to accept arbitrary calls. In other words, an unary function
object can be implemented instead of (maybe heavily overloaded) function
templates or function call operators.

The library provides several adapter variants that implement this
transformation, ranging from strictly typed to fully generic. The latter
provides a reusable, approximate solution to __the_forwarding_problem__.
Every generic variant has a corresponding generator function template that
returns an adapter instance for the given argument.

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

[section Concepts]


[section:callable Callable Object]

[heading Description]

A pointer to a function, a pointer to member function, a pointer to member
data, or a class type whose objects can appear immediately to the left of a
function call operator.

[heading Models]
* function pointer types
* member (function or data) pointer types
* all kinds of function objects

[heading Examples]

  & a_free_function
  & a_class::a_static_member_function
  & a_class::a_nonstatic_data_member
  & a_class::a_nonstatic_member_function
  std::less<int>()
  // using namespace boost;
  bind(std::less<int>(), _1, 5)
  lambda::_1 += lambda::_2;
  fusion::__make_fused_function_object__(std::less<int>())


[endsect]


[section:reg_callable Regular Callable Object]

[heading Description]

A non-member-pointer __callable_obj__ type: A pointer to a function or a class
type whose objects can appear immediately to the left of a function call operator.

[heading Refinement of]
* __callable_obj__

[variablelist Notation
    [[`F`][A possibly const qualified Deferred Callable Object type]]
    [[`f`][An object or reference to an object of type F]]
    [[`A1 ...AN`][Argument types]]
    [[`a1 ...aN`][Objects or references to objects with types `A1 ...AN`]]
]

[heading Expression requirements]

[table
    [[Expression][Return Type][Runtime Complexity]]
    [[`f(a1, ...aN)`][Unspecified][Unspecified]]
]

[heading Models]
* function pointer types
* all kinds of function objects

[heading Examples]

  & a_free_function
  & a_class::a_static_member_function
  std::less<int>()
  // using namespace boost;
  bind(std::less<int>(), _1, 5)
  lambda::_1 += lambda::_2;
  fusion::__make_fused_function_object__(std::less<int>())

[endsect]


[section:def_callable Deferred Callable Object]

[heading Description]

__callable_obj__ types that work with __boost_result_of__ to determine the
result of a call.

[heading Refinement of]
* __callable_obj__

[blurb note Once C++ supports the [^decltype] keyword, all models of
__callable_obj__ will also be models of __def_callable_obj__, because
function objects won't need client-side support for `result_of`.
]

[variablelist Notation
    [[`F`][A possibly const qualified Deferred Callable Object type]]
    [[`A1 ...AN`][Argument types]]
    [[`a1 ...aN`][Objects or references to objects with types `A1 ...AN`]]
    [[`T1 ...TN`][`T`i is `A`i `&` if `a`i is an __lvalue__, same as `A`i, otherwise]]
]

[heading Expression requirements]

[table
    [[Expression][Type]]
    [[__boost_result_of_call__`< F(T1 ...TN) >::type`][Result of a call with `A1 ...AN`-typed arguments]]
]

[heading Models]
* __poly_func_obj__ types
* member (function or data) pointer types

[heading Examples]

  & a_free_function
  & a_class::a_static_member_function
  & a_class::a_nonstatic_data_member
  & a_class::a_nonstatic_member_function
  std::less<int>()
  // using namespace boost;
  bind(std::less<int>(), _1, 5)
  // Note: Boost.Lambda expressions don't work with __boost_result_of__
  fusion::__make_fused_function_object__(std::less<int>())

[endsect]


[section:poly Polymorphic Function Object]

[heading Description]

A non-member-pointer __def_callable_obj__ type.

[heading Refinement of]
* __reg_callable_obj__
* __def_callable_obj__

[variablelist Notation
    [[`F`][A possibly const-qualified Polymorphic Function Object type]]
    [[`f`][An object or reference to an object of type F]]
    [[`A1 ...AN`][Argument types]]
    [[`a1 ...aN`][Objects or references to objects with types `A1 ...AN`]]
    [[`T1 ...TN`][`T`i is `A`i `&` if `a`i is an __lvalue__, same as `A`i, otherwise]]
]

[heading Expression requirements]

[table
    [[Expression][Return Type][Runtime Complexity]]
    [[`f(a1, ...aN)`][`result_of< F(T1, ...TN) >::type`][Unspecified]]
]

[heading Models]
* function pointers
* function objects of the Standard Library
* all Fusion __functional_adapters__

[heading Examples]

  & a_free_function
  & a_class::a_static_member_function
  std::less<int>()
  // using namespace boost;
  bind(std::less<int>(), _1, 5)
  // Note: Boost.Lambda expressions don't work with __boost_result_of__
  fusion::__make_fused_function_object__(std::less<int>())

[endsect]


[endsect]

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

[section Invocation]

[section Functions]

[section invoke]

[heading Description]

Calls a __def_callable_obj__ with the arguments from a __sequence__.

The first template parameter can be specialized explicitly to avoid copying
and/or to control the const qualification of a function object.

If the target function is a pointer to a class members, the corresponding
object can be specified as a reference, pointer, or smart pointer.
In case of the latter, a freestanding [^get_pointer] function must be
defined (Boost provides this function for [^std::auto_ptr] and
__boost_shared_ptr_call__).

[heading Synopsis]
    template<
        typename Function,
        class Sequence
        >
    typename __result_of_invoke__<Function, Sequence>::type
    invoke(Function f, Sequence & s);

    template<
        typename Function,
        class Sequence
        >
    typename __result_of_invoke__<Function, Sequence const>::type
    invoke(Function f, Sequence const & s);

[heading Parameters]
[table
    [[Parameter]  [Requirement]                    [Description]]
    [[`f`]        [A __def_callable_obj__]         [The function to call.]]
    [[`s`]        [A __forward_sequence__]         [The arguments.]]
]

[heading Expression Semantics]

    invoke(f,s);

[*Return type]: Return type of `f` when invoked with the elements in `s` as its
arguments.

[*Semantics]: Invokes `f` with the elements in `s` as arguments and returns
the result of the call expression.

/functional/invocation/invoke.hpp>

[heading Example]
    __std_plus_doc__<int> add;
    assert(invoke(add,__make_vector__(1,1)) == 2);

[heading See also]
* __invoke_procedure__
* __invoke_function_object__
* __result_of_invoke__
* __fused__

[endsect]

[section:invoke_proc invoke_procedure]

[heading Description]

Calls a __callable_obj__ with the arguments from a __sequence__. The result
of the call is ignored.

The first template parameter can be specialized explicitly to avoid copying
and/or to control the const qualification of a function object.

For pointers to class members corresponding object can be specified as
a reference, pointer, or smart pointer. In case of the latter, a freestanding
[^get_pointer] function must be defined (Boost provides this function for
[^std::auto_ptr] and __boost_shared_ptr_call__).

The target function must not be a pointer to a member object (dereferencing
such a pointer without returning anything does not make sense, so it isn't
implemented).

[heading Synopsis]
    template<
        typename Function,
        class Sequence
        >
    typename __result_of_invoke_procedure__<Function, Sequence>::type
    invoke_procedure(Function f, Sequence & s);

    template<
        typename Function,
        class Sequence
        >
    typename __result_of_invoke_procedure__<Function, Sequence const>::type
    invoke_procedure(Function f, Sequence const & s);

[heading Parameters]
[table
    [[Parameter]  [Requirement]                    [Description]]
    [[`f`]        [Model of __callable_obj__]      [The function to call.]]
    [[`s`]        [Model of __forward_sequence__]  [The arguments.]]
]

[heading Expression Semantics]

    invoke_procedure(f,s);

[*Return type]: `void`

[*Semantics]: Invokes `f` with the elements in `s` as arguments.

/functional/invocation/invoke_procedure.hpp>

[heading Example]
    __vector__<int,int> v(1,2);
    using namespace boost::lambda;
    invoke_procedure(_1 += _2, v);
    assert(__front__(v) == 3);

[heading See also]
* __invoke__
* __invoke_function_object__
* __result_of_invoke_procedure__
* __fused_procedure__

[endsect]

[section:invoke_fobj invoke_function_object]

[heading Description]

Calls a __poly_func_obj__ with the arguments from a __sequence__.

The first template parameter can be specialized explicitly to avoid copying
and/or to control the const qualification of a function object.

[heading Synopsis]
    template<
        typename Function,
        class Sequence
        >
    typename __result_of_invoke_function_object__<Function, Sequence>::type
    invoke_function_object(Function f, Sequence & s);

    template<
        typename Function,
        class Sequence
        >
    typename __result_of_invoke_function_object__<Function, Sequence const>::type
    invoke_function_object(Function f, Sequence const & s);

[heading Parameters]
[table
    [[Parameter]  [Requirement]                    [Description]]
    [[`f`]        [Model of __poly_func_obj__]     [The function object to call.]]
    [[`s`]        [Model of __forward_sequence__]  [The arguments.]]
]

[heading Expression Semantics]

    invoke_function_object(f,s);

[*Return type]: Return type of `f` when invoked with the elements in `s` as its
arguments.

[*Semantics]: Invokes `f` with the elements in `s` as arguments and returns the
result of the call expression.

/functional/invocation/invoke_function_object.hpp>

[heading Example]
    struct sub
    {
        template <typename Sig>
        struct result;

        template <class Self, typename T>
        struct result< Self(T,T) >
        { typedef typename remove_reference<T>::type type; };

        template<typename T>
        T operator()(T lhs, T rhs) const
        {