Borrowing

Most of the time, we’d like to access data without taking ownership over
it. To accomplish this, Rust uses a borrowing mechanism. Instead of
passing objects by value (T), objects can be passed by reference (&T).

The compiler statically guarantees (via its borrow checker) that references
always point to valid objects. That is, while references to an object
exist, the object cannot be destroyed.

  1. // This function takes ownership of a box and destroys it
  2. fn eat_box_i32(boxed_i32: Box<i32>) {
  3.     println!("Destroying box that contains {}", boxed_i32);
  4. }
  6. // This function borrows an i32
  7. fn borrow_i32(borrowed_i32: &i32) {
  8.     println!("This int is: {}", borrowed_i32);
  9. }
  11. fn main() {
  12.     // Create a boxed i32, and a stacked i32
  13.     let boxed_i32 = Box::new(5_i32);
  14.     let stacked_i32 = 6_i32;
  16.     // Borrow the contents of the box. Ownership is not taken,
  17.     // so the contents can be borrowed again.
  18.     borrow_i32(&boxed_i32);
  19.     borrow_i32(&stacked_i32);
  21.     {
  22.         // Take a reference to the data contained inside the box
  23.         let _ref_to_i32: &i32 = &boxed_i32;
  25.         // Error!
  26.         // Can't destroy `boxed_i32` while the inner value is borrowed.
  27.         eat_box_i32(boxed_i32);
  28.         // FIXME ^ Comment out this line
  30.         // `_ref_to_i32` goes out of scope and is no longer borrowed.
  31.     }
  33.     // `boxed_i32` can now give up ownership to `eat_box` and be destroyed
  34.     eat_box_i32(boxed_i32);
  35. }