The guide will walk you through creating a simple but complete number guessing game in Rust. By the end, you'll have built an interactive console application that:

  • Generates a random number
  • Takes user input
  • Compares the guess to the secret number
  • Provides feedback
  • Allows multiple guesses until the correct answer is found

Along the way, you'll learn key Rust concepts that form the foundation of the language.

Prerequisites

  • Rust installed on your system (see our installation guide)
  • Basic familiarity with command-line interfaces
  • A text editor of your choice

Step 1: Set Up a New Rust Project

First, let's create a new Rust project using Cargo:

$ cargo new guessing_game
$ cd guessing_game

This creates a new directory called guessing_game with the following structure:

  • Cargo.toml: The project configuration file
  • src/main.rs: The source code file with a "Hello, world!" starter program

Let's take a quick look at the generated files:

Cargo.toml:

[package]
name = "guessing_game"
version = "0.1.0"
edition = "2021"

[dependencies]

src/main.rs:

fn main() {
    println!("Hello, world!");
}

You can already compile and run this program with:

$ cargo run

Step 2: Set Up the Basic Game Structure

Let's modify src/main.rs to create the initial structure of our game:

use std::io;

fn main() {
    println!("Guess the number!");
    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {}", guess);
}

Let's break down what's happening here:

Understanding Each Part

  1. use std::io;: This imports the input/output functionality from Rust's standard library.

  2. println!("Guess the number!");: The println! macro prints text to the screen.

  3. let mut guess = String::new();: This line creates a new variable called guess.

    • let declares a new variable
    • mut makes the variable mutable (able to change its value)
    • String::new() creates a new, empty string
    • Without mut, Rust variables are immutable by default!

  4. io::stdin().read_line(&mut guess): This reads a line of input from the user.

    • stdin() returns a handle to the standard input
    • read_line() reads user input into the string we provided
    • &mut guess passes a mutable reference to our guess variable
    • The & indicates this is a reference, allowing multiple parts of code to access the same data

  5. .expect("Failed to read line");: Handles potential errors from read_line().

    • read_line() returns a Result type, which can be either Ok or Err
    • expect() will crash the program with the given message if an error occurs
    • If successful, expect() returns the value inside Ok

  6. println!("You guessed: {}", guess);: Prints out what the user guessed.

    • The {} is a placeholder where the value of guess will be inserted

Test this code by running:

$ cargo run

Step 3: Generate a Random Number

To make our game functional, we need to generate a random number. Rust's standard library doesn't include random number functionality, so we'll use the rand crate (a Rust package).

First, update Cargo.toml to include the rand dependency:

[dependencies]
rand = "0.8.5"

Now, modify src/main.rs to use this crate:

use std::io;
use rand::Rng;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    println!("The secret number is: {}", secret_number); // We'll remove this later

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {}", guess);
}

Understanding the New Code

  1. use rand::Rng;: Imports the Rng trait, which defines methods that random number generators implement.

  2. let secret_number = rand::thread_rng().gen_range(1..=100);:

    • thread_rng() gives us the random number generator for the current thread
    • gen_range(1..=100) generates a random number in the range 1 to 100 (inclusive)
    • The 1..=100 syntax creates an inclusive range

When you run cargo build for the first time after adding a dependency, Cargo downloads all necessary crates from the registry (crates.io). This happens only once unless you update the dependency.

Step 4: Compare the Guess with the Secret Number

Now we need to compare the user's guess with our secret number. We'll need to:

  1. Convert the user's input (a string) to a number
  2. Compare the two numbers
  3. Tell the user if they're too high, too low, or correct

Update src/main.rs:

use std::io;
use std::cmp::Ordering;
use rand::Rng;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    println!("The secret number is: {}", secret_number);

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    let guess: u32 = guess.trim().parse().expect("Please type a number!");

    println!("You guessed: {}", guess);

    match guess.cmp(&secret_number) {
        Ordering::Less => println!("Too small!"),
        Ordering::Greater => println!("Too big!"),
        Ordering::Equal => println!("You win!"),
    }
}

Understanding the New Code

  1. use std::cmp::Ordering;: Imports the Ordering enum, which has variants Less, Greater, and Equal.

  2. let guess: u32 = guess.trim().parse().expect("Please type a number!");:

    • This creates a new variable called guess that shadows (reuses) the name of the previous guess variable
    • guess.trim() removes whitespace at the beginning and end, including the newline character
    • .parse() tries to convert the string to another type (in this case, a number)
    • let guess: u32 tells Rust that we want guess to be an unsigned 32-bit integer
    • expect() handles any errors from parsing

  3. match guess.cmp(&secret_number) { ... }:

    • guess.cmp(&secret_number) compares the two values and returns an Ordering
    • match works like a sophisticated switch statement that handles all possible cases
    • Each arm of the match has a pattern and code to run if the pattern matches

Step 5: Allow Multiple Guesses with Looping

Let's improve our game by allowing the player to guess until they get it right, using Rust's loop keyword:

use std::io;
use std::cmp::Ordering;
use rand::Rng;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    println!("The secret number is: {}", secret_number);

    loop {
        println!("Please input your guess.");

        let mut guess = String::new();

        io::stdin()
            .read_line(&mut guess)
            .expect("Failed to read line");

        let guess: u32 = guess.trim().parse().expect("Please type a number!");

        println!("You guessed: {}", guess);

        match guess.cmp(&secret_number) {
            Ordering::Less => println!("Too small!"),
            Ordering::Greater => println!("Too big!"),
            Ordering::Equal => {
                println!("You win!");
                break;
            }
        }
    }
}

Understanding the Loop

  1. loop { ... }: Creates an infinite loop that will keep asking for guesses.

  2. break;: Exits the loop when the user guesses correctly.

Step 6: Handle Invalid Input

Our game currently crashes if the user enters something that's not a number. Let's handle this gracefully:

use std::io;
use std::cmp::Ordering;
use rand::Rng;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    loop {
        println!("Please input your guess.");

        let mut guess = String::new();

        io::stdin()
            .read_line(&mut guess)
            .expect("Failed to read line");

        let guess: u32 = match guess.trim().parse() {
            Ok(num) => num,
            Err(_) => continue,
        };

        println!("You guessed: {}", guess);

        match guess.cmp(&secret_number) {
            Ordering::Less => println!("Too small!"),
            Ordering::Greater => println!("Too big!"),
            Ordering::Equal => {
                println!("You win!");
                break;
            }
        }
    }
}

Understanding Error Handling

  1. match guess.trim().parse() { ... }:

    • Instead of using expect(), we're now using match to handle the Result returned by parse()
    • If parsing succeeds, parse() returns Ok(num) where num is the parsed number
    • If parsing fails, parse() returns an Err value

  2. Ok(num) => num,: If parsing succeeded, extract and use the number.

  3. Err(_) => continue,: If parsing failed, ignore the error and start the next loop iteration.

    • The underscore _ is a catchall pattern that matches any error
    • continue skips the rest of the current loop iteration and starts the next one

Step 7: Final Polishing - Remove Debug Output

Now that our game is complete, let's remove the line that prints the secret number:

use std::io;
use std::cmp::Ordering;
use rand::Rng;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    loop {
        println!("Please input your guess.");

        let mut guess = String::new();

        io::stdin()
            .read_line(&mut guess)
            .expect("Failed to read line");

        let guess: u32 = match guess.trim().parse() {
            Ok(num) => num,
            Err(_) => continue,
        };

        println!("You guessed: {}", guess);

        match guess.cmp(&secret_number) {
            Ordering::Less => println!("Too small!"),
            Ordering::Greater => println!("Too big!"),
            Ordering::Equal => {
                println!("You win!");
                break;
            }
        }
    }
}

Key Rust Concepts You've Learned

  1. Variables and Mutability

    • Variables are immutable by default
    • Use mut to make variables mutable

  2. Data Types

    • Explicit type annotations (let guess: u32)
    • Type conversion (string to number)

  3. Functions and Macros

    • Function calls (e.g., trim(), parse())
    • Macros (e.g., println!)

  4. Control Flow

    • match expressions for pattern matching
    • loop for creating infinite loops
    • break to exit loops
    • continue to skip to the next iteration

  5. Error Handling

    • Result type with Ok and Err variants
    • Using expect() to handle errors simply
    • Pattern matching on Result for more nuanced error handling

  6. External Crates

    • Adding dependencies to Cargo.toml
    • Importing functionality with use

  7. Ownership and References

    • Using & to pass references
    • Mutable references (&mut)

Conclusion

Congratulations! You've built a complete Rust program from scratch. This guessing game demonstrates many of Rust's core concepts in a practical way. Here's what your program can now do:

  1. Generate a random number between 1 and 100
  2. Accept user input as a guess
  3. Compare the guess to the secret number
  4. Give feedback (too small, too big, or you win)
  5. Allow multiple guesses until the correct answer is found
  6. Handle invalid input gracefully

As you continue your Rust journey, you'll explore these concepts in more depth and learn about Rust's powerful features like ownership, traits, and concurrency.

Next Steps

To further enhance your game, consider these challenges:

  • Add a counter to track how many guesses the player needed
  • Add difficulty levels with different number ranges
  • Limit the number of guesses the player can make
  • Add a timer to measure how long it takes to guess correctly

Happy Rust coding.