This course has been set up for students of the Telecommunication Department at INSA-Lyon (5th year), it is vastly inspired by the Rust book and many other resources on the web. It assumes that students do not have any programming experience in Rust, but have a strong programming experience in other languages (C/C++ and object-oriented languages in particular).

• Setting up the environnement for using Rust
  • Course: What is cargo used for?
• Rust Hello World
  • Course: What about println!
• Variables, Types and Mutability
• Functions in Rust
• Generic types, traits and #derive directive
  • Course: Generic Types
  • Course: Traits: Defining common behaviour
  • Course: Deriving traits
• First example of Move semantics: the cube
  • Course: Move semantics
• Introduction to Visual Studio Code
  • Key Features of Visual Studio Code {#key-features-of-visual-studio-code .unnumbered}
  • How to use VS code efficiently for Rust {#how-to-use-vs-code-efficiently-for-rust .unnumbered}

In addition to these documents, some others are available on Moodle https://moodle.insa-lyon.fr/course/view.php?id=10386, presenting the concepts covered in this course. Don't forget to check it before you start. Many of the information listed here come from https://www.rust-lang.org/learn/.

The course is organized in sections that have questions. In addition, you will find text boxes labeled Course:, in which important concepts are presented.

Course: What is Rust and Why Rust

Setting up the environnement for using Rust

We're going to start by setting up the environment that will enable you to program in Rust. We recommend that you use Rust on your own machine, but the environment is already installed on the department computers.

This environment simply consists in having:

1. An editor for programming, we strongly recommend Visual Studio Code that is available on all OS, for instance here: https://visualstudio.microsoft.com/fr/downloads/. Together with the rust-analyzer extension. See Appendix below for an introduction to Visual Studio Code.

2. Install both the rust compiler (rustc) and cargo, with the rustup installer script.

cargo is Rust's package manager and build system. Its installation and versioning are managed by rustup.

Below is a summary for installing Rust and cargo on your laptop. The original complete instructions can be found here: https://doc.rust-lang.org/book/ch01-01-installation.html.

As a summary:

• On linux, use the following command:

  curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh

• On (recent) macOS:

1) curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh -s -- --no-modify-path

2) Choose 1)

3) . "$HOME/.cargo/env"

4) rustc --version
    cargo --version

• on Windows, go to https://www.rust-lang.org/tools/install and follow the instructions for installing Rust.

Course: What is cargo used for?

Rust Hello World

A Rust project is contained in a directory which has the name of the project. From now on, we suggest making a project in your home directory and keeping all your Rust code there.

We will use the cargo command to build our first hello_world project. Note that this is not mandatory, everything can be built by hand, the Rust compiler can be invoked without cargo by using the command rustc.

Execute the following command:

cargo new hello_world

Check the generated files:

• Cargo.toml is the project configuration file written in the TOML (Tom's Obvious, Minimal Language) format¹.
• src/main.rs is the Rust main file (the program entrypoint).

Now, build your project with the cargo build command.

• Where is the generated executable file?
• What is the bang (!) after println?

Course: What about println!

Variables, Types and Mutability

What is the problem with the program below? Does it compile?

#![allow(unused)]
fn main() {
let x = 5;
println!("The value of x is: {x}");
x = 6;
println!("The value of x is: {x}");
}

      |     let x = 5;
      |         -
      |         |
      |         first assignment to `x`
      |         help: consider making this binding mutable: `mut x`
    3 |     println!("The value of x is: {x}");
    4 |     x = 6;
      |     ^^^^^ cannot assign twice to immutable variable

What are the values printed by the program below?

#![allow(unused)]
fn main() {
let x = 5;
{
    let x = x + 1;
    {
        let x = x * 2;
        println!("The value of x in the inner scope is: {x}");
    }
}
println!("The value of x is: {x}");
}

The notion of scope is quite important in Rust, a scope can be manipulated in the language as an object, we will see it in more details in TD4.

Functions in Rust

Functions in Rust have little difference with functions in other programming languages. They are declared with the fn keyword, and their parameters (arguments) are passed by value or reference.

Write a function fibonacci: fibonacci(n: i32) -> i32, which computes element n of the fibonacci sequence.

We will not use a recursive solution, but rather a for loop whose syntax will be: for i in 2..n+1 ( half-open range) and mutable variables.

We recall the definition of the fibonacci function fib:

fib(0)=1
fib(1)=1
fib(i)=fib(i-1)+fib(i-2)  for i >= 2

#![allow(unused)]
fn main() {
fn fibonacci(n: i32) -> i32 {
    let mut next = 1;
    let mut prev = 1;
    let mut old;
    if n<=1 {
        return 1;
    } else {
        for _i in 2..n+1 {
            old = next;
            next = next + prev;
            prev =  old;
        }
        return next;
    } 
}
}

Generic types, traits and #derive directive

Just like in C++ with class and struct, Rust types can be defined and be implemented by using different methods. For instance, the following code defines the type Complex as a struct of two floats (type names begin with an uppercase character by convention).

#![allow(unused)]
fn main() {
struct Complex {
    re: f32,
    im: f32,
}

fn build_complex(re: f32,im:f32)->  Complex {
    Complex {re,im}
}       

let mut a = build_complex(2.3, 4.0);
println!("a = ({}, {})", a.re, a.im);
a.re = a.re+1.;
println!("a = ({}, {})", a.re, a.im);
}

Course: Generic Types

#![allow(unused)]
fn main() {
struct Point<T> {
    x: T,
    y: T,
}

let integer = Point { x: 5, y: 10 };
let float = Point { x: 1.0, y: 4.0 };
}

Modify the program of Complex creation above by using a type struct Complex<T> which uses a generic type, Test it with println!

#![allow(unused)]
fn main() {
struct Complex<T> {
    re: T,
    im: T,
}

fn build_complex<T>(re: T,im: T)->  Complex<T> {
    Complex {re,im}
}

let  a = build_complex(2.3, 4.0);
println!("a = ({}, {})", a.re, a.im);

}

Course: Traits: Defining common behaviour

impl Clone for Complex {
    fn clone(&self) -> Self {
        Complex{re: self.re, im: self.im}
    }
     // Now a.clone() can be used on Complex variables
}

Implement the Clone trait for the struct Complex<T> type defined before. You will have to use impl<T: Clone> to ensure that the T generic type implements the Clone trait.

impl<T: Clone> Clone for complex<T> {
    fn clone(&self)->Self{
        complex {re: self.re.clone(),im: self.im.clone()}
    }
}

By the way, do you know the difference between Copy and Clone?

Select your preferred answer:

• Clone is a supertrait of Copy²

• Copy is implicit, inexpensive, and cannot be re-implemented (memcpy). Clone is explicit, may be expensive, and may be re-implemented arbitrarily.

• The main difference is that cloning is explicit. Implicit notation means move for a non-Copy type.

Course: Deriving traits

#[derive(Clone)]
struct Complex {
    re: f32,
    im: f32,
}

[... no need to implement Clone ...]

let a = build_complex(2.3,4.0);
let _c = a.clone()

[...]

How could we use println! to display Complex variables? Test the two following methods:

1. Implement the std::fmt::Display trait for type Complex.

This will require to:

• use std::fmt
• search for the prototype of the Display trait
• use the macro write! to print fields

2. Derive the Debug trait that includes the fmt::Display trait and use the "{:?}" format.

use std::fmt;
[...]

impl fmt::Display for Complex {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
    write!(f, "({}, {})", self.re, self.im)
    }
}

[...]

let mut a = build_complex(2.3, 4.0);
println!("a = {}", a);

First example of Move semantics: the cube

In this first example we define a very simple data structure, a Cube with a single field c that indicates its size.

Write a Rust program that defines a structure Cube and prints its size

#![allow(unused)]
fn main() {
struct Cube {c:f32}

println!("My cube: {}", Cube{c:0.5}.c);
}

Can you print the cube itself? Can you write:

println!("My cube: {}", Cube{c:0.5});

If not, how can you make the cube printable?

Hint: You can derive the std::fmt::Display trait or the Debug trait

  error[E0277]: `Cube` doesn't implement `std::fmt::Display`
     --> src/main.rs:4:29
      |
    4 |     println!("My cube: {}", Cube{c:0.5});
      |                             ^^^^^^^^^^^ `Cube` cannot be formatted\
     with the default formatter
      |
      = help: the trait `std::fmt::Display` is not implemented for `Cube`
      = note: in format strings you may be able to use `{:?}` \
    (or {:#?} for pretty-print) instead

#![allow(unused)]
fn main() {
#[derive(Debug)]
struct Cube {
    c: f32,
}

println!("My cube size is: {}", Cube{c:0.5}.c);
println!("My cube is: {:?}", Cube{c:0.75});
}

Define a variable x assigned to a given cube, print it and then define a second variable y defined by let y = x;. Then print x again, what is the problem?

#![allow(unused)]
fn main() {
#[derive(Debug)]
struct Cube {
    c: f32,
}

let x = Cube { c: 0.75 };
println!("My cube x size is: {}", x.c);
let y = x;
println!("My cube x is: {:?}", x);
println!("My cube y is: {:?}", y);

}

    error[E0382]: borrow of moved value: `x`
      --> src/main.rs:10:36
       |
    7  |     let x = Cube { c: 0.75 };
       |         - move occurs because `x` has type `Cube`, which does not\
     implement the `Copy` trait
    8  |     println!("My cube x size is: {}", x.c);
    9  |     let y = x;
       |             - value moved here
    10 |     println!("My cube x is: {:?}", x);
       |                                    ^ value borrowed here after move
       |

Course: Move semantics

Modify your program by cloning x into y

#![allow(unused)]
fn main() {
#[derive(Debug, Clone)]
struct Cube {
    c: f32,
}

let x = Cube { c: 0.75 };
let y = x.clone();
println!("My cube size is: {}", x.c);
println!("My cube is: {:?}", y);
}

Introduction to Visual Studio Code

Visual Studio Code (often abbreviated as VS Code) is a cross-platform source code editor developed by Microsoft. It is compatible with Windows, macOS, and Linux, offering great flexibility to developers working in diverse environments. This lightweight yet powerful editor is designed to meet the needs of modern developers, providing a wide range of features.

Key Features of Visual Studio Code

Visual Studio Code stands out due to the following features:

• Built-in support for multiple programming languages: VS Code supports a wide array of languages such as Python, JavaScript, C++, Java, and more, thanks to its extension system.

• Extensions and customization: A vast library of extensions is available to add functionalities like debugging, version control, and language-specific tools.

• Integrated debugger: VS Code provides an interactive debugging environment to simplify error correction in the code.

• Version control integration: Seamless integration with Git and other version control systems allows developers to track code changes directly within the editor.

• Integrated terminal: A terminal is available inside the editor, enabling command execution without leaving the application.

• IntelliSense: This feature offers intelligent code completion and contextual suggestions based on syntax and variable types.

• Cross-platform compatibility: VS Code works consistently on Windows, macOS, and Linux, ensuring a uniform user experience regardless of the operating system.

Thanks to its intuitive interface and powerful tools, Visual Studio Code has become one of the most popular editors among developers, whether they are beginners or experienced professionals. Its active community and frequent updates make it a reliable choice for addressing the evolving needs of software development.

How to use VS code efficiently for Rust

Installation with snap (Linux):

sudo snap install code --classic

• Open the project directory:

  code myproject
  

• Add the Rust Analyzer extension (left bar, small squares), search rust → install rust-analyzer

• Go to Explorer

• Ctrl-Shift-P: command palette

• Ctrl-P: search for a file

• Ctrl-Shift-E: explorer

• Ctrl-J: command line inside VS Code

• Ctrl-Shift-I: indent the whole Rust file

To compile:

• Either use the Run button above main (Rust Analyzer)

• Or Ctrl-Shift-P and type Run, then select

• Or Ctrl-J and type:

  cargo build
  

• Move semantics and Copy semantics
• References and borrowing
  • Course: Reference in Rust
• Mutable Reference
  • Course: Mutable reference
• Heap and Stack: the String example
• Smart Pointers
• Rust Lifetimes
  • Why Rust Needs Lifetimes
    • Course: Lifetimes
  • Lifetimes in Structs
  • Lifetimes in Methods: self and Lifetime Propagation
• Recalls on Heap and Stack {#appStack}

Course: Ownership (from https://doc.rust-lang.org/book/)

Move semantics and Copy semantics

As we have seen in previous course, the following program will compile because:

1. default semantics of assignement is for type Cube is move.

2. But the derivation of the Copy trait turns it into a copy semantics, hence x and y represent two different values.

#[derive(Debug, Clone, Copy)]
struct Cube {
    c: f32,
}

fn main() {
    let x = [Cube{c:0.5},Cube{c:0.75},Cube{c:1.0}];
    let y = x;
    println!("x is: {:?}", x);
    println!("y is: {:?}", y);
}

Try this program:

fn main() {
    let x = [(10,20),(30,40),(50,60)];
    let y = x;
    println!("x is: {:?}", x);
    println!("y is: {:?}", y);
}

Why does it work?

References and borrowing

There is an alternative to moving or duplicating (i.e. cloning) a value: you can borrow it. Borrowing in Rust is done with the reference operator: ’&’.

in the original Cube program which has not derived the Copy trait, create a reference to x by using let y = &x. Can you print x after that?

#[derive(Debug)]
struct Cube {
    c: f32,
}

fn main() {
    let mut x = Cube { c: 0.75 };
    let y = &x;
    println!("My cube size is: {}", x.c);
    println!("My cube is: {:?}", y);
}

Course: Reference in Rust

#![allow(unused)]
fn main() {
let mut x = 10;
let y = &mut x;

*y = 20; // explicit dereferencing is required here
}

Borrowing is extremely useful in function calls. Each time you call a function with a parameter, the ownership of the object passed as a parameter is transferred to the function (actually, it is transferred to the formal parameter of the function). If, instead, you pass a reference to the object, the ownership does not change, so you can call many functions that only use an object without modifying it by using references.

Mutable Reference

Sometimes, you wish to have a function call that modifies an object. For that, you can use a mutable reference with the syntax: let y = &mut x. Mutable references in Rust do not change ownership. They only provide exclusive access to a value for mutation while ensuring that the ownership of the value remains unchanged.

By using a mutable reference to x (let y = &mut x), write a function called double that double the size of your cube x.

#[derive(Debug)]
struct Cube {
    c: f32,
}

fn double(y : &mut Cube) {
    y.c = 2.*y.c;
}

fn main() {
    let mut x = Cube { c: 0.75 };
    let y = &mut x;
    double(y);
    println!("My cube is: {:?}", x);
}

Course: Mutable reference

It is important to understand that the Rust compiler evaluate very precisely the scope of variable.

In the two codes below, only one of them is correct, which one and why?

#[derive(Debug)]
struct Cube {
    c: f32,
}

fn double(y : &mut Cube) {
    y.c = 2.*y.c;
}    

fn main() {
    let mut x = Cube { c: 0.75 };
    let y = &mut x;
    double(y);
    println!("My cube is: {:?}", x);
    println!("My cube is: {:?}", y);    
}

#[derive(Debug)]
struct Cube {
    c: f32,
}

fn double(y : &mut Cube) {
    y.c = 2.*y.c;
}    

fn main() {
    let mut x = Cube { c: 0.75 };
    let y = &mut x;
    double(y);
    println!("My cube is: {:?}", y);
    println!("My cube is: {:?}", x);    
}

Heap and Stack: the String example

Many programming languages don't require you to think about the stack and the heap very often. But in a systems programming language like Rust, whether a value is on the stack or the heap affects how the language behaves and why you have to make certain decisions.

Section 6 recalls the basics that everyone should know about the heap and the stack; please read it if you are not very familiar with these concepts.

The following code manipulates a string that contains hello:

#![allow(unused)]
fn main() {
let s1 = String::from("hello"); 
let s2 = s1;
}

As you know, if s1 were set to an integer (say 5), then s2 would have been set to a copy of 5, because int32 has copy semantics by default. But here, s1 is assigned to a String. We will study strings in more detail later, but this is a good example to understand the difference between the heap and the stack.

A String is made up of three parts, shown in the left figure 2 (taken from the Rust book): a pointer to the memory that holds the contents of the string, a length, and a capacity. This group of data is stored on the stack. On the right is the memory on the heap that holds the contents. The reason for this is that a string might contain an arbitrarily long character string, but the size used to store the structural information (i.e., pointer, length, and capacity) does not change from one string to another; it is known statically.

(a)                        (b)

When we assign s1 to s2, the String data is copied, meaning we copy the pointer, the length, and the capacity that are on the stack. We do not copy the data on the heap that the pointer refers to. In other words, the data representation in memory looks the right of like Figure above.

Note that the effective content of the string (i.e. the hello characters) is not duplicated, moreover it cannot be reached anymore with s1 string have move semantics so s1 is moved to s2 (data is now owned by s2)².

Write a function fn append_world(s: & mut String) which appends " world" to string s. Call it giving a mutable reference to s2. you can use the function pub fn push_str(&mut self, string: &str)

fn append_world(s:& mut String){
    s.push_str(" world!")
}

fn main() {
    let s1 = String::from("hello"); 
    let mut s2 = s1;
    append_world(&mut s2);
    println!("my string: {:?}", s2);
}

Smart Pointers

Smart pointers are inherited from other language such as C++. Smart pointers are data structures that act like a pointer but also have additional metadata and capabilities. Rust has a variety of smart pointers defined in the standard library that provide functionality beyond that provided by references. To explore the general concept, we'll look at a couple of different examples of smart pointers, including a reference counting smart pointer type (Rc) and a unique pointer on the heap (Box).

The most straightforward smart pointer is a Box, whose type is written Box<T>. Boxes allow you to store data on the heap rather than the stack with a Unique pointer. What remains on the stack is the pointer to the heap data. This is usefull for instance to create recursive type.

Create a type List based on the following structure: a list is either (the "either" correspond to an enum) the constant Nil or the concatenation of an integer and a List: Cons(i32, List). Try without using Box then using Box.

You will have to declare the use of the created symbols after the definition of List by writing: use crate::List::{Cons,Nil};

enum List{
    Cons(i32,List),
    Nil,
}

use crate::List::{Cons,Nil};

fn main() {
    let l1 = Cons(4,Cons(3,Nil));
}

    error[E0072]: recursive type `List` has infinite size
     --> src/main.rs:1:1
      |
    1 | enum List{
      | ^^^^^^^^^
    2 |     Cons(i32,List),
      |              ---- recursive without indirection

#[derive(Debug)]
enum List{
    Cons(i32,Box<List>),
    Nil,
}

use crate::List::{Cons,Nil};

fn main() {
    let l1 = Cons(4,Box::new(Cons(3,Box::new(Nil))));
    println!("L1 = {:?}",l1);
}

In the majority of cases, ownership is clear: you know exactly which variable owns a given value. However, there are applications where a single value might have multiple "owners". For example, in graph data structures, multiple edges might point to the same node, and that node is conceptually owned by all of the edges that point to it. A node shouldn't be cleaned up unless it doesn't have any edge pointing to it and so has no owners.

You have to enable multiple ownership explicitly by using the Rust type Rc<T>, which is an abbreviation for reference counting. We use the Rc<T> type when we want to allocate some data on the heap for multiple parts of our program to read and we can't determine at compile time which part will finish using the data last. Note that Rc<T> is only for use in single-threaded scenario, other constructs are used in multithreaded programs.

Consider the scheme below where a list (a) is shared by two other lists (b and c).

Write a program that creates this object by using Rc<T> instead of Box<T>. For that you will have to:

• use std::rc::Rc;
• Provide 2 clones (for b and c) of references to a:Rc::clone(&a)  

#[derive (Debug)]
enum List {
    Cons(i32,Rc<List>),
    Nil,
}
use crate::List::{Cons,Nil};
use std::rc::Rc;
fn main() {
    let a=Rc::new(Cons(5,Rc::new(Cons(10,Rc::new(Nil)))));
    let b = Cons(3,Rc::clone(&a));
    let c = Cons(3,Rc::clone(&a));
    println!("a={:?}",a);
    println!("b={:?}",b);
    println!("c={:?}",c);
    drop(a); //b and c still exist
    println!("b={:?}",b);
    println!("c={:?}",c);
    drop(b);
    drop(c);
}

Rust Lifetimes

Rust’s memory model aims to guarantee safety (no dangling pointers, no data races) without a garbage collector. To achieve this, Rust enforces a system of ownership, borrowing, and finally, the essential but sometimes confusing concept of lifetimes.

Lifetimes don’t control allocation or deallocation. Instead, they allow the compiler to reason about the validity of references. Their purpose is to ensure that no reference outlives the data it points to.

Why Rust Needs Lifetimes

Consider a function that returns a reference:

#![allow(unused)]
fn main() {
fn get_ref<'a>(s: &'a String) -> &'a str {
    &s[..]
}
}

Rust must ensure that:

• the returned reference is valid, and
• it never points to data that might be freed or moved before it is used.

Rust cannot always infer the relationships between the lifetimes of multiple references. When inference is too ambiguous, it requires explicit lifetime annotations.

A lifetime is therefore a static constraint, used at compile time, to avoid errors like dangling references.

Course: Lifetimes

#![allow(unused)]
fn main() {
fn demo<'a>(x: &'a i32) { /* ... */ }
}

#![allow(unused)]
fn main() {
fn len(s: &str) -> usize { s.len() }
}

Why is the following Rust code invalid? Try to correct it.

#![allow(unused)]
fn main() {
fn longest(x: &str, y: &str) -> &str {
    if x.len() > y.len() { x } else { y }
}

}

#![allow(unused)]
fn main() {
fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
    if x.len() > y.len() { x } else { y }
}
}

Lifetimes in Structs

A struct containing references must almost always define lifetimes:

#![allow(unused)]
fn main() {
struct Holder<'a> {
    value: &'a str,
}
}

This means:

• A Holder instance cannot outlive the value it references.

This is essential for safety: if a struct contains a reference, Rust ensures that the struct is destroyed before the data it refers to.

Lifetimes in Methods: self and Lifetime Propagation

In method implementations, lifetimes apply to self:

#![allow(unused)]
fn main() {
impl<'a> Holder<'a> {
    fn get(&self) -> &str {
        self.value
    }
}
}

Rust infers that the returned reference has the same lifetime as &self, which is 'a. No explicit annotation is needed because of elision rules.

The most famous lifetime is 'static. It indicates that the data:

• is available for the entire program (e.g., string literals), or
• is stored in a location that will never be freed prematurely.

Recalls on Heap and Stack

Although knowing the exact memory management is generaly not necessary to a programmer, in many case (system programming or embedded programming for instance, often done in Rust), it is crucial to understand how memory is handle by the compiler/OS. From the programmer point of view, and thanks to virtual memory system, everything happens as if we had all the memory available.

The memory management is more or less the same for every language and system, what differ is what is visible for the programmer: explicit memory management (malloc/free) or garbage collecting etc. This memory is organized in different section, almost allways in the following way:

The "code" section contains the assemble code of the program. The "static" section contains all the "static" variables (i.e. variables that are available during the whole execution of the program). The two other section are managed dynamically during execution:

• The heap is used for dynamic memory allocation: malloc (in C) or new (in object languages). The object stored in the heap have a lifetime that is independent of function execution, they can survive after the function that created them has finished. The heap can be managed explicitely (as is C with malloc and free) or implicitely (using a garbage collector as in Python for instance).

• The stack is used to manage the execution of functions (or procedures in general) which includes in particuly the allocation and management of functions local variables.

The stack start from big adresses and grows downward, although it is often represented upside-down as below: small adresses up, big addresses down. The heap grows upward, when the two bounds meet, the system is out of memory.

The stack execution principle is important to know. when a function is called, a space is allocated on the stack to store its local variables: this space is called the function frame. When the function ends, its frame is freed and the stack goes back to the frame of the calling function.

Below is an illustration of the evolution of the stack during a function call, two registers of the processor are indicated: the stack pointer (SP) that indicate the top of the stack and the frame pointer that indicate the beginning of the frame of the current fonction. The frame contains all the information needed to the execution of the function, including room for local variables.

         

(a) before call       (b) during call                   (c) after call 

1. before the call, the frame pointer FP points to the frame of the calling function

2. during the call, the stack is increase (i.e. SP is decreased as the stack is upside-down) to have room for the frame of the called function. This includes room for local variable of the function, parameter given to the function and information for returning from the function (return address in the code because a given function can be called from many places in the code), room for the function result as well as some bookeeping information such as saved values of the processor registers.

3. after the call, the called fonction frame has disappeared. Actually its content is still there but cannot be accessed anymore because the stack pointer SP has been put back to its location before the call

Important to remember: The function variables whose size are known at compile time are usually stored in the stack. The variable whose size are know during execution, such as String or object created by new are usually stored on the heap.

• Compound types
  • Course: Tuples
  • Course: Arrays (primitive type)
  • Course: Ranges & Iterators
  • Course: Iterators
• Collections
  • Course: Vectors
  • Course: Hash-maps
• 'string' types (str and String)
  • Course: str primitive
  • Course: String
• Slices

Compound types

Compound types can group multiple values into one type. Rust has two primitive compound types: tuples and arrays.

Course: Tuples

#![allow(unused)]
fn main() {
// Explicit type:
let mut tup: (i32, i32, f32, &str) = (31, 16, 47.27, "hello!"); 

// Inferred type:
let mut tup = (31, 16, 47.27, "hello!"); 
}

#![allow(unused)]
fn main() {
let mut tup = (31, 16, 47.27, "hello!"); 

// Access by index:
tup.0 = 22;
tup.3 = "world!";

// 'Destructuring' a tuple:
let (t0, t1, t2, t3) = tup;
println!("y = ({t0}, {t2})");
}

Take a mutable reference to the third element (f32) of the tuple tup and pass it to a function that multiplyies it by 2:

let mut tup = (31, 16, 47.27, "hello!"); 

// The function's prototype (to be implemented):
fn mul2(t: &mut f32);

mul2(...);

assert!(tup == (31, 16, 94.54, "hello!"));

#![allow(unused)]
fn main() {
let mut tup = (31, 16, 47.27, "hello!"); 

fn mul2(t: &mut f32) {
    *t += *t;
}

mul2(&mut tup.2);
assert!(tup == (31, 16, 94.54, "hello!"));
}

#![allow(unused)]
fn main() {
// A function returning a pair of signed integers:
fn return_tuple(x: i32) -> (i32, i32) {
    return (x+1, x+2);
}

// Calling a function, and storing its result:
let y: (i32, i32) = return_tuple(8);
println!("y = {:?}", y);
println!("y = ({:?}, {:?})", y.0, y.1);

// Passing a tuple as an argument to a function:
fn print_tuple(x: &(i32, i32)) {
    println!("x = ({:?}, {:?})", x.0, x.1);
}

print_tuple(&y);
}

Write a function that transforms a (i32, i32) tuple by swapping its two values:

#![allow(unused)]
fn main() {
// The function prototype to be implemented:
fn swap(tup: &mut(i32, i32));

let mut x = (31, 27);
swap(&mut x);

assert!(x == (27, 31));
}

#![allow(unused)]
fn main() {
fn swap(tup: &mut(i32, i32)) {
    *tup = (tup.1, tup.0);
}

let mut x = (31, 27);
swap(&mut x);

assert!(x == (27, 31));
}

Course: Arrays (primitive type)

#![allow(unused)]
fn main() {
// Explicit type:
let a: [i32; 3] = [31, 16, 47];

// Inferred type:
let b = [0, 1, 2, 3, 4]; // #[i32; 5]

// Create and zero-initialize an array:
let mut a: [usize; 10] = [0; 10];
// same as:
let mut a = [0 as usize; 10];
// same as:
let mut a = [0usize; 10];

// Writing at a specific index:
// Note: in Rust, as in C, array indices start at 0
a[0] = 2;
println!("a[0] = {}", a[0]);
}

#![allow(unused)]
fn main() {
// 2-dimensional array, 2 arrays of `i32` with a length of 10 each:
let mut multi_array = [[0 as i32; 10]; 2];
[...]
multi_array[0][0] = 1;
}

What would be the type of the following arrays?

#![allow(unused)]
fn main() {
let a1 = [(1, 2), (3, 4), (5, 6)];
let a2 = [(1, 2), (3, 4), (5, (6, 7))];
}

#![allow(unused)]
fn main() {
let a1: [(i32, i32); 3] = [(1, 2), (3, 4), (5, 6)];
}

Course: Ranges & Iterators

Examine the following assert! statements, will this program compile?

let a = 0..10;
let b = 1..=10;

// 'a' range:
assert!(a.contains(&0));
assert!(!a.contains(&10));

// 'b' range:
assert!(!b.contains(&0));
assert!(b.contains(&10)); 

// The 'a' and 'b' ranges have the same number of elements:
assert_eq!(a.count(), b.count());

Course: Iterators

#![allow(unused)]
fn main() {
let r = 0..10;
// Iterate over a range:
for n in r.into_iter() {
    print!("{n} ");
    // -> 0 1 2 3 4 5 6 7 8 9
}
println!();

// Iterate over an array:
let mut a = [0; 10];

// Basic for-loop iteration:
for x in a {
    println!("{x}");
}
// From a 'range':
for n in (0 .. a.len()) {
    println!("{}", a[n]);
}
// As mutable, changing the values of the array:
for x in &mut a {
    *x += 1;
}
// Equivalent to (using a 'closure'):
a.iter_mut().for_each(|x| *x += 1 );

// Iterate with both element and index:
for (i, x) in a.iter_mut().enumerate() {
    *x += i;
}
}

Using ranges and/or iterators, write in the following multidimensional array's first sub-array values that incrementally go from 1 to 10, and in the second, decrement the values from 10 to 1, as shown below:

#![allow(unused)]
fn main() {
let mut multi_array = [[0 as i32; 10]; 2];

// The following must be true:
assert_eq!(multi_array, [
    [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
    [10, 9, 8, 7, 6, 5, 4, 3, 2, 1]
]);
}

#![allow(unused)]
fn main() {
let mut multi_array = [[0 as i32; 10]; 2];
for n in 1..=10 {
    multi_array[0][n-1] = n as i32;
}
for n in (1..=10).rev() {
    multi_array[1][10-n] = n as i32;
}
// The resulting 2D-array
assert_eq!(multi_array, [
    [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
    [10, 9, 8, 7, 6, 5, 4, 3, 2, 1]
]);
}

Collections

In addition to primitive compound types, the Rust standard library includes a number of very useful data structures called collections. Unlike the built-in array and tuple types, the data these collections point to is stored on the heap, which means the amount of data does not need to be known at compile time and can grow or shrink as the program runs.

Course: Vectors

#![allow(unused)]
fn main() {
// The easiest way to create a vector is to use the 'vec!()' macro:
let mut v = vec![0, 1, 2, 3, 4, 5]; // Vec<i32>
println!("Value: {:?}", v);

// 'Pushing' (appending) a new value at the end:
v.push(6);
println!("Value: {:?}", v);

// 'Popping' (removing) its last value:
let last = v.pop();
println!("Last value: {:?}, Vector: {:?}", last, v);

// removing value at index i:
v.remove(i)
}

Examine the following v1, v2 and v3 vectors and their underlying heap buffer pointers.

#![allow(unused)]
fn main() {
let mut v0: Vec<i32> = vec![0, 1, 2, 3, 4];
// get a pointer to the underlying heap memory buffer:
let v0_ptr: *const i32 = v0.as_ptr();

// Create another vec 'v1' from 'v0', and get its heap pointer again:
// i.e. move v0 to v1
let mut v1: Vec<i32> = v0;
let v1_ptr = v1.as_ptr();

// Create another vec 'v2' from 'v1'using clone():
let mut v2: Vec<i32> = v1.clone();
let v2_ptr = v2.as_ptr();
}

Which of the following assertions are true:

#![allow(unused)]
fn main() {
// Assertion A: the address of pointer 'v0' is the same as pointer 'v1'
assert_eq!(v0_ptr.addr(), v1_ptr.addr());

// Assertion B: the address of pointer 'v1' is the same as pointer 'v2'
assert_eq!(v1_ptr.addr(), v2_ptr.addr());

// Assertion C: the address of pointer 'v0' is the same as pointer 'v2'
assert_eq!(v0_ptr.addr(), v2_ptr.addr());
}

#![allow(unused)]
fn main() {
// Initializing from a range and iterator:
let mut v = Vec::from_iter((0..6).map(|i| i+1 ));
println!("Value: {:?}", v);

// Iterate/increment:
for x in &mut v {
    *x += 1;
}
println!("Value: {:?}", v);
// General operations:
v.rotate_left(1);
println!("Value: {:?}", v);
// etc.
}

Using a single loop, move the contents of vector v to array a such as vector v is equal to vec![] (empty vector) and array a is equal to the inverse of v : [5, 4, 3, 2, 1, 0]:

#![allow(unused)]
fn main() {
let mut v = vec![0, 1, 2, 3, 4, 5];
let mut a = [0; 6];

(...)

assert_eq!(v, vec![]);
assert_eq!(a, [5, 4, 3, 2, 1, 0]);
}

#![allow(unused)]
fn main() {
let mut v = vec![0, 1, 2, 3, 4, 5];
let mut a = [0; 6];

for n in (0..v.len()) {
    a[n] = v.pop().unwrap();
}
assert_eq!(v, vec![]);
assert_eq!(a, [5, 4, 3, 2, 1, 0]);
}

Course: Hash-maps

#![allow(unused)]
fn main() {
// Unlike Vec, the HashMap data structure need to be explicitly included!
use std::collections::HashMap;

// Inferred type:
let mut departments = HashMap::new(); // HashMap<i32, str>
departments.insert(85, "Vendée");
departments.insert(31, "Haute-Garonne");
departments.insert(44, "Loire-Atlantique");

// We use the ampersand(&) and the key (&1) as the argument 
// because [..] returns us a reference of the value. It is not 
//the actual value in the HashMap.
let d31 = departments[&31];
assert_eq!(d31, "Haute-Garonne");

// Removing a key:
departments.remove(&85);

// Iterating over all values:
for department in departments {
    // We get a tuple!
    println!("Key: {}, Value: {}", department.0, department.1);
}
}

Move the contents of the following Vec object into a BTreeMap (which behaves the same as a HashMap, but will sort its contents by key) in order to get these athlete names sorted by their score in points.

Note: some of them have the same score, which should appear in the same key.

#![allow(unused)]
fn main() {
use std::collections::BTreeMap;

let vec = vec![
    ("Y. Horigome", 281),
    ("N. Huston", 279),
    ("M. Dell", 153),
    ("J. Eaton", 281),
    ("S. Shirai", 278),
    ("K. Hoefler", 270),
    ("C. Russell", 211),
    ("R. Tury", 273),
];

let mut map = BTreeMap::new();

[...]

for score in map {
    println!("{:?}", score);
}
}

Hints:

• build a BTreeMap with the key being the score
• use the entry(key) method of HashMap that return the HashMap entru corresponding to key
• apply or_defaulton the result of entry (it creates an entry with no value for this key, if the key does not exists in the HashMap)

The last for loop should print:

(153, ["M. Dell"])
(211, ["C. Russell"])
(270, ["K. Hoefler"])
(273, ["R. Tury"])
(278, ["S. Shirai"])
(279, ["N. Huston"])
(281, ["Y. Horigome", "J. Eaton"])

#![allow(unused)]
fn main() {
use std::collections::BTreeMap;

let vec = vec![
    ("Y. Horigome", 281),
    ("N. Huston", 279),
    ("M. Dell", 153),
    ("J. Eaton", 281),
    ("S. Shirai", 278),
    ("K. Hoefler", 270),
    ("C. Russell", 211),
    ("R. Tury", 273),
];

let mut map: BTreeMap<i32, Vec<&str>> = BTreeMap::new();
for v in vec {
    map.entry(v.1)
        .or_default()
        .push(v.0);
}
for score in map {
    println!("{:?}", score);
}
}

'string' types (str and String)

Course: str primitive

#![allow(unused)]
fn main() {
// String literal:
let s = "Hello, World!";
}

#![allow(unused)]
fn main() {
// Here, the three syntaxes are equivalent:
let s = "Hello, World!"; // Inferred type & lifetime
let s: &str = "Hello, World!"; // Explicit type, inferred lifetime
let s: &'static str = "Hello, World!"; // Explicit type & lifetime
}

#![allow(unused)]
fn main() {
let s = "Hello, World!";
println!("Pointer: {:?}, Length: {} bytes", s.as_ptr(), s.len());

for (n, char) in s.chars().enumerate() {
    println!("Char {n}: {char}");
}
}

#![allow(unused)]
fn main() {
let s: &mut str = "Hello, World!";
}

Run the following code:

#![allow(unused)]
fn main() {
let s1 = "It's not about the bunny      \t"; 

// trim() Returns a string slice with leading and trailing whitespace removed.
let s2 = s1.trim();
println!("{s1}");
println!("Address: {:?}, Length: {}", s1.as_ptr(), s1.len());
println!();
println!("{s2}");
println!("Address: {:?}, Length: {}", s2.as_ptr(), s2.len());
}

• Since Rust forbids modifying the contents of a str literal, why are we in this case allowed to use the .trim() function? What is truly happening in this code?

• What would happen if we modified s1 as follows?

#![allow(unused)]
fn main() {
let s1 = "     It's not about the bunny      \t"; 
let s2 = s1.trim();
}

#![allow(unused)]
fn main() {
let s1 = "     It's not about the bunny      \t"; 
let s2 = s1.trim();

// s2 pointer address minus 5 (removing the whitespaces) is equal to s1 pointer's address
assert_eq!(s2.as_ptr().addr()-5, s1.as_ptr().addr());
}

Course: String

#![allow(unused)]
fn main() {
// Create from a string literal:
let mut s = String::from("Owls are not what they seem");

// Append a 'char':
s.push('!');
println!("Value: {:?}", s);

// Append another string:
s.push_str(" Really?");
println!("Value: {:?}", s);

// Other ways of appending to the String:
s = s + " Yes, ";
s += "really!";

// Iterate over every 'char'
for c in s.chars() {
    print!("{c} ");
}
println!("");

// Example of transformation:
s = s.chars().rev().collect();

println!("Value: {:?}", s);
}

Examine the following code:

#![allow(unused)]
fn main() {
let s0: &str = "That gum you like is going to come back in style";

// Build a 'String' object from the previous '&str':
let mut s1: String = String::from(s0);

// Now modify 'string':
s1 = s1.to_ascii_uppercase();
println!("{s1}");

}

Is s0 still accessible? If yes, what is now its value? Is it the same as s1 and why?

We now call the as_str() method on s1, and store the resulting &str value in a new variable called s2. Can you guess what is the lifetime of s2?

#![allow(unused)]
fn main() {
let s0: &str = "That gum you like is going to come back in style";

// Build a 'String' object from the previous '&str':
let mut s1: String = String::from(s0);
let s2: &str = s1.as_str();
}

Slices

#![allow(unused)]
fn main() {
// Create a byte buffer:
let mut buffer = [0 as u8; 16];

// Get a slice on half the buffer:
// (notice how the slice itself is not mutable, 
// but instead points to a mutable sequence in the buffer)
let slice: &mut[u8] = &mut buffer[0..8]; // we use the 'range syntax' here to capture the slice

// Iterate on the slice to change values:
for (i, n) in slice.iter_mut().enumerate() {
    *n = i as u8;
}
println!("{:?}", buffer);
}

Take a slice out of the string object, starting from character 25 until the end, and use the .make_ascii_lowercase() method on the captured slice.

#![allow(unused)]
fn main() {
let mut string = String::from("YOU REMIND ME TODAY OF A SMALL MEXICAN CHIHUAHUA");

let slice = ...;

slice.make_ascii_lowercase();

println!("{string}");
}

#![allow(unused)]
fn main() {
let mut string = String::from("YOU REMIND ME TODAY OF A SMALL MEXICAN CHIHUAHUA");

let slice = &mut string[25..];

slice.make_ascii_lowercase();

println!("{string}");
}

What is the inferred type of the slice variable?

• Struct in Rust
  • Course: Structs (from https://doc.rust-lang.org/book/)
  • Methods in Rust
• Enum and pattern matching
  • Course: Enum and option Enum (from https://doc.rust-lang.org/book/)
  • The Option Enum
• Generic Types
• Traits: Defining Shared Behavior
  • Trait as parameter: the Trait Bound Syntax
  • Using Trait Bounds to Conditionally Implement Methods
• Programming paradigms in Rust
  • A simple example: integer Vector sum.
  • A More Complete Example

Struct in Rust

Course: Structs (from https://doc.rust-lang.org/book/)

#![allow(unused)]
fn main() {
struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}
}

#![allow(unused)]
fn main() {
let user1 = User {
    active: true,
    username: String::from("someusername123"),
    email: String::from("someone@example.com"),
    sign_in_count: 1,
};
}

#![allow(unused)]
fn main() {
let user2 = User {
    email: String::from("another@example.com"),
    ..user1
};
}

Consider the following struct definition (replacing string by string slice str):

#![allow(unused)]
fn main() {
struct User {
    active: bool,
    username: &str,
    email: &str,
    sign_in_count: u64,
}
}

Try to create an instance of this structure in a main program.

You will not be able because the lifetime of the str slice is not known (it depends on the lifetime of the string it points to). In a Struct all fields must have the same lifetime.

Try to solve the problem by adding lifetime in your definition, using the compiler error message.

$ cargo run
   Compiling structs v0.1.0 (file:///projects/structs)
error[E0106]: missing lifetime specifier
 --> src/main.rs:3:15
  |
3 |     username: &str,
  |               ^ expected named lifetime parameter
  |
help: consider introducing a named lifetime parameter
  |
1 ~ struct User<'a> {
2 |     active: bool,
3 ~     username: &'a str,

#![allow(unused)]
fn main() {
struct User<'a> {
    active: bool,
    username: &'a str,
    email: &'a str,
    sign_in_count: u64,
}
}

Methods in Rust

As in any object-oriented langage, methods can be defined within the context of a struct making a struct a regular object as defined in the object-oriented programming paradigm. (In Rust, methods can be also defined in the context of an enum or a trait object. The definition of methods use the keyword fn as function but the are preceded by the keyword impl (eg: impl MyStruct { fn [...] }) to specify that this function is only defined in the context of a particular type object.

For a method, the first parameter is always &self (or self if the method need to take ownership of self). &self is a short cut for &self: MyObjectType whatever this type is.

For example, if we want to defined a methode name() for the previous structure User (the first on, with String) in order to obtain the username of a User, we will use the following syntax:

impl User {
    fn name(&self)->&String{
        &self.username
    }
}

When calling this method, the self argument is never written, it is implicit (e.g. : user1.name()). The above method is ofter called a getter. Getters are not implemented by default for Rust Struct, it is a good habit to name the getter after the field name they are getting (hence we should have called this method username())

Define a struct Rectangle with two integer fields width and height. Then implement two methods for Rectangle: area(&self) (which computes the surface of the rectangle) and fits_in(&self, other_rect: &Rectangle) which indicate if self fits completely inside the other_rectrectangle.

#![allow(unused)]
fn main() {
struct Rectangle {
    height: i32,
    width: i32,
}

impl Rectangle {
    fn area(&self)->i32{
        self.height * self.width
    }
}

impl Rectangle {
    fn fits_in(&self,other_rect: &Rectangle)->bool{
        if other_rect.width>self.width && other_rect.height>self.height {
            return true;
        } else  {
            return false;
        }
    }
}
}

Enum and pattern matching

Course: Enum and option Enum (from https://doc.rust-lang.org/book/)

#![allow(unused)]
fn main() {
enum IpAddrKind {
    V4,
    V6,
}
}

#![allow(unused)]
fn main() {
enum IpAddr {
    V4(u8, u8, u8, u8),
    V6(String),
}

let home = IpAddr::V4(127, 0, 0, 1);

let loopback = IpAddr::V6(String::from("::1"));
}

#![allow(unused)]
fn main() {
enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter,
}

fn value_in_cents(coin: Coin) -> u8 {
    match coin {
        Coin::Penny => 1,
        Coin::Nickel => 5,
        Coin::Dime => 10,
        Coin::Quarter => 25,
    }
}
}

The Option Enum

As explained in TD1, the Null value was invented to represent the "no value" value and it was a bad invention. With the Option Enum Rust proposes a mecanism that explicitely distinguish the cases where a variable has a value or no value. Rust defines (in the standard library, in the prelude) a particular Option<T> enum:

#![allow(unused)]
fn main() {
 enum Option<T> {
    None,
    Some(T),
}
}

The <T> syntax is a feature of Rust called a generic type parameter (similar to template in C++) that will be explained hereafter.

Write a function that computes the square root of a f32 number and return None if the number is negative.

fn square_root(a: f32) -> Option<f32>{
    match a  {
        n if n >= 0.0 => Some(a.sqrt()),
        _ => None,
    }
}

fn main() {
    println!("square root of N={:?}: {:?}",5,square_root(5.0));
    println!("square root of N={:?}: {:?}",-5,square_root(-5.0)); 
}

Of course, a Some(T) object cannot be "casted" or "simplified" in a T object. The only way to get the Tobject is to unwrap the option.

unwrap will be explained in next course (for Result type), here it will return the Tobject or panic in case of None. The Option<T> enum has a large number of methods that are useful in a variety of situations https://doc.rust-lang.org/std/option/enum.Option.html.

Try to unwrap (i.e. apply .unwrap()) your square root for positive and negative number.

fn square_root(a: f32) -> Option<f32>{
    match a  {
        n if n >= 0.0 => Some(a.sqrt()),
        _ => None,
    }
}

fn main() {
    println!("square root of N={:?}: {:?}",5,square_root(5.0).unwrap());
    println!("square root of N={:?}: {:?}",-5,square_root(-5.0).unwrap()); //fails
}

Generic Types

Every programming language has tools for effectively handling the duplication of concepts. In Rust, one such tool is generics. Generic Types, Traits and Lifetimes are three kind of generics.

Generic Data Types can be used in the definition of functions, struct or enum. Generic Data Type are very close to the template concept in C++.

Write a function that will be able to find the minimum of a Vector may this vector be a vector of i32, f32 or characters or on any type that has the possibility of comparing elements. Use the following function signature: smallest<T: PartialOrd> (v: &[T])-> &T

fn smallest<T: PartialOrd> (v: &[T])-> &T {
    let mut min=&v[0];
    for e in v{
        if e < min {
            min = e;
        }
    }
    min
}

fn main() {
    let v1 = vec![2,7,9,1];
    println!("min v1= {}",smallest(&v1));
    let v2 = vec![2.0,7.7,9.9,1.1];
    println!("min v2= {}",smallest(&v2));
    let v3 = vec!['a','t','4','j'];
    println!("min v3= {}",smallest(&v3));
}

Define a structure Point with two fields xand y that can be integer or floating point. Is Point{x:2,y:2.3} a valid instance of the structure Point?

#![allow(unused)]
fn main() {
struct Point<T> {
    x: T,
    y: T,
}
}

Traits: Defining Shared Behavior

A trait defines the functionality or behaviour that a particular type has and can share with other types. We have already seen some very common traits: Clone or Debug. The trait Clone for instance represents the fact that a variable of a type can be duplicated (i.e. cloned) to a second instance of the type, identical to the variable but refering to a different memory location. Traits are similar to a feature often called interfaces in other languages, although with some differences.

Defining a trait consists in the following syntax: impl TheTrait for TheType {...}.

In general, trait names should be defined in UpperCamelCase (e.g. IsEven) and traits methods should be defined with snake_case name (e.g. is_even(&self)). Implementing a trait for a particular type is done using impl name_of_trait for name_of_type{[...]}.

Define a trait IsEven that is composed of the method is_even(&self). Implement the trait for the Rectangletype defined préviously (a Rectangle is even if both height and width are even)

trait IsEven {
    fn is_even(&self)->bool;
}

#[derive(Debug)]
struct Rectangle {
    height: i32,
    width: i32,
}

impl IsEven for Rectangle {
    fn is_even(&self)->bool {
        return (self.height%2 == 0) && (self.width%2 == 0)
    }
}

fn main() {
    println!("Hello, world!");
    let r1=Rectangle{height:20,width:30};
    println!("Rectangle {:?} is even: {}",r1,r1.is_even());
}

You can specify a default implementation of each method in the definition of the trait (then an explicit implementation will hide the default implementation)

Trait as parameter: the Trait Bound Syntax

Trait can be used as function parameter, the function will be valid for any type implementing the trait. There are two possible syntaxes, the impl Trait syntax for simple cases and the Trait Bound Syntax for the general case:

fn myFunction(a_variable: &impl TheTrait) { [..]}

fn myFunction<T: TheTrait>(a_variable: &T) { [..]}

Define a function notifyEven that takes as parameter a type that implements the trait IsEven and notify (i.e. print) the fact that the object is even. Note that you can implement IsEven and Debug traits together by specifying IsEven+Debug.

fn notify_even<T: IsEven+Debug> (o: &T){
    println!("This object: {:?} is even? {}",o,o.is_even());
}

Sometimes, this syntax can be heavy and you can use the where Clause: instead of writing this:

fn some_function<T: Display + Clone, U: Clone + Debug>(t: &T, u: &U) -> i32 {

we can use a where clause, like this:

fn some_function<T, U>(t: &T, u: &U) -> i32
where
    T: Display + Clone,
    U: Clone + Debug,
{

The impl trait syntax can be used to specify that a result of a function must implement a trait.

Using Trait Bounds to Conditionally Implement Methods

The following example (from https://doc.rust-lang.org/book/ch10-02-traits.html) illustrates the fact the trait can be used to conditional implementation of methods

#![allow(unused)]
fn main() {
use std::fmt::Display;

struct Pair<T> {
    x: T,
    y: T,
}

impl<T> Pair<T> {
    fn new(x: T, y: T) -> Self {
        Self { x, y }
    }
}

impl<T: Display + PartialOrd> Pair<T> {
    fn cmp_display(&self) {
        if self.x >= self.y {
            println!("The largest member is x = {}", self.x);
        } else {
            println!("The largest member is y = {}", self.y);
        }
    }
}
}

Programming paradigms in Rust

This section is largely inspired by https://corrode.dev/blog/paradigms/.

Rust is a multi-paradigm programming language, accommodating imperative, object-oriented, and functional programming styles. It is important to be aware that the programming paradigm is an important design choice when you start a new Rust program. The choice of style often depends on a developer’s background and the specific problem they’re addressing. but there are also many "known habits" of Rust developpers.

A specificity compared to other recent languages is the important and growing influence of functional programming in Rust.

A simple example: integer Vector sum.

Consider the problem of suming all the component of vector with i32 values. Write a program to do it in an iterative/imperative way (i.e. a loop accumulating in a temporary variable)

#![allow(unused)]
fn main() {
let vector = vec![9,6,-2,7];
    let mut sum = 0;
    for i in 0..vector.len()
     {
        sum += vector[i];
    }
    println!("Hello, world sum = {}!",sum);
}

Do the same thing in a more functionnal way: Use the iter() method of Vector type and sum() method of iterators

#![allow(unused)]
fn main() {
let vector = vec![9,6,-2,7]; 
let sum2 :i32 = vector.iter().sum();
println!("Hello, world sum2 = {}!",sum2);
}

The second formulation is, of course, much more concise, as is often the case in functional programming, but it is less suited to certain types of processing (matrix calculations, for example).

A More Complete Example

Consider the following Rust code, which defines a list of several languages along with the paradigms they are associated with. You will start from this code. The task will be to find the top five languages that support functional programming and have the most users.

#![allow(unused)]
fn main() {
#[derive(PartialEq,Clone,Debug)]
enum Paradigm {
    Functional,
    ObjectOriented,
}

#[derive(Clone,Debug)]
struct Language {
    name: &'static str,
    paradigms: Vec<Paradigm>,
    nb_users: i32,
}

impl Language {
    fn new(name: &'static str, paradigms: Vec<Paradigm>, nb_users: i32) -> Self {
        Language { name, paradigms, nb_users }
    }
}

let languages = vec![
    Language::new("Rust", vec![Paradigm::Functional,Paradigm::ObjectOriented], 100_000),
    Language::new("Go", vec![Paradigm::ObjectOriented], 200_000),
    Language::new("Haskell", vec![Paradigm::Functional], 5_000),
    Language::new("Java", vec![Paradigm::ObjectOriented], 1_000_000),
    Language::new("C++", vec![Paradigm::ObjectOriented], 1_000_000),
    Language::new("Python", vec![Paradigm::ObjectOriented, Paradigm::Functional], 1_000_000),
];
}

Give an imperative solution to the task using nested for loops

#![allow(unused)]
fn main() {
fn five_best_func_lang1(lang_list: &Vec<Language>)->Vec<Language>{
    let mut fun_lang: Vec<Language> =   vec![];
    for l in lang_list {
        if l.paradigms.contains(&Paradigm::Functional){
            fun_lang.push(l.clone());
        }
    }
    //buble sort to sort the vector
    let mut changed = true;
    while changed {
        changed = false;
        for i in 1..fun_lang.len(){
            if fun_lang[i].nb_users > fun_lang[i-1].nb_users {
                fun_lang.swap(i,i-1);
                changed = true;
            }
        }
    }
         //Select the first five
    while fun_lang.len()>5 {
        fun_lang.remove(fun_lang.len()-1);
        }
    fun_lang 
    }
}

Give a more functional implementation by transforming the vector in an iterator and using the following method (see https://docs.rs/itertools/latest/itertools/trait.Itertools.html):

• use itertools::Itertools;

• into_iter() method transforms a Vector into an iterator

• filter() method can keep only element with a property (use a lambda as an argument to filter)

• sorted_by_key() sorts all iterator elements into a new iterator in ascending order (use Reverse())

• collect() transform an iterator into a collection.

#![allow(unused)]
fn main() {
fn five_best_func_lang2(lang_list: &Vec<Language>)->Vec<Language>{
      lang_list.into_iter()
            .sorted_by_key(|lang| lang.nb_users)
            .filter(|lang| lang.paradigms.contains(&Paradigm::Functional))
            .rev()
            .take(5)
            .cloned()
            .collect()
}
}

Which implementation is more efficient in terms of computation time?

-use std::time::Instant;

• Or (more complex) use criterion crate:

#![allow(unused)]
fn main() {
[dev-dependencies]
criterion = "0.5"
}

   let start = Instant::now();
   let l2 = five_functionnal_lang2(&languages);
   let t2 = start.elapsed();
   println!("func2: {:?}", t2);

• Pattern matching in Rust
  • Course: match statements
  • Course: match statements: "flexible" patterns
  • Course: Pattern summary
• The Result enum type
  • Course: Returning a Result from a function
  • Course: propagating Errors
  • Course: returning a Result from the main() function
  • Course: Handling Result types immediately
    • .unwrap(), .expect()
    • panic!, assert! and other macros
• The Option enum type
• Simple macros with macro_rules!
  • Course: Basic macro_rules! usage
    • Advantages of using macros
    • The different types of arguments (or fragment specifiers)
    • Matching a specific pattern
  • Course: pattern overloading
  • Course: pattern matching for macro_rules!

Pattern matching in Rust

Pattern matching is the act of checking a given sequence of tokens or expressions for the presence of one or more specific patterns. The concept is implemented in many programming languages (Rust, Haskell, Swift, etc.) and tools, for various purposes, such as: regular expressions, search and replace features, etc.

In Rust, patterns and pattern matching constitute a specific syntax, that is used in different places in the language (match statements, if let expressions, function parameters, simple macros, etc.)

A pattern consists of some combination of the following:

• Literals
• Destructured arrays, enums, structs, or tuples
• Variables
• Wildcards and Placeholders (most used: _ meaning Anything, and .. meaning The rest). A wildcard matches values; a placeholder stands in for something not yet specified (often a type).

Course: match statements

// C basic switch case:
enum Colors {
    Red, Blue, Green, Yellow, Orange
};

bool match_color_orange(Colors color) {
    switch (color) {
        case Orange: {
            printf("Orange!\n");
            return true;            
        }
        case Red:
        case Blue: {
            printf("Not orange :(\n"));
            return false
        }
        default: {
            printf("Still not orange\n");
            return false;
        }
    }
}

#![allow(unused)]
fn main() {
enum Colors {
    Red, Blue, Green, Yellow, Orange
}

fn match_color_orange(color: Colors) -> bool {
    match color {
        // 'case' statements are replaced by the
        // 'PATTERN => EXPRESSION' syntax:
        Colors::Orange => {
            println!("Orange!");
            true
        }
        // We use '|' operators here, instead of having 
        // multiple 'case' statements: 
        Colors::Red | Colors::Blue => {
            println!("Not orange :(");
            false
        }
        // Anything else (equivalent to 'default'):
        _ => {
            println!("Still not orange...");
            false
        }
    }
}
}

#![allow(unused)]
fn main() {
enum Colors { Red, Blue, Green, Yellow, Orange }

let color = Colors::Red;

let is_color_warm = match color {
    Colors::Orange => true,
       Colors::Red => true,
    Colors::Yellow => true,
                 _ => false
};
}

#![allow(unused)]
fn main() {
fn match_number(number: i32) {
    match number {
          50..=99 => println!("Between 50 and 99"),
       100..=1000 => println!("Between 100 and 1000"),
                _ => println!("Other value")
    }
}
}

#![allow(unused)]
fn main() {
fn match_str(s: &'static str) {
    match s {
        "Orange" => println!("Orange!"),
        "Yellow" => println!("Not orange"),
        _ => println!("Something else...")
    }
}
}

#![allow(unused)]
fn main() {
fn match_tup(tup: (i32, i32)) {
    match tup {
        (0, 0) => println!("Zeroes!"),
        (1, 1) => println!("Ones"),
        _ => println!("Something else...")
    }
}

match_tup((1, 1));
match_tup((0, 1));

fn match_array(arr: [u8; 3]) {
    match arr {
        [0, 1, 2] => println!("Array match!"),
                _ => println!("No match")
    }
}

match_array([0, 1, 2]);
match_array([4, 5, 6]);

fn match_slice(sl: &[i32]) {
    match sl {
        &[0, 1, 2] => println!("Slice matches!"),
                 _ => println!("No match")
    }
}

match_slice(&[0, 1, 2]);
}

Write a match statement which applies to any i32 number to check if it is lower than 100. It should only have the two following patterns:

1. The value is below 100 (including negative numbers);
2. The value is equal or higher than 100.

#![allow(unused)]
fn main() {
fn match_number(number: i32) {
    match number {
        ..100 => println!("Below a hundred"),
            _ => println!("A hundred or above")
    }
}
}

Course: match statements: "flexible" patterns

#![allow(unused)]
fn main() {
struct Point {
    x: isize,
    y: isize
}

let point = Point {x: 0, y: 100};

match point {
    // Only match Point if its 'x' member is equal to 0
    // and 'y' is equal to 100:
    Point {x: 0, y: 100} => println!("Match!"),
    _ => println!("No match!")
}
}

#![allow(unused)]
fn main() {
struct Point {
    x: isize,
    y: isize
}

let point = Point {x: 25, y: 100};
    
match point {
    // Only match if 'x' is between 0 and 100,
    // and 'y' is between 50 and 100
    Point {x: 0..=100, y: 50..=100} => println!("Match!"),
    _ => println!("No match!")
}
}

#![allow(unused)]
fn main() {
struct Point {
    x: isize,
    y: isize
}

let p = Point {x: 0, y: 100};
    
match p {
    // Only match if 'x' is between 0 and 100,
    // and ignore the 'y' field:
    Point {x: 0..=100, y: _} => println!("Match!"),
   // Only match if 'x' is between 101 and 1000,
    // Similarly, the '..' syntax will ignore all the struct fields after 'x':
    Point {x: 101..=1000, ..} => println!("Match!"),
    _ => println!("No match!")
}
}

#![allow(unused)]
fn main() {
let tup = (0, 1, 2, 3, 4);

match tup {
    // The first element of the tuple should be '0', and the last should be '4',
    // we ignore the values in-between:
    (0, .., 4) => println!("Match!"),
    _ => println!("No match")
}
}

Implement a match statement on a &[i32] slice. It should match all of the following patterns:

1. The slice's first value should be 0;
2. The slice's second value should be either 10 or 20;
3. The slice's final value should be 100;
4. The slice can have an arbitrary size.

You can use the following assert! statements to test your code:

#![allow(unused)]
fn main() {
fn match_slice(s: &[i32]) -> bool;

assert_eq!(match_slice(&[1, 20, 20, 30, 100]), false);
assert_eq!(match_slice(&[0, 5, 20, 30, 100]), false);
assert_eq!(match_slice(&[0, 10, 20, 30, 99]), false);
assert!(match_slice(&[0, 10, 20, 30, 40, 100]));
assert!(match_slice(&[0, 20, 20, 30, 50, 60, 70, 80, 90, 100]));
}

#![allow(unused)]
fn main() {
fn match_slice(s: &[i32]) -> bool {
    match s {
        &[0, 10 | 20, .., 100] => {
            println!("Match!");
            true
        }
        _ => {
            println!("No match!");
            false
        }
    }
}
assert_eq!(match_slice(&[1, 20, 20, 30, 100]), false);
assert_eq!(match_slice(&[0, 5, 20, 30, 100]), false);
assert_eq!(match_slice(&[0, 10, 20, 30, 99]), false);
assert!(match_slice(&[0, 10, 20, 30, 40, 100]));
assert!(match_slice(&[0, 20, 20, 30, 50, 60, 70, 80, 90, 100]));
}

Course: Pattern summary

The Result enum type

Course: Returning a Result from a function

#![allow(unused)]
fn main() {
enum Result<T, E> {
    Ok(T),
    Err(E)
}
}

#![allow(unused)]
fn main() {
// This function returns a u8 slice if there is no error, a Vec<f32> if there is.
// This is probably not very useful, but it's still perfectly valid code:
fn my_function(i: i32) -> Result<&[u8], Vec<f32>> {...} 

// This too (empty tuple type for both):
fn my_function(i: i32) -> Result<(),()> {
    Ok(())
} 
}

let u = my_function(3).unwrap(); 

Write a function called positive() that takes an i32 as argument and checks whether it is (strictly) positive. It should return the same argument value if it is positive, or a String with an error message if the argument is negative or equal to zero.

#![allow(unused)]
fn main() {
fn positive(i: i32) -> Result<i32, String> {
    if i > 0 {
        Ok(i)
    } else {
        Err(String::from("Argument is negative or == 0"))
    }
}
}

Course: propagating Errors

#![allow(unused)]
fn main() {
fn my_function(i: i32) -> Result<i32, ()> {...}

fn my_other_function() -> Result<i32, ()> {
    // Append the '?' operator right after the function call:
    let mut i = my_function(1)?;
    // Do something with 'i': 
    i += 1;
    // Return an 'Ok' result with the modified 'i' value:
    Ok(i)
}
}

#![allow(unused)]
fn main() {
fn my_other_function() -> Result<i32, ()> {
    let mut i = match my_function(1) {
        Ok(i) => i,
        Err() => return Err(())
    };
    i += 1;
    Ok(i)
}
}

Implement the same mechanism for the previous positive(i: i32) example, using the ? syntax, and test it with both positive and negative values in a new function with the same return type, in order to see what happens.

// Your 'positive' function:
fn positive(i: i32) -> Result<i32, String> {...}

// Define a new function, and call 'positive(...)' from here:
fn check_positive() -> Result<i32, String> {
    ... // <- test positive & negative values here using the '?' syntax
}

// Check the return type from main:
fn main() {
    println!("{:?}", check_positive());
}

fn positive(i: i32) -> Result<i32, String> {
    if i > 0 {
        Ok(i)
    } else {
        Err(String::from("Argument is negative or == 0"))
    }
}

fn check_positive() -> Result<i32, String> {
    let mut i = positive(1)?;
    i = positive(-1)?;
    Ok(i)
}

fn main() {
    println!("{:?}", check_positive());
}

Course: returning a Result from the main() function

int main(void) {
    // No error, return 0:
    return 0;
}

fn main() -> i32 {
    0
}

error[E0277]: `main` has invalid return type `i32`
 --> src/main.rs:3:14
  |
3 | fn main() -> i32 {
  |              ^^^ `main` can only return types that implement `Termination`
  |
  = help: consider using `()`, or a `Result`

#![allow(unused)]
fn main() {
impl Termination for Infallible;
impl Termination for !;
impl Termination for ();
impl Termination for ExitCode;
impl<T: Termination, E: Debug> Termination for Result<T, E>;
}

fn main() -> Result<i32, String> {
    Ok(0)
}

// Using an empty tuple as the 'Ok' result:
fn main() -> Result<(), String> {
    Ok(())
}

// Or using the ExitCode type:
use std::process::ExitCode;

fn main() -> Result<ExitCode, String> {
    Ok(ExitCode::from(0))
}

Using a valid Result type in the main() function, propagate the Result of our positive() function down to the main function which returns it.

fn positive(i: i32) -> Result<i32, String> {...}

fn check_positive() -> Result<i32, String> {...}

// Use a valid Result type here:
fn main() -> Result<?, ?>{
    // Call the 'check_positive' function here, and propagate its Result as the main() return type:
}

fn positive(i: i32) -> Result<i32, String> {
    if i > 0 {
        Ok(i)
    } else {
        Err(String::from("Argument is negative or == 0"))
    }
}

fn check_positive() -> Result<i32, String> {
    let mut i = positive(1)?;
    i = positive(-1)?;
    Ok(i)
}

fn main() -> Result<(), String> {
    check_positive()?;
    Ok(())
}

Course: Handling Result types immediately

#![allow(unused)]
fn main() {
// Get the current working directory:
let dir: std::path::PathBuf = std::env::current_dir().unwrap();
println!("{:?}", dir);
}

#![allow(unused)]
fn main() {
fn my_function() -> Result<(), i32> {
    Err(1)
}
my_function().expect("Error! Now exiting program with error code");
}

fn main() {
    use std::io;
    // Read input from stdin:
    let mut buffer = String::new();
    println!("Please enter password:");
    io::stdin().read_line(&mut buffer).unwrap();
    // Panic if password is not long enough:
    if buffer.len() < 8 {
        panic!("Password should be at least 8 characters");
    } else {
        println!("{buffer}");
    }
}

fn main() {
    use std::io;
    // Read input from stdin:
    let mut buffer = String::new();
    println!("Please enter password:");
    io::stdin().read_line(&mut buffer).unwrap();

    // We assert that the password is at least 8 characters
    // This will cause a 'panic' if the assertion is false:
    assert!(buffer.len() >= 8, "Password should be at least 8 characters");

    // Here, we forbidden choosing 'password' as a password:
    assert_ne!(buffer.trim(), "password", "Choosing 'password' as password is unsafe.");
}

The Option enum type

#![allow(unused)]
fn main() {
pub enum Option<T> {
    None, 
    Some(T)
}
}

#![allow(unused)]
fn main() {
struct MyContact {
    name: &'static str,
 address: &'static str,
   email: Option<&'static str>,
   phone: Option<&'static str>,
}

let mut list: Vec<MyContact> = Vec::new();
list.push(MyContact {
       name: "Marlo Stanfield",
    address: "2601 E Baltimore St, Baltimore, MD 21224",
      email: None,
      phone: Some("+1 410-915-0909")
});
}

#![allow(unused)]
fn main() {
for contact in list {
    match (contact.email, contact.phone) {
        // Both e-mail and phone are available:
        (Some(email), Some(phone)) => {
            if is_email_correct(email) {
                contact_by_email(email);
            } else {
                contact_by_phone(phone);
            }
        }
        // Only e-mail is available:
        (Some(email), None) => {
            contact_by_email(email);
        }
        // Only phone is available:
        (None, Some(phone)) => {
            contact_by_phone(phone);
        }
        // Neither phone nor email:
        (None, None) => {
            send_mail_to_address(contact.address);
        }
    }
}
}

#![allow(unused)]
fn main() {
fn money_left() -> Option<i32>;
money_left().expect("No money left :(");
}

Using the previous contact list example, implement a small database of books that would be used by a library. It should have a search_book(...) function which searches for a specific book using its name and/or the name of the author (we assume here that there's only one book per author). The function should return a reference to the Book object if it has been found, or None otherwise.

#![allow(unused)]
fn main() {
struct Book {
      name: String,
    author: String,
}

#[derive(Default)]
struct LibraryDatabase {
    books: Vec<Book>
}

impl LibraryDatabase {
    // The function to implement:
    fn search_book(&self, 
        name: Option<&'static str>, 
        author: Option<&'static str>
    ) -> Option<&Book> {...}
}
}

You can use the following #[test] function to verify your code:

#![allow(unused)]
fn main() {
#[test]
fn test() {
    let mut database = LibraryDatabase::default();
    database.books.push(Book { name: String::from("Peter Pan"), author: String::from("Barrie")});

    assert!(database.search_book(Some("Peter Pan"), None).is_some());
    assert!(database.search_book(None, Some("Barrie")).is_some());
    assert!(database.search_book(None, None).is_none());
    assert!(database.search_book(Some("Barrie"), None).is_none());
    assert!(database.search_book(None, Some("Peter Pan")).is_none());
    assert!(database.search_book(Some("Alice in Wonderland"), Some("Barrie")).is_none());
    assert!(database.search_book(Some("Peter Pan"), Some("Lewis Carroll")).is_none());
}
}

#![allow(unused)]
fn main() {
impl LibraryDatabase {
    fn search_book(&self, 
          name: Option<&'static str>, 
        author: Option<&'static str>) -> Option<&Book> {
            match (name, author) {
                (Some(n), Some(a)) => {
                    self.books.iter().find(|e| e.name == n && e.author == a)
                }
                (Some(n), None) => {
                    self.books.iter().find(|e| e.name == n)
                }
                (None, Some(a)) => {
                    self.books.iter().find(|e| e.author == a)
                }
                (None, None) => None
            }
    }
}
}

Using Result, Option and all the previous examples, create a program which parses a password, with the following rules:

• Password must:
  • be at least 8 characters long;
  • should contain at least one of these special characters: !, ? or _;
  • should contain at least one number;
  • should not contain any whitespace.
• A specific error message should be displayed for each rule.

hint: in order to chain the tests in a functionnal way, one can use the then_some(self, value T) called on a bool that returns value if the bool is true, or ok_or<E>(self, err: E) that can transform an Option in a Result.

Note: in order to verify your program, you can implement a #[test] function, such as:

#![allow(unused)]
fn main() {
#[test]
fn password_test() {
    let pwd0 = String::from("pass");
    let pwd1 = String::from("password");
    let pwd2 = String::from("password!");
    let pwd3 = String::from("pass word!");
    let pwd4 = String::from("password!1");
    assert!(parse_password(&pwd0).is_err());
    assert!(parse_password(&pwd1).is_err());
    assert!(parse_password(&pwd2).is_err());
    assert!(parse_password(&pwd3).is_err());
    assert!(parse_password(&pwd4).is_ok());
}
}

and then run cargo test on your program.

use std::io;

fn parse_password(buffer: &String) -> Result<(), &'static str> {
    buffer
        .len().ge(&8)
        .then_some(&buffer).ok_or(
            "Password should at least contain 8 characters"
        )?
        .chars().all(|c| !char::is_whitespace(c))
        .then_some(&buffer).ok_or(
            "Password should not contain any whitespace"
        )?
        .contains(|c: char| c.eq(&'?') | c.eq(&'!') | c.eq(&'_'))
        .then_some(&buffer).ok_or(
            "Password should contain at least 1 special character"
        )?
        .contains(char::is_numeric)
        .then_some(&buffer).ok_or(
            "Password should contain at least 1 number"
        )?;
    Ok(())
}
fn main() -> Result<(), &'static str> {
    let mut buffer = String::new();
    println!("Please enter password:");
    io::stdin().read_line(&mut buffer).expect(
        "Error reading password!"
    );
    // Remove the ending character:
    buffer.pop();
    parse_password(&mut buffer)?;
    println!("Success!");
    Ok(())
}

Simple macros with macro_rules!

Unlike other programming languages, such as C or C++, Rust's macro system is based on abstract syntax trees (AST), instead of string preprocessing, which makes them a bit more complex to use, but also more reliable and powerful. macros are expanded before the compiler interprets the meaning of the code. The difference between a macro and a function is that macro definitions are more complex than function definitions because you’re writing Rust code that writes Rust code. Due to this indirection, macro definitions are generally more difficult to read, understand, and maintain than function definitions.

Throughout this course, we have already encoutered a few of them, including vec!, panic!, assert!, and of course println!. These macros are defined by the macro!(...) syntax (don't forget the trailling exclamation mark) and are called simple macros, as opposed to Rust's more complex macro systems, such as attribute macros (for instance the #[test] function attribute), and derive macros (the #[derive(Debug)] statement on top of a struct), which we have already both seen as well.

Course: Basic macro_rules! usage

#![allow(unused)]
fn main() {
macro_rules! hello_world {
    () => {
        println!("Hello World!")
    };
}

hello_world!();
}

#![allow(unused)]
fn main() {
let v1 = vec![1, 2, 3, 4, 5];
let v2 = vec!();
let v3 = vec![1];
}

#![allow(unused)]
fn main() {
let v1 = <[_]>::into_vec(Box::new([1, 2, 3, 4, 5]));
let v2 = Vec::new<i32>();
let v3 = std::vec::from_elem(1, 1);
}

#![allow(unused)]
fn main() {
macro_rules! define_fn {
    ($fn_name:ident) => {
        fn $fn_name() {
            println!(
                "This function's name (ident) is: '{}()'.", 
                stringify!($fn_name)
            );
        }
    }
}
define_fn!(foo);
define_fn!(bar);
foo();
bar();
}

#![allow(unused)]
fn main() {
($fn_name:ident) => {
}

#![allow(unused)]
fn main() {
fn $fn_name() {
}

#![allow(unused)]
fn main() {
println!(
    "This function's name (ident) is: '{}()'.", 
    stringify!($fn_name)
);
}

What would be the generated code for the define_fn!(foo) macro call?

#![allow(unused)]
fn main() {
fn foo() {
    println!(
        "This function's name (ident) is: '{}()'.",
        stringify!(foo)
    );
}
}

Create a similar macro, but this time the generated code should define a struct and its impl block like the following:

#![allow(unused)]
fn main() {
// All of this code should be generated by our new macro,
// but the name 'Foo' should be made variable:
struct Foo {
    print: &'static str
}
impl Foo {
    fn new() -> Foo {
        Foo { 
            print: "Foo" 
        }
    }
}
}

#![allow(unused)]
fn main() {
// The macro to implement:
macro_rules! define_struct { 
    ... 
}

// Use the following to verify that the macro is correct:
define_struct!(Foo);

let bar = Foo::new();
assert_eq!(bar.print, "Foo");
}

#![allow(unused)]
fn main() {
macro_rules! define_struct {
    ($name:ident) => {
        struct $name {
            print: &'static str
        }        
        impl $name {
            fn new() -> $name {
                $name {
                    print: stringify!($name)
                }
            }
        }
    }
}
define_struct!(Foo);
let bar = Foo::new();
assert_eq!(bar.print, "Foo");

}

Course: pattern overloading

#![allow(unused)]
fn main() {
macro_rules! define_fn {
    ($fn_name:ident) => {
        fn $fn_name() {
            println!(
                "This function's name (ident) is: '{}()'.", 
                stringify!($fn_name)
            );
        }
    }; // <-- pattern blocks must end with a semicolon if they're followed by other blocks
    
    // Our new pattern:
    ($fn_name:ident, $additional_code:expr) => {
        fn $fn_name() {
            println!(
                "This function's name (ident) is: '{}()'.", 
                stringify!($fn_name)
            );
            // Append the additional code 'expr' at the end of the defined fn:
            $additional_code
        }
    }
}
define_fn!(foo);
define_fn!(bar, println!("Additional code"));
foo();
bar();
}

In our previous example, try replacing the ',' symbol between $fn_name:ident and $additional_code:expr with another symbol (e.g. + or *). Then, call the define_fn! macro with two arguments separated by the same new symbol, and see what it does.

#![allow(unused)]
fn main() {
macro_rules! define_fn {
    ($fn_name:ident) => {
        fn $fn_name() {
            println!(
                "This function's name (ident) is: '{}()'.", 
                stringify!($fn_name)
            );
        }
    };
    // Here, we replace it with the '+' symbol:
    ($fn_name:ident + $additional_code:expr) => {
        fn $fn_name() {
            println!(
                "This function's name (ident) is: '{}()'.", 
                stringify!($fn_name)
            );
            $additional_code
        }
    }
}
define_fn!(foo);
define_fn!(bar + println!("Additional code"));
foo();
bar();
}

Course: pattern matching for macro_rules!

#![allow(unused)]
fn main() {
let mut max = std::cmp::max(1, 2);
max = std::cmp::max(max, 3);
max = std::cmp::max(max, 4);
max = std::cmp::max(max, 5);
}

#![allow(unused)]
fn main() {
max!(1, 2, 3, 4, 5, 6*7, 3*4);
}

#![allow(unused)]
fn main() {
macro_rules! max {
    // Only one argument 'x', return 'x':
    ($x:expr) => {$x};
    // At least two arguments, 
    // - 'x' being the first,
    // - 'y' being one or more additional argument(s),
    // which is defined by the '$(...),+' syntax:
    ($x:expr, $($y:expr),+) => {
        // We recursively call 'max!' on the tail 'y'
        std::cmp::max($x, max!($($y),+))
    }
}
}

#![allow(unused)]
fn main() {
max!(1);
}

#![allow(unused)]
fn main() {
max!(1, 2); // expands to:
std::cmp::max(1, max!(2)); // expands to:
std::cmp::max(1, 2);
}

#![allow(unused)]
fn main() {
max!(1, 2, 3); // expands to:
std::cmp::max(1, max!(2, 3)); // expands to:
std::cmp::max(1, std::cmp::max(2, max!(3))); // expands to:
std::cmp::max(1, std::cmp::max(2, 3));
}

Bonus: Transform our previous define_struct! example into a more elaborated macro. It should now have the following interface: at least one member (bar), 0 ore some methods

#![allow(unused)]
fn main() {
// Define the struct 'Foo':
define_struct!(
    name: Foo,
    members: {
        bar: i32
    }
    methods: {
        fn hello() {
            println!("hello!")
        }
        fn bar(&self) {
            println!("{}", self.bar);
        }
    }
);
// Instantiate the struct 'Foo':
let f = Foo::default();
// Call its bar method:
f.bar();
// Or its static 'hello' method:
Foo::hello();
}

#![allow(unused)]
fn main() {
macro_rules! define_struct {
    (
        name: $name:ident, 
        members: { $($field:ident : $type:ty),* } 
        methods: { $($meth:tt)* }
    ) => {
        #[derive(Default)]
        struct $name {
            $($field : $type),*
        }
        impl $name {
            $($meth)*
        }      
    };
}
}

Bonus: Add a nested macro_rules! definition into define_struct! which allows to copy the members and methods of the defined struct into a new different one, such as:

#![allow(unused)]
fn main() {
// Define Foo struct:
define_struct!(
    name: Foo,
    members: {
        bar: i32
    }
    methods: {
        fn hello() {
            println!("hello!")
        }
        fn bar(&self) {
            println!("{}", self.bar);
        }
    }
);

// The define_struct! macro should define a new 'Foo!' macro,
// which allows copying the members and methods of 'Foo' into another new struct:
Foo!(FooCopy);

let c = FooCopy::default();
c.bar();
FooCopy::hello();
}

#![allow(unused)]
fn main() {
macro_rules! define_struct {
    (
        name: $name:ident, 
        members: { $($field:ident : $type:ty),* } 
        methods: { $($meth:tt)* }
    ) => {
        #[derive(Default)]
        struct $name {
            $($field : $type),*
        }
        impl $name {
            $($meth)*
        }      
        macro_rules! $name {
            ($copy:ident) => {
                #[derive(Default)]
                struct $copy {
                    $($field : $type),*                    
                }
                impl $copy {
                    $($meth)*
                }      
            }
        }
    };
}
}

• Introduction
• Using Threads and Closures to Run Code Simultaneously
  • Course: Closures
    • Borrowed captures
    • Moved captures
  • Course: Passing closures as objects or arguments
  • Course: Spawning Threads using Closures
• Sharing data safely between threads
  • Using Shared State data sets
    • Course: Exclusive access with Mutexes
    • Course: Reference Counted Mutexes
    • Course: Lock-free data sharing with Atomics
  • Using Message passing to transfer data between threads
• Asynchronous programming
  • Futures and await: the Async syntax
    • Futures and .await
    • Async execution contexts
    • Async runtimes
    • Spawning concurrent tasks
    • Shared states & Message passing
    • Async and networking

Introduction

Modern CPU architectures offer many ways to run high-performance programs. The most obvious is threading: because most CPUs have multiple cores, threads can be executed in parallel. A thread is a standard abstraction available in most programming languages and managed by the operating system. The Rust thread API is presented in Section 2, and the common tools used for distributed programming are presented in Section 3.

Another way to handle parallel tasks is to use concurrency, i.e., having a single process or thread switch between different tasks, so that no time is wasted when a task is idle. Rust provides the async mode to support concurrency. In async mode, Rust launches a runtime (sometimes called an executor) that can interrupt idle tasks and schedule tasks that are ready to run. The async model may use threading if the runtime is multithreaded by it is transparent to the programmer, conceptually it runs sequentially and implements a hidden state machine that regularly polls suspended tasks to determine whether they can resume. Several runtimes exist that support the async model. The most widely used is Tokio, which is introduced in Section 3.

Using Threads and Closures to Run Code Simultaneously

Course: Closures

#![allow(unused)]
fn main() {
// Define a closure and store it into a variable:
let my_closure = |x: i32| -> i32 {
    println!("my_closure");
    x*2
};

// Execute the closure like you would normally do with a function:
let y = my_closure(2);
println!("{y}");
}

#![allow(unused)]
fn main() {
let x = 2;

let my_closure = || -> i32 {
    // Use a borrowed (immutable) capture of 'x', 
    // and return two times its value:
    x*2
};

println!("{}", my_closure());
}

#![allow(unused)]
fn main() {
// Same, but this time, we modify 'x' directly in the closure:
let mut x = 2;

// The closure itself also has to be made 'mutable' 
// in the case of a mutable borrow:
let mut my_closure_mut = || x *= 2;

my_closure_mut();
println!("{x}");
}

#![allow(unused)]
fn main() {
let mut x = 2;

// Capturing 'x' by value. Here, it is made with a simple copy:
let mut my_closure_mut = move || {
    x *= 2;
    println!("x (closure): {x}");
};

my_closure_mut();
println!("x: {x}");
}

Why is the following code invalid? How can we solve the issue?

#![allow(unused)]
fn main() {
let mut x = vec![31, 47, 27, 16];

let mut my_closure_mut = move || {
    x.push(32);
    println!("{:?}", x);
};

my_closure_mut();
println!("{:?}", x);
}

#![allow(unused)]
fn main() {
let mut x = vec![31, 47, 27, 16];

let mut my_closure_mut = || x.push(32);

my_closure_mut();
println!("{:?}", x);
}

#![allow(unused)]
fn main() {
let mut x = vec![31, 47, 27, 16];
let mut x2 = x.clone();

let mut my_closure_mut = move || {
    x2.push(32);
    x2
};

x = my_closure_mut();
println!("{:?}", x);
}

Course: Passing closures as objects or arguments

#![allow(unused)]
fn main() {
// Utility function that prints out the type of a variable:
fn print_type_of<T>(_: &T) {
    println!("Type of my closure: {}", std::any::type_name::<T>());
}

let my_closure = |x: i32| -> i32 {
    x*2
};

print_type_of(&my_closure);
}

#![allow(unused)]
fn main() {
// All of the 'Fn' traits have the format:
// 'Fn(argument-types) -> return types'
fn exec_closure(x: i32, closure: impl Fn(i32) -> i32) -> i32 {
    closure(x)
}

let c = |x: i32| x + 27;
let r = exec_closure(31, c);

println!("{r}");
}

#![allow(unused)]
fn main() {
fn exec_closure<T>(x: i32, closure: T) -> i32 
where 
    T: Fn(i32) -> i32 
{
    closure(x)
}
let c = |x: i32| x + 27;
let r = exec_closure(31, c);

println!("{r}");
}

Using the generic form, store the following chirp_fn closure as a member of the struct Bird, with a valid type signature:

let chirp_fn = |times: i32| {
    for _ in 0..times {
        println!("chirp!");
    }
}

// The struct to implement (use generics!):
struct Bird<...> { 
    chirp: ... 
}

// Create a new instance of 'Bird' with the chirp_fn closure:
let bird = Bird { chirp: chirp_fn };

// Call the 'chirp' closure from inside the struct:
// operator precedence priority can be found here: https://doc.rust-lang.org/reference/expressions.html
(bird.chirp)(10);

#![allow(unused)]
fn main() {
struct Bird<F> 
where
    F: Fn(i32) -> ()
{
    chirp: F,
}

let chirp_fn = |times: i32| {
    for _ in 0..times {
        println!("chirp!");
    }
};

let bird = Bird { chirp: chirp_fn };
(bird.chirp)(10);
}

Course: Spawning Threads using Closures

#![allow(unused)]
fn main() {
// Spawn a new thread which will execute its given closure:
std::thread::spawn(|| {
    println!("Thread 1: chirp!");
});
// At the 'same time', print something from the main thread:
println!("Main thread: chirp chirp!");
}

#![allow(unused)]
fn main() {
// Bind the thread's "handle" to a variable:
let th = std::thread::spawn(|| {
    println!("Thread 1: chirp!");
});

println!("Main thread: chirp chirp!");

// Wait for 'th' to finish executing, and re-synchronise both threads:
th.join().unwrap();
}

The following code prints a modified value of variable var from 3 different threads, running independently from one another. Is the code safe? Can you guess what will be the resulting output?

use std::thread;
let mut var = 32;

let t1 = thread::spawn(move || {
    var += 1;
    println!("Thread 1: reading value {}!", var);
});

let t2 = thread::spawn(move || {
    var += 2;
    println!("Thread 2: reading value {}!", var);
});

var += 3;
println!("Main thread: reading value {}", var);

// Re-synchronise both threads:
t1.join().unwrap();
t2.join().unwrap();

Main thread: reading value 35
Thread 1: reading value 33!
Thread 2: reading value 34!

What would happen if we removed all the move keywords from the code?

Sharing data safely between threads

Using Shared State data sets

Course: Exclusive access with Mutexes

#![allow(unused)]
fn main() {
use std::sync::Mutex;
// Instantiate a new Mutex<i32> instance with the value '32':
let var: Mutex<i32> = Mutex::new(32);
{
    // Acquire the mutex's lock (and panic in case of failure):
    let mut v = var.lock().unwrap();
    // Modify the value safely:
    *v += 32;
}
// Print the result:
println!("var = {var:?}");
}

In the following example, we want to try to use a Mutex to get both threads to use and modify var, but the compiler doesn't allow it, what is the underlying issue here?

#![allow(unused)]
fn main() {
use std::thread;

let mut var = 32;

let t1 = thread::spawn(move || {
    var += 1;
});

let t2 = thread::spawn(move || {
    var += 2;
});
// Re-synchronise both threads:
t1.join().unwrap();
t2.join().unwrap();

println!("Result: {var}");
}

#![allow(unused)]
fn main() {
use std::thread;
use std::sync::Mutex;
let mtx = Mutex::new(32);
    
let t1 = thread::spawn(move || {
    let mut v = mtx.lock().unwrap();
    *v += 1;
});
    
let t2 = thread::spawn(move || {
    let mut v = mtx.lock().unwrap();
    *v += 2;
});
// Re-synchronise both threads:
t1.join().unwrap();
t2.join().unwrap();
    
println!("Result: {mtx:?}");
}

Course: Reference Counted Mutexes

#![allow(unused)]
fn main() {
use std::thread;
use std::sync::{Arc, Mutex};

// We wrap the Mutex in a Atomically Reference-Counted object:
let arc = Arc::new(Mutex::new(32));

// We prepare two clones, for moving into the two distinct closures:
let rc1 = Arc::clone(&arc);
let rc2 = Arc::clone(&arc);

let t1 = thread::spawn(move || {
    let mut v = rc1.lock().unwrap();
    *v += 1;
});

let t2 = thread::spawn(move || {
    let mut v = rc2.lock().unwrap();
    *v += 2;
});

// Re-synchronise both threads:
t1.join().unwrap();
t2.join().unwrap();

println!("Result: {arc:?}");
}

If an Arc object is sufficient to provide multiple ownership and thread-safe access to data, why do we still need a Mutex guarding our data?

Course: Lock-free data sharing with Atomics

#![allow(unused)]
fn main() {
use std::thread;
use std::sync::Arc;
use std::sync::atomic::AtomicI32;
use std::sync::atomic::Ordering;

// We replace 'Mutex::new()' with the following:
let arc = Arc::new(AtomicI32::new(32));
let rc1 = Arc::clone(&arc);
let rc2 = Arc::clone(&arc);

let t1 = thread::spawn(move || {
    // Acquire underlying data as a copy:
    let mut v = rc1.load(Ordering::Acquire);
    // Modify the copy:
    v += 1;
    // Update the value atomically, release the lock:
    rc1.store(v, Ordering::Release);
});

let t2 = thread::spawn(move || {
    // Another (more compact) way of doing this:
    rc2.fetch_add(2, Ordering::AcqRel);
});
// Re-synchronise both threads:
t1.join().unwrap();
t2.join().unwrap();

println!("Result: {arc:?}");
}

Using Message passing to transfer data between threads

#![allow(unused)]
fn main() {
// Create a 'data channel' between a Sender `tx`, and a Receiver `rx`:  
let (tx, rx) = std::sync::mpsc::channel::<i32>();

// Send the values `32` and then `16` through the channel:
tx.send(32).unwrap();
tx.send(16).unwrap();

// Poll the channel, read data if available:
println!("n = {}", rx.recv().unwrap());
println!("n = {}", rx.recv().unwrap());
}

#![allow(unused)]
fn main() {
use std::thread;
use std::sync::mpsc;
let (tx, rx) = mpsc::channel();

// Do the same thing in a separate thread:
let th = thread::spawn(move || {
    tx.send(32).unwrap();
    tx.send(16).unwrap();
});

th.join();

// Poll the channel, read data if available:
println!("n = {}", rx.recv().unwrap());
println!("n = {}", rx.recv().unwrap());
}

#![allow(unused)]
fn main() {
use std::thread;
use std::sync::mpsc;

let (tx, rx) = mpsc::channel();
let mut vec = Vec::new();

for n in 0..8 {
    // Clone the Sender `tx` for each thread:
    let tx = tx.clone();
    vec.push(thread::spawn(move || {
        tx.send(n).unwrap();
    }));
}
for t in vec {
    t.join().unwrap();
}
for _ in 0..8 {
    // Consume the FIFO value-by-value:
    let value = rx.recv().unwrap();
    println!("Received value: {}", value);
}
}

Using an mpsc::channel, an Arc<T> and a Mutex (or an Atomic), implement a program which creates and run two independent threads:

• A producer thread which continuously counts from 0 to infinity.
• A consumer thread which continuously reads and prints the count produced by the producer thread.
• The two threads should run for 5 seconds and then stop.
• Hint: you can use thread::sleep to pause a thread for a certain amount of time.

#![allow(unused)]
fn main() {
use std::thread;
use std::sync::mpsc;
use std::sync::Arc;
use std::sync::atomic::Ordering;
use std::sync::atomic::AtomicBool;
use std::time::Duration;

let (tx, rx) = mpsc::channel();
let running = Arc::new(AtomicBool::new(true));
let run_arc1 = running.clone();
let run_arc2 = running.clone();

let pth = thread::spawn(move || {
    let mut n = 0;
    while run_arc1.load(Ordering::Acquire) {
        n += 1;
        tx.send(n).unwrap();
        println!("Sending value: {n}");
    }
});
let cth = thread::spawn(move || {
    while run_arc2.load(Ordering::Acquire) {
        match rx.try_recv() {
            Ok(v) => {
                println!("Received value: {v}");
            }
            Err(..) => ()
        }
    }
});
thread::sleep(Duration::from_secs(5));
running.store(false, Ordering::Release);
pth.join().unwrap();
cth.join().unwrap();
}

Asynchronous programming

While programming with threads is a perfectly valid way of implementing concurrent programming, it also has a few disadvantages, such as having to rely on operating system scheduling, as well as sometimes making the code difficult to re-use or modify. To address these issues, programmers came up with a new way of structuring a program in a different set of tasks (whether they are independent, concurrent, or sequential), which has been called asynchronous programming.

Code within a thread is written in sequential style and the operating system executes them concurrently. With asynchronous programming, concurrency happens entirely within a program: the operating system is not involved, making context switch faster, and memory overhead also lower. By being natively integrated into a programming language, which is the case with Rust, it also makes control flow more flexible and expressive.

Futures and await: the Async syntax

Rust relies on two keywords async and await, as well as a few underlying concepts (such as futures) to implement asynchronous programming within the language.

Futures and .await

#![allow(unused)]
fn main() {
// in std::future module
pub trait Future {
    type Output;

    // Required method:
    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>;
}
}

#![allow(unused)]
fn main() {
let result = some_future.await;
}

#![allow(unused)]
fn main() {
let result = match unsafe {Pin::new_unchecked(&mut some_future)}.poll(cx) {
    Poll::Ready(val) => val,
    Poll::Pending => return Poll::Pending
}
}

Async execution contexts

#![allow(unused)]
fn main() {
async fn some_fn() {
    let result = some_future.await;
}
}

#![allow(unused)]
fn main() {
fn some_fn() -> impl Future<Output = ()> {
    async move {
        let result = some_future.await;
    }
}
}

async fn some_fn() {
    let result = some_future.await;
}

async fn main() {
    some_fn().await;
}

async fn some_fn() {
    // async code...
}

// The main function has to be annotated
// in order to be async compatible:
#[tokio::main]
async fn main() {
    some_fn().await;
}

Try to implement the "equivalent" program with async/await:

use std::thread::{sleep, spawn};
use std::time::Duration;

fn count_to(N: i32) {
    for n in 1..=N {
        println!("{n}");
        sleep(Duration::from_secs(1));
    }
}
fn main() {
    let t1 = spawn(|| { count_to(5) });
    t1.join().unwrap();
    println!("joined!");
}

use tokio::{spawn, time::{sleep, Duration}};

async fn count_to(N: i32) {
    for n in 1..=N {
        println!("{n}");
        sleep(Duration::from_secs(1)).await;
    }
}

#[tokio::main]
async fn main() {
    count_to(5).await;
    println!("joined!");
}

Spawning concurrent tasks

#[tokio::main]
async fn main() {
    tokio::spawn(async move {
        my_async_fn("first task").await;
    });
    tokio::spawn(async move {
        my_async_fn("second parallel task").await;
    });
}

Try now to wrap our previous count_to(5).await function call inside tokio::spawn as a closure. Notice anything? What is the problem here? How can we fix it?

use tokio::{spawn, time::{sleep, Duration}};

async fn count_to(N: i32) {
    for n in 1..=N {
        println!("{n}");
        sleep(Duration::from_secs(1)).await;
    }
}

#[tokio::main]
async fn main() {
    tokio::spawn(async move {
        count_to(5).await;
    }).await.unwrap();
    println!("joined!");
}

Let's now improve our count_to function by setting the sleep duration as a variable parameter, and add a start offset as well. We could do this for instance by using a std::ops::Range instead of a i32 for the parameter N:

#![allow(unused)]
fn main() {
async fn count_to(R: Range<i32>, sleep_dur: Duration) {...}
}

Implement the modified version of the function, and its usage inside the main function. Try to also spawn another function call with different parameters. Are the two tasks now running in parallel?

use std::ops::Range;

use tokio::{join, spawn, time::{Duration, sleep}};

async fn count_to(R: Range<i32>, sleep_dur: Duration) {
    for n in R {
        println!("{n}");
        sleep(sleep_dur).await;
    }
}

#[tokio::main]
async fn main() {
    // We remove the .await.unwrap() calls,
    // so that the tasks can be joined afterwards together:
    let task_1 = tokio::spawn(async move {
        count_to(0..5, Duration::from_secs(2)).await;
    });
    let task_2 = tokio::spawn(async move {
        count_to(5..10, Duration::from_secs(1)).await;
    });
    let (t1, t2) = join!(task_1, task_2);
    t1.unwrap();
    t2.unwrap();
    println!("joined!");
}

Shared states & Message passing

Transform the counter example by using tokio (with a mutex or with channels) to share the count of one task with another

use tokio::{join, sync::mpsc, time::{Duration, sleep}};

#[tokio::main]
async fn main() {
    let (tx, mut rx) = mpsc::channel::<i32>(10);
    let task_1 = tokio::spawn(async move {
        for n in 0..5 {
            tx.send(n).await.unwrap();
            sleep(Duration::from_secs(1)).await;
        }
    });
    let task_2 = tokio::spawn(async move {
        loop {
            if rx.is_closed() {
                break;
            }
            match rx.recv().await {
                Some(n) => {
                    println!("Counting: {n}");
                }
                _ => ()
            }
        }
    });
    let (t1, t2) = join!(task_1, task_2);
    t1.unwrap();
    t2.unwrap();
    println!("joined!");
}

Async and networking

use std::error::Error;
use tokio::{net::{TcpListener, TcpStream}};

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let addr = "127.0.0.1:8047";
    // Bind a TCP listener to addr:
    let listener = TcpListener::bind(addr).await?;

    let streams = tokio::spawn(async move {
        // Connect to same addr:
        TcpStream::connect(addr)
            .await
            .unwrap();
        println!("Connected!");
    });
    // Wait for a client to connect:
    let (..) = listener.accept().await?;
    streams.await?;
    Ok(())
}

With help from the example above and the tokio tutorial and documentation, write a simple echo example between a TCP server and a single client.

use std::error::Error;
use tokio::{io::{AsyncReadExt, AsyncWriteExt}, net::{TcpListener, TcpStream}};

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let addr = "127.0.0.1:8047";
    // Bind a TCP listener to addr:
    let listener = TcpListener::bind(addr).await?;

    let streams = tokio::spawn(async move {
        let mut stream = TcpStream::connect(addr)
            .await
            .unwrap();
        let mut buf = vec![0; 128];
        loop {
            let n = stream.read(&mut buf).await.unwrap();
            if n == 0 {
                break;
            }
            println!("Received {:?}", String::from_utf8_lossy(&buf[..n]));
        }
    });
    // Wait for a client to connect:
    let (mut socket, ..) = listener.accept().await?;
    tokio::spawn(async move {
        socket.write_all(b"echo!\n").await.unwrap(); 
    });
    streams.await?;
    Ok(())
}

Project Rules

• The project can be for a single student, or a group of at most 2 students
• The Rust code should be written by you, it means:
  • no copy/paste from existing code
  • LLM help is OK but only for correcting a code that you wrote
• The projet should illustrate one or several Rust concept or mechanism
• An open source github repository should be set up for the project and communicated to the teacher. This git repository will be used by the teacher to follow project evolution

Project life

• The project is first validated by teachers
• Teachers will not answer questions by mail, they will answer questions during course slots.
• During the project period, students are free to develop whenever and wherever they want: teacher will be present at course slots but student presence is not mandatory, except for Final Project presentation : Wednesday 21/01/2026 14h-18h
• There will be a Mid-term project check on Wednesday 14/10/2026 14h-16h at that point you should have send us your github site and a roadmap (text of 1/2 page) for your project

Evaluation

• The final presentation (Wednesday 21/01/2026 14h-18h) should take 15mn per project:

  • 4-6 mn slide presentation
  • 4-6 mn demo
  • 4-6 mn questions (from teachers and other students)

• The project will be evaluated following criteria:

  • Amount of work estimated
  • Overall quality of the code and the demo
  • Code readability and documentation
  • Adequation between the announced project and the final result
  • Quality of the final presentation

• During the slide presentation, we do not need a very complete presentation of the code (we can see it on the github site), we need a description of the application, of the Rust crates used and we except you to give you feeling about what's different with Rust:

  • What helped you?
  • What were the obstacles?
  • What did you like?
  • What did you not like?
  • Will Rust become you favourite language?

A few audio examples:

• Audio example with the jack crate: https://gitlab.inria.fr/emeraude/5tc-rust/-/tree/main/audio-examples?ref_type=heads
• Audio & network example with cxx-juce: https://gitlab.inria.fr/emeraude/5tc-rust/-/tree/main/network-examples?ref_type=heads

Example of Project ideas

Networking (Crates: tokio, websocket, ...)

• Chat system in Rust
• peer-to-peer in Rust

Audio (Crates: cpal, jack (linux), cxx-juce, portaudio, ...ask us!)

• Audio streaming in Rust
• Synthesizer/effect in Rust

GUI/TUI (Crates: egui, dioxus, cxx-qt, ratatui, cursive)

• Web app with UI
• Gome with UI

Benchmark (Crates: criterion, divan, hyperfine, ...)

• compare Rust and C performance
• efficiency of thread vs. Async

Explore Rust Crates

• provide pedagogical use of original Crates

Document design

• inspired from typst

Useful Rust Audio Crates

Audio backend crates

How audio works (in a nutshell...)

Usually, when working with audio, whether it's with Rust or any other programming language, you need an interface with OS audio drivers, which are usually wrapped into higher-level libraries, such as JACK, or PortAudio. They all have usually similar APIs, based on audio callbacks.

Audio callbacks

Real-time audio is tightly time-constrained, a continuous audio stream in stereo for instance usually needs 44100 (or 48000, or higher) audio samples (values) per second in order to be viable. In order to achieve this, audio is usually processed or synthesized in buffers (usually 512 samples or lower), to be more efficient. The APIs of most audio backend libraries provide buffer-based audio callback interfaces that will give you an input buffer, an output buffer, or both (duplex). In this callback, you can for example read a buffer of audio inputs (usually a f32 slice) that's given to you by the backend, and write it back to the audio output buffer after you've done your processing:

#![allow(unused)]
fn main() {
// a passthrough example, 
// If our sample-rate is 48000 Hz, and our buffer-sizer is 128 samples,
// then our function is going to be called 375 times in one second:
let my_callback = |inputs: &[f32], outputs: &mut[f32]| {
    for s in inputs.len() {
        outputs[s] = inputs[s];
    }
}
}

Which backend crate should I use?

If you're on Linux, JACK is probably the easiest and most efficient in terms of performance. Otherwise, for other platforms, cpal is probably safer, but a little harder to use, especially if you need both audio inputs and outputs, because the audio processing callbacks are not "duplex", meaning you need to have 2 separate audio callbacks (one for inputs, one for outputs), running in two different contexts of execution. The difficulty with this is that, if you need to exchange audio data between the two callbacks, you will have to use a shared ringbuffer (mpsc-like). You can find a very good crate for this here:

• https://github.com/agerasev/ringbuf

JACK (Jack Audio Connection Kit)

• Use case: recommended for low-latency audio on Linux.

• Git: https://github.com/RustAudio/rust-jack

• Duplex callback: YES

• Platforms:

  • Linux (recommended)
  • Should be harder to make it work on macOS and Windows.

• Dependencies:

  • Linux: jack2 package on Linux, or pipewire-jack
  • macOS and Windows: install from here https://jackaudio.org/downloads/

• Documentation: https://rustaudio.github.io/rust-jack/

• Code examples:

  • https://github.com/RustAudio/rust-jack/blob/main/examples
  • See also the audio example in the 5TC gitlab repository

• Utilities:

  • qjackctl, to dynamically patch/connect the audio clients in a GUI graph.
  • qpwgraph, same but works with pipewire-jack

• Comments:

  • If using with PipeWire (with pipewire-jack), run pw-jack cargo-run in order to enable PipeWire to emulate a jack client.
  • Otherwise, don't forget to start the JACK server before running your executable (manually in the terminal, or with qjackctl)

cpal

• Use case: generic use, multi-platform
• Git: https://github.com/RustAudio/cpal
• Duplex callback: NO, need to share a ringbuffer between input/output callbacks
• Platforms: multi-platform
• Dependencies:
  • Linux: ALSA (libasound2-dev) or JACK (jack2, libjack2-dev)
  • Windows: WASAPI (default), or ASIO (or JACK) optionally
  • macOS/iOS: CoreAudio (or JACK)
  • Android: AAudio
  • Emscripten, WebAssembly
• Documentation:
  • https://docs.rs/cpal/0.17.1/cpal/
• Code examples:
  • https://github.com/RustAudio/cpal/tree/master/examples

cxx-juce (bindings)

• Use case: generic use, multi-platform (?), more recent and probably less stable than the others...
• Git: https://github.com/JamesHallowell/cxx-juce
• Duplex callback: YES
• Platforms: Supposed to be multi-platform, but only tested on Linux...
• Dependencies: JUCE (fetched and built automatically)
• Documentation: see examples
• Code examples:
  • https://github.com/JamesHallowell/cxx-juce/tree/main/examples
  • see network example in 5TC gitlab repository.

project presentation: Wednesday 21/01/2026 14h-18h Room TD-A (Ground floor, Hedy Lamarr)

Schedule:

14h00-14h15: Granular Simulation

• Student(s): PEYRIE Pierre-Angelo
• Description:
  • Simple granular simulation using the ggez library. It simulates 2D colliding particles subject to gravity using a simple verlet integration. Inspired by pezzza's work.
• Git: https://github.com/Pierre-AngeloPeyrie/rust_project
• Crates used:
  • ggez

14h15-14h30: Task TUI

• Student(s): VAUDEY Rémy
• Description: Simple Task Manager made with ratatui.
• Git: https://gitlab.com/RVaudey21/rust-task-tui
• Crates used:
  • ratatui
  • crossterm
  • color-eyre
  • serde (json)

14h30-14h45: Whac'A'Whole

• Student(s): LIN Hanqi
• Description: Simple 2D Game
• Git: https://github.com/Hanqi-b/whac_a_whole
• Crates used:
  • macroquad
  • rand

14h45-15h00: McDoSim

• Student(s): ZHAN Xuan
• Description: Fast-food scheduling simulation
• Git: https://github.com/duckduckxuan/McDoSim
• Crates used:
  • tokio
  • rand

15h00-15h15: Pacman

• Student(s): ROUQUET Gabriel
• Description: Simple pacman game on terminal
• Git: https://github.com/grouquet/RUST_PROJECT
• Crates used:
  • crossterm

15h15-15h30: Bugglers

• Student(s): HAUTBOIS Guewen, VATAN Hélio
• Description: Imagification : generate an image from a sound.
• Git: https://github.com/MadMuses/Bugglers
• Crates used:
  • hound (soundfiles)
  • image
  • num (numeric types)
  • rustfft

15h30-15h45: Radiooooo CLI

• Student(s): MORAES Augusto
• Description: A command-line client made on RUST for radiooooo.com.
• Git: https://github.com/augusto-moraes/radiooooo-rust-cli
• Crates used:
  • clap
  • tokio
  • reqwest (http requests)
  • serde (json)
  • colored
  • log, env_logger
  • inquire (terminal prompts)
  • chrono

15h45-16h15: Pause

16h15-16h30: Password Manager

• Student(s): LEBLANC Lucas
• Description:
• Git: https://github.com/LSLeblanc/password-manager-rust
• Crates used:
  • aes-gcm (crypto)
  • rand
  • serde (json)
  • sha2

16h30-16h45: Audio Chat

• Student(s): GIRARD Hippolyte, LAMBERT Thibaud
• Description: un chat audio en temps réel entre plusieurs clients sur Rust.
• Git: https://github.com/HippG/Rust_Audio_Chat
• Crates used:
  • jack (audio)
  • opus (audio codec, VoIP, ...)
  • ringbuf
  • tokio
  • quinn (async impl. of IETF QUIC transport protocol)
  • rustls
  • axum (tokio http routing and request handling)
  • serde (json)
  • tower-http

16h45-17h00: Rust-networking

• Student(s): SEVERIN Stefan, SCHROTH Stephan
• Description: create a simple TCP-based chat server and client in Rust
• Git: https://github.com/Multi-5/Rust_networking
• Crates used: tokio, mini-redis

17h00-17h15: Tuner

• Student(s): MÜLLER Nadine, VOINCHET Lena
• Description:
  • develop a high-performance musical instrument tuner. It uses Rust for Digital Signal Processing (DSP) to ensure memory safety and execution speed, and CPAL the cross-platform audio library.
• Git: https://github.com/LenaVcht/RUST_Tuner
• Crates used: cpal

17h15-17h30: Snake

• Student(s): RENAUD Valentin
• Description: Simple Snake Game.
• Git : https://github.com/Valdyzer/Snake.git
• Crates used: dioxus