Boost C++ Libraries of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of Boost. Click here to view this page for the latest version.

Using the library

Introductory Examples
Parameter and return types of lambda functors
About actual arguments to lambda functors
Storing bound arguments in lambda functions

The purpose of this section is to introduce the basic functionality of the library. There are quite a lot of exceptions and special cases, but discussion of them is postponed until later sections.

Introductory Examples

In this section we give basic examples of using BLL lambda expressions in STL algorithm invocations. We start with some simple expressions and work up. First, we initialize the elements of a container, say, a list, to the value 1:

list<int> v(10);
for_each(v.begin(), v.end(), _1 = 1);

The expression _1 = 1 creates a lambda functor which assigns the value 1 to every element in v.[7]

Next, we create a container of pointers and make them point to the elements in the first container v:

vector<int*> vp(10); 
transform(v.begin(), v.end(), vp.begin(), &_1);

The expression &_1 creates a function object for getting the address of each element in v. The addresses get assigned to the corresponding elements in vp.

The next code fragment changes the values in v. For each element, the function foo is called. The original value of the element is passed as an argument to foo. The result of foo is assigned back to the element:

int foo(int);
for_each(v.begin(), v.end(), _1 = bind(foo, _1));

The next step is to sort the elements of vp:

sort(vp.begin(), vp.end(), *_1 > *_2);

In this call to sort, we are sorting the elements by their contents in descending order.

Finally, the following for_each call outputs the sorted content of vp separated by line breaks:

for_each(vp.begin(), vp.end(), cout << *_1 << '\n');

Note that a normal (non-lambda) expression as subexpression of a lambda expression is evaluated immediately. This may cause surprises. For instance, if the previous example is rewritten as

for_each(vp.begin(), vp.end(), cout << '\n' << *_1);

the subexpression cout << '\n' is evaluated immediately and the effect is to output a single line break, followed by the elements of vp. The BLL provides functions constant and var to turn constants and, respectively, variables into lambda expressions, and can be used to prevent the immediate evaluation of subexpressions:

for_each(vp.begin(), vp.end(), cout << constant('\n') << *_1);

These functions are described more thoroughly in the section called “Delaying constants and variables”

Parameter and return types of lambda functors

During the invocation of a lambda functor, the actual arguments are substituted for the placeholders. The placeholders do not dictate the type of these actual arguments. The basic rule is that a lambda function can be called with arguments of any types, as long as the lambda expression with substitutions performed is a valid C++ expression. As an example, the expression _1 + _2 creates a binary lambda functor. It can be called with two objects of any types A and B for which operator+(A,B) is defined (and for which BLL knows the return type of the operator, see below).

C++ lacks a mechanism to query a type of an expression. However, this precise mechanism is crucial for the implementation of C++ lambda expressions. Consequently, BLL includes a somewhat complex type deduction system which uses a set of traits classes for deducing the resulting type of lambda functions. It handles expressions where the operands are of built-in types and many of the expressions with operands of standard library types. Many of the user defined types are covered as well, particularly if the user defined operators obey normal conventions in defining the return types.

There are, however, cases when the return type cannot be deduced. For example, suppose you have defined:

C operator+(A, B);

The following lambda function invocation fails, since the return type cannot be deduced:

A a; B b; (_1 + _2)(a, b);

There are two alternative solutions to this. The first is to extend the BLL type deduction system to cover your own types (see the section called “Extending return type deduction system”). The second is to use a special lambda expression (ret) which defines the return type in place (see the section called “Overriding the deduced return type”):

A a; B b; ret<C>(_1 + _2)(a, b);

For bind expressions, the return type can be defined as a template argument of the bind function as well:

bind<int>(foo, _1, _2);

About actual arguments to lambda functors

A general restriction for the actual arguments is that they cannot be non-const rvalues. For example:

int i = 1; int j = 2; 
(_1 + _2)(i, j); // ok
(_1 + _2)(1, 2); // error (!)

This restriction is not as bad as it may look. Since the lambda functors are most often called inside STL-algorithms, the arguments originate from dereferencing iterators and the dereferencing operators seldom return rvalues. And for the cases where they do, there are workarounds discussed in the section called “Rvalues as actual arguments to lambda functors”.

Storing bound arguments in lambda functions

By default, temporary const copies of the bound arguments are stored in the lambda functor. This means that the value of a bound argument is fixed at the time of the creation of the lambda function and remains constant during the lifetime of the lambda function object. For example:

int i = 1;
(_1 = 2, _1 + i)(i);

The comma operator is overloaded to combine lambda expressions into a sequence; the resulting unary lambda functor first assigns 2 to its argument, then adds the value of i to it. The value of the expression in the last line is 3, not 4. In other words, the lambda expression that is created is lambda x.(x = 2, x + 1) rather than lambda x.(x = 2, x + i).

As said, this is the default behavior for which there are exceptions. The exact rules are as follows:

  • The programmer can control the storing mechanism with ref and cref wrappers [ref]. Wrapping an argument with ref, or cref, instructs the library to store the argument as a reference, or as a reference to const respectively. For example, if we rewrite the previous example and wrap the variable i with ref, we are creating the lambda expression lambda x.(x = 2, x + i) and the value of the expression in the last line will be 4:

    i = 1;
    (_1 = 2, _1 + ref(i))(i);

    Note that ref and cref are different from var and constant. While the latter ones create lambda functors, the former do not. For example:

    int i; 
    var(i) = 1; // ok
    ref(i) = 1; // not ok, ref(i) is not a lambda functor

    The functions ref and cref mostly exist for historical reasons, and ref can always be replaced with var, and cref with constant_ref. See the section called “Delaying constants and variables” for details. The ref and cref functions are general purpose utility functions in Boost, and hence defined directly in the boost namespace.

  • Array types cannot be copied, they are thus stored as const reference by default.

  • For some expressions it makes more sense to store the arguments as references. For example, the obvious intention of the lambda expression i += _1 is that calls to the lambda functor affect the value of the variable i, rather than some temporary copy of it. As another example, the streaming operators take their leftmost argument as non-const references. The exact rules are:

    • The left argument of compound assignment operators (+=, *=, etc.) are stored as references to non-const.

    • If the left argument of << or >> operator is derived from an instantiation of basic_ostream or respectively from basic_istream, the argument is stored as a reference to non-const. For all other types, the argument is stored as a copy.

    • In pointer arithmetic expressions, non-const array types are stored as non-const references. This is to prevent pointer arithmetic making non-const arrays const.

[7] Strictly taken, the C++ standard defines for_each as a non-modifying sequence operation, and the function object passed to for_each should not modify its argument. The requirements for the arguments of for_each are unnecessary strict, since as long as the iterators are mutable, for_each accepts a function object that can have side-effects on their argument. Nevertheless, it is straightforward to provide another function template with the functionality ofstd::for_each but more fine-grained requirements for its arguments.