2. Programming a Guessing Game

Learning objectives

By the end of this session you should be able to …

• build a simple command line guessing game, with user interaction
• write basic Rust syntax (variables, functions)
• use Rust’s standard library and external crates
• implement error handling in Rust using the Result type
• control program flow using conditionals (if, else) and loops (loop)

• You can add notes on each slide with blocks like this!

Guessing Game

Our goal is to implement a guessing game that:

• generates a (secret) random integer between 1 and 100
• prompts the player to guess the number
• indicates if the guess is too low or too high
• prints a congratulatory message and exit if the guess is correct

Setting Up the Project

Create the new Project

$ cargo new guessing_game
$ cd guessing_game

• recall, cargo is Rust’s package manager and build tool
• cargo new creates a new project with the given name
• by default, this creates a “Hello World” program

Compile and run it

$ cargo run

• cargo run both compiles and runs the project
• you should see “Hello, world!” output to your console
• you can also just compile with cargo build

Processing a Guess

We will process a guess by:

• prompting the user for input
• storing the input as a string

Storing Values with Variables

let mut guess = String::new();

• add this to the main function in src/main.rs
• use let to create variables
• variables are immutable by default
• use let mut for mutable variable

Receiving User Input

use std::io;
// ...
println!("Please input your guess.");
io::stdin().read_line(&mut guess);

• call stdin().read_line(&mut guess) to get user input
• input is appended to the empty guess string
• & indicates a reference to the variable
• &mut is necessary, because references are immutable by default

Handling Potential Failure with Result

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

• read_line returns a Result type (either Ok or Err)
• use .expect() to handle errors and crash if an error occurs

Printing Values with println!

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

• use println! with placeholders ({}) for formatted output
• combines user input and text in one statement

Testing the First Part

$ cargo run

• program now accepts input and prints the guess
• test by entering values to see the output

Code checkpoint 1

use std::io;

fn main() {
    let mut guess = String::new();
    println!("Please input your guess.");
    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

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

Generating a Secret Number

use rand::Rng;

• we will need to use the rand crate for random number generation
• use the use keyword to bring this crate into scope

Using a Crate to Get More Functionality

[dependencies]
rand = "0.8.5"

• add the rand crate to Cargo.toml under [dependencies]
• cargo build will fetch and compile external dependencies
• you can also use cargo add to add dependencies
  • e.g. cargo add rand

Generating a Random Number

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

• this code should now compile
• use rand::Rng; brings the random number generator trait (Rng) into scope
• use thread_rng() for random number generation

Comparing the Guess to the Secret Number

Matching the Guess to the Secret Number

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

• use cmp() from the standard library to compare guess with secret_number
• cmp() returns the Ordering enum, which has values (Less, Greater, or Equal)
• match will match the appropriate arm of the enum, and print “Too small”, “Too big”, or “You win!”

Parsing a String into a Number

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

• guess is a string, but we want to compare it to an integer
• use trim() to remove unexpected whitespace from the string
• use parse() to convert the string to an integer
• this code should now compile

Code Checkpoint 2

use rand::Rng;
use std::{cmp::Ordering, io};

fn main() {
    let secret_number = rand::thread_rng().gen_range(1..=100);
    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!"),
    }
}

Allowing Multiple Guesses with Looping

loop {
    // all guessing logic here
}

• add a loop to allow repeated guesses
• place the entire guessing logic inside the loop
• the program continues to ask for guesses until correct or manually exited

Quitting After a Correct Guess

Ordering::Equal => {
    println!("You win!");
    break;
}

• we can add additional logic to the Equal branch of the enum using {}
• add a break statement to exit the loop when the guess is correct
• break exits both the loop and the program

Handling Invalid Input

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

• currently, we crash on an error by using .expect()
• we could instead handle the error, by matching the Err enum
• replace .expect() with match to handle possibility of non-numeric input
• if parsing fails (Err), ignore the guess and continue looping

Final Code Checkpoint

use rand::Rng;
use std::{cmp::Ordering, io};

fn main() {
    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;
            }
        }
    }
}

Summary

Congrats, we have now successfully built a CLI game in Rust!

We now have a basic understanding of Rust syntax, error handling, and working with external libraries

Next, we’ll dive into deeper concepts like ownership, enums, and more!