[/==============================================================================
    Copyright (C) 2001-2010 Joel de Guzman
    Copyright (C) 2001-2005 Dan Marsden
    Copyright (C) 2001-2010 Thomas Heller

    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)
===============================================================================/]

[section Bind]

['Binding] is the act of tying together a function to some arguments for
deferred (lazy) evaluation. Named [link phoenix.reference.modules.function lazy functions]
require a bit of typing. Unlike (unnamed) lambda expressions, we need to write a
functor somewhere offline, detached from the call site. If you wish to transform a
plain function, member function or member variable to a lambda expression, `bind`
is your friend.

[note Take note that binders are monomorphic. Rather than binding
functions, the preferred way is to write true generic and polymorphic [link
phoenix.reference.modules.function lazy functions]. However, since most of the time we
are dealing with adaptation of existing code, binders get the job done faster.]

There is a set of overloaded `bind` template functions. Each `bind(x)`
function generates a suitable binder object.
[/, a [link phoenix.reference.composite
composite].]

[section Binding Functions]

    #include <boost/phoenix/bind/bind_function.hpp>

Example, given a function `foo`:

    void foo(int n)
    {
        std::cout << n << std::endl;
    }

Here's how the function `foo` may be bound:

    bind(&foo, arg1)

This is now a full-fledged composite that can finally
be evaluated by another function call invocation. A second function call will
invoke the actual `foo` function. Example:

    bind(&foo, arg1)(4);

will print out "4".

[endsect]
[section Binding Member Functions]

    #include <boost/phoenix/bind/bind_member_function.hpp>

Binding member functions can be done similarly. A bound member function takes in
a pointer or reference to an object as the first argument. For instance, given:

    struct xyz
    {
        void foo(int) const;
    };

`xyz`'s `foo` member function can be bound as:

    bind(&xyz::foo, obj, arg1) // obj is an xyz object

Take note that a lazy-member functions expects the first argument to be a
pointer or reference to an object. Both the object (reference or pointer) and
the arguments can be lazily bound. Examples:

    xyz obj;
    bind(&xyz::foo, arg1, arg2)     // arg1.foo(arg2)
    bind(&xyz::foo, obj, arg1)      // obj.foo(arg1)
    bind(&xyz::foo, obj, 100)       // obj.foo(100)

[endsect]
[section Binding Member Variables]

    #include <boost/phoenix/bind/bind_member_variable.hpp>

Member variables can also be bound much like member functions. Member variables
are not functions. Yet, like the [link phoenix.reference.modules.core.references `ref(x)`] that
acts like a nullary function returning a reference to the data, member variables,
when bound, act like a unary function, taking in a pointer or reference to an
object as its argument and returning a reference to the bound member variable.
For instance, given:

    struct xyz
    {
        int v;
    };

`xyz::v` can be bound as:

    bind(&xyz::v, obj) // obj is an xyz object

As noted, just like the bound member function, a bound member variable also
expects the first (and only) argument to be a pointer or reference to an object.
The object (reference or pointer) can be lazily bound. Examples:

    xyz obj;
    bind(&xyz::v, arg1)             // arg1.v
    bind(&xyz::v, obj)              // obj.v
    bind(&xyz::v, arg1)(obj) = 4    // obj.v = 4

[endsect]

[section Compatibility with other bind libraries]

`phoenix::bind` passes all testcases of the Boost.Bind library. It is therefore
completely compatible and interchangeable.

Note that at the current state of the library, you can not mix phoenix and lambda
expressions just like that.

Given the compatibility with Boost.Bind, we also assume compatibility with
std::tr1::bind and std::bind from the upcoming C++0x standard

[endsect]

[endsect]