Week 02 Laboratory Exercises

Objectives

To practice using Rust's basic collection tyoes
Exposure to simple derive macros
Understand and use Rust's error handling philosopy, and the try trait

Activities To Be Completed

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

Tribonacci
My Caesar
To Upper (Investigating strings!)
Collections
Data analysis

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 lab02, change to this directory, and fetch the provided code for this week by running these commands:

mkdir lab02
cd lab02
6991 fetch lab 02

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

Exercise:
Tribonacci

In this task, you will write a function that computes a variable number of Tribonacci numbers , and also their sum.

Your program should read a single integer, n, from the command-line arguments, and subsequently compute the first n Tribonacci numbers, along with their sum.

If no command-line arguments are given, you should assume the value of n to be 10.

Invalid input should be handled by returning a custom error message "Please enter a valid size!" through the struct TribonacciError, and then subsequently exiting the program.

Your program need only be able to calculate from n = 3 to n = 145 inclusive. Note that n = 145 produces very large numbers that increase far past the width of a i64 type. You may want to (strongly) consider using one of i128 or u128 instead, both of which can fit the largest number in that sequence.

6991 cargo run -- 4
    Finished dev [unoptimized + debuginfo] target(s) in 0.00s
     Running `target/debug/tribonacci 4`
Values: [1, 1, 1, 3]

Sum: 6
6991 cargo run -- 10
    Finished dev [unoptimized + debuginfo] target(s) in 0.00s
     Running `target/debug/tribonacci 10`
Values: [1, 1, 1, 3, 5, 9, 17, 31, 57, 105]

Sum: 230
6991 cargo run -- -1
    Finished dev [unoptimized + debuginfo] target(s) in 0.00s
     Running `target/debug/tribonacci -1`
Error: Please enter a valid size

You can approach this by storing all intermediate values into a vector, where all values should be of type i128 or u128. The vector's initial values should be [1, 1, 1].

You may find the below documentation, especially the examples, particularly helpful:

The documentation for the args function may be useful.

The documentation for the vec type may be useful.

The documentation for the result type may be useful.

The documentation for the parse method may be useful.

The documentation for the map method may be useful.

The documentation for the map_err method may be useful.

The documentation for the sum method may be useful.

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 3 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 std::env;
use std::num::ParseIntError;

#[derive(Debug)]
struct TribonacciError(String);

fn main() {
    let args: Vec<String> = env::args().collect();
    let error_message = String::from("Please enter a valid size");
    
    let n = match args.get(1) {
        Some(s) => s.parse::<usize>(),
        None => Ok(10),
    };

    if let Err(e) = compute_tribonacci(n, error_message) {
        println!("Error: {}", e.0)
    }
}

/// Computes the tribonacci sequence of a given size
/// Prints the sequence, and its sum
fn compute_tribonacci(size: Result<usize, ParseIntError>, error_msg: String) -> Result<(), TribonacciError> {
    let mut tribonacci = vec![1_u128; 3];
    let size = size.map_err(|_| TribonacciError(error_msg))?;

    for i in 3..size {
        tribonacci.push(tribonacci[i - 1] + tribonacci[i - 2] + tribonacci[i - 3]);
    }

    println!("Values: {:?}", tribonacci);
    
    let value: u128 = tribonacci.into_iter().sum();
    println!("\nSum: {}", value);
    
    Ok(())
}

Exercise:
My Caesar

In this activity, your task is to write a program that encrypts a message using a Caesar cipher.

The program should read in a single command-line argument, which is the number of positions to shift each letter (i32). If there is no command-line argument, or if the argument is not a number, the program should use a default shift of 5.

The program should then iterate over each line of standard input, shifting each letter by the specified number of positions. The shifted line should then be printed to standard output.

However, only letters of the alphabet (i.e. 'A'..='Z', 'a'..='z') should be shifted. All other characters should be printed as-is.

Shifted letters should wrap around the alphabet, so that 'A' shifted by 1 becomes 'B', 'Z' shifted by 1 becomes 'A', 'y' shifted by 3 becomes 'b'.

If the provided shift is negative, you should treat the shift as operating in the opposite direction.

For example, 'A' shifted by -1 becomes 'Z', 'Z' shifted by -1 becomes 'Y', 'b' shifted by -3 becomes 'X'.

A shift of 0 should not modify the input text at all.

For example:

6991 cargo run 
    Finished dev [unoptimized + debuginfo] target(s) in 0.00s
     Running `target/debug/my_caesar`
hello!
Shifted ascii by 5 is: mjqqt!
Dr. Taylor Swift is the worlds greatest musician! 
Shifted ascii by 5 is: Iw. Yfdqtw Xbnky nx ymj btwqix lwjfyjxy rzxnhnfs!

6991 cargo run -- 10 
    Finished dev [unoptimized + debuginfo] target(s) in 0.00s
     Running `target/debug/my_caesar`
And I know it's long gone and 👋 That magic's not here no more 😭🫀🇧🇷🇪🇦🇰
Shifted ascii by 10 is: Kxn S uxyg sd'c vyxq qyxo kxn 👋 Drkd wkqsm'c xyd robo xy wybo 😭🫀🇧🇷🇪🇦🇰
T_T crying
Shifted ascii by 10 is: D_D mbisxq

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 3 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 std::io;

const DEFAULT_SHIFT: i32 = 5;
const UPPERCASE_A: i32 = 65;
const LOWERCASE_A: i32 = 97;
const ALPHABET_SIZE: i32 = 26;

fn main() {
    let shift_by: i32 = std::env::args()
        .collect::<Vec<String>>()
        .get(1)
        .unwrap_or(&DEFAULT_SHIFT.to_string())
        .parse::<i32>()
        .unwrap_or(DEFAULT_SHIFT);

    let stdin = io::stdin();

    stdin.lines().for_each(|line| {
        println!(
            "Shifted ascii by {shift_by} is: {}",
            shift(shift_by, line.expect("no input line"))
        );
    });
}

fn shift(shift_by: i32, line: String) -> String {
    let mut result: Vec<char> = Vec::new();

    // turn shift_by into a positive number between 0 and 25
    let shift_by = shift_by % ALPHABET_SIZE + ALPHABET_SIZE;

    line.chars().for_each(|c| {
        let ascii = c as i32;

        if ('A'..='Z').contains(&c) {
            result.push(to_ascii(
                abs_modulo((ascii - UPPERCASE_A) + shift_by, ALPHABET_SIZE) + UPPERCASE_A,
            ));
        } else if ('a'..='z').contains(&c) {
            result.push(to_ascii(
                abs_modulo((ascii - LOWERCASE_A) + shift_by, ALPHABET_SIZE) + LOWERCASE_A,
            ));
        } else {
            result.push(c)
        }
    });

    result.iter().collect()
}

fn abs_modulo(a: i32, b: i32) -> i32 {
    (a % b).abs()
}

fn to_ascii(i: i32) -> char {
    char::from_u32(i as u32).unwrap()
}

Exercise:
To Upper (Investigating strings!)

This activity is an investigation of Rust's strings!

You have been provided a simple crate, to_upper, which does not compile! Your task is to modify to_upper/src/main.rs so that it takes in a single command-line argument and converts the appropriate characters to uppercase. It may help to RTFC!

6991 cargo run -- "hello world!!!"
    Finished dev [unoptimized + debuginfo] target(s) in 0.00s
     Running `target/debug/to_upper 'hello world'\!''\!''\!''`
arg = "hello world!!!"
upp = "HELLO WORLD!!!"
6991 cargo run -- "uwu🥺👉👈"
    Finished dev [unoptimized + debuginfo] target(s) in 0.00s
     Running `target/debug/to_upper 'uwu🥺👉👈'`
arg = "uwu🥺👉👈"
upp = "UWU🥺👉👈"

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 3 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() {
    // try and get the first argument
    // using some iterator methods
    let arg = std::env::args().nth(1).unwrap();

    // the compiler suggests to "borrow here"
    // but we haven't learnt how to borrow :(
    // we have a String type, and want to get a &str
    // Try find a function that can help us using
    // the docs https://doc.rust-lang.org/stable/std/string/struct.String.html
    let upp = uppercase(arg.as_str());

    println!("arg = {}", arg);
    println!("upp = {}", upp);
}

fn uppercase(src: &str) -> String {
    let mut destination = String::new();

    for c in src.chars() {
        // this doesn't work either!!
        // what type does to_uppercase return?
        // what type does push expect?
        for c in c.to_uppercase() {
            destination.push(c);
        }
    }

    destination
}

Exercise:
Collections

Rust's collection types could be generally categorised into four groups:

Sequences
- Vec
- VecDeque
- LinkedList
Maps
- HashMap
- BTreeMap
Sets
- HashSet
- BTreeSet
Misc.
- BinaryHeap

In this activity, we'll be exploring the performance of first three (Vec, VecDeque, and LinkedList), and HashMap collections.

For each of the four collections above, your code should:

Create a new instance of the collection.
Add some MAX_ITER elements to it.
Remove MAX_ITER elements from it.
Time each of the above operations.

For LinkedList insertion, you should insert at the end of the list. You should remove from the start of the list.

For HashMap you only need to insert at key i where i is the current iteration. Similarly, you should remove from key i.

Before you start, please write down some of your expectations about what you think will be the most performant collection for these operations.

The analysis of Vec and VecDeque has already been completed for you in the provided code.

This exercise also contains a theory section. At the end of your main function, you should write a comment that answers the following questions:

Which collection type was the fastest for adding and removing elements?
- Why do you think this was the case?
Is there any significant difference between Vec and VecDeque deletion?
- If so, why? If not, why not?
When would you consider using VecDeque over Vec?
When would you consider using LinkedList over Vec?
Did the results suprise you? Why or why not?.

The above will be manually marked. 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.

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

6991 give

You must run give before Week 3 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 std::collections::{HashMap, LinkedList, VecDeque};

const MAX_ITER: i32 = 300000;

fn main() {
    // Vectors
    vec_operations();

    // VecDeque
    vec_deque_operations();

    // LinkedList
    linked_list_operations();

    // HashMap
    hashmap_operations();

    // TODO: your text answers to the questions in the spec
}

/// measure the insertion and removal
/// operations of a vector
fn vec_operations() {
    let mut vec = Vec::new();

    let time_start = std::time::Instant::now();
    for i in 0..MAX_ITER {
        vec.push(i);
    }
    let time_end = std::time::Instant::now();

    println!("==== Vector ====");
    println!("insert: {:?}", time_end - time_start);

    let time_start = std::time::Instant::now();
    for _ in 0..MAX_ITER {
        vec.remove(0);
    }
    let time_end = std::time::Instant::now();

    println!("remove: {:?}", time_end - time_start);
}

/// measure the insertion and removal
/// operations of a VecDeque
fn vec_deque_operations() {
    let mut vec_deque = VecDeque::new();

    let time_start = std::time::Instant::now();
    for i in 0..MAX_ITER {
        vec_deque.push_back(i);
    }
    let time_end = std::time::Instant::now();

    println!("==== VecDeque ====");
    println!("insert: {:?}", time_end - time_start);

    let time_start = std::time::Instant::now();
    for _ in 0..MAX_ITER {
        vec_deque.pop_front();
    }
    let time_end = std::time::Instant::now();

    println!("remove: {:?}", time_end - time_start);
}

// measure the insertion and removal
// operations for a linked list
fn linked_list_operations() {
    let mut linked_list = LinkedList::new();

    let time_start = std::time::Instant::now();
    for i in 0..MAX_ITER {
        linked_list.push_back(i);
    }
    let time_end = std::time::Instant::now();

    println!("==== LinkedList ====");
    println!("insert: {:?}", time_end - time_start);

    let time_start = std::time::Instant::now();
    for _ in 0..MAX_ITER {
        linked_list.pop_front();
    }
    let time_end = std::time::Instant::now();

    println!("remove: {:?}", time_end - time_start);
}

// measure the insertion and removal
// operations for a hashmap
fn hashmap_operations() {
    let mut hashmap = HashMap::new();

    let time_start = std::time::Instant::now();
    for i in 0..MAX_ITER {
        hashmap.insert(i, i);
    }
    let time_end = std::time::Instant::now();

    println!("==== HashMap ====");
    println!("insert: {:?}", time_end - time_start);

    let time_start = std::time::Instant::now();
    for i in 0..MAX_ITER {
        hashmap.remove(&i);
    }
    let time_end = std::time::Instant::now();

    println!("remove: {:?}", time_end - time_start);
}

Exercise:
Data analysis

In this exercise, you are taking on the role of a prospective data analyst and have gotten your hands on a dataset of (fictional!) CSE enrolments.

The dataset is in the file enrolments.psv and each row contains the following columns (in order):

UNSW Course Code
UNSW Student Number
Name
UNSW Program
UNSW Plan
WAM
UNSW Session
Birthdate
Sex

Each row of data represents one enrolment. One student may have multiple rows, as they may be enrolled in multiple courses.

You've been asked to process the data, and output answers to the following questions:

How many unique students are there?
What is the most common course (with how many students)?
What is the least common course (with how many students)?
What is the average WAM of all students in CSE (to 2 decimal places)?
Given a specific student number, output their details?

Note that you can assume that there will be no two equally most-common or equally least-common courses in the dataset -- i.e. there will always be exactly one answer.

 6991 cargo run 
    Finished dev [unoptimized + debuginfo] target(s) in 0.01s
     Running `target/debug/data_analysis`
Number of students: 8065
Most common course: COMP1511 with 953 students
Least common course: BIOM9002 with 1 students
Average WAM: 61.94
Enter a student id: 5231508
== STUDENT FOUND ==
Name: Xu, Michael Rahul
Program: 7003/1
Plan: COMPSS
WAM: 75.09
Session: 22T2
Birthdate: 20010410
Sex: M

If the given student is not found, your program should print an error:

6991 cargo run 
    Finished dev [unoptimized + debuginfo] target(s) in 0.50s
     Running `target/debug/data_analysis`
Number of students: 8065
Most common course: COMP1511 with 953 students
Least common course: BIOM9002 with 1 students
Average WAM: 61.94
Enter a student id: abcd
== NOT FOUND ==

This is a substantial exercise, break it down into steps! Try and avoid for-loops, and practice using iterator functions.

Remember, when you are iterating over something (e.g x) that x.into_iter() can sometimes move x (or in other words, "consume" x such that it cannot be used again later). You may need to either clone the data, or preferably use x.iter() instead. If you get stuck, ask on the course forum!

The documentation for the csv crate may be useful. Particularly, the ReaderBuilder struct, which will allow you to:

Specify the delimiter (pipe symbol),
Specify the headers (or alternatively that there are no headers),
Specify the path of the file.

The seek method may be useful to reset the reader to the start.

The documentation for the serde crate may be useful.

You will need to enable the derive feature for the serde crate in your Cargo.toml such that your dependency looks like:
serde = { version = "1.0", features = ["derive"] }
This will allow you to use a derive macro for the csv crate to automatically generate the code to deserialize the CSV file into a struct.

The documentation for the HashMap type may be useful.

The documentation for the entry method may be useful. The example is of particular note.

The documentation for the max_by_key method may be useful. Similarly, min_by_key is also useful.

The documentation for the sum method may be useful. This is useful for calculating the average.

The documentation for the print! macro may be useful. This is useful for printing the student id prompt. Note that the documentation recommends flushing stdout.

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

6991 give

You must run give before Week 3 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 csv::{Position, ReaderBuilder};
use serde::Deserialize;
use std::collections::HashMap;
use std::io::{self, Write};

#[derive(Deserialize, Debug)]
struct Student {
    course_code: String,
    zid: String,
    name: String,
    program: String,
    plan: String,
    wam: f64,
    session: String,
    birthdate: String,
    sex: String,
}

fn main() {
    // parse each line of input into a student struct
    // add each student to a hashmap, with the zid as a key
    // open the file enrollments.csv
    let mut rdr = ReaderBuilder::new()
        .delimiter(b'|')
        .has_headers(false)
        .from_path("enrolments.psv")
        .unwrap();

    // create hashmap
    let mut students: HashMap<String, Student> = HashMap::new();

    // iterate over each record, parse it, and add to hashmap
    rdr.deserialize().for_each(|result| {
        let student: Student = result.unwrap();
        students.insert(student.zid.clone(), student);
    });

    // print out the number of students
    println!("Number of students: {}", students.len());

    // find the most common course:
    // create a hashmap to store the number of students in each course
    let mut course_counts: HashMap<String, u32> = HashMap::new();
    rdr.seek(Position::new()).unwrap();
    rdr.deserialize().for_each(|student| {
        let student: Student = student.unwrap();
        // get the current count for the course
        course_counts
            .entry(student.course_code)
            .and_modify(|e| *e += 1)
            .or_insert(1);
    });

    // find the course with the highest count
    let (course, count) = course_counts
        .iter()
        .max_by_key(|(_, count)| *count)
        .unwrap();

    println!("Most common course: {} with {} students", course, count);

    // find the least common course:
    // find the course with the lowest course
    let (course, count) = course_counts
        .iter()
        .min_by_key(|(_, count)| *count)
        .unwrap();
    println!("Least common course: {} with {} students", course, count);

    // find the average wam
    let total_wam = students.iter().map(|(_, student)| student.wam).sum::<f64>();
    let average_wam = total_wam / students.len() as f64;

    println!("Average WAM: {:.02}", average_wam);

    // ask for a zid, and then provide their details
    print!("Enter a student id: ");
    // flush stdout
    io::stdout().flush().unwrap();
    let mut zid = String::new();
    std::io::stdin().read_line(&mut zid).unwrap();
    let zid = zid.trim();

    // provide details for the given zid
    if let Some(student) = students.get(zid) {
        println!("== STUDENT FOUND == ");
        println!("Name: {}", student.name);
        println!("Program: {}", student.program);
        println!("Plan: {}", student.plan);
        println!("WAM: {:.02}", student.wam);
        println!("Session: {}", student.session);
        println!("Birthdate: {}", student.birthdate);
        println!("Sex: {}", student.sex);
    } else {
        println!("== NOT FOUND ==");
    }
}

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 3 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