Capturing

Closures are inherently flexible and will do what the functionality requires
to make the closure work without annotation. This allows capturing to
flexibly adapt to the use case, sometimes moving and sometimes borrowing.
Closures can capture variables:

  • by reference: &T
  • by mutable reference: &mut T
  • by value: T

They preferentially capture variables by reference and only go lower when
required.

  1. fn main() {
  2.     use std::mem;
  4.     let color = "green";
  6.     // A closure to print `color` which immediately borrows (`&`)
  7.     // `color` and stores the borrow and closure in the `print`
  8.     // variable. It will remain borrowed until `print` goes out of
  9.     // scope. `println!` only requires `by reference` so it doesn't
  10.     // impose anything more restrictive.
  11.     let print = || println!("`color`: {}", color);
  13.     // Call the closure using the borrow.
  14.     print();
  15.     print();
  17.     let mut count = 0;
  19.     // A closure to increment `count` could take either `&mut count`
  20.     // or `count` but `&mut count` is less restrictive so it takes
  21.     // that. Immediately borrows `count`.
  22.     //
  23.     // A `mut` is required on `inc` because a `&mut` is stored inside.
  24.     // Thus, calling the closure mutates the closure which requires
  25.     // a `mut`.
  26.     let mut inc = || {
  27.         count += 1;
  28.         println!("`count`: {}", count);
  29.     };
  31.     // Call the closure.
  32.     inc();
  33.     inc();
  35.     //let reborrow = &mut count;
  36.     // ^ TODO: try uncommenting this line.
  38.     // A non-copy type.
  39.     let movable = Box::new(3);
  41.     // `mem::drop` requires `T` so this must take by value. A copy type
  42.     // would copy into the closure leaving the original untouched.
  43.     // A non-copy must move and so `movable` immediately moves into
  44.     // the closure.
  45.     let consume = || {
  46.         println!("`movable`: {:?}", movable);
  47.         mem::drop(movable);
  48.     };
  50.     // `consume` consumes the variable so this can only be called once.
  51.     consume();
  52.     //consume();
  53.     // ^ TODO: Try uncommenting this line.
  54. }

Using move before vertical pipes forces closure
to take ownership of captured variables:

  1. fn main() {
  2.     // `Vec` has non-copy semantics.
  3.     let haystack = vec![1, 2, 3];
  5.     let contains = move |needle| haystack.contains(needle);
  7.     println!("{}", contains(&1));
  8.     println!("{}", contains(&4));
  10.     // `println!("There're {} elements in vec", haystack.len());`
  11.     // ^ Uncommenting above line will result in compile-time error
  12.     // because borrow checker doesn't allow re-using variable after it
  13.     // has been moved.
  15.     // Removing `move` from closure's signature will cause closure
  16.     // to borrow _haystack_ variable immutably, hence _haystack_ is still
  17.     // available and uncommenting above line will not cause an error.
  18. }

See also:

Box and std::mem::drop