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 are const in the lambda body.

3) Omitted trailing-return-type: the return type of the closure's operator() is deduced from return statements as if for a function whose return type is declared auto.

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 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) const { 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

// generic lambda, operator() is a template with two parameters
auto glambda = []<class T>(T a, auto&& b) { return a < b; };
 
// generic lambda, operator() is a template with one parameter pack
auto f = []<typename ...Ts>(Ts&& ...ts) {
   return foo(std::forward<Ts>(ts)...);
};

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> constexpr 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() = default;

ClosureType(const ClosureType& ) = default;

ClosureType(ClosureType&& ) = default;

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

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

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

~ClosureType() = default;

T1 a;
T2 b;
...

Lambda capture

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

• & (implicitly capture the used automatic variables by reference) and
• = (implicitly capture the used automatic variables by copy).

The current object (*this) can be implicitly captured if either capture default is present. If implicitly captured, it is always captured by reference, even if the capture default is =. The implicit capture of *this when the capture default is = is deprecated. (since C++20).

The syntax of an individual capture in captures is.

If the capture-default is &, subsequent simple captures must not begin with &.

struct S2 { void f(int i); };
void S2::f(int i)
{
    [&]{};          // OK: by-reference capture default
    [&, i]{};       // OK: by-reference capture, except i is captured by copy
    [&, &i] {};     // Error: by-reference capture when by-reference is the default
    [&, this] {};   // OK, equivalent to [&]
    [&, this, i]{}; // OK, equivalent to [&, i]
}

If the capture-default is =, subsequent simple captures must begin with & or be *this (since C++17) or this (since C++20).

struct S2 { void f(int i); };
void S2::f(int i)
{
    [=]{};          // OK: by-copy capture default
    [=, &i]{};      // OK: by-copy capture, except i is captured by reference
    [=, *this]{};   // until C++17: Error: invalid syntax
                    // since c++17: OK: captures the enclosing S2 by copy
    [=, this] {};   // until C++20: Error: this when = is the default
                    // since C++20: OK, same as [=]
}

Any capture may appear only once:

struct S2 { void f(int i); };
void S2::f(int i)
{
    [i, i] {};        // Error: i repeated
    [this, *this] {}; // Error: "this" repeated (C++17)
}

Only lambda-expressions defined at block scope or in a default member initializer 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 g0 = [](auto a) { f(x); }; // ok: calls #1, does not capture x
    auto g1 = [=](auto a) { f(x); }; // does not capture x in C++14, captures x in C++17
                                     // the capture can be optimized away
    auto g2 = [=](auto a) {
            int selector[sizeof(a) == 1 ? 1 : 2] = {};
            f(x, selector); // ok: is a dependent expression, so captures x
    };
    auto g3 = [=](auto a) {
      typeid(a + x);  // captures x regardless of whether a + x is an unevaluated operand
    };
}

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), either the nearest enclosing function must be a non-static member function or the lambda must be in a default member initializer:

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 *this is always implicitly captured 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 captures 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
    // since C++14, lambda could own default arguments
    auto func1 = [](int i = 6) { return i + 4; };
    std::cout << "func1: " << func1() << '\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