Cloning Owned Data with `clone()`

1. What Does It Mean to "Clone" Data?

In Rust, when we talk about owned types that manage data on the heap, like the String type we've been using, the variable itself lives on the stack and holds a pointer to the actual data on the heap.

When you move a String, you are just copying the stack data (the pointer, length, and capacity) to a new variable. The heap data itself is not touched; ownership is simply transferred.

Cloning is different. Calling .clone() on a String tells Rust to allocate new memory on the heap and copy the data from the original location to the new one. The result is two completely independent String instances.

The following video provides a clear demonstration of this difference.

As the video showed, the syntax is straightforward:

fn main() {
    let s1 = String::from("hello");
    
    // .clone() creates a new String on the heap with the same content.
    let s2 = s1.clone(); 

    // Now both s1 and s2 are valid and own their own data.
    println!("s1 = {}, s2 = {}", s1, s2);
}

This is powerful, but the video also gives an important warning: cloning can be an expensive operation, especially if the data on the heap is large. This is why Rust makes cloning an explicit action; you should think about whether you really need it.

2. Clone vs. Copy: Why Integers are Different

You might be wondering: "If moving is the default, why could I assign integers to new variables without the original becoming invalid?"

let x = 5;
let y = x; // This works fine!
println!("x = {}, y = {}", x, y); // We can still use x.

The reason is that simple types like integers (i32), booleans (bool), and characters (char) don't have data on the heap. Their values are stored entirely on the stack. Copying them is trivial and cheap.

Rust has a special trait called Copy. If a type implements the Copy trait, assignments don't move the value; they create a bit-for-bit copy. All primitive scalar types implement Copy.

String, on the other hand, does not implement Copy because it manages heap memory. A cheap bit-for-bit copy would mean two String variables pointing to the same heap data, which would lead to memory safety problems (the "double free" error we discussed earlier).

So, the rule is:

• Types that are Copy are implicitly copied on assignment.
• Types that are not Copy (but are Clone) must be explicitly duplicated with the .clone() method.

Let's return to the video to see this distinction explained.

3. Making Your Own Types Clonable

This is all great for built-in types, but what about the structs we'll be creating for our chess game, like Piece or BoardPosition? By default, your own structs have move semantics, just like String.

If you want to be able to clone your struct, you need to explicitly tell Rust how to do it. Thankfully, this is usually very easy using the derive attribute.

As the article explains, adding #[derive(Clone)] tells the compiler to generate the code for the clone() method automatically. It will do this by cloning each field of the struct individually. A struct can only derive Clone if all of its fields are also Clone.

4. Hands-On Activity: Log a Player

Let's put this into practice with a scenario you might encounter. Imagine you have a function that logs player information to a database or a file. This function needs to take ownership of the player data, but you still want to use the player variable in your main game loop.

1. Open your rust_chess project in src/main.rs.

2. Use the ChessPlayer struct from our last lesson. If you removed it, here it is again. Notice we've added #[derive(Clone)] to it.

   
   
   
   #[derive(Clone)] // This allows us to call .clone() on ChessPlayer
   struct ChessPlayer {
       username: String,
       elo: u32,
   }
   

3. Create a "consuming" function. This function simulates a process that needs to take full ownership of the data.

   // This function takes ownership of the player data
   fn log_player_session(player: ChessPlayer) {
       println!("[LOG] Player '{}' session started.", player.username);
       // The `player` value is dropped here at the end of the function.
   }
   

4. Now, in your main function, try to log the player and then use the player variable again.

   fn main() {
       let player1 = ChessPlayer {
           username: String::from("Hikaru"),
           elo: 2785,
       };
   
       // Try to log the player
       log_player_session(player1);
   
       // What happens when you try to use player1 again?
       println!("Welcome back, {}!", player1.username); // <-- This will cause an error!
   }
   

5. Run cargo run. You will see the familiar value borrowed here after move error. The log_player_session function consumed player1.

6. Fix it with clone()! As the error message suggests, the solution is to pass a clone to the logging function. Modify the function call in main:

   fn main() {
       let player1 = ChessPlayer {
           username: String::from("Hikaru"),
           elo: 2785,
       };
   
       // Pass a CLONE of player1 to the function.
       // The original player1 remains owned by the main function.
       log_player_session(player1.clone());
   
       // Now this works perfectly!
       println!("Welcome back, {}!", player1.username);
   }
   

7. Run cargo run again. Everything now compiles and runs as expected. You successfully gave owned data to another function while retaining your own copy.

A Look Ahead at Our Chess Game

This concept is directly applicable to our chess project. Imagine you're writing the logic to check for valid moves. You might want to:

1. Take the current board state.
2. Create a temporary clone of the board.
3. Apply a hypothetical move to the cloned board.
4. Check if that move puts your own king in check.
5. Discard the cloned board.

Without clone(), you'd have to make the move on your main board and then undo it if it was illegal, which is much more complex. Cloning allows you to explore possibilities in a safe, isolated way.

You'll also see clone() used frequently in graphics programming, as shown in the "Chess game in Rust using Bevy" tutorial you have. Often, you're not cloning huge amounts of data, but rather lightweight "handles" (smart pointers) to graphical assets like models or materials. This is a cheap operation that allows multiple objects to share the same underlying asset.

Conclusion

You've now completed the trifecta of Rust's ownership system: moving, borrowing, and cloning.

Key Takeaways:

• clone() creates a deep copy of data, including any data on the heap.
• It's an explicit method you must call; it's not automatic for types like String.
• Use clone() when you need a separate, owned copy of data and borrowing isn't sufficient.
• Be mindful that clone() can be expensive for large data structures. Prefer borrowing (&, &mut) when possible.
• You can make your own structs clonable by adding the #[derive(Clone)] attribute, as long as all their fields are also Clone.

This concludes our first module on Rust's fundamentals and its powerful ownership system. You've built a solid foundation.

In the next module, Core Data Types and Control Flow, we will start modeling our chess game in earnest. We'll begin by defining structs and enums to represent all the core concepts of chess: the pieces, their colors, and the board squares.