1. 1. Introduction
  2. 2. Getting Started
  3. 3. Tutorial: Guessing Game
  4. 4. Syntax and Semantics
    1. 4.1. Variable Bindings
    2. 4.2. Functions
    3. 4.3. Primitive Types
    4. 4.4. Comments
    5. 4.5. if
    6. 4.6. Loops
    7. 4.7. Vectors
    8. 4.8. Ownership
    9. 4.9. References and Borrowing
    10. 4.10. Lifetimes
    11. 4.11. Mutability
    12. 4.12. Structs
    13. 4.13. Enums
    14. 4.14. Match
    15. 4.15. Patterns
    16. 4.16. Method Syntax
    17. 4.17. Strings
    18. 4.18. Generics
    19. 4.19. Traits
    20. 4.20. Drop
    21. 4.21. if let
    22. 4.22. Trait Objects
    23. 4.23. Closures
    24. 4.24. Universal Function Call Syntax
    25. 4.25. Crates and Modules
    26. 4.26. `const` and `static`
    27. 4.27. Attributes
    28. 4.28. `type` aliases
    29. 4.29. Casting between types
    30. 4.30. Associated Types
    31. 4.31. Unsized Types
    32. 4.32. Operators and Overloading
    33. 4.33. Deref coercions
    34. 4.34. Macros
    35. 4.35. Raw Pointers
    36. 4.36. `unsafe`
  5. 5. Effective Rust
    1. 5.1. The Stack and the Heap
    2. 5.2. Testing
    3. 5.3. Conditional Compilation
    4. 5.4. Documentation
    5. 5.5. Iterators
    6. 5.6. Concurrency
    7. 5.7. Error Handling
    8. 5.8. Choosing your Guarantees
    9. 5.9. FFI
    10. 5.10. Borrow and AsRef
    11. 5.11. Release Channels
    12. 5.12. Using Rust without the standard library
  6. 6. Nightly Rust
    1. 6.1. Compiler Plugins
    2. 6.2. Inline Assembly
    3. 6.3. No stdlib
    4. 6.4. Intrinsics
    5. 6.5. Lang items
    6. 6.6. Advanced linking
    7. 6.7. Benchmark Tests
    8. 6.8. Box Syntax and Patterns
    9. 6.9. Slice Patterns
    10. 6.10. Associated Constants
    11. 6.11. Custom Allocators
  7. 7. Glossary
  8. 8. Syntax Index
  9. 9. Bibliography

Mutability

Mutability, the ability to change something, works a bit differently in Rust than in other languages. The first aspect of mutability is its non-default status:

let x = 5;
x = 6; // error!Run

We can introduce mutability with the mut keyword:

let mut x = 5;

x = 6; // no problem!Run

This is a mutable variable binding. When a binding is mutable, it means you’re allowed to change what the binding points to. So in the above example, it’s not so much that the value at x is changing, but that the binding changed from one i32 to another.

You can also create a reference to it, using &x, but if you want to use the reference to change it, you will need a mutable reference:

let mut x = 5;
let y = &mut x;Run

y is an immutable binding to a mutable reference, which means that you can’t bind 'y' to something else (y = &mut z), but y can be used to bind x to something else (*y = 5). A subtle distinction.

Of course, if you need both:

let mut x = 5;
let mut y = &mut x;Run

Now y can be bound to another value, and the value it’s referencing can be changed.

It’s important to note that mut is part of a pattern, so you can do things like this:

let (mut x, y) = (5, 6);

fn foo(mut x: i32) {Run

Note that here, the x is mutable, but not the y.

Interior vs. Exterior Mutability

However, when we say something is ‘immutable’ in Rust, that doesn’t mean that it’s not able to be changed: we are referring to its ‘exterior mutability’ that in this case is immutable. Consider, for example, Arc<T>:

use std::sync::Arc;

let x = Arc::new(5);
let y = x.clone();Run

When we call clone(), the Arc<T> needs to update the reference count. Yet we’ve not used any muts here, x is an immutable binding, and we didn’t take &mut 5 or anything. So what gives?

To understand this, we have to go back to the core of Rust’s guiding philosophy, memory safety, and the mechanism by which Rust guarantees it, the ownership system, and more specifically, borrowing:

You may have one or the other of these two kinds of borrows, but not both at the same time:

  • one or more references (&T) to a resource,
  • exactly one mutable reference (&mut T).

So, that’s the real definition of ‘immutability’: is this safe to have two pointers to? In Arc<T>’s case, yes: the mutation is entirely contained inside the structure itself. It’s not user facing. For this reason, it hands out &T with clone(). If it handed out &mut Ts, though, that would be a problem.

Other types, like the ones in the std::cell module, have the opposite: interior mutability. For example:

use std::cell::RefCell;

let x = RefCell::new(42);

let y = x.borrow_mut();Run

RefCell hands out &mut references to what’s inside of it with the borrow_mut() method. Isn’t that dangerous? What if we do:

use std::cell::RefCell;

let x = RefCell::new(42);

let y = x.borrow_mut();
let z = x.borrow_mut();Run

This will in fact panic, at runtime. This is what RefCell does: it enforces Rust’s borrowing rules at runtime, and panic!s if they’re violated. This allows us to get around another aspect of Rust’s mutability rules. Let’s talk about it first.

Field-level mutability

Mutability is a property of either a borrow (&mut) or a binding (let mut). This means that, for example, you cannot have a struct with some fields mutable and some immutable:

struct Point {
    x: i32,
    mut y: i32, // nope
}Run

The mutability of a struct is in its binding:

struct Point {
    x: i32,
    y: i32,
}

let mut a = Point { x: 5, y: 6 };

a.x = 10;

let b = Point { x: 5, y: 6};

b.x = 10; // error: cannot assign to immutable field `b.x`Run

However, by using Cell<T>, you can emulate field-level mutability:

use std::cell::Cell;

struct Point {
    x: i32,
    y: Cell<i32>,
}

let point = Point { x: 5, y: Cell::new(6) };

point.y.set(7);

println!("y: {:?}", point.y);Run

This will print y: Cell { value: 7 }. We’ve successfully updated y.