Rust

Rust has an extensive set of explicitly defined numeric types.

// 8--64-bit un/signed integers
let w:u8 = 0;
let x:u16 = 0;
let y = 0_u32;
let z:i64 = -1;

// un/signed "sizes", the type of pointer indices and offsets:
let a:usize = 0;
let b = -5_isize;

// floating point numbers in 32- and 64-bit flavors
let f:f32 = 0.0;
let g = 0.0_f64;

One area where Rust introduces a little friction is in doing arithmetic between different types of numbers; you can't add an i32 and a usize, or a u8 and an i8. This removes large classes of bugs (e.g., accidentally shifting a byte value by more than eight positions) but the lack of automatic promotions does introduce some noise, which you can handle in a few different ways:

let q = w as u16 * x;
// This often works too, guessing a type for _:
let q = w as _ * x;
// Or shadow w...
let w = w as u16;
let q = w * x;

Note that there's a big difference between that last example and this:

let mut w:u8 = 0;
w = w as u16; // Won't compile!
let q = w * x;

In particular, the former variation creates a new variable named w which hides the old w on subsequent lines. It can even be scoped:

let w = 17_u8;
let q = {
    let w = w as u16;
    w * x
};
// w is still a u8

And now w remains a u8 for the rest of the code.

While this doesn't occur in this particular case, casting can in general lose bytes of numbers. To do this in the safest way possible, you'd want something like this which avoids casting:

let q:u16 = u16::from(w) + x;

If our situation were a little different…:

let q:u8 = w+x;

Casting x to u8 with as would potentially lose data if x were greater than 255. The cast would compile but could lead to surprising outputs. If we were in the habit of using from, the code wouldn't compile:

let q:u8 = w+u8::from(x);
// The trait bound u8: std::convert::From<u16> is not satisfied

From and Into are used only for so-called infallible conversions. They have safer variants for handling errors:

// let q: u8 = w + u8::try_from(x);
// ^ Whoops, won't compile since we can't add a number and a Result.
let q: Result<u8,_> = u8::try_from(x).map(|x| w + x);
// Instead we can propagate the error (if any) and get the result otherwise using map.

Rust has heterogeneous tuple types like Python does:

let t1 = (1_i8, 2.0_f32, 0_u64);
// The type of t1 is (i8, f32, u64)
let t2 = (t1, 0_u8); // ((i8, f32, u64), u8)

We can get values out of tuples in a few ways:

let t1_1 = t1.1; // An f32 value, 2.0
let t2_0_0 = t2.0.0; // An i8 value, 1
// Destructuring assignment is even better:
let (a, b) = t2;
// Or even:
let ((a0, a1, _), b) = t2;

And we can write functions taking tuples as parameters:

// Note that a rust function or block evaluates to its last expression (look ma, no semicolon!)
fn distance_a(p1:(f32,f32), p2:(f32,f32)) -> f32 {
    ((p2.0-p1.0)*(p2.0-p1.0) + (p2.1-p1.1)*(p2.1-p1.1)).sqrt()
}
// But I think this can read nicer:
fn distance_b((x1,y1):(f32,f32), (x2,y2):(f32,f32)) -> f32 {
    ((x2-x1)*(x2-x1) + (y2-y1)*(y2-y1)).sqrt()
}
// You can always use temporaries too:
fn distance_c((x1,y1):(f32,f32), (x2,y2):(f32,f32)) -> f32 {
    let dx = x2-x1; // Semicolons end expressions by turning them into statements...
    let dy = y2-y1;
    (dx*dx+dy*dy).sqrt() // No semicolon here
}

Rather than tuples for points, though, we should probably define some custom data structure.

Custom data structures in Rust come in two flavors: tuple structs and named structs (properly, structs with named fields). First, tuple structs:

struct Vec2(f32, f32);
let v1 = Vec2(0.0, 0.0);
let v2 = Vec2(4.9, 9.4);
let v3 = Vec2(v1.0, v2.1);

We can implement methods on Vec2, which we can then call with namespace notation (for methods without a self parameter) or dot notation.

impl Vec2 {
    pub fn new(x:f32, y:f32) -> Self { // Self just means "the type I'm implementing"
        Self(x,y) // We can use it here too
    }
    // let v = Vec2::new(10.0, 10.0);
    pub fn magnitude(&self) -> f32 { // More on &self in the Memory and Ownership section
        distance_b((self.0, self.1), (0.0, 0.0))
    }
    // let mag = v.magnitude();
    pub fn magnitude_b(&self) -> f32 {
        let Self(x,y) = self; // We can destructuring-assign from structs too
        distance_b((*x,*y),(0.0,0.0)) // These * are related to the &self
    }
    // let mag_b = v.magnitude_b();
}

To see how we could implement subtraction of one Vec2 from another, read ahead to the section on Traits.

Note that the struct itself will be private to the module in which it's defined. If we wrote it like so:

pub struct Vec2(f32, f32);

We'd be able to call Vec2 functions but not use the constructor!

let v = Vec2::new(4.9, 9.4); // new is an "associated function"
let mag = v.magnitude(); // magnitude is a "method" since it takes a self parameter
let v2 = Vec2(0.0, 0.0); // won't compile!

To allow using the constructor, we'd want to make those two fields public as well.

Struct members (also called "fields") can also be named:

pub struct Vec2{
    pub x:f32,
    pub y:f32
}
impl Vec2 {
    pub fn new(x:f32, y:f32) -> Self {
        // Note curly braces; could also have been Self{x,y} since
        // field names and variable/param names line up
        Self{x:x,y:y}
    }
    pub fn magnitude(&self) -> f32 {
        distance_b((self.x, self.y), (0.0, 0.0))
    }
    pub fn magnitude_b(&self) -> f32 {
        let Self{x:sx,y:sy} = self; // We can destructuring-assign from named structs too!
        // let sx = self.x;
        // let sy = self.y;
        distance_b((*sx,*sy),(0.0,0.0)) // These * are to dereference through our input, &self
    }
}

And now we can both create and access members of Vec2 directly:

let mut v = Vec2{x:0.0, y:0.0};
v.x = 4.7;
v.y = 1.0;
// {} is a format specifier for the println! macro
println!("{},{} --> {}", v.x, v.y, v.magnitude());

Besides structs, Rust lets programmers define enumeration types. Variants of an enum are mutually exclusive and may also carry data in a way similar to tuple structs.

enum Day {
    Monday,
    Tuesday,
    Wednesday,
    Thursday,
    Friday,
    Saturday,
    Sunday
}
let d1 = Day::Monday;
let d2 = Day::Tuesday;

The main thing we can do with enums is discriminate based on their, uh, discriminant:

fn weekday(day:Day) -> bool {
    match day {
        Day::Monday => true,
        Day::Tuesday => true,
        Day::Wednesday => true,
        //... Don't skip any in your real code or it won't compile!
        Day::Saturday | Day::Sunday => false
    }
}

match is a very powerful expression and I suggest reading up on it in the Rust book or Rust By Example. A more compact version:

fn weekday(day:Day) -> bool {
    match day {
        Day::Saturday | Day::Sunday => false,
        // This "catchall" handles the rest
        _ => true
    }
}

But like I said, enums can hold information too (flashbacks to CSCI 054 PO are permitted but by no means required):

enum MovementType {
    Flying(f32), // wingspan in cm
    Walking(usize), // number of legs
    Wriggling
}

fn is_creepy(movement:MovementType) -> bool {
    match movement {
        MovementType::Flying(wing) => wing < 10.0,
        // You can put "guards" on match arms
        MovementType::Walking(legs) if legs > 4 => true,
        // But in this case it's probably not that helpful
        MovementType::Walking(_) => false,
        MovementType::Wriggling => true
    }
}

Or we could implement it on the type itself:

impl MovementType {
    fn is_creepy(&self) -> bool {
        match self {
            MovementType::Flying(wing) => wing < 10.0,
            // You can put "guards" on match arms
            MovementType::Walking(legs) if legs > 4 => true,
            // But in this case it's probably not that helpful
            MovementType::Walking(_) => false,
            MovementType::Wriggling => true
        }
    }
}

Rust supports generics in a manner similar to C++ templates or Haskell polymorphism and type classes.

Examples from the standard library include Vec<T> (a linear sequence of values, like a growable array) and Option<T> (Rust's answer to null: a distinct type implemented as an enum that may have Some(value) or None).

let mut v = vec![1_u8,2,3];
v.push(4); // "4.0" wouldn't have compiled!
match v.first() {
  Some(n) => println!("first:{}",n),
  None => () // do nothing, "unit", ...
}
// The below is the moral equivalent of the match above: if the destructuring assignment is permissible, do the body of the if
if let Some(n) = v.last() {
    println!("last:{}", n);
}

You can implement a polymorphic ("generic") struct like so:

struct<T,U> Poly<T,U> {
    ts: Vec<T>,
    u:U
}

And even put bounds on them, e.g. that the things are strictly ordered:

struct<T:Ord> MinHeap<T> {
    // ...
}

When it's time to implement methods, the angle brackets return in a few positions:

impl Poly<i32, usize> {
    // ... implement poly for specific types i32 and usize
}
impl<T,U> Poly<T,U> {
    // ... implement poly for any T and U
}

Rust doesn't have inheritance, so instead we use traits and trait bounds (we saw Ord a bit earlier); often these can be implemented automatically:

// In order: Can be cloned, copied (cheaply), ordered (always), equated (always), and debug-printed
#[derive(Clone, Copy, PartialOrd, Ord, PartialEq, Eq, Debug)]
struct IntVec3 {
    // A little weird, but we'll use integer points here
    pub x:i64,
    pub y:i64,
    pub z:i64
}

We can also make our own traits, which are similar to Java interfaces and support default implementations of methods (not shown in this sample):

trait AABBBounded {
    fn origin(&self) -> IntVec3;
    fn extent(&self) -> IntVec3;
}

impl AABBBounded for Mesh {
    fn origin(&self) -> IntVec3 {
        IntVec3{
            // more about map soon.
            x:*self.vertices.iter().map(|v| v.x).min().unwrap(),
            y:*self.vertices.iter().map(|v| v.y).min().unwrap(),
            z:*self.vertices.iter().map(|v| v.z).min().unwrap(),
        }
    }
    // ...
}

Traits can also have generic type parameters, be implemented for different combinations of types, have associated types and constants, etc.

One of the most expressive uses of the type system in Rust—and one maybe more comfortable to ML or Haskell programmers than C programmers—is iterators. The std::iter::Iterator trait is really important in Rust (as are the types Option and Result and Vec) so I recommend reading through the documentation when you can.

Iterators are chainable, lazy instructions for manipulating sequences: mapping (from one sequence of values to another), filtering (generating a new sequence whose values pass some test), enumerating (pairing up iterated values with indices), reversing, and more are implemented lazily (so no intermediate collections are allocated); even linear algorithms like finding the min or max of a sequence, or finding the position of an element in a sequence are provided in the Iterator trait. All this comes with no performance penalty compared to hand-written for-loops (!!!). Using the example from above…

*self.vertices.iter().map(|v| v.x).min().unwrap()

iter() builds an iterator over (references to) the elements of self.vertices. map takes a function as its argument (in this case an anonymous function of one argument, v) which takes us from an iterator over &IntVec3 to an iterator over &i64 values. min() finds the least element of the iterator it's called on—but what if the iterator is empty? We've got to return something, so min() yields (in this case) an Option<&i64>, which we summarily unwrap (assuming the mesh has at least one vertex). Finally, we dereference (with *) the &i64 that comes out to obtain an i64.

In Rust, every value is owned by a single binding. When we reassign a binding (e.g. a variable) the old value is dropped and the new one is moved in:

{
    let mut file = std::fs::File::open("file1.txt");
    // ... do some stuff with file ...
    file = std::fs::File::open("file2.txt");
    // The old file handle is dropped and closed!
} // Now the new file handle is dropped and closed too!

That's dropping for you. Note here it's literally impossible to forget to close a file or deallocate memory accidentally.

Moving is a bit more subtle:

let v = vec![1,2,3];
let v2 = v;
println!("{}", v.len()); // Whoops, moved out of v, won't compile

Methods and functions might also use up (or "move out of") a binding:

let v = vec![1,2,3];
for num in v { // implicitly, v2.into_iter()
  println!("{}",num);
}
let n = v[0]; // Uh-oh

This is because the IntoIterator trait defines into_iter() as:

fn into_iter(self) -> Self::IntoIter;

(Where IntoIter is some iterator type, that's not the key detail here.)

Note that this method takes its self parameter as self and not &self; that is, it takes an owned self (or it takes self by move) rather than a reference to self (or by reference). Here's another example:

impl Liquid {
  pub fn mass(&self) -> f32 {
    // ...
  }
  pub fn density(&self) -> f32 {
    // ...
  }
  pub fn freeze(self) -> Solid {
    // ...
  }
  pub fn evaporate(self) -> Gas {
    // ...
  }
}

You can call mass and density as much as you like, but once you call freeze or evaporate the original Liquid is used up and moved out of—the self parameter is the owning binding, which is then dropped at the end of the method.

The last vital concept for understanding basic Rust memory ownership is the borrow. A value is owned by one binding, but it's useful if that binding can loan it out to other bindings for a while. We call these temporary loans borrows and pass them around via references. References are a bit like pointers, except they are guaranteed to be valid. They also have this extremely important guarantee:

Every value has, at any given location in the code, either:

1. No borrows
2. One or more shared, immutable references (&)
3. Exactly one exclusive, mutable reference (&mut)

The upshot is that if you have a value, you know that it is impossible for any other code to change the state of the value you have. You'll never have aliasing bugs and you'll never forget to copy a string just in case the code that sent it to you modifies it later.

(Rust does support internal mutability through types like Cell and RefCell; a Python or Java-style object reference is something like a Rust Arc<RefCell<T>>. The gnarly type tells you it's not a thing you use often in Rust.)

Vecs (Vec<T>, vec![1,2,3]) are contiguous, growable, heap-allocated regions of memory. Arrays ([u8; 4], [1,2,3,4]) are contiguous, fixed size, stack-allocated regions of memory. But in many cases, a reference to one is as good as a reference to the other: you can index into it, get an iterator from it, etc. We call a "reference to a contiguous memory region" a slice and its type is & [T] or &mut [T]. So if you want to know what you can do with a Vec, you probably want to read the documentation for Vec, std::slice, and std::iter::Iterator. It wouldn't hurt to look through the traits that Vec implements too!

Strings (String) are contiguous, growable, heap-allocated UTF-8 sequences. String slices (&str) are contiguous, fixed-size UTF-8 sequences which might be references to String values or might be references to str values on the stack or in the data segment of our compiled binary. (We don't have any way to make str values directly, they don't have their size as part of their type.) Rust makes the commitment that str and String always represent valid UTF-8 data; that means that other encodings and arrangements of bytes need different types like CString/CStr, OsString/OsStr, Vec<u8>/&[u8], and so on. As it turns out, C has all of these types too but it calls them all char *.

You can get pretty far with just String and &str; the compiler will tell you when you need to convert from one to the other.

If you have a value that needs to live in two places, you'll need to clone it (if you actually need two references to the same exact data, consider using references or smart pointers like Rc; or use your own handle type). Any type implementing the Clone trait has a handy method clone() you can call. This will also be your move if you have an &T and need a T (and Rust won't let you "move out of" the reference).

Types for which a simple bitwise copy gives a true copy of the value (e.g. integers, floats, arrays of copyable objects) may implement (by a derive) the Copy trait. Instead of moving out, Copy types get copied to their new location instead. This means you won't need to call clone() on Copy types.

Rust projects each specify which dependencies they need to do their work. Since Rust has an intentionally small standard library, most projects will pull in at least one crate. You'll see some examples later on; for now, just remember that the special file Cargo.toml (uppercase C!) is how cargo knows you have a Rust project to build.

Cargo.lock will appear once you've built your code and stores information about the versions of dependencies you're using; generally this should be version-controlled for binary crates and not version-controlled for library crates.

Cargo expects all project code to live in a src directory next to Cargo.toml. If the project is a library crate (package) it should have a file src/lib.rs, and if it's a binary crate it should have src/main.rs. Either way, the entry point defines the module hierarchy of the crate using mod or (for libraries) pub mod statements, and sometimes use and pub use.

This point bears repeating: Rust won't automatically add every file in src to the build! Only modules rooted at the entry point will be included. A corollary of this is that each module should appear in a mod statement at most once---mod is for defining structure, use is for importing names. It's weird at first compared to e.g. Python, which doesn't distinguish between defining a module and importing it.

Library crates can specify additional entry points with files in a src/bin directory, each of which should define a function main; each will implicitly have the library as a dependency. The same goes for files inside of a special examples/ directory (not inside of src!) which can be run with cargo run --example example_name.

Cargo builds in three main configurations (dev, test, and release), and Cargo.toml allows you to override aspects of those configurations. In this class we may want to trade off longer debug compile times for better performance:

[profile.test]
opt-level = 3
lto = "thin"

[profile.dev]
opt-level = 3
lto = "thin"

Another option is to compile dependencies only with optimizations, but not optimize your current crate's code:

# Set the default for dependencies.
[profile.dev.package."*"]
opt-level = 2

# Set the settings for build scripts and proc-macros.
[profile.dev.build-override]
opt-level = 3

But of course, you should probably wait to do these things until you measure a need for it.

Build

cargo build or cargo build --release

Test

cargo test or, to filter particular tests containing the string "my_module", cargo test my_module

Run

cargo run or cargo run --release; you can pass arguments with e.g. cargo run inputs/my_file.txt