A Proposal to Add an Enhanced Binder to the Library Technical Report (revision 1)

I. Motivation

The standard C++ library supports and encourages a powerful programming style that relies on a combination of generic algorithms and small utility components known as function objects, used to adapt algorithm behavior. A collection of standard algorithms that cover a wide range of practical problems is provided by the standard header <algorithm> . The standard header <functional> provides some commonly used function objects, and algorithms are able to work with ordinary C++ functions as well. Nevertheless, the problem at hand often calls for a slightly different function object. For example, the order of the two parameters may need to be reversed, one of the parameters may need to have a specific value, or the desired functionality may be already present but provided by a member function.

One obvious solution is to write a new function or a function object by hand. This is often tedious, and the result is typically difficult to reuse, being tightly specialized to handle one particular situation. The standard library recognizes the need of function object creation tools, and attempts to provide a solution in the form of the function object adaptors bind1st, bind2nd, ptr_fun, mem_fun, and mem_fun_ref.

The standard adaptors bind1st and bind2nd have a number of limitations. They do not support function objects with reference arguments well, they only support adaptable function objects forcing users to adapt pointers to functions and pointers to member functions manually using ptr_fun, mem_fun, or mem_fun_ref as appropriate, and they only produce unary function objects given a binary function object. Some of these problems are described in [Simonis00]. [Järvi00], [Rodgers00] and [Williams01] offer solutions.

Function object composition libraries ([Josuttis00], [SGI97a], [SGI97b]) provide another useful tool for function object creation.

Lambda libraries ([Boost02], [Guzman02]) use operator overloading and expression template techniques to go even further. They provide a powerful framework that is not constrained to pre-existing function objects. As a result, these libraries can duplicate most of the functionality of the existing facilities provided in <functional>, while offering a familiar syntax built on C++ expressions. However, due to language limitations, most notably lack of a suitable typeof operator [Stroustrup00], such a library is not implementable in its "perfect" form, although the existing implementations use increasingly sophisticated heuristics to approximate typeof. Furthermore, it should be noted that the field is still a subject of active research [Järvi03].

This document proposes an enhanced binder facility that:

• Supports but does not require adaptable function objects;
• Supports functions, function pointers, and pointers to members (including data members) natively, without requiring the use of ptr_fun, mem_fun, and mem_fun_ref;
• Supports functions with reference arguments;
• Supports function objects with arbitrary arity (subject to implementation-imposed constraints);
• Supports references to noncopyable or stateful function objects;
• Can bind an arbitrary argument of the target function object to an arbitrary value, or reference;
• Can re-route, reorder, and ignore input arguments;
• Supports function object composition via the use of nested subexpressions;
• Delivers exceptional expressive power using a simple and consistent syntax;
• Fills an obvious gap in the current standard library, as reflected by the number of independent solutions to various parts of the problem;
• Requires no language support;
• Reflects existing practice with several years of refinement and use [Järvi99] [Boost01] [Boost02];
• Has an open architecture and provides a standard interface for extensibility;
• Naturally complements the polymorphic function object wrapper proposed in [Gregor02];
• Is recommended as the standard way to pass arguments to Boost.Threads thread routines [Kempf02].

A. Examples

The following example demonstrates the basic functionality of bind:

double m; double s; double x;
double gauss(double x, double mean, double std);

bind(gauss, _1, m, s);             // #1
bind(gauss, x, _1, _2);            // #2
bind(gauss, bind(std::rand), m, s) // #3

Line #1 applies the gauss function partially, binding the parameters mean and std to m and s, respectively, resulting in a unary function. When called with an actual argument, say x, the special placeholder argument _1 is replaced by x and the gauss function is invoked with x, m, and s. Hence, bind(gauss, _1, m, s)(x) computes the same result as gauss(x, m, s). In line #2 we are using another placeholder variable _2, and the result is a binary function. The expression in line #3 shows how function compositions can be expressed as nested bind functions. Here, the result is a zero-argument function that calls gauss(std::rand(), m, s) on every invocation.

A simple demonstration of bind interacting with a standard algorithm is given by the following example:

class Employee
{
public:

  int number() const;
};

std::vector<Employee> v;

// sort by employee ID number

std::sort(v.begin(), v.end(), 
  bind(std::less<int>(),
    bind(&Employee::number, _1),
    bind(&Employee::number, _2)
  )
);

Note that the syntax of the bind calls doesn't change if number is made a public data member of Employee.

Finally, an example of bind and function [Gregor02] being used together:

class button
{
public:

    function< void() > onClick;
};

class player
{
public:

    void play(bool m);
};

button playButton, stopButton;
player thePlayer;

void connect()
{
    playButton.onClick = bind(&player::play, &thePlayer, true);
    stopButton.onClick = bind(&player::play, &thePlayer, false);
}

II. Impact On the Standard

This proposal is almost a pure library extension. It proposes changes to an existing header, <functional>, but it does not require changes to any standard classes or functions and it does not require changes to any of the standard requirement tables.

The proposal does not require any changes in the core language, although it would benefit greatly from a solution to the forwarding problem [Dimov02] or from a typeof extension [Stroustrup02]. Two independent and widely used implementations exist [Boost01] [Boost02].

In order to transparently handle pointers to members as function objects, the proposal depends on the pointer to member adaptor mem_fn [Dimov03].

To allow users to indicate that a function object should store references instead of values, this proposal depends on the auxilliary class template reference_wrapper [Gregor03a].

To deduce the return types of function object calls, the proposal depends on the result_of proposal [Gregor03b].

III. Design Decisions

A. Open and Closed Implementations

This proposal defines the class templates is_placeholder and is_bind_expression, used by bind to recognize placeholders and nested subexpressions, respectively.

Open implementations honor user specializations of is_placeholder and is_bind_expression, allowing user extensibility. Closed implementations do not.

Existing implementations are closed. Boost.Bind's primary goal has been portability to a wide range of compilers. The bind implementation in Boost.Lambda is tightly integrated with the rest of the library. However, as standard implementations of bind start becoming available, we firmly believe that a public extension interface would benefit libraries that aim to go beyond the functionality provided by bind [Boost02] [Guzman02]. Such libraries can even recognize each other's function objects and placeholders through the standard interface presented in this proposal.

Therefore, this proposal requires an open implementation.

B. Unspecified Return Types and Placeholder Types

This proposal does not specify the return types of the various bind overloads and the types of the placeholder variables. The exact types are almost never needed, are too unwieldy to manipulate, and vary greatly between existing implementations. For example, the innocent expression

bind(&X::f, &x, _1)

typically has a return type of

boost::_bi::bind_t<void, boost::_mfi::mf1<void, X, int>, boost::_bi::list2<boost::_bi::value<X *>, boost::arg<1> > >

in Boost.Bind (the actual type may vary across compilers), and

boost::lambda::lambda_functor<boost::lambda::lambda_functor_base<boost::lambda::action<3, boost::lambda::function_action<3, boost::lambda::detail::unspecified> >, boost::tuples::tuple<void (X::*const)(int), X * const, boost::lambda::lambda_functor< boost::lambda::placeholder<1> > const, boost::tuples::null_type, boost::tuples::null_type, boost::tuples::null_type, boost::tuples::null_type, boost::tuples::null_type, boost::tuples::null_type, boost::tuples::null_type> > >

in Boost.Lambda.

C. Placeholders Defined in a Nested Namespace

The placeholder variables _1, _2, ... are defined in a nested namespace, std::placeholders, in order to allow a single

using namespace std::placeholders;

directive to make them visible without qualification without bringing the whole namespace std into scope.

This proposal diverges from existing implementations in this regard. Boost.Bind defines its placeholders in a global unnamed namespace. Boost.Lambda defines both the bind function templates and the placeholders in the same namespace, boost::lambda.

D. Optional DefaultConstructible and Assignable Requirements

Some libraries create iterators that store function objects [Siek00]. As most iterators need to be DefaultConstructible and Assignable, this proposal requires implementations to document whether function objects produced by bind conform to these requirements.

Boost.Bind has DefaultConstructible and Assignable placeholders, and produces DefaultConstructible and/or Assignable function objects when all arguments to bind are DefaultConstructible and/or Assignable.

Boost.Lambda overloads the assignment operator to create a lambda expression, and its function objects and placeholders aren't Assignable.

E. result_type Requirement

It is generally accepted as good practice for a function object type F to define a nested typedef F::result_type that denotes the return type of F::operator(). Return type inference is difficult in the current language, and many libraries rely on result_type instead. Additionally, modern programming techniques allow the existence of result_type to be determined at compile time. The presence of result_type can even be used to enable an overload only for function objects.

Therefore, this proposal requires implementations to define result_type when it can be determined.

As a side note, as the current language allows fairly acceptable forwarding [Dimov02], the argument type typedefs described in 20.3/5 are rarely, if ever, required.

F. Arity Errors

In our experience, one of the most common user errors is invoking bind with a number of arguments that does not correspond to the arity of the function object being bound. In particular, it is easy to forget that pointers to members have an additional implicit argument that identifies the object.

It is important to detect these mistakes as early as possible, at the point where bind is called, hence the "f(w1, ..., wm) must be a valid expression" requirement in the proposed text.

Boost.Bind implements this early check by using separate overloads for function pointers and member pointers.

G. Dependency on mem_fn

This proposal specifies the behavior of bind with a pointer to member as a first argument in terms of mem_fn [Dimov03] to avoid unnecessary duplication. Within the scope of this proposal, implementations are not required to provide, or actually call, mem_fn.

H. bind Uses Pass by Value

The bind specification uses pass by value signatures to take advantage of the automatic function- and array-to-pointer decay, but the number of copies that is made for each argument is not specified. This is consistent with the resolution of Library Issue 181.

The additional CopyConstructible requirement is imposed to disallow arguments of types such as std::auto_ptr that implement destructive copy.

I. Qualifier Propagation

As the arguments passed to bind are stored in the returned function object, and are part of its state, they should inherit its cv-qualifiers, if any.

J. Limits of Existing Implementations

Boost.Bind defines nine placeholders, from _1 to _9, and supports up to nine arguments (N = 9).

Boost.Lambda defines three placeholders, _1, _2, and _3, and also supports up to nine arguments (N = 9). A future release will increase the number of placeholders substantially.

IV. Proposed Text

A. Additions to header <functional> synopsis (20.3)

    template<class T> struct is_bind_expression;
    template<class T> struct is_placeholder;

    template<class F> unspecified bind(F f);
    template<class R, class F> unspecified bind(F f);

    template<class F, class A1> unspecified bind(F f, A1 a1);
    template<class R, class T, class A1> unspecified bind(R T::* pm, A1 a1);
    template<class R, class F, class A1> unspecified bind(F f, A1 a1);

    // for all positive integers n in [2, N)

    template<class F, class A1, ..., class An> unspecified bind(F f, A1 a1, ..., An an);
    template<class R, class T, class A1, ..., class An> unspecified bind(R T::* pmf, A1 a1, ..., An an);
    template<class R, class F, class A1, ..., class An> unspecified bind(F f, A1 a1, ..., An an);
    
    namespace placeholders {
      // M is the implementation-defined number of placeholders
      extern unspecified _1;
      extern unspecified _2;
                  .
                  .
                  .
      extern unspecified _M;
    }

B. Class template is_bind_expression

  namespace std {
    template<class T> struct is_bind_expression {
      static const bool value = unspecified;
    };
  }

is_bind_expression can be used to detect function objects generated by bind. bind uses is_bind_expression to detect subexpressions. The template can be specialized by users to indicate that a type should be treated as a subexpression in a bind call.

      static const bool value;

true if T is a type returned from bind, false otherwise.

C. Class template is_placeholder

  namespace std {
    template<class T> struct is_placeholder {
      static const int value = unspecified;
    };
  }

is_placeholder can be used to detect the standard placeholders _1, _2, and so on. bind uses is_placeholder to detect placeholders. The template can be specialized by users to indicate a placeholder type.

      static const int value;

value is N if T is the type of std::placeholders::_N, 0 otherwise.

struct forward {
  template<typename T1, typename T2, ..., typename Tn>
    void operator()(T1&, T2&, ...,Tn&);
};
        

    template<class F> unspecified bind(F f);

    template<class R, class F> unspecified bind(F f);

    template<class F, class A1> unspecified bind(F f, A1 a1);

    template<class R, class T, class A1> unspecified bind(R T::* pm, A1 a1);

    template<class R, class F, class A1> unspecified bind(F f, A1 a1);

    template<class F, class A1, ..., class An> unspecified bind(F f, A1 a1, ..., An an);

    template<class R, class T, class A1, ..., class An> unspecified bind(R T::* pmf, A1 a1, ..., An an);

    template<class R, class F, class A1, ..., class An> unspecified bind(F f, A1 a1, ..., An an);

  namespace std {
    namespace placeholders {
      extern unspecified _1;
      extern unspecified _2;
      extern unspecified _3;
      // implementation defined number of additional placeholders
    }
  }