11.14 — Lambda captures

Capture clauses and capture by value

In the previous lesson (11.13 -- Introduction to lambdas (anonymous functions)), we introduced this example:

Now, let’s modify the nut example and let the user pick a substring to search for. This isn’t as intuitive as you might expect.

This code won’t compile. Unlike nested blocks, where any identifier defined in an outer block is accessible in the scope of the nested block, lambdas can only access specific kinds of identifiers: global identifiers, entities that are known at compile time, and entities with static storage duration. search fulfills none of these requirements, so the lambda can’t see it. That’s what the capture clause is there for.

The capture clause

The capture clause is used to (indirectly) give a lambda access to variables available in the surrounding scope that it normally would not have access to. All we need to do is list the entities we want to access from within the lambda as part of the capture clause. In this case, we want to give our lambda access to the value of variable search, so we add it to the capture clause:

The user can now search for an element of our array.


search for: nana
Found banana

So how do captures actually work?

While it might look like our lambda in the example above is directly accessing the value of main‘s search variable, this is not the case. Lambdas might look like nested blocks, but they work slightly differently (and the distinction is important).

When a lambda definition is executed, for each variable that the lambda captures, a clone of that variable is made (with an identical name) inside the lambda. These cloned variables are initialized from the outer scope variables of the same name at this point.

Thus, in the above example, when the lambda object is created, the lambda gets its own cloned variable named search. This cloned search has the same value as main‘s search, so it behaves like we’re accessing main‘s search, but we’re not.

While these cloned variable have the same name, they don’t necessarily have the same type as the original variable. We’ll explore this in the upcoming sections of this lesson.

Key insight

The captured variables of a lambda are clones of the outer scope variables, not the actual variables.

For advanced readers

Although lambdas look like functions, they’re actually objects that can be called like functions (these are called functors -- we’ll discuss how to create your own functors from scratch in a future lesson).

When the compiler encounters a lambda definition, it creates a custom object definition for the lambda. Each captured variable becomes a data member of the object.

At runtime, when the lambda definition is encountered, the lambda object is instantiated, and the members of the lambda are initialized at that point.

Captures default to const value

By default, variables are captured by const value. This means when the lambda is created, the lambda captures a constant copy of the outer scope variable, which means that the lambda is not allowed to modify them. In the following example, we capture the variable ammo and try to decrement it.

In the above example, when we capture ammo, a new const variable with the same name and value is created in the lambda. We can’t modify it, because it is const, which causes a compile error.

Mutable capture by value

To allow modifications of variables that were captured by value, we can mark the lambda as mutable. The mutable keyword in this context removes the const qualification from all variables captured by value.


Pew! 9 shot(s) left.
Pew! 8 shot(s) left.
10 shot(s) left

While this now compiles, there’s still a logic error. What happened? When the lambda was called, the lambda captured a copy of ammo. When the lambda decremented ammo from 10 to 9 to 8, it decremented its own copy, not the original value.

Note that the value of ammo is preserved across calls to the lambda!


Because captured variables are members of the lambda object, their values are persisted across multiple calls to the lambda!

Capture by reference

Much like functions can change the value of arguments passed by reference, we can also capture variables by reference to allow our lambda to affect the value of the argument.

To capture a variable by reference, we prepend an ampersand (&) to the variable name in the capture. Unlike variables that are captured by value, variables that are captured by reference are non-const, unless the variable they’re capturing is const. Capture by reference should be preferred over capture by value whenever you would normally prefer passing an argument to a function by reference (e.g. for non-fundamental types).

Here’s the above code with ammo captured by reference:

This produces the expected answer:

Pew! 9 shot(s) left.
9 shot(s) left

Now, let’s use a reference capture to count how many comparisons std::sort makes when it sorts an array.

Possible output

Comparisons: 2
Honda Civic
Toyota Corolla
Volkswagen Golf

Capturing multiple variables

Multiple variables can be captured by separating them with a comma. This can include a mix of variables captured by value or by reference:

Default captures

Having to explicitly list the variables you want to capture can be burdensome. If you modify your lambda, you may forget to add or remove captured variables. Fortunately, we can enlist the compiler’s help to auto-generate a list of variables we need to capture.

A default capture (also called a capture-default) captures all variables that are mentioned in the lambda. Variables not mentioned in the lambda are not captured if a default capture is used.

To capture all used variables by value, use a capture value of =.
To capture all used variables by reference, use a capture value of &.

Here’s an example of using a default capture by value:

Default captures can be mixed with normal captures. We can capture some variables by value and others by reference, but each variable can only be captured once.

Defining new variables in the lambda-capture

Sometimes we want to capture a variable with a slight modification or declare a new variable that is only visible in the scope of the lambda. We can do so by defining a variable in the lambda-capture without specifying its type.

userArea will only be calculated once when the lambda is defined. The calculated area is stored in the lambda object and is the same for every call. If a lambda is mutable and modifies a variable that was defined in the capture, the original value will be overridden.

Best practice

Only initialize variables in the capture if their value is short and their type is obvious. Otherwise it’s best to define the variable outside of the lambda and capture it.

Dangling captured variables

Variables are captured at the point where the lambda is defined. If a variable captured by reference dies before the lambda, the lambda will be left holding a dangling reference.

For example:

The call to makeWalrus creates a temporary std::string from the string literal “Roofus”. The lambda in makeWalrus captures the temporary string by reference. The temporary string dies when makeWalrus returns, but the lambda still references it. Then when we call sayName, the dangling reference is accessed, causing undefined behavior.

Note that this also happens if name is passed to makeWalrus by value. The variable name still dies at the end of makeWalrus, and the lambda is left holding a dangling reference.


Be extra careful when you capture variables by reference, especially with a default reference capture. The captured variables must outlive the lambda.

If we want the captured name to be valid when the lambda is used, we need to capture it by value instead (either explicitly or using a default-capture by value).

Unintended copies of mutable lambdas

Because lambdas are objects, they can be copied. In some cases, this can cause problems. Consider the following code:



Rather than printing 1, 2, 3, the code prints 2 twice. When we created otherCount as a copy of count, we created a copy of count in its current state. count‘s i was 1, so otherCount‘s i is 1 as well. Since otherCount is a copy of count, they each have their own i.

Now let’s take a look at a slightly less obvious example:



This exhibits the same problem as the prior example in a more obscure form. When std::function is created with a lambda, the std::function internally makes a copy of the lambda object. Thus, our call to fn() is actually being executed on the copy of our lambda, not the actual lambda.

If we need to pass a mutable lambda, and want to avoid the possibility of inadvertent copies being made, there are two options. One option is to use a non-capturing lambda instead -- in the above case, we could remove the capture and track our state using a static local variable instead. But static local variables can be difficult to keep track of and make our code less readable. A better option is to prevent copies of our lambda from being made in the first place. But since we can’t affect how std::function (or other standard library functions or objects) are implemented, how can we do this?

Fortunately, C++ provides a convenient type (as part of the <functional> header) called std::reference_wrapper that allows us to pass a normal type as if it were a reference. For even more convenience, a std::reference_wrapper can be created by using the std::ref() function. By wrapping our lambda in a std::reference_wrapper, whenever anybody tries to make a copy of our lambda, they’ll make a copy of the reference instead, which will copy the reference rather than the actual object.

Here’s our updated code using std::ref:

Our output is now as expected:


Note that the output doesn’t change even if invoke takes fn by value. std::function doesn’t create a copy of the lambda if we create it with std::ref.


Standard library functions may copy function objects (reminder: lambdas are function objects). If you want to provide lambdas with mutable captured variables, pass them by reference using std::ref.

Best practice

Try to avoid lambdas with states altogether. Stateless lambdas are easier to understand and don’t suffer from the above issues, as well as more dangerous issues that arise when you add parallel execution.

Quiz time

Question #1

Which of the following variables can be used by the lambda in main without explicitly capturing them?

Show Solution

Question #2

What does the following code print? Don’t run the code, work it out in your head.

Show Solution

Question #3

We’re going to write a little game with square numbers (numbers which can be created by multiplying an integer with itself (1, 4, 9, 16, 25, …)).

Ask the user to input 2 numbers, the first is the square root of the number to start at, the second is the amount of numbers to generate. Generate a random integer from 2 to 4, and square numbers in the range that was chosen by the user. Multiply each square number by the random number. You can assume that the user enters valid numbers.

The user has to calculate which numbers have been generated. The program checks if the user guessed correctly and removes the guessed number from the list. If the user guessed wrong, the game is over and the program prints the number that was closest to the user’s final guess, but only if the final guess was not off by more than 4.

Here are a couple of sample sessions to give you a better understanding of how the game works:

Start where? 4
How many? 8
I generated 8 square numbers. Do you know what each number is after multiplying it by 2?
> 32
Nice! 7 number(s) left.
> 72
Nice! 6 number(s) left.
> 50
Nice! 5 number(s) left.
> 126
126 is wrong! Try 128 next time.
  • The user chose to start at 4 and wants to play with 8 numbers.
  • Each square number will be multiplied by 2. 2 was randomly chosen by the program.
  • The program generates 8 square numbers, starting with 4 as a base:
  • 16 25 36 49 64 81 100 121
  • But each number is multiplied by 2, so we get:
  • 32 50 72 98 128 162 200 242
  • Now the user starts to guess. The order in which in guesses are entered doesn’t matter.
  • 32 is in the list.
  • 72 is in the list.
  • 126 is not in the list, the user loses. There is a number in the list (128) that is not more then 4 away from the user’s guess, so that number is printed.
Start where? 1
How many? 3
I generated 3 square numbers. Do you know what each number is after multiplying it by 4?
> 4
Nice! 2 numbers left.
> 16
Nice! 1 numbers left.
> 36
Nice! You found all numbers, good job!
  • The user chose to start at 1 and wants to play with 3 numbers.
  • Each square number will be multiplied by 4.
  • The program generates these square numbers:
  • 1 4 9
  • Multiplied by 4
  • 4 16 36
  • The user guesses all numbers correctly and wins the game.
Start where? 2
How many? 2
I generated 2 square numbers. Do you know what each number is after multiplying it by 4?
> 21
21 is wrong!
  • The user chose to start at 2 and wants to play with 2 numbers.
  • Each square number will be multiplied by 4.
  • The program generates these numbers:
  • 16 36
  • The user guesses 21 and loses. 21 is not close enough to any of the remaining numbers, so no number is printed.

Use std::find (10.25 -- Introduction to standard library algorithms) to search for a number in the list.
Use std::vector::erase to remove an element, e.g.

Use std::min_element and a lambda to find the number closest to the user’s guess. std::min_element works analogous to std::max_element from the previous quiz.

Show Hint

Show Solution

11.x -- Chapter 11 comprehensive quiz
11.13 -- Introduction to lambdas (anonymous functions)

210 comments to 11.14 — Lambda captures

  • ItsOkayTryAgain

    If std::function always creates its own copy why do we even bother to pass to it by reference?

  • does anyone who study in this website can answer this?

    for me, I think I cannot and I'm a little discouraged by that fact.

  • Lesommeil

    I just want to finish the question and go to the next chapter, sorry for not follow the best practices and my bad style.

  • Waldo Lemmer

    Section "Mutable capture by value":
    > Note that the value of ammo is preserved across calls to the lambda!

    I think this deserves to be in a red "warning" block.

    Section "Unintended copies of mutable lambdas", code block 2, line 4 has the `&`
    next to the identifier.

    Question #3, first list:
    > The program generates 8 square number, starting with 4 as a base:

    "number" should be "numbers"

  • Miguel Barbosa

    Dear Alex, why not put & in the lambda when passing "i"?

    • Alex

      You should. The example is showing a case where a problem occurs due to using a mutable capture by value rather than a capture by reference.

    • Rico

      Yeah this should be the best way. I personally prefer using capture by reference over passing in std::reference_wrapper

  • James C

    Not sure if this is a bad practice or what, but in the example using std::function, it has std::function<void(void)>. Is the void parameter intended?

  • AS

    please review my code
    thank you

  • AS

    can you please review my code
    thank you

    • nascardriver

      - `getRandomNumber()` is not random. Try calling it in a loop.
      - `numberOfGuesses` mirrors `numbers.size()`, you don't need it
      - Using non-bools as conditions requires extra thinking time. You can use `while (!numbers.empty())` instead.
      - Your loop to fill the vector causes several resizes of the vector. If you know how many element you will have beforehand, use the count constructor or `reserve()`.

      Good job :)

  • Szymon :)

    Thought this was interesting, maybe it will help someone understand how lambdas work

  • Christofle

    Here's my answer to the multiplied square number game. There's probably so many stuff I could've done better.

  • Kolunikus

    Never mind, I found my mistake. At first reading, I was under the impressions that the scoping restrictions also restricted the eligibility for variables to be passed to the lambda as arguments. I realize now that that's not what was meant.

  • Kolunikus

    Sorry about the last comment, my browser just randomly decided to post before I finished typing. Anoy who can, please delete my previous unfinished comment.

    Again: I do not understand why variable

    in question 1 is not visible to the lambda without capture, but the

    array in question 2 from the previous lesson is. The array and all of the values assigned to it are only defined in the

    function and should also have automatic storage duration, right? What am I missing?

  • Rayyan Khan

    I know you have probably moved on a lot, but there is quite a bit of spaghetti code inside the do-while loop. (coming from me, who is always writing spaghetti code ;). Try making modular functions.

  • gerry laisina

    Hi Alex and Nascardriver
    I wanna ask something here (again)
    about the error related to dangling captured variables.
    You said that "if we want the captured "name" to be valid when the lambda is used, we need to capture it by value instead (either explicitly or using a default-capture by value)."
    So what's actually gonna happen if i pass the string ("Roofus") by reference and capture the "name" variable by value. Is it gonna result in undefined behaviour if i run statement in line 20("sayName();")?

    Because from my judgement, when the statement in line 20 is executed, the variable "name" inside the lambda should be no longer a parameter referring to the string "Roofus". Please correct me if my understanding here is wrong.
    Thanks Before!

    • nascardriver


      If you capture `name` by value, everything is fine. The lambda no longer refers to the temporary `std::string` that was created by `main()`, but instead to a local (inside the lambda) `std::string` that was initialized from the temporary.

      The lambda is an object that has all captured variables as members. Omitting the magic that make the lambda callable, you get this

      This is undefined behavior, because `` refers to the temporary created and destroyed in line 15.
      If you capture by value, the `const std::string&` in line 10 is a `const std::string` (No reference), and the program works.

      • gerry laisina

        so what you're trying to say here is, when the lambda tries to capture "name" variable by value, although the type of "name" variable it captures (from function parameter) is const std::string&, the lambda is actually doing some kind of 'implicit convertion' of the "name" type here (from const std::string& into const std::string)? Is that it?

        Thanks before.

  • well, im stepping through this tutorials and im  almost pretty sure we never did something like this, code work fine ,but is was new to see it, it should write like that:

    its not a big thing but i will appreciate if u tall me what is different ? or same?

    • nascardriver

      There used to be a section about init-statements, it must have been lost when the if-statement lesson was separated into 2. I've adjusted this lesson to declare `found` outside of the if-statement. Thanks for pointing it out!

    Line 72,37 here:

    and can u answer me plz why do we remove found here:

    • nascardriver


      Do you mind pointing out what is wrong with the code you quoted?

      The number needs to be removed from the list so the user can't guess it again.

  • Azazel

    It's been easier for me to create my own functions instead of using the provided functions from the standard library, the main reason is probably because I don't understand the errors displayed when I do something wrong. I also don't understand the syntax behind it's codes as there's advanced stuff for me(classes,templates, etc...)
    So if Alex, Nascardriver or another experienced programmer could tell me if it's ok using my own functions(even if it means having more lines of code)if I'm more confortable this way?
    I've tried to answer question #3 with the way shown in this lesson, but I've failed and got frustated, so I tried using my own functions and it was fine.(I didn't use lambdas in this one)
    Here's the link for anyone who wants to see the almost "C++ raw code" solution(144 lines):

    • nascardriver

      It's fine, and good for practice, to implement standard library functions to understand how they work. If you just want to use a function, you should use the standard library version. It's very likely better every way than code you or me could write.
      A reader of your code would have to assume that your function is different than the standard one, why else would you have implemented in manually. The reader will waste time trying to understand what you did, just to figure out that you didn't do anything special. Your code is also harder to use for other people. Everyone knows the standard library, but only you know your code.
      The standard library is a powerful part of C++, there's no way around learning it. The sooner you understand how to use it, the more you will benefit from it.

      • Azazel

        Thank you for the answer, it was very clever. I'm already on operator overloading by now, and also started looking to some API's and frameworks and came to the conclusion some times it's not worth trying to build my own code from scratch, some other times it's even impossible!

  • Patrick

    Hey there, here's my solution to the game. Any feedback would be much appreciated. Thanks for all the time you guys spend reading through these.

    • nascardriver


      - Avoid abbreviations, name variables descriptively.
      - `GetRandyNumeric` isn't random, because you're creating a new random number generator (With potentially the same seed) every time this function gets called.
      - Line 19: It is unspecified when `start` gets incremented. This function can yield different results with different compilers. If you want something to happen in a specific order, write it in a specific order.
      - Pass non-fundamental types by const reference. Copying them is slow (Unless they're small).
      - `abs()` should be `std::abs()`. The functions without a `std::` prefix are from C.

  • Sahil

    Here's my answer to squares game. Please let me know if I did anything wrong, or there are certain changes that would optimize the code. The playGame() is a bit too long but I found it a bit difficult to split it into multiple functions, so I kept it as it is. I would highly appreciate it if you would also let me know if the comments were helpful or not, and if not then what more should I be doing to make them better.

    • nascardriver

      - Use descriptive names, avoid abbreviations, avoid nameless things (`std::pair`) unless they're obvious.

      You can use list-initialization

      - `min` and `max` can be parameters of `randomNum` to increase reusability
      - `std::vector::at()` validates the index every time you call it. You just created the vector, you know the indexes are valid. Having the indexes validated is wasted time. `operator[]` doesn't validate the index.
      - Modifying arguments is confusing, especially if you change their meaning such that the name is no longer accurate
      - Use `.empty()` to check if a container is empty
      - Pass by `const` reference unless you want to have an out-parameter. You shouldn't want to have out-parameters, they're confusing.
      - `closestNum` can be declared in a smaller scope. Calculating it when you won't access it is wasteful.

      If you think you need a comment in your code (ie. not a documentation comment), you either

      1) are doing something complicated or potentially confusing that needs explaining as to how it works or why it works
      2) have bad names
      3) have bad structure

      (1) is rare but not always avoidable. (2) and (3) need to be solved. You're not in situation (1), so you need better names and/or structure. You already noticed that you have situation (3), you said that, and that's fine, you're just getting started. You also noticed, even if subconsciously, that you have (2), because you wrote comments that contain better names.

      //asks user for input and returns a std::pair for start at and number of squares to be generated
      Naming the struct is the most difficult part here, because it's only got 2 members

      "Input" can be anything. Now that you've got a named struct, you can change it to `getConfiguration()`. Where does the configuration come from? You said it, from the user: `getConfigurationFromUser()`.

      //Gets user guess number
      `getGuess()` provides enough information given the context.

      //Generates a random num between 2 and 4
      Spell out "number", `randomNumber()`. Avoid using nouns as function names, `generateRandomNumber()`. Don't hide 2 and 4 in the documentation, `generateRandomNumber(int min = 2, int max = 4)`

      //Generates squares, multiplies the squares with a random num and returns a vector of these numbers
      You can remove the "a vector of", the user can see your return type. This is a good comment

      //will be used to find a number closest to user guess if the guess is wrong
      `allowedVariation` provides enough information given the context.

      //Generate the vector that holds the numbers
      This comment doesn't add any information, it can be removed

      //Num that is closest to user guess

      //if the guessed no. was found in the vector
      `std::find()` is well-known, no need to explain its return value

      //erase the number that was found
      No extra information

      //if the guess was not in the vec, was it closer to one of the answers?
      Use an unconditional `else` to get rid of this comment

      //Guess wasn't found, nor closer to any answer, You fail!
      Should be obvious after you use an unconditional `else`

      //Used to find a number thats closest to the user guess
      You don't know what functions will be used for. You don't know that `guess` is a guess, you don't know that `squares` are square numbers. `guess` can be renamed to `value` or `needle`. `squared` doesn't really have a meaning to it, so a short undescriptive name line "v" or "container" is fine.

  • chai

    Hi there, seemingly if "auto" is replaced with "std::function<void(void)>" then passing by reference seems to behave as expected.

    Any thoughts on this?

  • Tomek

    This is my solution. What do you think?

  • J34NP3T3R

    my answer is very faaaarrrrr again ... triple fail

    • J34NP3T3R

      line 42 mistake    const int input{ static_cast<int>(numInput("")) };  //should be const int input{ numInput() };
      line 50 mistake    const int diff{ elem };                             //forgot to erase its unfinished statement

      • J34NP3T3R

        must have forgotten something in function pointers but if i have a function called

        then in main() when i create a function pointer to numInput it will no longer accept empty parameter.

  • J34NP3T3R

    so even though invoke() referenced the parameter fn "&fn" its still using a copy ?

    • nascardriver

      `invoke()` wants a reference to a `std::function`. If you call `invoke()` with something that's no a `std::function`, eg. with a lambda, a temporary `std::function` has to be created first. This causes the lambda to be copied into the temporary `std::function`.

  • Mehmet Uluskan

    I'm thankful for this expressive tutorial also I'm getting benefits from answers to comments, many thanks @nascardriver.

    By the way, I want to state something as constructive feedback;
    it is getting time-consuming to read the related comments(and codes) about Question #3 (Game task). Of course, discussions on Q3 are useful for learning C++ and I read all of them (bcz I'm wondering:q). However, most of the issues at these comments could be out of "lamda" subject. So it seems very long and tiresome to read the post with comments.

    Regards and Greetings

  • Okay, here is the optimized code with the Lambda check to see if the guessed number was within 4 digits of the closest number! :) Forced myself to not look at the solution. I'm getting better at Googling the answers to my problems and std::cout'n at each step to make sure the output is correct before proceeding.
    Debugging info remains in code :)

  • This is my solution to Question 3 as it stands now. I still need to added the final Lambda feature. :)

  • Saurabh

    #include <iostream>
    #include <functional>

    void invoke(const std::function<void(void)>& fn)

    int main()
        int i{ 0 };

        // Increments and prints its local copy of @i.
        auto count{ [i]() mutable {
          std::cout << ++i << '\n';
        } };


        return 0;

    With C++17 this prints

    It seems in C++17, by default reference of lambda object is used to create copy.

Leave a Comment

Put all code inside code tags: [code]your code here[/code]