Raw data, clear context.

[
[
[

]
]
]

A function needs to display some text, and its caller needs that text afterwards. Pass a reference so the function can borrow the value while the caller keeps ownership.[1] The ampersand marks this change in how the argument is passed.[1]

Let a function look

Tested on Linux ARM64 with rustc 1.99.1 and Cargo 1.99.1. Create a fresh project, then open its borrowing folder in your editor and terminal.

Shell
cargo new --vcs none borrowing
Output
$ cargo new --vcs none borrowing
Creating binary (application) `borrowing` package
note: see more `Cargo.toml` keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
exit=0

Replace src/main.rs with this complete programme.

src/main.rs
Rust
fn show(note: &String) {
println!("Borrowed: {note}");
}
fn main() {
let note = String::from("shopping");
show(&note);
println!("Still owned: {note}");
}

String::from creates an owned String from the quoted text.[2] In main, note owns that value.

At the call, &note creates a reference to the existing value. In the parameter, &String says that show accepts a reference to a String.[1] Read the two ampersands together: the call supplies what the function expects.

A reference provides access to a value owned elsewhere and must remain valid while it is used.[1] Borrowing here leaves the caller’s String in place; the function receives a reference rather than taking ownership of that String.[1]

Run from the borrowing folder. Captures include the executed command and exit status.

Shell
cargo run --quiet
Output
$ cargo run --quiet
Borrowed: shopping
Still owned: shopping
exit=0

The first line comes from show. The second line comes from main, using the same note after the call.

Main owns one String containing shopping. During show, its note parameter holds a shared reference to that same String. After show returns, main still owns the String and prints shopping again.
The call passes a shared reference to the existing String. The owner stays in main before, during and after show; the two printed lines use the same text.

When show returns, its parameter goes out of scope. The borrowed String remains owned by note in main.[1] This reference gives show shared access; it cannot use that reference to change this String.[1]

A common error: forgetting the borrow

Replace src/main.rs with this deliberately failing version. Only the call changes.

src/main.rs
Rust
fn show(note: &String) {
println!("Borrowed: {note}");
}
fn main() {
let note = String::from("shopping");
show(note);
println!("Still owned: {note}");
}

Check it. Failure is expected.

Shell
cargo check --quiet
Output
$ cargo check --quiet
error[E0308]: mismatched types
--> src/main.rs:7:10
|
7 | show(note);
| ---- ^^^^ expected `&String`, found `String`
| |
| arguments to this function are incorrect
|
note: function defined here
--> src/main.rs:1:4
|
1 | fn show(note: &String) {
| ^^^^ -------------
help: consider borrowing here
|
7 | show(&note);
| +
For more information about this error, try `rustc --explain E0308`.
error: could not compile `borrowing` (bin "borrowing") due to 1 previous error
exit=101

Our check returned E0308 and exit 101: expected &String, found String. The compiler suggests adding & at the call.

E0308 means the received type differs from the expected type.[3]

Restore the ampersand and rerun the working version. Compare the parameter type with the argument before changing the function.

Exercise

Change shopping to weekend in the working programme. Run it and expect both output lines to end with weekend.

Next: mutable references let a function change borrowed data.

Browse Rust, one step at a time

Sources

  1. The Rust Book: References and Borrowing
  2. Rust standard library: String
  3. Rust error E0308: mismatched types

Leave a Reply