Boost C++ Libraries

The BLL defines three placeholder types: placeholder1_type, placeholder2_type and placeholder3_type. BLL has a predefined placeholder variable for each placeholder type: _1, _2 and _3. However, the user is not forced to use these placeholders. It is easy to define placeholders with alternative names. This is done by defining new variables of placeholder types. For example:

boost::lambda::placeholder1_type X;
boost::lambda::placeholder2_type Y;
boost::lambda::placeholder3_type Z;

With these variables defined, X += Y * Z is equivalent to _1 += _2 * _3.

The use of placeholders in the lambda expression determines whether the resulting function is nullary, unary, binary or 3-ary. The highest placeholder index is decisive. For example:

_1 + 5              // unary
_1 * _1 + _1        // unary
_1 + _2             // binary
bind(f, _1, _2, _3) // 3-ary
_3 + 10             // 3-ary

Note that the last line creates a 3-ary function, which adds 10 to its third argument. The first two arguments are discarded. Furthermore, lambda functors only have a minimum arity. One can always provide more arguments (up the number of supported placeholders) that is really needed. The remaining arguments are just discarded. For example:

int i, j, k; 
_1(i, j, k)        // returns i, discards j and k
(_2 + _2)(i, j, k) // returns j+j, discards i and k

See the section called “ Lambda functor arity ” for the design rationale behind this functionality.

In addition to these three placeholder types, there is also a fourth placeholder type placeholderE_type. The use of this placeholder is defined in the section called “Exceptions” describing exception handling in lambda expressions.

When an actual argument is supplied for a placeholder, the parameter passing mode is always by reference. This means that any side-effects to the placeholder are reflected to the actual argument. For example:

int i = 1; 
(_1 += 2)(i);         // i is now 3
(++_1, cout << _1)(i) // i is now 4, outputs 4

The basic rule is that any C++ operator invocation with at least one argument being a lambda expression is itself a lambda expression. Almost all overloadable operators are supported. For example, the following is a valid lambda expression:

cout << _1, _2[_3] = _1 && false

However, there are some restrictions that originate from the C++ operator overloading rules, and some special cases.

int i; 
_1 = i;      // ok
i = _1;      // not ok. i is not a lambda expression

var(i) = _1; // ok

bool flag = true; int i = 0;
(_1 || ++_2)(flag, i);

for_each(a.begin(), a.end(), (++_1, cout << _1));

Bind expressions can have two forms:

bind(target-function, bind-argument-list)
bind(target-member-function, object-argument, bind-argument-list)

A bind expression delays the call of a function. If this target function is n-ary, then the bind-argument-list must contain n arguments as well. In the current version of the BLL, 0 <= n <= 9 must hold. For member functions, the number of arguments must be at most 8, as the object argument takes one argument position. Basically, the bind-argument-list must be a valid argument list for the target function, except that any argument can be replaced with a placeholder, or more generally, with a lambda expression. Note that also the target function can be a lambda expression. The result of a bind expression is either a nullary, unary, binary or 3-ary function object depending on the use of placeholders in the bind-argument-list (see the section called “Placeholders”).

The return type of the lambda functor created by the bind expression can be given as an explicitly specified template parameter, as in the following example:

bind<RET>(target-function, bind-argument-list)

This is only necessary if the return type of the target function cannot be deduced.

The following sections describe the different types of bind expressions.

X foo(A, B, C); A a; B b; C c;
bind(foo, _1, _2, c)(a, b);
bind(&foo, _1, _2, c)(a, b);
bind(_1, a, b, c)(foo);

void foo(int);
void foo(float);
int i; 
  ...
bind(&foo, _1)(i);                            // error 
  ...
void (*pf1)(int) = &foo;
bind(pf1, _1)(i);                             // ok
bind(static_cast<void(*)(int)>(&foo), _1)(i); // ok

bind(target-member-function, object-argument, bind-argument-list)

bool A::foo(int) const; 
A a;
vector<int> ints; 
  ...
find_if(ints.begin(), ints.end(), bind(&A::foo, a, _1)); 
find_if(ints.begin(), ints.end(), bind(&A::foo, &a, _1));

bool A::foo(int); 
list<A> refs; 
list<A*> pointers; 
  ...
find_if(refs.begin(), refs.end(), bind(&A::foo, _1, 1)); 
find_if(pointers.begin(), pointers.end(), bind(&A::foo, _1, 1));

class A {
  int i; mutable int j;
public:

  A(int ii, int jj) : i(ii), j(jj) {};
  void set_i(int x) { i = x; }; 
  void set_j(int x) const { j = x; }; 
};

A a(0,0); int k = 1;
bind(&A::set_i, &a, _1)(k); // a.i == 1
bind(&A::set_j, &a, _1)(k); // a.j == 1

A a(0,0); int k = 1;
bind(&A::set_i, a, _1)(k); // error; a const copy of a is stored. 
                           // Cannot call a non-const function set_i
bind(&A::set_j, a, _1)(k); // a.j == 0, as a copy of a is modified

bind(&A::set_i, ref(a), _1)(k); // a.j == 1
bind(&A::set_j, cref(a), _1)(k); // a.j == 1

A a(0,0);
bind(&A::set_i, _1, 1)(a); // a.i == 1
bind(&A::set_j, _1, 1)(a); // a.j == 1

struct A { int data; };
A a;
bind(&A::data, _1)(a) = 1;     // a.data == 1

const A ca = a;
bind(&A::data, _1)(ca) = 1;     // error

struct A {
  typedef B result_type;
  B operator()(X, Y, Z); 
};

struct A {
  template <class Args> struct sig { typedef B type; }
  B operator()(X, Y, Z); 
};

struct A {

  // the return type equals the third argument type:
  template<class T1, class T2, class T3>
  T3 operator()(const T1& t1, const T2& t2, const T3& t3) const;

  template <class Args> 
  class sig {
    // get the third argument type (4th element)
    typedef typename 
      boost::tuples::element<3, Args>::type T3;
  public:
    typedef typename 
      boost::remove_cv<T3>::type type;
  };
};

The return type deduction system may not be able to deduce the return types of some user defined operators or bind expressions with class objects. A special lambda expression type is provided for stating the return type explicitly and overriding the deduction system. To state that the return type of the lambda functor defined by the lambda expression e is T, you can write:

ret<T>(e);

The effect is that the return type deduction is not performed for the lambda expression e at all, but instead, T is used as the return type. Obviously T cannot be an arbitrary type, the true result of the lambda functor must be implicitly convertible to T. For example:

A a; B b;
C operator+(A, B);
int operator*(A, B); 
  ...
ret<D>(_1 + _2)(a, b);     // error (C cannot be converted to D)
ret<C>(_1 + _2)(a, b);     // ok
ret<float>(_1 * _2)(a, b); // ok (int can be converted to float)
  ...
struct X {
  Y operator(int)();   
};
  ...
X x; int i;
bind(x, _1)(i);            // error, return type cannot be deduced
ret<Y>(bind(x, _1))(i);    // ok

For bind expressions, there is a short-hand notation that can be used instead of ret. The last line could alternatively be written as:

bind<Z>(x, _1)(i);

This feature is modeled after the Boost Bind library [bind].

Note that within nested lambda expressions, the ret must be used at each subexpression where the deduction would otherwise fail. For example:

A a; B b;
C operator+(A, B); D operator-(C);
  ...
ret<D>( - (_1 + _2))(a, b); // error 
ret<D>( - ret<C>(_1 + _2))(a, b); // ok

If you find yourself using ret repeatedly with the same types, it is worth while extending the return type deduction (see the section called “Extending return type deduction system”).

struct F { int operator()(int i) const; }; 
F f;
  ...
bind(f, _1);           // fails, cannot deduce the return type
ret<int>(bind(f, _1)); // ok
  ...
bind(f, 1);            // fails, cannot deduce the return type
ret<int>(bind(f, 1));  // fails as well!

bind<int>(f, 1);       // ok

The unary functions constant, constant_ref and var turn their argument into a lambda functor, that implements an identity mapping. The former two are for constants, the latter for variables. The use of these delayed constants and variables is sometimes necessary due to the lack of explicit syntax for lambda expressions. For example:

for_each(a.begin(), a.end(), cout << _1 << ' ');
for_each(a.begin(), a.end(), cout << ' ' << _1);

The first line outputs the elements of a separated by spaces, while the second line outputs a space followed by the elements of a without any separators. The reason for this is that neither of the operands of cout << ' ' is a lambda expression, hence cout << ' ' is evaluated immediately. To delay the evaluation of cout << ' ', one of the operands must be explicitly marked as a lambda expression. This is accomplished with the constant function:

for_each(a.begin(), a.end(), cout << constant(' ') << _1);

The call constant(' ') creates a nullary lambda functor which stores the character constant ' ' and returns a reference to it when invoked. The function constant_ref is similar, except that it stores a constant reference to its argument. The constant and consant_ref are only needed when the operator call has side effects, like in the above example.

Sometimes we need to delay the evaluation of a variable. Suppose we wanted to output the elements of a container in a numbered list:

int index = 0; 
for_each(a.begin(), a.end(), cout << ++index << ':' << _1 << '\n');
for_each(a.begin(), a.end(), cout << ++var(index) << ':' << _1 << '\n');

The first for_each invocation does not do what we want; index is incremented only once, and its value is written into the output stream only once. By using var to make index a lambda expression, we get the desired effect.

In sum, var(x) creates a nullary lambda functor, which stores a reference to the variable x. When the lambda functor is invoked, a reference to x is returned.

var_type<T>::type delayed_i(var(i));
constant_type<T>::type delayed_c(constant(c));

int i = 0; int j;
for_each(a.begin(), a.end(), (var(j) = _1, _1 = var(i), var(i) = var(j))); 

int i = 0; int j;
var_type<int>::type vi(var(i)), vj(var(j));
for_each(a.begin(), a.end(), (vj = _1, _1 = vi, vi = vj));

constant_type<char>::type space(constant(' '));
for_each(a.begin(),a.end(), cout << space << _1);

int i; 
i = _1;       // error
var(i) = _1;  // ok

BLL defines several functions to create lambda functors that represent control structures. They all take lambda functors as parameters and return void. To start with an example, the following code outputs all even elements of some container a:

for_each(a.begin(), a.end(), 
         if_then(_1 % 2 == 0, cout << _1));  

The BLL supports the following function templates for control structures:

if_then(condition, then_part)
if_then_else(condition, then_part, else_part)
if_then_else_return(condition, then_part, else_part)
while_loop(condition, body)
while_loop(condition) // no body case
do_while_loop(condition, body)
do_while_loop(condition) // no body case 
for_loop(init, condition, increment, body)
for_loop(init, condition, increment) // no body case
switch_statement(...)

The return types of all control construct lambda functor is void, except for if_then_else_return, which wraps a call to the conditional operator

condition ? then_part : else_part

The return type rules for this operator are somewhat complex. Basically, if the branches have the same type, this type is the return type. If the type of the branches differ, one branch, say of type A, must be convertible to the other branch, say of type B. In this situation, the result type is B. Further, if the common type is an lvalue, the return type will be an lvalue too.

Delayed variables tend to be commonplace in control structure lambda expressions. For instance, here we use the var function to turn the arguments of for_loop into lambda expressions. The effect of the code is to add 1 to each element of a two-dimensional array:

int a[5][10]; int i;
for_each(a, a+5, 
  for_loop(var(i)=0, var(i)<10, ++var(i), 
           _1[var(i)] += 1));  

The BLL supports an alternative syntax for control expressions, suggested by Joel de Guzmann. By overloading the operator[] we can get a closer resemblance with the built-in control structures:

if_(condition)[then_part]
if_(condition)[then_part].else_[else_part]
while_(condition)[body]
do_[body].while_(condition)
for_(init, condition, increment)[body]

For example, using this syntax the if_then example above can be written as:

for_each(a.begin(), a.end(), 
         if_(_1 % 2 == 0)[ cout << _1 ])  

As more experience is gained, we may end up deprecating one or the other of these syntaces.

The lambda expressions for switch control structures are more complex since the number of cases may vary. The general form of a switch lambda expression is:

switch_statement(condition, 
  case_statement<label>(lambda expression),
  case_statement<label>(lambda expression),
  ...
  default_statement(lambda expression)
)

The condition argument must be a lambda expression that creates a lambda functor with an integral return type. The different cases are created with the case_statement functions, and the optional default case with the default_statement function. The case labels are given as explicitly specified template arguments to case_statement functions and break statements are implicitly part of each case. For example, case_statement<1>(a), where a is some lambda functor, generates the code:

case 1: 
  evaluate lambda functor a; 
  break;

The switch_statement function is specialized for up to 9 case statements.

As a concrete example, the following code iterates over some container v and ouptuts “zero” for each 0, “one” for each 1, and “other: n” for any other value n. Note that another lambda expression is sequenced after the switch_statement to output a line break after each element:

std::for_each(v.begin(), v.end(),
  ( 
    switch_statement(
      _1,
      case_statement<0>(std::cout << constant("zero")),
      case_statement<1>(std::cout << constant("one")),
      default_statement(cout << constant("other: ") << _1)
    ), 
    cout << constant("\n") 
  )
);

The BLL provides lambda functors that throw and catch exceptions. Lambda functors for throwing exceptions are created with the unary function throw_exception. The argument to this function is the exception to be thrown, or a lambda functor which creates the exception to be thrown. A lambda functor for rethrowing exceptions is created with the nullary rethrow function.

Lambda expressions for handling exceptions are somewhat more complex. The general form of a lambda expression for try catch blocks is as follows:

try_catch(
  lambda expression,
  catch_exception<type>(lambda expression),
  catch_exception<type>(lambda expression),
  ...
  catch_all(lambda expression)
)

The first lambda expression is the try block. Each catch_exception defines a catch block where the explicitly specified template argument defines the type of the exception to catch. The lambda expression within the catch_exception defines the actions to take if the exception is caught. Note that the resulting exception handlers catch the exceptions as references, i.e., catch_exception<T>(...) results in the catch block:

catch(T& e) { ... }

The last catch block can alternatively be a call to catch_exception<type> or to catch_all, which is the lambda expression equivalent to catch(...).

The Example 18.1, “Throwing and handling exceptions in lambda expressions.” demonstrates the use of the BLL exception handling tools. The first handler catches exceptions of type foo_exception. Note the use of _1 placeholder in the body of the handler.

The second handler shows how to throw exceptions, and demonstrates the use of the exception placeholder _e. It is a special placeholder, which refers to the caught exception object within the handler body. Here we are handling an exception of type std::exception, which carries a string explaining the cause of the exception. This explanation can be queried with the zero-argument member function what. The expression bind(&std::exception::what, _e) creates the lambda function for making that call. Note that _e cannot be used outside of an exception handler lambda expression. The last line of the second handler constructs a new exception object and throws that with throw exception. Constructing and destructing objects within lambda expressions is explained in the section called “Construction and destruction”

Finally, the third handler (catch_all) demonstrates rethrowing exceptions.

for_each(
  a.begin(), a.end(),
  try_catch(
    bind(foo, _1),                 // foo may throw
    catch_exception<foo_exception>(
      cout << constant("Caught foo_exception: ") 
           << "foo was called with argument = " << _1
    ),
    catch_exception<std::exception>(
      cout << constant("Caught std::exception: ") 
           << bind(&std::exception::what, _e),
      throw_exception(bind(constructor<bar_exception>(), _1)))
    ),      
    catch_all(
      (cout << constant("Unknown"), rethrow())
    )
  )
);

Operators new and delete can be overloaded, but their return types are fixed. Particularly, the return types cannot be lambda functors, which prevents them to be overloaded for lambda expressions. It is not possible to take the address of a constructor, hence constructors cannot be used as target functions in bind expressions. The same is true for destructors. As a way around these constraints, BLL defines wrapper classes for new and delete calls, as well as for constructors and destructors. Instances of these classes are function objects, that can be used as target functions of bind expressions. For example:

int* a[10];
for_each(a, a+10, _1 = bind(new_ptr<int>())); 
for_each(a, a+10, bind(delete_ptr(), _1));

The new_ptr<int>() expression creates a function object that calls new int() when invoked, and wrapping that inside bind makes it a lambda functor. In the same way, the expression delete_ptr() creates a function object that invokes delete on its argument. Note that new_ptr<T>() can take arguments as well. They are passed directly to the constructor invocation and thus allow calls to constructors which take arguments.

As an example of constructor calls in lambda expressions, the following code reads integers from two containers x and y, constructs pairs out of them and inserts them into a third container:

vector<pair<int, int> > v;
transform(x.begin(), x.end(), y.begin(), back_inserter(v),
          bind(constructor<pair<int, int> >(), _1, _2));

Table 18.1, “Construction and destruction related function objects.” lists all the function objects related to creating and destroying objects, showing the expression to create and call the function object, and the effect of evaluating that expression.

The BLL defines common STL algorithms as function object classes, instances of which can be used as target functions in bind expressions. For example, the following code iterates over the elements of a two-dimensional array, and computes their sum.

int a[100][200];
int sum = 0;

std::for_each(a, a + 100, 
	      bind(ll::for_each(), _1, _1 + 200, protect(sum += _1)));

The BLL versions of the STL algorithms are classes, which define the function call operator (or several overloaded ones) to call the corresponding function templates in the std namespace. All these structs are placed in the subnamespace boost::lambda:ll.

Note that there is no easy way to express an overloaded member function call in a lambda expression. This limits the usefulness of nested STL algorithms, as for instance the begin function has more than one overloaded definitions in container templates. In general, something analogous to the pseudo-code below cannot be written:

std::for_each(a.begin(), a.end(), 
	      bind(ll::for_each(), _1.begin(), _1.end(), protect(sum += _1)));

Some aid for common special cases can be provided though. The BLL defines two helper function object classes, call_begin and call_end, which wrap a call to the begin and, respectively, end functions of a container, and return the const_iterator type of the container. With these helper templates, the above code becomes:

std::for_each(a.begin(), a.end(), 
	      bind(ll::for_each(), 
                   bind(call_begin(), _1), bind(call_end(), _1),
                        protect(sum += _1)));