Lambda expressions (since C++11)

Constructs a closure: an unnamed function object capable of capturing variables in scope.

Syntax

1) Full declaration.

2) Declaration of a const lambda: the objects captured by copy cannot be modified.

3) Omitted trailing-return-type: the return type of the closure's operator() is determined according to the following rules:

4) Omitted parameter list: function takes no arguments, as if the parameter list was (). This form can only be used if none of constexpr, mutable, exception specification, attributes, or trailing return type is used.

Explanation

The lambda expression is a prvalue expression whose value is (until C++17)whose result object is (since C++17) an unnamed temporary object of unique unnamed non-union non-aggregate class type, known as closure type, which is declared (for the purposes of ADL) in the smallest block scope, class scope, or namespace scope that contains the lambda expression. The closure type has the following members:

ret operator()(params) const { body }

ret operator()(params) { body }

template<template-params>
ret operator()(params) { body }

// generic lambda, operator() is a template with two parameters
auto glambda = [](auto a, auto&& b) { return a < b; };
bool b = glambda(3, 3.14); // ok
 
// generic lambda, operator() is a template with one parameter
auto vglambda = [](auto printer) {
    return [=](auto&&... ts) // generic lambda, ts is a parameter pack
    { 
        printer(std::forward<decltype(ts)>(ts)...);
        return [=] { printer(ts...); }; // nullary lambda (takes no parameters)
    };
};
auto p = vglambda([](auto v1, auto v2, auto v3) { std::cout << v1 << v2 << v3; });
auto q = p(1, 'a', 3.14); // outputs 1a3.14
q();                      // outputs 1a3.14

struct X {
    int x, y;
    int operator()(int);
    void f()
    {
        // the context of the following lambda is the member function X::f
        [=]()->int
        {
            return operator()(this->x + y); // X::operator()(this->x + (*this).y)
                                            // this has type X*
        };
    }
};

using F = ret(*)(params);
operator F() const;

using F = ret(*)(params);
constexpr operator F() const;

template<template-params> using fptr_t = /*see below*/;
template<template-params> operator fptr_t<template-params>() const;

template<template-params> using fptr_t = /*see below*/;
template<template-params> operator fptr_t<template-params>() const;

void f1(int (*)(int)) {}
void f2(char (*)(int)) {}
void h(int (*)(int)) {} // #1
void h(char (*)(int)) {} // #2
auto glambda = [](auto a) { return a; };
f1(glambda); // ok
f2(glambda); // error: not convertible
h(glambda); // ok: calls #1 since #2 is not convertible
 
int& (*fpi)(int*) = [](auto* a)->auto& { return *a; }; // ok

auto Fwd= [](int(*fp)(int), auto a){return fp(a);};
auto C=[](auto a){return a;};
static_assert(Fwd(C,3)==3);//OK
auto NC=[](auto a){static int s; return a;};
static_assert(Fwd(NC,3)==3); // error: no specialization can be constexpr because of s

ClosureType() = delete;

ClosureType(const ClosureType& ) = default;

ClosureType(ClosureType&& ) = default;

ClosureType& operator=(const ClosureType&) = delete;

~ClosureType() = default;

T1 a;
T2 b;
...

Lambda-expressions are not allowed in unevaluated expressions, template arguments, alias declarations, typedef declarations, and anywhere in a function (or function template) declaration except the function body and the function's default arguments.

Lambda capture

The capture-list is a comma-separated list of zero or more captures, optionally beginning with the capture-default. The only capture defaults are.

• & (implicitly catch the odr-used automatic variables and *this by reference) and
• = (implicitly catch the odr-used automatic variables by copy and implicitly catch *this by reference if this is odr-used).

The syntax of an individual capture in capture-list is.

If the capture-default is &, subsequent captures must not begin with &. If the capture-default is =, subsequent captures must begin with & or be *this (since C++17). Any capture may appear only once.

struct S2 { void f(int i); };
void S2::f(int i)
{
    [&]{}; //ok: by-reference capture default
    [=]{}; //ok: by-copy capture default
    [&, i]{}; // ok: by-reference capture, except i is captured by copy
    [=, &i]{}; // ok: by-copy capture, except i is captured by reference
    [&, &i] {}; // error: by-reference capture when by-reference is the default
    [=, this] {}; // error: this when = is the default
    [=, *this]{}; // ok: captures the enclosing S2 by copy (C++17)
    [i, i] {}; // error: i repeated
    [this, *this] {}; // error: "this" repeated (C++17)
}

Only lambda-expressions defined at block scope may have a capture-default or captures without initializers. For such lambda-expression, the reaching scope is defined as the set of enclosing scopes up to and including the innermost enclosing function (and its parameters). This includes nested block scopes and the scopes of enclosing lambdas if this lambda is nested.

The identifier in any capture without an initializer (other than the this-capture) is looked up using usual unqualified name lookup in the reaching scope of the lambda. The result of the lookup must be a variable with automatic storage duration declared in the reaching scope. The variable (or this) is explicitly captured.

int x = 4;
auto y = [&r = x, x = x + 1]()->int
    {
        r += 2;
        return x * x;
    }(); // updates ::x to 6 and initializes y to 25.

If a capture list has a capture-default and does not explicitly capture the enclosing object (as this or *this) or an automatic variable, it captures it implicitly if.

• the body of the lambda odr-uses the variable or the this pointer

void f(int, const int (&)[2] = {}) {} // #1
void f(const int&, const int (&)[1]) {} // #2
void test()
{
    const int x = 17;
    auto g1 = [](auto a) { f(x); }; // ok: calls #1, does not capture x
    auto g2 = [=](auto a) {
            int selector[sizeof(a) == 1 ? 1 : 2] = {};
            f(x, selector); // ok: is a dependent expression, so captures x
    };
}

If the body of a lambda odr-uses an entity captured by copy, the member of the closure type is accessed. If it is not odr-using the entity, the access is to the original object:

void f(const int*);
void g()
{
    const int N = 10;
    [=]{ 
        int arr[N]; // not an odr-use: refers to g's const int N
        f(&N); // odr-use: causes N to be captured (by copy)
               // &N is the address of the closure object's member N, not g's N
    }();
}

#include <iostream>
 
auto make_function(int& x) {
  return [&]{ std::cout << x << '\n'; };
}
 
int main() {
  int i = 3;
  auto f = make_function(i); // the use of x in f binds directly to i
  i = 5;
  f(); // OK; prints 5
}

Within the body of a lambda, any use of decltype on any variable with automatic storage duration is as if it were captured and odr-used, even though decltype itself isn't an odr-use and no actual capture takes place:

void f3() {
    float x, &r = x;
    [=]
    { // x and r are not captured (appearance in a decltype operand is not an odr-use)
        decltype(x) y1; // y1 has type float
        decltype((x)) y2 = y1; // y2 has type float const& because this lambda
                               // is not mutable and x is an lvalue
        decltype(r) r1 = y1;   // r1 has type float& (transformation not considered)
        decltype((r)) r2 = y2; // r2 has type float const&
    };
}

Any entity captured by a lambda (implicitly or explicitly) is odr-used by the lambda-expression (therefore, implicit capture by a nested lambda triggers implicit capture in the enclosing lambda).

All implicitly-captured variables must be declared within the reaching scope of the lambda.

If a lambda captures the enclosing object (as this or *this), the nearest enclosing function must be a non-static member function:

struct s2 {
  double ohseven = .007;
  auto f() { // nearest enclosing function for the following two lambdas
    return [this] { // capture the enclosing s2 by reference
      return [*this] { // capture the enclosing s2 by copy (C++17)
          return ohseven; // OK
       }
     }();
  }
  auto g() {
     return []{ // capture nothing
         return [*this]{}; // error: *this not captured by outer lambda-expression
      }();
   }
};

If a lambda expression (or an instantiation of a generic lambda's function call operator) ODR-uses this or any variable with automatic storage duration, it must be captured by the lambda expression.

void f1(int i)
{
    int const N = 20;
    auto m1 = [=] {
            int const M = 30;
            auto m2 = [i] {
                    int x[N][M]; // N and M are not odr-used 
                                 // (ok that they are not captured)
                    x[0][0] = i; // i is explicitly captured by m2
                                 // and implicitly captured by m1
            };
    };
 
    struct s1 // local class within f1()
    {
        int f;
        void work(int n) // non-static member function
        {
            int m = n * n;
            int j = 40;
            auto m3 = [this, m] {
                auto m4 = [&, j] { // error: j is not captured by m3
                        int x = n; // error: n is implicitly captured by m4
                                   // but not captured by m3
                        x += m;    // ok: m is implicitly captured by m4
                                   // and explicitly captured by m3
                        x += i;    // error: i is outside of the reaching scope
                                   // (which ends at work())
                        x += f;    // ok: this is captured implicitly by m4
                                   // and explicitly captured by m3
                };
            };
        }
    };
}

Class members cannot be captured explicitly by a capture without initializer (as mentioned above, only variables are permitted in the capture list):

class S {
  int x = 0;
  void f() {
    int i = 0;
//  auto l1 = [i, x]{ use(i, x); };    // error: x is not a variable
    auto l2 = [i, x=x]{ use(i, x); };  // OK, copy capture
    i = 1; x = 1; l2(); // calls use(0,0)
    auto l3 = [i, &x=x]{ use(i, x); }; // OK, reference capture
    i = 2; x = 2; l3(); // calls use(1,2)
  }
};

When a lambda captures a member using implicit by-copy capture, it does not make a copy of that member variable: the use of a member variable m is treated as an expression (*this).m, and the this pointer is what's captured (by value) instead. The member behaves as if caught by reference:

class S {
  int x = 0;
  void f() {
    int i = 0;
    auto l1 = [=]{ use(i, x); }; // captures a copy of i and a copy of the this pointer
    i = 1; x = 1; l1(); // calls use(0,1), as if i by copy and x by reference
    auto l2 = [i, this]{ use(i, x); }; // same as above, made explicit
    i = 2; x = 2; l2(); // calls use(1,2), as if i by copy and x by reference
    auto l3 = [&]{ use(i, x); }; // captures i by reference and a copy of the this pointer
    i = 3; x = 2; l3(); // calls use(3,2), as if i and x are both by reference
    auto l4 = [i, *this]{ use(i, x); }; // makes a copy of *this, including a copy of x
    i = 4; x = 4; l4(); // calls use(3,2), as if i and x are both by copy
  }
};

If a lambda-expression appears in a default argument, it cannot explicitly or implicitly capture anything.

Members of anonymous unions cannot be captured.

If a nested lambda m2 captures something that is also captured by the immediately enclosing lambda m1, then m2's capture is transformed as follows:

• if the enclosing lambda m1 captures by copy, m2 is capturing the non-static member of m1's closure type, not the original variable or this.
• if the enclosing lambda m1 by reference, m2 is capturing the original variable or this.

#include <iostream>
 
int main()
{
    int a = 1, b = 1, c = 1;
 
    auto m1 = [a, &b, &c]() mutable {
        auto m2 = [a, b, &c]() mutable {
            std::cout << a << b << c << '\n';
            a = 4; b = 4; c = 4;
        };
        a = 3; b = 3; c = 3;
        m2();
    };
 
    a = 2; b = 2; c = 2;
 
    m1();                             // calls m2() and prints 123
    std::cout << a << b << c << '\n'; // prints 234
}

Example

#include <vector>
#include <iostream>
#include <algorithm>
#include <functional>
 
int main()
{
    std::vector<int> c = {1, 2, 3, 4, 5, 6, 7};
    int x = 5;
    c.erase(std::remove_if(c.begin(), c.end(), [x](int n) { return n < x; }), c.end());
 
    std::cout << "c: ";
    std::for_each(c.begin(), c.end(), [](int i){ std::cout << i << ' '; });
    std::cout << '\n';
 
    // the type of a closure cannot be named, but can be inferred with auto
    auto func1 = [](int i) { return i + 4; };
    std::cout << "func1: " << func1(6) << '\n';
 
    // like all callable objects, closures can be captured in std::function
    // (this may incur unnecessary overhead)
    std::function<int(int)> func2 = [](int i) { return i + 4; };
    std::cout << "func2: " << func2(6) << '\n';
}

c: 5 6 7
func1: 10
func2: 10

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

See also