Rust ownership and moves.

Every value in Rust has an owner: the binding (or struct field, or collection) that holds it. There is exactly one owner at a time. A binding’s scope runs from its let to the closing brace of its block. When the owner goes out of scope, Rust drops the value: it runs the value’s cleanup code, if its type has any, and frees any memory the value owns elsewhere, such as a String’s text. A value with no such memory, such as an i32, simply stops existing.

So cleanup happens at a place you can see in the code, without a garbage collector and without calling free.

One owner per value; the value is dropped when its owner’s scope ends.

A String has two parts. Its text is on the heap, an area of memory for data whose size is decided while the program runs. Its small part holds a pointer (the address of the text), a length (how many bytes the text uses), and a capacity (how many bytes fit in the space reserved for it).

let second = first; copies the small part into second and makes second the owner. The text itself is not copied. If first and second could both be used, both would free the same text when they go out of scope. Freeing the same memory twice is called a double free, and it can corrupt memory. So first stops being an owner, and the compiler rejects any later use of first:

error[E0382]: borrow of moved value: `first`

The error marks three places: “move occurs because `first` has type `String`, which does not implement the `Copy` trait” at the let, “value moved here” under let second = first, and “value borrowed here after move” at the later use. It says borrow because println! takes its arguments through references, and even a borrow is a use. To fix it, use second from that line on, or call first.clone() if you need two Strings, as a later section shows.

Taking a String out of a Vec is a move too. A Vec, a growable list written vec![...], owns its elements, so let one = names[0]; would move a String out and leave a hole in the Vec. The compiler refuses:

error[E0507]: cannot move out of index of `Vec<String>`

with “help: consider borrowing here: `&names[0]`”. A borrow, as in the Variables lesson, uses a value without taking ownership: &names[0] reads the element while the Vec stays its owner. names[0].clone() also works, at the cost of copying the text.

Assigning a String moves it; the old binding cannot be used.

Passing a value to a function works like assignment: the parameter becomes the owner. If the function does not return the value, the value is dropped when the function ends. The caller can no longer use it: a later println!("{}", message) gives the same error[E0382]: borrow of moved value: `message`, with “value moved here” under shout(message).

A for loop takes ownership the same way. for name in names moves the whole Vec into the loop, so a later names.len() gives error[E0382]: borrow of moved value: `names`, with the label “`names` moved due to this implicit call to `.into_iter()`”. into_iter is the method a for loop calls to get the elements. The compiler’s help suggests for name in &names, which borrows each element and leaves the Vec with its owner.

If the caller still needs a value, the function should borrow it: take &String and pass &message. The next lesson, Rust borrowing and references, covers borrowing; its link is at the end of this page.

A parameter taken by value becomes the new owner.

The Variables lesson showed that an i32 is Copy: assigning it copies the number, and the old binding stays usable. Passing a Copy value to a function copies it the same way, so the caller keeps its own.

Copy is allowed only for types whose bytes are the whole value: integers, floating-point numbers, bool, char, and tuples or arrays made only of these. A String cannot be Copy. Copying its small part would give two owners of one text, and the double free from the section on assignment. That is what the E0382 label “which does not implement the `Copy` trait” refers to.

Copy types are copied when assigned or passed; everything else moves.

When you really need two independent Strings, call clone. clone copies the heap text into new memory, so each String has its own text and its own owner. Changing one does not change the other.

clone does real work: it reserves new heap memory and copies the text into it. Use it when you need two values, not to make a compiler error go away.

clone makes a second, independent value, at the cost of copying it.

A function can give ownership back by returning the value. The caller’s binding becomes the new owner. In add_mark below, mut text lets the function change the String it now owns.

Passing a value in and returning it again works, but it is clumsy: every caller has to store the returned value in a new binding. A function that only needs to look at a value borrows it instead.

Returning a value moves ownership back to the caller.

Code that compiles can still use ownership badly. Four mistakes are common. If the compiler says E0382 or E0507, look at the first three.

Cloning only to make the code compile. When E0382 or E0507 appears inside a loop, adding .clone() makes the code compile, but then every pass of the loop allocates and copies. First ask whether the loop only reads the value, so it can borrow it, or whether this is the last use, so it can move it.

Moving into a closure. thread::spawn(move || …) moves every value the closure uses into the new thread. A later use of names in the function that started the thread gives error[E0382]: borrow of moved value: `names`, with “value moved into closure here” under move ||. If that function needs the value again, return it from the closure: handle.join().unwrap() gives back what the closure returned.

Moving out of a field behind &mut. In a method that takes &mut self, let messages = self.messages; gives error[E0507]: cannot move out of `self.messages` which is behind a mutable reference. The struct must still own a complete value afterwards. std::mem::take moves the value out and leaves an empty one, as below. It works only for a type that has an empty value, which is what the Default trait provides; Vec, String, and Option have one. Option::take leaves None. std::mem::replace leaves a value you choose, so it works for any type.

Dropping at once with let _. let _ = value; binds no name, so the value is dropped at the end of that statement. let _guard = value; keeps it until the end of the scope. The guard that Mutex::lock returns unlocks when it is dropped, so let _ = unlocks at once.

Borrow instead of cloning in a loop, take values out of fields with std::mem::take, and name a value that must live to the end of its scope.

Name the owner of each String at every line, then predict the output.