[Rust Guide] 13.4. Capturing the Environment With Closures

13.4.0 Before We Begin

During its design, Rust drew inspiration from many languages, and functional programming had a particularly strong influence on Rust. Functional programming often includes passing functions as values to parameters, returning them from other functions, assigning them to variables for later execution, and so on.

In this chapter, we will discuss some Rust features that are similar to what many languages call functional features:

• Closures (this article)
• Iterators
• Improving the I/O Project with Closures and Iterators
• Performance of Closures and Iterators

13.4.1 Closures Can Capture Their Environment

Closures have a capability that functions do not: a closure can access variables in the scope where it is defined.

Take a look at an example:

fn main() {
    let x = 4;
    let equal_to_x = |z| z == x;
    let y = 4;
    assert!(equal_to_x(y));
}

Enter fullscreen mode Exit fullscreen mode

The closure part is:

let equal_to_x = |z| z == x;

Enter fullscreen mode Exit fullscreen mode

Some people may find it hard to distinguish the roles of = and == here, so let’s rewrite it another way:

let equal_to_x = |z| {
    z == x
};

Enter fullscreen mode Exit fullscreen mode

In other words, the closure takes z as its parameter, compares it with x (which is 4, because x = 4 was defined above), and returns a boolean. If they are equal, the result is true; otherwise it is false. Note that there is no semicolon after z == x: with a semicolon the block would return () instead of the comparison result.

Here the closure directly accesses the variable x in the same scope, which functions cannot do.

But this feature has a cost: it introduces memory overhead. In most cases we do not need a closure to capture its environment, and we do not want the extra overhead either. That is why functions are not allowed to capture variables from the environment, and defining and using a function never introduces this kind of overhead.

13.4.2 How Closures Capture Values From Their Environment

Closures capture values from the environment in three ways, just like functions receive parameters in three ways:

• Taking ownership, whose trait is FnOnce. Once means once, because a closure cannot take and consume the same variable more than once, so it can only be called once.
• Mutable borrowing, whose trait is FnMut
• Immutable borrowing, whose trait is Fn

When a programmer creates a closure, Rust infers which trait should be used based on how the closure uses values from the environment:

• All closures implement FnOnce, because every closure can be called at least once
• Closures that do not move captured variables implement FnMut
• Closures that do not need mutable access to captured variables implement Fn

In fact, these three have an inclusion relationship: every Fn also implements FnMut, and every FnMut also implements FnOnce.

13.4.3 The move Keyword

Using the move keyword before the parameter list forces a closure to take ownership of the environment values it uses. This is most useful when passing a closure to a new thread and moving data so that it belongs to that new thread.

Take a look at an example:

fn main() {
    let x = vec![1, 2, 3];
    let equal_to_x = move |z| z == x;
    println!("can't use x here {:?}", x);
    let y = vec![1, 2, 3];
    assert!(equal_to_x(y));
}

Enter fullscreen mode Exit fullscreen mode

After using move, ownership of x moves into the closure, so x can no longer be used afterward.

13.4.4 Best Practice

When you specify one of the Fn trait bounds, start with Fn. Depending on what happens inside the closure, the compiler will tell you if FnOnce or FnMut is needed instead.