Introduction to Rust - Homework

• Objective
• Configuration of the workspace
• TASK A - Once upon a time, there was a star
  • The custom Star type
  • Star, what’s your name?
  • Giving is giving, taking back is stealing
  • To be mutable or not to be mutable
  • Structuring the project: modules and privacy
  • Unit testing
• TASK B - Asteroid field
  • Matching the resource interest
  • Do you also have a name?
• TASK C - The planets
  • Is there someone over there?
• TASK D (Optional) - Space: the final frontier
  • The SpaceMap type
  • The Default trait
  • Complete our space map
  • Time to create your space map

Objective

We would like to represent a space map in Rust.

A space map represents space bodies, linked with space routes:

A space body can be:

• a star ⭐
• an asteroid field 🪨
• or a planet 🪐

Each space body is identified with a name.

An asteroid field 🪨 has also a resource interest, which can be:

• high
• medium
• or low

A planet 🪐 can be habitable or not.

• If it is habitable, we have the number of inhabitants.
• If not, it can be because of:
  • the atmosphere
  • the climate
  • or the wild fauna

📂 /
└── 📂 submit
    └── 📂 rust
        └── 📂 userid
            ├── 📄 protocol.txt # your answers, or the protocol.md file
            └── 📂 intro-rs # your code

Configuration of the workspace

Go where you prefer to create the new project, then:

cargo new intro-rs
cd intro-rs

Build the default code:

cargo build
# or cargo b

(Before building the code, you can check it: cargo check or cargo c)

Run your code (it executes the main function in src/main.rs):

cargo run
# or cargo r

At the top of the src/main.rs file, configure the clippy linter by adding the inner attribute:

// Warn all clippy lints
#![warn(clippy::all)]

Test the clippy linter:

cargo clippy

Autoformat the code:

cargo fmt

TASK A - Once upon a time, there was a star

🎶 Shooting Stars, Marvellous (1994), Michel Petrucciani Trio

The custom Star type

The star is the first space body we will define.

Star, what’s your name?

Giving is giving, taking back is stealing

~ French proverb.

To be mutable or not to be mutable

Structuring the project: modules and privacy

We already know in advance our code will grow, so we would like to structure it using a module system. We don’t really want to keep everything in the src/main.rs file. Actually, we want to keep the minimum of things in that module.

We would like to avoid directly using the attribute name of Star, and keep it private. In fact, it is a good practice to separate the internal logic from the public interface (such that we reduce the chance of breaking changes if one day we change the internal implementation of name).

Now the name attribute is private, we cannot construct a Star directly, we must implement a public constructor.

Unit testing

We would like to test the methods Star::name and Star::set_name, and the associated function Star::new.

For tests, Rust provides a default test runner called cargo test, but instead we will use cargo nextest, because it provides a better user experience (see nextest website). It is already installed on our server, test it via cargo nextest --version.

#[cfg(test)]
mod tests {

}

We would like to reuse a Star instance in the future test functions. The default Rust testing framework is not well suited for what we call a fixture. We need to add a (developer) dependency: the crate rstest.

cargo add --dev rstest

cat Cargo.toml

[dev-dependencies]
rstest = "0.26.1" # or a more recent version

#[cfg(test)]
mod tests {
    use super::*;
    use rstest::fixture;

    #[fixture]
    fn sun() -> Star {
        // do something
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use rstest::fixture;
    use rstest::rstest;

    // Your fixture function before...

    #[rstest]
    fn new(sun: Star) { // sun is the name of the fixture function, rstest will handle that for you
        // do something
    }
}

Try to run the tests via cargo nextest run (or cargo nextest r).

TASK B - Asteroid field

🎶 The Asteroid Field, Star Wars The Empire Strikes Back (1980), John Williams and the London Symphony Orchestra

In the space, we don’t just have stars, but also asteroid fields. An asteroid field has also a name, and a resource interest, which can be high, medium or low.

cargo nextest run bodies::tests::asteroid_field
# or by matching:
cargo nextest run asteroid_field

Matching the resource interest

You are the scientist of your team, and help your space crew to decide whether to visit an asteroid field or not.

Do you also have a name?

As you may have noticed, the Star and AsteroidField structures are sharing behaviour: they have a name we can access with the name method.

If you go back to main.rs, you see that the function print_name takes as argument a Star. We would like it also accepts an AsteroidField.

TASK C - The planets

🎶 Monde constraté, Parallèles (2019), Chapelier Fou

Planets are the last space bodies we have to define. Each of them has also a name. They have a dedicated property: they can be habitable. If they are, we must provide the number of inhabitants. If not, we can provide the reason why they are not habitable: because of the atmosphere, the climate, or the wild fauna.

Is there someone over there?

Your colleague is required to fix the oxygen pump on the spaceship. He was coding a method Planet::set_number_of_inhabitants that sets the number of inhabitants of the planet, such that:

• if the planet is habitable, the method must return the previous number of inhabitants as a (positive) result;
• if the planet is not habitable, the method must return an error containing the value of UninhabitableCause.

Unfortunately, he did not succeed to build the code.

pub fn set_number_of_inhabitants(
        &mut self,
        new_inhabitants: u64,
    ) -> Result<u64, UninhabitableCause> {
        match &mut self.habitable {
            Habitability::Yes { inhabitants } => {
                let old = inhabitants;
                inhabitants = new_inhabitants;
                Ok(old)
            }
            Habitability::No { reason } => Err(reason),
        }
    }

To test your function, you can copy the test code below, and run cargo nextest run:

// In the `bodies::tests` module
mod planet {
    use super::*;
    // If you have used the `pretty_assertions` crate:
    // use pretty_assertions::assert_eq;
    use rstest::{fixture, rstest};

    #[fixture]
    fn earth() -> Planet {
        Planet {
            name: "Earth".to_string(),
            habitable: Habitability::Yes {
                inhabitants: 8_000_000_000,
            },
        }
    }

    #[rstest]
    fn set_number_of_inhabitants(mut earth: Planet) {
        assert_eq!(
            earth.set_number_of_inhabitants(9_000_000_000),
            Ok(8_000_000_000)
        );
        assert_eq!(
            earth.habitable,
            Habitability::Yes {
                inhabitants: 9_000_000_000
            }
        );
    }
}

TASK D (Optional) - Space: the final frontier

🎶 Façades, Glassworks, Philip Glass (1981)

Now we have our three space bodies: stars, asteroid fields and planets.

Your starship’s mission is to create routes between the space bodies.

The space bodies and the routes connecting them naturally define a graph (specifically an undirected graph).

Suppose you named the asteroid field AF. Your spaceship crew realized you can reach the sun from the Earth, and then use the sun energy to reach the asteroid field AF. The corresponding graph looks like this, where the space bodies are the vertices and the routes are the edges of the graph:

graph LR
    Earth --- Sun
    Sun --- AF

The SpaceMap type

There are many ways to implement a graph. We will use the adjacency list structure: for each space body (vertex) we associate the list of the other spaces bodies we can reach from it (neighbours).

In what follow, we will consider the space bodies to have distinct names. It follows that we will associate to each of the name a list of names.

The Default trait

As for the space bodies, we would like to implement a constructor for the SpaceMap type.

You have probably already noticed that, unlike space bodies, SpaceMap is a container, and that we would expect a new container to be empty. The SpaceMap is a composition of two other containers (neighbours and bodies are both maps), and a SpaceMap is new i.e. empty if and only if both neighbours and bodies are empty. A default container is an empty container. So a SpaceMap is a default one if and only if both neighbours and bodies are default.

The above statement implies a cascade structure: a cascade of “default” behaviours. In rust, the default behaviour is implemented via the Default trait.

To test the behaviour of the SpaceMap::new constructor, you can instantiate a new graph in your main function, and print the debug representation of the graph with println!("{:?}", graph). You thus must derive the Debug trait for the SpaceMap type.

You must see something like SpaceMap { neighbours: {}, bodies: {} } in the output.

Complete our space map

Time to create your space map