Week 03 Laboratory Exercises

Objectives

Understand and practice Rust's borrowing rules
Practice use of basic and complex lifetimes
Understand the different types of smart pointers, their strengths and weaknesses

Activities To Be Completed

The following is a list of all the activities available to complete this week...

My first Borrow!
Pusheen
First Home Buyers
Pokedex and Lifetimes!
Build A (Christmas) Tree with Boxes

Preparation

Before the lab you should re-read the relevant lecture slides and their accompanying examples.

Getting Started

Create a new directory for this lab called lab03, change to this directory, and fetch the provided code for this week by running these commands:

mkdir lab03
cd lab03
6991 fetch lab 03

Or, if you're not working on CSE, you can download the provided code as a tar file.

Exercise:
My first Borrow!

Outcomes

Complete a basic immutable borrow
Understand the difference between moved and borrowed values
Exposure to common ownership compiler errors

In this exercise we will practice an extremely simple borrow!

You have been given a start code in the form of a crate my_first_borrow.

Your job is to make the program compile! There are two given TODOs in the code.

You should not need to modify the code in any other places than the TODOs.

When your code compiles, it should look like:

 6991 cargo run 
   Compiling my_first_borrow v0.1.0 (/home/cs6991/web/22T3/course/activities/my_first_borrow/solutions)
    Finished dev [unoptimized + debuginfo] target(s) in 0.35s
     Running `target/debug/my_first_borrow`
inside print_strings: hello, world!
I want to use these strings! hello, world!

Do not use the clone method.

You should only need to insert four characters to make the program compile.

This exercise is not about the idiomatic use of &str and String.

As such, you should not need to use the type &str in your solution.

When you think your program is working, you can use autotest to run some simple automated tests:

6991 autotest

When you are finished working on this exercise, you must submit your work by running give:

6991 give

You must run give before Week 4 Wednesday 21:00:00 to obtain the marks for this exercise. Note that this is an individual exercise; the work you submit with give must be entirely your own.

main.rs

fn main() {
    let s = String::from("hello, ");
    let t = String::from("world!");

    // currently, this function takes
    // OWNERSHIP of s and t
    // and so the compiler
    // complains: `use of moved value: s`
    // TODO: change the function call
    print_strings(&s, &t);

    // we try to use s and t here
    // but we can't because
    // they have been moved into the function
    // print_strings above
    println!("I want to use these strings! {}{}", s, t);
}

// TODO: change the function signature
fn print_strings(s: &String, t: &String) {
    println!("inside print_strings: {}{}", s, t);
}

Exercise:
Pusheen

Outcomes

Introduction to mutable references
Understanding of Rust's multiple mutable reference rules
Theory of ownership

In this exercise, you are given a basic crate pusheen which does not compile!

Your task consists of three steps:

Write a comment explaining why this program does not compile, and what potential problems Rust is trying to protect you from.
Fix the program so that it compiles.
Write a comment explaining how you enabled the program to compile.

The above will be manually marked, so please ensure that you have completed all three steps. There will be an opportunity to discuss this with a tutor and get marked during your week 4 workshop. If you cannot attend, your work will instead be manually marked (offline) during week 5.

You should only have to change a few lines of code! This exercise should not take long, if you get stuck - ask on the course forum! The documentation for the mutable references section in the Book may be useful.

When you are finished working on this exercise, you must submit your work by running give:

6991 give

You must run give before Week 4 Wednesday 21:00:00 to obtain the marks for this exercise. Note that this is an individual exercise; the work you submit with give must be entirely your own.

main.rs

fn main() {
    let mut vec = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10];

    let a = &mut vec;

    a.push(11);
    a.push(12);
}

Exercise:
First Home Buyers

Objectives

Practical usage of mutable references
Exposure to simple derive lab_macros
Exposure more usages of enums

In this exercise, you are given some starter code in the crate first_home_buyers .

The starter code defines the House struct, the Owner enum and the Person struct.

Your job finish the four TODO's, such that our program will compile and run successfully, and the output will match the expected output.

 6991 cargo run 
    Finished dev [unoptimized + debuginfo] target(s) in 0.36s
     Running `target/debug/first_home_buyers`
House1 is owned by: Individual(Person { name: "John", age: 34 })
House2 is owned by: Bank("Bank of Melbourne")
House3 is owned by: Bank("Bank of Melbourne")

Due to the problem setup, there will probably be warnings. You can ignore these!

When you think your program is working, you can use autotest to run some simple automated tests:

6991 autotest

When you are finished working on this exercise, you must submit your work by running give:

6991 give

You must run give before Week 4 Wednesday 21:00:00 to obtain the marks for this exercise. Note that this is an individual exercise; the work you submit with give must be entirely your own.

main.rs

#[derive(Debug)]
enum Owner {
    Individual(Person),
    Bank(String),
}

#[derive(Debug)]
struct Person {
    name: String,
    age: u8,
}

struct House {
    house_id: i32,
    address: String,
    price: i32,
    owner: Owner,
}

fn main() {
    let dan = Person {
        age: 18,
        name: "Dan".to_string(),
    };

    let mitch = Person {
        age: 21,
        name: "Mitch".to_string(),
    };

    let john = Person {
        age: 34,
        name: "John".to_string(),
    };

    let mut house1 = House {
        house_id: 1,
        address: "123 Main St".to_string(),
        price: 1000000,
        owner: Owner::Bank("Commonwealth Bank".to_string()),
    };

    let mut house2 = House {
        house_id: 2,
        address: "456 Main St".to_string(),
        price: 2000000,
        owner: Owner::Individual(mitch),
    };

    let house3 = House {
        house_id: 3,
        address: "789 Main St".to_string(),
        price: 3000000,
        owner: Owner::Bank("Bank of Melbourne".to_string()),
    };

    // exercise starts here

    // john wants to buy house1
    buy_house(&mut house1, Owner::Individual(john));

    // the bank of melbourne wants to buy house2
    buy_house(&mut house2, Owner::Bank("Bank of Melbourne".to_string()));

    // you can leave these here :)
    println!("House1 is owned by: {:?}", house1.owner);
    println!("House2 is owned by: {:?}", house2.owner);
    println!("House3 is owned by: {:?}", house3.owner);
}

// you should implement this :)
fn buy_house(house: &mut House, buyer: Owner) {
    house.owner = buyer;
}

Exercise:
Pokedex and Lifetimes!

Objectives

Exposure to a non-trivial lifetime problem
Understand the importance of why rust uses lifetimes to validate references

Reading and analysing given Rust code

"Living is using time given to you. You cannot recall lost time." an NPC from a Pokemon Game, probably explaning how awesome Rust is.

In this exercise, we have written some code to query the Pokedex -- a list of every Pokemon! (If you don't know what a pokedex is, think of it like an encyclopedia, but for fictional creatures from the Pokemon universe). Our code, however, does not compile. We have ignored the fact that our code tries to have multiple ownership in many places. So, we need your help to fix the lifetimes and borrowing in this code.

You will at least need to:

Replace uses of the Pokemon type with references.
Replace uses of the String type with references.

However you can expect that more changes to the code will be required.

You should not:

Construct any extra Strings.
Construct any extra Pokemon structs.
Edit the code marked with "DO NOT EDIT THIS CODE" -- if you want to, you have misunderstood the task.

You should also think about, from a compilers point of view, why are lifetimes needed here?

When your program is behaving correctly, the user should be able to type in multiple queries (each being a string representing part of a name in English, Chinese or Japanese), and the program should print out all pokemon which matched any query, and which queries they matched:

6991 cargo run
    Finished dev [unoptimized + debuginfo] target(s) in 0.00s
     Running `target/debug/pokedex`

wit
sha
フシギ
妙蛙
Clawitzer            : wit;
Oshawott             : sha;
Musharna             : sha;
Mienshao             : sha;
Bisharp              : sha;
Marshadow            : sha;
Bulbasaur            : フシギ; 妙蛙;
Ivysaur              : フシギ; 妙蛙;
Venusaur             : フシギ; 妙蛙;

When you think your program is working, you can use autotest to run some simple automated tests:

6991 autotest

When you are finished working on this exercise, you must submit your work by running give:

6991 give

You must run give before Week 4 Wednesday 21:00:00 to obtain the marks for this exercise. Note that this is an individual exercise; the work you submit with give must be entirely your own.

main.rs

use serde::Deserialize;
use std::{fs::File, io::BufReader};

////////////////////////////////////////////////////////////
// DO NOT EDIT THE BELOW CODE

#[derive(Debug, Deserialize, PartialEq, Eq)]
enum PokemonTypes {
    Bug, Dark, Dragon, Electric, Fairy, Fighting,
    Fire, Flying, Ghost, Grass, Ground, Ice,
    Normal, Poison, Psychic, Rock, Steel, Water
}

// DO NOT EDIT THIS CODE

#[derive(Debug, Deserialize, PartialEq, Eq)]
struct PokemonNames {
    english: String,
    japanese: String,
    chinese: String,
}

// DO NOT EDIT THIS CODE

#[derive(Debug, Deserialize, PartialEq, Eq)]
struct Pokemon {
    id: u32,
    #[serde(rename = "type")]
    types: Vec<PokemonTypes>,
    name: PokemonNames
}

// DO NOT EDIT THIS CODE

type Pokedex = Vec<Pokemon>;

// DO NOT EDIT THIS CODE

fn get_pokemon(path: &str) -> Pokedex {
    let file = File::open(path).unwrap();
    let reader = BufReader::new(file);

    serde_json::from_reader(reader).unwrap()
}

// DO NOT EDIT THIS CODE

fn get_pokedex_and_queries() -> (Pokedex, Vec<String>) {
    let all_pokemon = get_pokemon("pokedex.json");
    let queries: Vec<String> = std::io::stdin().lines().filter_map(|s| s.ok()).collect();

    (all_pokemon, queries)
}


/// DO NOT EDIT THE ABOVE CODE
////////////////////////////////////////////////////////////

// TODO: Below this point, you should never:
//  - Use the type "Pokemon", except as a reference.
//  - Construct or clone a "Pokemon"
//  - Use the type "String", use "str" instead.
//  - Construct or clone a String

#[derive(Debug, PartialEq, Eq)]
struct FoundPokemon<'query> {
    pokemon: &'query Pokemon,
    matching_queries: Vec<&'query str>
}


fn search_pokedex<'query>(query: &'query str, pokedex: &'query Pokedex, search_results: &mut Vec<FoundPokemon<'query>>) {
    for pokemon in pokedex {
        let contains_en = pokemon.name.english.contains(query);
        let contains_cn = pokemon.name.chinese.contains(query);
        let contains_jp = pokemon.name.japanese.contains(query);
        if contains_en || contains_cn || contains_jp {
            match search_results.iter_mut().find(|found_pokemon| found_pokemon.pokemon == pokemon) {
                Some(found_pokemon) => found_pokemon.matching_queries.push(query),
                None => search_results.push(FoundPokemon {pokemon, matching_queries: vec![query]})
            }
        }
    }
}

fn print_found_pokemon(found_pokemon: Vec<FoundPokemon>) {
    for pokemon in found_pokemon {
        let name = &pokemon.pokemon.name.english;
        print!("{name:20} : ");

        for query in pokemon.matching_queries {
            print!("{query}; ")
        }

        print!("\n");
    }
}

fn main() {
    let (pokedex, queries) =  get_pokedex_and_queries();

    let mut found_pokemon: Vec<FoundPokemon> = Vec::new();

    for query in queries.iter() {
        search_pokedex(&query, &pokedex, &mut found_pokemon);
    }

    search_pokedex("test", &pokedex, &mut found_pokemon);

    print_found_pokemon(found_pokemon);

}

two_lifetime.rs

use serde::Deserialize;
use std::{fs::File, io::BufReader};

////////////////////////////////////////////////////////////
// DO NOT EDIT THE BELOW CODE

#[derive(Debug, Deserialize, PartialEq, Eq)]
enum PokemonTypes {
    Bug, Dark, Dragon, Electric, Fairy, Fighting,
    Fire, Flying, Ghost, Grass, Ground, Ice,
    Normal, Poison, Psychic, Rock, Steel, Water
}

// DO NOT EDIT THIS CODE

#[derive(Debug, Deserialize, PartialEq, Eq)]
struct PokemonNames {
    english: String,
    japanese: String,
    chinese: String,
}

// DO NOT EDIT THIS CODE

#[derive(Debug, Deserialize, PartialEq, Eq)]
struct Pokemon {
    id: u32,
    #[serde(rename = "type")]
    types: Vec<PokemonTypes>,
    name: PokemonNames
}

// DO NOT EDIT THIS CODE

type Pokedex = Vec<Pokemon>;

// DO NOT EDIT THIS CODE

fn get_pokemon(path: &str) -> Pokedex {
    let file = File::open(path).unwrap();
    let reader = BufReader::new(file);

    serde_json::from_reader(reader).unwrap()
}

// DO NOT EDIT THIS CODE

fn get_pokedex_and_queries() -> (Pokedex, Vec<String>) {
    let all_pokemon = get_pokemon("pokedex.json");
    let queries: Vec<String> = std::io::stdin().lines().filter_map(|s| s.ok()).collect();

    (all_pokemon, queries)
}


/// DO NOT EDIT THE ABOVE CODE
////////////////////////////////////////////////////////////

// TODO: Below this point, you should never:
//  - Use the type "Pokemon", except as a reference.
//  - Construct or clone a "Pokemon"
//  - Use the type "String", use "str" instead.
//  - Construct or clone a String

#[derive(Debug, PartialEq, Eq)]
struct FoundPokemon<'query, 'poke> {
    pokemon: &'poke Pokemon,
    matching_queries: Vec<&'query str>
}


fn search_pokedex<'query, 'poke>(query: &'query str, pokedex: &'poke Pokedex, search_results: &mut Vec<FoundPokemon<'query, 'poke>>) {
    for pokemon in pokedex {
        let contains_en = pokemon.name.english.contains(query);
        let contains_cn = pokemon.name.chinese.contains(query);
        let contains_jp = pokemon.name.japanese.contains(query);
        if contains_en || contains_cn || contains_jp {
            match search_results.iter_mut().find(|found_pokemon| found_pokemon.pokemon == pokemon) {
                Some(found_pokemon) => found_pokemon.matching_queries.push(query),
                None => search_results.push(FoundPokemon {pokemon, matching_queries: vec![query]})
            }
        }
    }
}

fn print_found_pokemon(found_pokemon: Vec<FoundPokemon>) {
    for pokemon in found_pokemon {
        let name = &pokemon.pokemon.name.english;
        print!("{name:20} : ");

        for query in pokemon.matching_queries {
            print!("{query}; ")
        }

        print!("\n");
    }
}

fn main() {
    let (pokedex, queries) =  get_pokedex_and_queries();

    let mut found_pokemon: Vec<FoundPokemon> = Vec::new();

    for query in queries.iter() {
        search_pokedex(&query, &pokedex, &mut found_pokemon);
    }

    print_found_pokemon(found_pokemon);

}

Exercise:
Build A (Christmas) Tree with Boxes

Objectives

Usage of the Box smart pointer
Exposure to the ron crate
Problem solving with complex references

Tom is getting ready for Christmas! He is simulating a custom Christmas tree he is building. He needs your help to find the average brightness of his simulated Christmas tree.

The lights on this christmas tree form a binary tree; each light has up to two lights that it controls below it. We call those lights "left" and "right". Each light also has a brightness value, between 0 (off), and 100 (keep Zac and Shrey up at night). Tom is starting his tree with just one light, at brightness 0.

We can control the tree by sending it a vector of instructions. In this exercise, we have given you code to scan in this vector from a line of standard input, using rusty object notation There are only four instructions the tree supports:

Set(i32): Overwrite the current light to the given brightness.
Left: Move to the left from the current light. If it does not exist, install (i.e. create) a new light to the left with 0 brightness.
Right: Move to the right from the current light. If it does not exist, install (i.e. create) a new light to the right with 0 brightness.
Reset: Set the current node to the top-most node of the tree.

Our task is to simulate this unusual Christmas tree, and calculate it's final average brightness.

Here is an example, and a diagram to help explain. You are not required to produce the diagram, it's just to help understand.

 6991 cargo run 
    Finished dev [unoptimized + debuginfo] target(s) in 0.01s
     Running `target/debug/christmas_tree`
[Set(75), Left, Set(33), Reset, Right, Set(67), Left, Set(25)]
50

1. Initial State *0	2. Set(75) *75	3. Left 75 / *0	4. Set(33) 75 / *33	5. Reset *75 / 33
6. Right 75 / \ 33 *0	7. Set(67) 75 / \ 33 *67	8. Left 75 / \ 33 67 / *0	9. Set(25) 75 / \ 33 67 / *25	10. Calculation 33 + 75 + 67 + 25 / 4 = 50

 6991 cargo run 
    Finished dev [unoptimized + debuginfo] target(s) in 0.01s
     Running `target/debug/christmas_tree`
[Left, Set(100), Reset, Right, Set(100)]
66

 6991 cargo run 
    Finished dev [unoptimized + debuginfo] target(s) in 0.01s
     Running `target/debug/christmas_tree`
[Left, Left, Reset, Left, Right, Reset, Right, Left, Reset, Right, Right]
0

When you think your program is working, you can use autotest to run some simple automated tests:

6991 autotest

When you are finished working on this exercise, you must submit your work by running give:

6991 give

You must run give before Week 4 Wednesday 21:00:00 to obtain the marks for this exercise. Note that this is an individual exercise; the work you submit with give must be entirely your own.

main.rs

use serde::Deserialize;
use std::collections::VecDeque;
use std::io;

#[derive(Debug, Deserialize)]
enum Instruction {
    Set(i32),
    Left,
    Right,
    Reset,
}

#[derive(Debug, Default)]
struct Light {
    left: Option<Box<Light>>,
    right: Option<Box<Light>>,
    brightness: i32,
}

fn get_instructions_from_stdin() -> VecDeque<Instruction> {
    let mut instructions = String::new();
    io::stdin().read_line(&mut instructions).unwrap();
    ron::from_str(&instructions).unwrap()
}

fn tree_sum_and_count(light: &Light) -> (i32, i32) {
    let left = if let Some(left) = &light.left {
        tree_sum_and_count(left)
    } else {
        (0, 0)
    };
    let right = if let Some(right) = &light.right {
        tree_sum_and_count(right)
    } else {
        (0, 0)
    };
    (left.0 + right.0 + light.brightness, left.1 + right.1 + 1)
}

fn main() {
    let mut instructions = get_instructions_from_stdin();
    let mut light = Light {
        left: None,
        right: None,
        brightness: 0,
    };
    let mut current = &mut light;
    loop {
        match instructions.pop_front() {
            Some(Instruction::Set(x)) => current.brightness = x,
            Some(Instruction::Left) => current = current.left.get_or_insert_with(Default::default),
            Some(Instruction::Right) => {
                current = current.right.get_or_insert_with(Default::default)
            }
            Some(Instruction::Reset) => current = &mut light,
            None => break,
        }
    }

    let (sum, count) = tree_sum_and_count(&light);
    let avg = sum / count;
    println!("{avg}");
}

Submission

When you are finished each exercise make sure you submit your work by running give.

You can run give multiple times. Only your last submission will be marked.

Don't submit any exercises you haven't attempted.

If you are working at home, you may find it more convenient to upload your work via give's web interface.

Remember you have until Week 4 Wednesday 21:00:00 to submit your work.

You cannot obtain marks by e-mailing your code to tutors or lecturers.

Automarking will be run several days after the submission deadline, using test cases different to those autotest runs for you. (Hint: do your own testing as well as running autotest.)

After automarking is run you can view your results here.

Lab Marks

When all components of a lab are automarked you should be able to view the the marks via give's web interface or by running this command on a CSE machine:

6991 classrun -sturec