Constructs aclosure (an unnamed function object capable of capturing variables in scope).

[edit]Syntax

[edit]Lambda expressions without an explicit template parameter list (possibly non-generic)

[edit]Lambda expressions with an explicit template parameter list (always generic)(since C++20)

[edit]Explanation

A variable__func__ is implicitly defined at the beginning ofbody, with semantics as describedhere.

[edit]Closure type

The lambda expression is a prvalue expression of unique unnamed non-union non-aggregate class type, known asclosure type, which is declared (for the purposes ofADL) in the smallest block scope, class scope, or namespace scope that contains the lambda expression.

The closure type has the following members, they cannot beexplicitly instantiated,explicitly specialized, or(since C++14) named in afriend declaration:

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

// generic lambda, operator() is a template with two parametersauto glambda=[]<class T>(T a,auto&& b){return a< b;}; // generic lambda, operator() is a template with one parameter packauto 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*};}};

1. ↑Although function return type deduction is introduced in C++14, its rule is available for lambda return type deduction in C++11.

void f1(int(*)(int)){}void f2(char(*)(int)){}void h(int(*)(int)){}// #1void h(char(*)(int)){}// #2 auto glambda=[](auto a){return a;};f1(glambda);// OKf2(glambda);// error: not convertibleh(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){staticint s;return a;};static_assert(Fwd(NC,3)==3);// error: no specialization can be// constexpr because of static s

[edit]Lambda capture

Thecaptures defines the outside variables that are accessible from within the lambda function body. Its syntax is defined as follows:

The syntax ofcapture is defined as follows:

If thecapture-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 thecapture-default is=, subsequent simple captures must begin with& or be*this(since C++17)orthis(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, and its name must be different from any parameter name:

struct S2{void f(int i);};void S2::f(int i){[i, i]{};// Error: i repeated[this,*this]{};// Error: "this" repeated (C++17) [i](int i){};// Error: parameter and capture have the same name}

A lambda expression can use a variable without capturing it if the variable

• is a non-local variable or has static or thread localstorage duration (in which case the variable cannot be captured), or
• is a reference that has been initialized with aconstant expression.

A lambda expression can read the value of a variable without capturing it if the variable

• has const non-volatile integral or enumeration type and has been initialized with aconstant expression, or
• is constexpr and has no mutable members.

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)

Only lambda expressions satisfying any of the following conditions may have acapture-default orcapture without initializers:

• Its innermostenclosing scope is ablock scope.
• It appears within adefault member initializer, and its innermost enclosing scope is the correspondingclass scope.

For such lambda expression, thereaching 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.

Theidentifier in any capture without an initializer (other than thethis-capture) is looked up using usualunqualified name lookup in thereaching scope of the lambda. The result of the lookup must be avariable with automatic storage duration declared in the reaching scope, or astructured binding whose corresponding variable satisfies such requirements(since C++20). The entity isexplicitly 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.

Ifcaptures has acapture-default and does not explicitly capture the enclosing object (asthis or*this), or an automatic variable that isodr-usable in the lambda body, or astructured binding whose corresponding variable has atomic storage duration(since C++20), it captures the entityimplicitly if the entity is named in apotentially-evaluated expression within an expression (including when the implicitthis-> is added before a use of non-static class member).

For the purpose of determining implicit captures,typeid is never considered to make its operands unevaluated.

void f(int,constint(&)[2]={}){}// #1void f(constint&,constint(&)[1]){}// #2 struct NoncopyableLiteralType{constexprexplicit NoncopyableLiteralType(int n): n_(n){}    NoncopyableLiteralType(const NoncopyableLiteralType&)= delete; int n_;}; void test(){constint x=17; auto l0=[]{ f(x);};// OK: calls #1, does not capture xauto g0=[](auto a){ f(x);};// same as above auto l1=[=]{ f(x);};// OK: captures x (since P0588R1) and calls #1// the capture can be optimized awayauto g1=[=](auto a){ f(x);};// same as above auto ltid=[=]{typeid(x);};// OK: captures x (since P0588R1)// even though x is unevaluated// 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}; constexpr NoncopyableLiteralType w{42};auto l4=[]{return w.n_;};// OK: w is not odr-used, capture is unnecessary// auto l5 = [=]{ return w.n_; };  // error: w needs to be captured by copy}

If the body of a lambdaodr-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(constint*);void g(){constint 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}();}

If a lambda odr-uses a reference that is captured by reference, it is using the object referred-to by the original reference, not the captured reference itself:

#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 with capture default=, the type of any capturable entity is as if it were captured (and thus const-qualification is often added if the lambda is notmutable), even though the entity is in an unevaluated operand and not captured (e.g. indecltype):

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 thereaching scope of the lambda.

If a lambda captures the enclosing object (asthis or*this), either the nearest enclosing function must be a non-static member function or the lambda must be in adefault 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 a specialization of a generic lambda's function call operator)(since C++14) ODR-uses*this or any variable with automatic storage duration, it must be captured by the lambda expression.

void f1(int i){intconst N=20;auto m1=[=]{intconst 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, onlyvariables are permitted in thecapture-list ):

class S{int x=0; void f(){int i=0;//  auto l1 = [i, x] { use(i, x); };      // error: x is not a variableauto 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 variablem 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 adefault argument, it cannot explicitly or implicitly capture anything, unless all captures have initializers which satisfy the constraints of an expression appearing in a default argument(since C++14):

void f2(){int i=1; void g1(int=[i]{return i;}());// error: captures somethingvoid g2(int=[i]{return0;}());// error: captures somethingvoid g3(int=[=]{return i;}());// error: captures something void g4(int=[=]{return0;}());// OK: capture-lessvoid g5(int=[]{return sizeof i;}());// OK: capture-less // C++14void g6(int=[x=1]{return x;}());// OK: 1 can appear//     in a default argumentvoid g7(int=[x= i]{return x;}());// error: i cannot appear//        in a default argument}

Members ofanonymous unions members cannot be captured.Bit-fields can only be captured by copy.

If a nested lambdam2 captures something that is also captured by the immediately enclosing lambdam1, thenm2's capture is transformed as follows:

• if the enclosing lambdam1 captures by copy,m2 is capturing the non-static member ofm1's closure type, not the original variable or*this; ifm1 is not mutable, the non-static data member is considered to be const-qualified.
• if the enclosing lambdam1 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 123std::cout<< a<< b<< c<<'\n';// prints 234}

struct C{template<typename T>    C(T);}; void func(int i){int x=[=](thisauto&&){return i;}();// OKint y=[=](this C){return i;}();// errorint z=[](this C){return42;}();// OK auto lambda=[n=42](thisauto self){return n;};using Closure= decltype(lambda);struct D:private Closure{        D(Closure l): Closure(l){}using Closure::operator();friend Closure;};    D{lambda}();// error}

[edit]Notes

The rule for implicit lambda capture is slightly changed by defect reportP0588R1. As of 2023-10, some major implementations have not completely implemented the DR, and thus the old rule, which detectsodr-using, is still used in some cases.

[edit]Example

#include <algorithm>#include <functional>#include <iostream>#include <vector> 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 argumentsauto 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'; constexprint fib_max{8};std::cout<<"Emulate `recursive lambda` calls:\nFibonacci numbers: ";auto nth_fibonacci=[](int n){std::function<int(int,int,int)> fib=[&](int n,int a,int b){return n? fib(n-1, a+ b, a): b;};return fib(n,0,1);}; for(int i{1}; i<= fib_max;++i)std::cout<< nth_fibonacci(i)<<(i< fib_max?", ":"\n"); std::cout<<"Alternative approach to lambda recursion:\nFibonacci numbers: ";auto nth_fibonacci2=[](auto self,int n,int a=0,int b=1)->int{return n? self(self, n-1, a+ b, a): b;}; for(int i{1}; i<= fib_max;++i)std::cout<< nth_fibonacci2(nth_fibonacci2, i)<<(i< fib_max?", ":"\n"); #ifdef __cpp_explicit_this_parameterstd::cout<<"C++23 approach to lambda recursion:\n";auto nth_fibonacci3=[](thisauto self,int n,int a=0,int b=1)->int{return n? self(n-1, a+ b, a): b;}; for(int i{1}; i<= fib_max;++i)std::cout<< nth_fibonacci3(i)<<(i< fib_max?", ":"\n");#endif}

c: 5 6 7func1: 10func2: 10Emulate `recursive lambda` calls:Fibonacci numbers: 0, 1, 1, 2, 3, 5, 8, 13Alternative approach to lambda recursion:Fibonacci numbers: 0, 1, 1, 2, 3, 5, 8, 13

[edit]Defect reports

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

[edit]See also

[edit]External links

• In other languages

• Deutsch
• Español
• Français
• Italiano
• 日本語
• Português
• Русский
• 中文