Our previous post introduced Rust variables and data types. Now we need to touch upon the important topic of mutability, as it is central to how Rust provides memory safety.

Introduction

If you’re new to Rust and missed our post on setting up your Rust development environment and our post introducing Rust variables and data types, you can find them here:

Setting Up Your Rust Development Environment

Rust Variables and Data Types

After learning about variables and data types, the next step in your Rust mastery journey has to be a discussion of mutability.

One of the key features driving the popularity of Rust is memory safety, helping you avoid double-free, dangling pointers, and memory bugs. This is achieved via Rust’s ownership model.

Immutable by Default

As you start to play around with Rust, you’ll likely have these questions:

• why can’t I change this variable?
• why does the compiler say, “value moved”?
• why do some variables become unusable?

All values in Rust are immutable by default. That means by default you cannot change their values.

If you’ve used other programming languages, you’re probably used to being able to do just about whatever you want to values. Set the value of a variable, define another variable and set its value to another variable, these things are common actions in programming.

But in Rust, a central theme is safety and predictability.

Rust is designed to eliminate entire classes of bugs—like data races and unexpected mutations. By defaulting to immutability:

• you can’t accidentally change a value
• you don’t have to worry about someone else changing it
• multi-threaded code is safer, reducing race conditions

When you do need mutation, you have to explicitly opt in using the mut keyword, so your intent is clear to others, and to the compiler (and to yourself six months from now). This is great because your code becomes more self-documenting.

Rust draws from functional programming, where immutability is a common pattern.

Encouraging immutability leads to pure functions and easier-to-test code. It reduces side effects, making your codebase more robust.

By defaulting to immutability, Rust often catches bugs at compile time that would be hard-to-find runtime issues in other languages.

Once you start using Rust you may experience some frustration at times. But hang in there, because once you get used to it you’ll start to appreciate the value of default immutability and how to work with it effectively.

Immutability and Mutability in Action

Let’s get started writing some code. CD into the directory where you store Rust packages and execute this command:

cargo new mutability

Now CD into the mutability directory and open that directory in VS Code or your favorite IDE.

Note: using VS Code will make it easier to follow along with our posts. And installing the Rust Analyzer extension is also beneficial.

Also, opening the directory containing your Rust package allows the Rust Analyzer VS Code extension to work better. If you open a parent folder in VS Code the Rust Analyzer extension might not work at all. So open the mutability directory in VS Code.

Open the file src/main.rs and replace its contents entirely with this code:

fn main() {
    let x = 10;
    x = 20;
}

Pretty simple right? Something you may have done in other programming languages. But if you are using VS Code and you have the Rust Analyzer extension installed, you’ll see a squiggly red line indicating an error. You can hover over it to see the error:

You can also see this error if you build the package:

cargo build

cargo build will build the package but not run it. You could also execute cargo run and still see this error, because before running your package cargo builds it.

cargo is a tool that was installed with Rust. It is the package manager and build system for Rust. It creates new packages, build and runs them, manages dependencies, runs tests, builds documentation, and more.

The error message says we cannot mutate variable x because it is immutable. You might be thinking, come on, this is just about the simplest code you would see.

Trust me, most Rust packages are complex, and that’s where default immutability shines.

The error message also gives you a hint on how to fix this error, add the mut keyword. Let’s do that now and run the package with cargo run.

fn main() {
    let mut x = 10;
    x = 20;
}

You’ll get warnings that x is assigned to but never read but you get no errors. Notice that to make variable x mutable we add the keyword mut before the variable identifier.

Now I’ll show you another aspect of Rust that might surprise you. Go ahead and replace the code in main.rs with the following:

fn main() {
    let x = 10;
    let x = 20;
}

Once again you might be thinking, what’s going on here, I can’t do this in other languages I’ve used.

This is known as shadowing. The Rust compiler doesn’t complain that you are changing the value of variable x because to the compiler, the first definition of variable x, setting its value to 10, is gone, and there is a new definition, setting the new variable x to 20.

This shadowing in Rust is controversial and could be dangerous, but let’s understand the pros and cons.

Why It Can Be Dangerous

1. Accidental Shadowing
   Unintentionally reusing a variable name, assuming the original is being modified, when in fact a new variable is being created.
2. Reduced Readability
   Especially in larger scopes, shadowing can make code harder to trace, especially when variables are reassigned multiple times with different types or purposes.
3. Confusion in Debugging
   Debugging tools might not clearly show which version of a variable is currently active, which can lead to hard-to-find bugs.

Why Rust Allows It (and Encourages It). Rust views shadowing as a feature that promotes:

• Immutability by Default with Controlled Reassignment
  You can “reassign” to the same name without making the variable mutable.
• Type Change with Same Identifier
  You can reuse the name when changing the type—this isn’t allowed with mut, but is allowed with shadowing.

mut for Mutability

Believe it or not, you’ve just learned one of the most important concepts in Rust. As you write Rust code, you need to be thinking about whether or not your code needs to change data values.

At first, this concept of mut, mutability, and default immutability will seem like one huge hassle, but don’t give up on Rust yet.

This is one reason why Rust has been rapidly gaining in popularity. The Rust compiler exercises very tight control over ownership of data values in your code. And this is what enables Rust to avoid many of the terrible problems you face when you program in a language like C++ and C.

Don’t get me wrong, C++ and C are great, they’re still used extensively as they have been for decades. But Rust is ushering in a sea change in systems programming.

• Rust is being integrated into the Linux kernel
• Google is starting to use Rust in Android
• Microsoft initiatives rewriting core Windows libraries in Rust

Back to mutability. Here’s another example of using the mut keyword to make a variable mutable:

fn main() {
    let mut name = String::from("Greg");
    println!("Original name: {}", name);

    name.push_str(" the Rustacean");
    println!("Updated name: {}", name);
}

We haven’t covered String and println!() yet, but as you might guess, a String is a bunch of characters together, like the above messages. The println!() macro is the primary way you output to stdout, the terminal in this case.

We’ll use println!() alot, and String as well. And we’ll talk about String and string slices &str in depth in other posts. And we’ll talk about macros like println!() in Rust in depth later as well.

Replace the code in main.rs with the above code and run the program with cargo run. You should see two lines output to the terminal window:

Original name: Greg
Updated name: Greg the Rustacean

People who use Rust are known as Rustaceans, which comes from crustaceans, which points to the Rust unofficial mascot, Ferris:

In our code we have a mutable name defined to be a String created from a string literal “Greg”.

In this example we’re not reassigning a new value to name, we’re calling one of the String methods, push_str() to add to the end of the String. This is still considered mutation, so we have the mut keyword.

A Side Note on Code Comments

I’ve been asking you to replace our current code with new code, but if you’re like me, you sometimes want to keep code around for future examination.

So rather than replacing the current code you can comment it out. We won’t discuss comments for official code documentation here, but to comment out code you have two choices, and they are identical to many other languages.

Single Line Comments

// let mut x = 10;
// x = 20; 

Each line of code to be commented out has two forward slashes at the start of the line. Note you can also use this to add comments describing your code, either before the code or after it on the same line:

// initialize x to 10, then change it to 20
let mut x = 10;
x = 20;     // this lines changes x to 20

Multi-Line Comments

/* Commenting out this code until later */
/*
let mut x = 10;
x = 20; 
*/

Multi-line comments start with a forward slash, then one or more asterisks ( * ) then the code to be commented, and then one or more asterisks followed by a forward slash to end the multi-line comment.

The compiler ignores comments. The comments above are silly and don’t contribute anything meaningful or useful. Often your variable names will make the intent of code clear, but when comments are necessary, make sure they are concise and add some value.

Copying, Moving, and Borrowing

We know all values in Rust are immutable by default. Now we need to consider the Rust concepts of copying, moving, and borrowing.

In the code below we have defined a function, print_value(), that takes an i32 as a parameter, and simply prints out that value. In main() we define two variables named a and b. We initialize a to a value of 5 and then assign a to b, so both a and b both have the value 5. We call our function, passing in variable a.

fn print_value(x: i32) {
    println!("{}", x);
}

fn main() {
    let a = 5;
    let b = a; // `a` is copied into `b`, not moved
    print_value(a); // works fine
}

A function is some code that executes when we call the function. The main() function is called automatically when you execute cargo run because it is the entry point to your Rust package.

We’ll cover functions in depth soon in an upcoming post, but for now, just know that we have defined a function that prints a value passed to the function, and we call that function from main().

Copy the code to the Rust package and execute cargo run. You should see the value 5 printed to the terminal window.

The code compiles and runs with no errors. Now let’s look at another example. Comment out all the code in main.rs and below it add this code. It also compiles and runs fine if you execute cargo run.

fn take_string(s: String) {
    println!("{}", s);
}

fn main() {
    let a = String::from("hello");
    let b = a;        // move occurs here
    // println!("{}", a); // ❌ error: a is moved
    take_string(b);   // b is moved into function
}

Now uncomment the line that is currently commented:

println!("{}", a);

Run the code again and you should see an error. You can see the error in VS Code on hover or in the terminal.

The error is “borrow of moved value: ‘a’”

Let’s look at the code and see what’s going on.

fn take_string(s: String) {
    println!("{}", s);
}

fn main() {
    let a = String::from("hello");
    let b = a;        // move occurs here
    println!("{}", a); // ❌ error: a is moved
    take_string(b);   // b is moved into function
}

We’ve defined a function take_string() that takes a single String parameter, which we name s, and we print the value of s in the function.

In main() we define a String variable named a whose value is a String with the text hello. Then we define a new variable named b and assign the String value in a to it.

The next line is the cause of the error:

println!("{}", a);

This errors because of the way Rust manages ownership of values. Rust has three rules of ownership:

• each value in Rust has a variable that’s called its owner
• there can be only one owner at a time
• when the owner goes out of scope, the value is dropped

In our code, before the line causing the error, variable a owns the value, the String with the text hello.

When we assign the String value in a to the new variable b, ownership of the String value is moved to variable b.

When ownership of a value is moved, the previous owner is no longer valid and cannot be used.

This is incredibly important and is a great source of confusion for those new to Rust. Modify the code to add a println!() after the function call:

fn take_string(s: String) {
    println!("{}", s);
}

fn main() {
    let a = String::from("hello");
    let b = a;        // move occurs here
    println!("{}", a); // ❌ error: a is moved
    take_string(b); 
    println!("{}", b);  // ❌ error: b is moved into function
}

Now we have another error. It’s the same error as we got for variable a, but now we also get the error for variable b when we try to print it after calling function take_string(b).

Just like ownership of the String value in variable a was moved to variable b when we assigned a to b, when we pass b into the function ownership is also moved, making variable b unusable.

For most people new to Rust this is another frustrating moment. It sure was the first time I saw it. Why on earth is Rust doing it?

Remember, one of the brilliantly great qualities of Rust is the compiler’s strict control over data values. The compiler wants to be absolutely certain that values will not become invalid as the package runs.

When we assign the String value a to variable b, we’re not assigning a simple number like 25, or a boolean like true, we’re really assigning a reference to the String hello.

We won’t go in-depth into reference in this post, but just know that a reference is a number that represents the address of where the String hello is stored in memory.

Why is this necessary? Well, with Rust primitive data types like integers, floating point numbers, bools and chars, and some tuples and some arrays, they implement what is known as the Copy trait. We’ll cover traits in a future post, but data types that implement the Copy trait copy their data, they don’t move their data.

The String type does not implement the Copy trait, so for operations like reassignment and function calls, the String reference is moved not copied.

Okay, why does this matter? It matters because when a data type uses references, an address pointing to the data in memory, if we allowed two variables to have the same reference address, and one of the variables was used to change the data, then the other variable pointing to the data might think the data has not changed.

This is why the Rust compiler enforces the one owner rule for data values. It helps avoid situations where data can change unexpectedly.

And this is why this code we saw earlier in the post did not result in an error:

fn print_value(x: i32) {
    println!("{}", x);
}

fn main() {
    let a = 5;
    let b = a; // `a` is copied into `b`, not moved
    print_value(a); // works fine
}

Because variables a and b are both i32 integers (via compiler type inference, because we have not explicitly specified types), and because the integer primitive types implement the Copy trait, when we assign the value of variable a to variable b, it is copied, not moved.

We haven’t covered borrowing in this post, and that is another important topic in Rust. But you’re just getting started, and this post is already pretty long, so we’ll deal with borrowing in the future.

Congratulations, you’ve now been exposed to the tricky concepts of mutation, copying, moving, and data values becoming unusable in Rust. If your head is spinning, have no fear. I’ve been there. It took a while for these topics to solidify in my gray matter.

Thanks so much for stopping by, and come back soon as you move forward toward mastering Rust programming.