Rust Cheat Sheet

Explain
/// Documentation comments use triple slashes.

/// 

/// They are parsed in markdown format, so things

/// like headers, tables, task lists, and links to other types

/// can be included in the documentation.

/// 

/// Example code can also be included in doc comments with

/// three backticks (`). All example code in documentation is

/// tested with `cargo test` (this only applies to library crates).

fn is_local_phone_number(num: &str) -> bool {

    use regex::Regex;

    let re = Regex::new(r"[0-9]{3}-[0-9]{4}").unwrap();

    re.is_match(num)

}

Explain
// `let` will create a new variable binding

let foo = 1;

// bindings are immutable by default

foo = 2;              // ERROR: cannot assign; `foo` not mutable



let mut bar = 1;      // create mutable binding

bar = 2;              // OK to mutate



let baz = 'a';        // use single quotes to create a character

let baz = "ok";       // use double quotes to create a string

// variables can be shadowed, so these lines have been valid

let baz = 42;         // `baz` is now an integer; 'a' and "ok" no longer accessible



// Rust infers types, but you can use annotations as well

let foo: i32 = 50;    // set `foo` to i32

let foo: u8 = 100;    // set `foo` to u8

// let foo: u8 = 256; // ERROR: 256 too large to fit in u8



let bar = 14.5_f32;   // underscore can be used to set numeric type...

let bar = 99_u8;

let bar = 1_234_567;  // ...and also to make it easier to read long numbers



let baz;              // variables can start uninitialized, but they must be set before usage

// let foo = baz;     // ERROR: possibly uninitialized.

baz = 0;              // `baz` is now initialized

// baz = 1;           // ERROR: didn't declare baz as mutable



// naming convention:

let use_snake_case_for_variables = ();

Explain
// `const` will create a new constant value

const PEACE: char = '☮';    // type annotations are required

const MY_CONST: i32 = 4;    // naming conventions is SCREAMING_SNAKE_CASE



// const UNINIT_CONST: usize;  // ERROR: must have initial value for constants



// use `once_cell` crate if you need lazy initialization of a constant

use once_cell::sync::OnceCell;

const HOME_DIR: OnceCell<String> = OnceCell::new();

// use .set to set the value (can only be done once)

HOME_DIR.set(std::env::var("HOME").expect("HOME not set"));

// use .get to retrieve the value

HOME_DIR.get().unwrap();

Explain
// use `type` to create a new type alias

type Foo = Bar;

type Miles = u64;

type Centimeters = u64;

type Callbacks = HashMap<String, Box<dyn Fn(i32, i32) -> i32>>;



struct Contact {

    name: String,

    phone: String,

}

type ContactName = String;

// type aliases can contain other type aliases

type ContactIndex = HashMap<ContactName, Contact>;



// type aliases can be used anywhere a type can be used

fn add_contact(index: &mut ContactIndex, contact: Contact) {

    index.insert(contact.name.to_owned(), contact);

}



// type aliases can also contain lifetimes ...

type BorrowedItems<'a> = Vec<&'a str>;

// ... and also contain generic types

type GenericThings<T> = Vec<Thing<T>>;

Explain
// This block uses type aliases instead of New Types:

{

    type Centimeters = f64;

    type Kilograms = f64;

    type Celsius = f64;



    fn add_distance(a: Centimeters, b: Centimeters) -> Centimeters {

        a + b

    }

    fn add_weight(a: Kilograms, b: Kilograms) -> Kilograms {

        a + b

    }

    fn add_temperature(a: Celsius, b: Celsius) -> Celsius {

        a + b

    }



    let length = 20.0;

    let weight = 90.0;

    let temp = 27.0;



    // Since type aliases are the same as their underlying type,

    // it's possible to accidentally use the wrong data as seen here:

    let distance = add_distance(weight, 10.0);

    let total_weight = add_weight(temp, 20.0);

    let new_temp = add_temperature(length, 5.0);

}



// This block uses new types instead of type aliases:

{

    // create 3 tuple structs as new types, each wrapping f64

    struct Centimeters(f64);

    struct Kilograms(f64);

    struct Celsius(f64);



    fn add_distance(a: Centimeters, b: Centimeters) -> Centimeters {

        // access the field using .0

        Centimeters(a.0 + b.0)

    }

    fn add_weight(a: Kilograms, b: Kilograms) -> Kilograms {

        Kilograms(a.0 + b.0)

    }

    fn add_temperature(a: Celsius, b: Celsius) -> Celsius {

        Celsius(a.0 + b.0)

    }



    // the type must be specified

    let length = Centimeters(20.0);

    let weight = Kilograms(90.0);

    let temp = Celsius(27.0);



    let distance = add_distance(length, Centimeters(10.0));

    let total_weight = add_weight(weight, Kilograms(20.0));

    let new_temp = add_temperature(temp, Celsius(5.0));



    // using the wrong type is now a compiler error:

    // let distance = add_distance(weight, Centimeters(10.0));

    // let total_weight = add_weight(temp, Kilograms(20.0));

    // let new_temp = add_temperature(length, Celsius(5.0));

}

Explain
// use the `fn` keyword to create a function

fn func_name() { /* body */ }



// type annotations required for all parameters

fn print(msg: &str) {

    println!("{msg}");

}



// use -> to return values

fn sum(a: i32, b: i32) -> i32 {

    a + b   // `return` keyword optional

}

sum(1, 2);  // call a function



// `main` is the entry point to all Rust programs

fn main() {}



// functions can be nested

fn outer() -> u32 {

    fn inner() -> u32 { 42 }

    inner()         // call nested function & return the result

}



// use `pub` to make a function public

pub fn foo() {}



// naming convention:

fn snake_case_for_functions() {}

Explain
// use pipes to create closures

let hello = || println!("hi");

// parameters to closures go between the pipes

let msg = |msg| println!("{msg}");

// closures are called just like a function

msg("hello");



// type annotations can be provided...

let sum = |a: i32, b: i32| -> i32 { a + b };

// ...but they are optional

let sum = |a, b| a + b;

let four = sum(2, 2);

assert_eq!(four, 4);



// closures can be passed to functions using the `dyn` keyword

fn take_closure(clos: &dyn Fn()) {

    clos();

}

let hello = || println!("hi");

take_closure(&hello);



// use the `move` keyword to move values into the closure

let hi = String::from("hi");

let hello = move || println!("{hi}");

// `hi` can no longer be used because it was moved into `hello`

Explain
if some_bool { /* body */ }



if one && another {

    // when true

} else {

    // when false

}



if a || (b && c) {

    // when one of the above

} else if d {

    // when d

} else {

    // none are true

}



// `if` is an expression, so it can be assigned to a variable

let (min, max, num) = (0, 10, 12);

let num = if num > max {

    max

} else if num < min {

    min

} else {

    num

};

assert_eq!(num, 10);

Explain
let something = Some(1);

if let Some(inner) = something {

    // use `inner` data

    assert_eq!(inner, 1);

}



enum Foo {

    Bar,

    Baz

}

let bar = Foo::Bar;

if let Foo::Baz = bar {

    // when bar == Foo::Baz

} else {

    // anything else 

}



// `if let` is an expression, so it can be assigned to a variable

let maybe_num = Some(1);

let definitely_num = if let Some(num) = maybe_num { num } else { 10 };

assert_eq!(definitely_num, 1);

Explain
let num = 0; 

match num {

    // ... on a single value

    0 => println!("zero"),

    // ... on multiple values

    1 | 2 | 3 => println!("1, 2, or 3"),

    // ... on a range

    4..=9 => println!("4 through 9"),

    // ... with a guard

    n if n >= 10 && n <= 20 => println!("{n} is between 10 and 20"),

    // ... using a binding

    n @ 21..=30 => println!("{n} is between 21 and 30"),

    // ... anything else

    _ => println!("number is ignored"),

}



// `match` is an expression, so it will evaluate and can be assigned

let num = 0;

let msg = match num {

    0 => "zero",

    1 => "one",

    _ => "other",

};

assert_eq!(msg, "zero");

Explain
// must be mutable so it can be modified in the loop

let mut i = 0;



// as long as `i` is less than 10, execute the body

while i < 10 {

    if i == 5 {

        break;     // completely stop execution of the loop

    }

    if i == 8 {

        continue;  // stop execution of this iteration, restart from `while`

    }



    // don't forget to adjust `i`, otherwise the loop will never terminate

    i += 1;

}



// `while` loops can be labeled for clarity and must start with single quote (')

let mut r = 0;

let mut c = 0;

// label named 'row

'row: while r < 10 {

    // label named 'col

    'col: while c < 10 {

        if c == 3 {

            break 'row;     // break from 'row, terminating the entire loop

        }

        if c == 4 {

            continue 'row;  // stop current 'col iteration and continue from 'row

        }

        if c == 5 {

            continue 'col;  // stop current 'col iteration and continue from 'col

        }

        c += 1;

    }

    r += 1;

}

Explain
let mut maybe = Some(10);

// if `maybe` is a `Some`, bind the inner data to `value` and execute the loop

while let Some(value) = maybe {

    println!("{maybe:?}");

    if value == 1 {

        // loop will exit on next iteration

        // because the pattern match will fail

        maybe = None;

    } else {

        maybe = Some(value - 1);

    }

}

Explain
// iterate through a collection

let numbers = vec![1, 2, 3];

for num in numbers {

    // values are moved into this loop

}



// .into_iter() is implicitly called when using `for`

let numbers = vec![1, 2, 3];

for num in numbers.into_iter() {

    // values are moved into this loop

}



// use .iter() to borrow the values

let numbers = vec![1, 2, 3];

for num in numbers.iter() {

    // &1

    // &2

    // &3

}



// ranges can be used to iterate over numbers

for i in 1..3 {     // exclusive range

    // 1

    // 2

}

Explain
loop { /* forever */ }



// loops can be labled

'outer: loop {

    'inner: loop {

        continue 'outer;    // immediately begin the next 'outer loop

        break 'inner;       // exit out of just the 'inner loop

    }

}



// loops are expressions

let mut iterations = 0;

let total = loop {

    iterations += 1;

    if iterations == 5 {

        // using `break` with a value will evaluate the loop

        break iterations;

    }

};

// total == 5

Explain
struct Foo;          // define a structure containing no data

let foo = Foo;       // create a new `Foo`



struct Dimension(i32, i32, i32);     // define a "tuple struct" containing 3 data points

let container = Dimension(1, 2, 3);  // create a new `Dimension`

let (w, d, h) = (container.0, container.1, container.2);

// w, d, h, now accessible



// define a structure containing two pieces of information

struct Baz {

    field_1: i32,   // an i32

    field_2: bool,  // a bool

}

// create a new `Baz`

let baz = Baz {

    field_1: 0,     // all fields must be defined

    field_2: true,

};

Explain
struct Bar {

    inner: bool,

}



// `impl` keyword to implement functionality

impl Bar {

    // `Self` is an alias for the name of the structure

    pub fn new() -> Self {

        // create a new `Bar`

        Self { inner: false }

    }

    // `pub` (public) functions are accessible outside the module

    pub fn make_bar() -> Bar {

        Bar { inner: false }

    }



    // use `&self` to borrow an instance of `Bar`

    fn is_true(&self) -> bool {

        self.inner

    }



    // use `&mut self` to mutably borrow an instance of `Bar`

    fn make_true(&mut self) {

        self.inner = true;

    }



    // use `self` to move data out of `Bar`

    fn into_inner(self) -> bool {

        // `Bar` will be destroyed after returning `self.inner`

        self.inner

    }

}



let mut bar = Bar::new();           // make a new `Bar`

bar.make_true();                    // change the inner value

assert_eq!(bar.is_true(), true);    // get the inner value

let value = bar.into_inner();       // move the inner value out of `Bar`



// `bar` was moved into `bar.into_inner()` and can no longer be used

Explain
struct Point {

    x: i32,

    y: i32,

}



let origin = Point { x: 0, y: 0 };



match origin {

    // match when ...

    // ... x == 0 && y == 0

    Point { x: 0, y: 0 } => (),

    // ... x == 0 and then ignore y

    Point { x: 0, .. } => (),

    // ... y == 0 and then ignore x

    Point { y: 0, .. } => (),

    // ... x == 0 and then capture y while checking if y == 2; bind y

    Point { x: 0, y } if y == 2 => println!("{y}"),

    // ... the product of x and y is 100; bind x and y

    Point { x, y } if x * y == 100 => println!("({x},{y})"),

    // ... none of the above are satisfied; bind x and y

    Point { x, y } => println!("({x},{y})"),

    // ... none of the above are satisfied while also ignoring x and y

    // (this will never match because `Point {x, y}` matches everything)

    _ => (),

}

Explain
struct Member {

    name: String,

    address: String,

    phone: String,

}



let m = Member {

    name: "foo".to_string(),

    address: "bar".to_string(),

    phone: "phone".to_string(),

};



// move `name` out of the structure; ignore the rest

let Member { name, .. } = m;

// move `name` out of the structure; bind to `id`; ignore the rest

let Member { name: id, .. } = m;

// move `name` out of the structure; bind to `id`

let id = m.name;

Explain
// a structure wrapping a usize which represents an error code

struct ErrorCode(usize);



// enumerations are created with the `enum` keyword

enum ProgramError {

    // a single variant

    EmptyInput,

    // a variant containing String data

    InvalidInput(String),

    // a variant containing a struct

    Code(ErrorCode),

}



// create one ProgramError of each variant

let empty = ProgramError::EmptyInput;

let invalid = ProgramError::InvalidInput(String::from("whoops!"));

let error_code = ProgramError::Code(ErrorCode(9));

Explain
enum ProgramError {

    // a single variant

    EmptyInput,

    // a variant containing String data

    InvalidInput(String),

    // a variant containing a struct

    Code(ErrorCode),

}



let some_error: ProgramError = some_fallible_fn();



match some_error {

    // match on the ...

    // ... EmptyInput variant

    ProgramError::EmptyInput => (),

    // ... InvalidInput variant only when the String data is == "123"; bind `input`

    ProgramError::InvalidInput(input) if input == "123" => (),

    // ... InvalidInput variant containing any other String data not capture above; bind `input`

    ProgramError::InvalidInput(input) => (),

    // ... Code variant having an ErrorCode of 1

    ProgramError::Code(ErrorCode(1)) => (),

    // ... Code variant having any other ErrorCode not captured above; bind `other`

    ProgramError::Code(other) => (),

}



// enumeration variant names can be brought into scope with `use` ...

use ProgramError::*;

match some_error {

    // ... only need to specify the variant names now

    EmptyInput => (),

    InvalidInput(input) if input == "123" => (),

    InvalidInput(input) => (),

    Code(ErrorCode(1)) => (),

    Code(other) => (),

}

Explain
// create a new tuple named `tup` containing 4 pieces of data

let tup = ('a', 'b', 1, 2);

// tuple members are accessed by index

assert_eq!(tup.0, 'a');

assert_eq!(tup.1, 'b');

assert_eq!(tup.2, 1);

assert_eq!(tup.3, 2);



// tuples can be destructured into individual variables

let (a, b, one, two) = (tup.0, tup.1, tup.2, tup.3);

let (a, b, one, two) = ('a', 'b', 1, 2);

// a, b, one, two now can be used as individual variables



// tuple data types are just existing types surrounded by parentheses

fn double(point: (i32, i32)) -> (i32, i32) {

    (point.0 * 2, point.1 * 2)

}

let array = [0; 3]; // array size 3, all elements initialized to 0

let array: [i32; 5] = [1, 2, 3, 4, 5];

let slice: &[i32] = &array[..];

Explain
let mut nums = vec![1, 2, 3, 4, 5];

let num_slice = &mut nums[..];  // make a slice out of the Vector

num_slice.first();              // Some(&1)

num_slice.last();               // Some(&5)

num_slice.reverse();            // &[5, 4, 3, 2, 1]

num_slice.sort();               // &[1, 2, 3, 4, 5]



// get a view of "chunks" having 2 elements each

let mut chunks = num_slice.chunks(2);

chunks.next(); // Some(&[1, 2])

chunks.next(); // Some(&[3, 4])

chunks.next(); // Some(&[5])

Explain
let chars = vec!['A', 'B', 'C', 'D'];



// two ways to create a slice from a Vector

let char_slice = &chars[..];

let char_slice = chars.as_slice();



match char_slice {

    // match ...

    // ... the first and last element. minimum element count == 2

    [first, .., last] => println!("{first}, {last}"),

    // ... one and only one element

    [single] => println!("{single}"),

    // ... an empty slice

    [] => (),

}



match char_slice {

    // match ...

    // ... the first two elements. minimum elements == 2

    [one, two, ..] => println!("{one}, {two}"),

    // ... the last element. minimum elements == 1

    [.., last] => println!("{last}"),

    // ... an empty slice

    [] => (),

}



let nums = vec![7, 8, 9];

match nums.as_slice() {

    // match ...

    // First element only if element is == 1 or == 2 or == 3,

    // with remaining slice bound to `rest`. minimum elements == 1

    [first @ 1..=3, rest @ ..] => println!("{rest:?}"),

    // ... one element, only if == 5 or == 6

    [single] if single == &5 || single == &6 => (),

    // ... two and only two elements

    [a, b] => (),

    // Two-element slices are captured in the previous match 

    // arm, so this arm will match either:

    //   * One element

    //   * More than two elements

    [s @ ..] => println!("one element, or 2+ elements {s:?}"),

    // ... empty slice

    [] => (),

}

Explain
// Option in the standard library is defined as a generic enumeration:

enum Option<T> {

    Some(T),    // data exists

    None,       // no data exists

}

// an Option's variants are available for use without specifying Option::Some / Option::None



// create an Option containing usize data

let maybe_number: Option<usize> = Some(1);

// add 1 to the data, but only if the option is `Some` (this is a no-op if it is `None`)

let plus_one: Option<usize> = maybe_number.map(|num| num + 1);



// `if let` can be used to access the inner value of an Option

if let Some(num) = maybe_number {

    // use `num`

} else {

    // we have `None`

}



// Options can be used with `match`

match maybe_number {

    // match when ...

    // ... there is some data and it is == 1

    Some(1) => (),

    // ... there is some data not covered above; bind the value to `n`

    Some(n) => (),

    // ... there is no data

    None => (),

}



// since `if let` is an expression, we can use it to conditionally destructure an Option

let msg = if let Some(num) = maybe_number {

    format!("We have a {num}")

} else {

    format!("We have None")

};

assert_eq!(msg, "We have a 1");



// combinators can be used to easily manipulate Options

let maybe_number = Some(3);

let odd_only = maybe_number      // take `maybe_number`

    .and_then(|n| Some(n * 3))   // then access the inner value, multiply by 3, and make a new Option

    .map(|n| n - 1)              // then take the inner value and subtract 1

    .filter(|n| n % 2 == 1)      // then if the inner value is odd, keep it

    .unwrap_or(1);               // then unwrap the inner value if it exists; otherwise use 1

assert_eq!(odd_only, 1);



// same as above but with named functions instead of inline closures

let maybe_number = Some(4);

let odd_only = maybe_number      // take `maybe_number`

    .and_then(triple)            // then run the `triple` function with the inner value

    .map(minus_one)              // then transform the inner value with the `minus_one` function

    .filter(is_odd)              // then filter the value using the `is_odd` function

    .unwrap_or(1);               // then unwrap the inner value if it exists; otherwise use 1

assert_eq!(odd_only, 11);



fn triple(n: i32) -> Option<i32> {

    Some(n * 3)

}



fn minus_one(n: i32) -> i32 {

    n - 1

}



fn is_odd(n: &i32) -> bool {

    n % 2 == 1

}

Explain
// Result in the standard library is defined as a generic enumeration:

enum Result<T, E> {

    Ok(T),      // operation succeeded

    Err(E),     // operation failed

}

// a Results's variants are available for use without specifying Result::Ok / Result::Err



// create a Result having a success type of i32 and an error type of String

let maybe_number: Result<i32, String> = Ok(11);



// Combinators can be used to easily manipulate Results. The following sequence

// transformed the inner value by multiplying it by 3 if it is an Ok. If

// `maybe_number` is an Err then the error returned will be the supplied String.

let maybe_number = maybe_number

    .map(|n| n * 3)

    .map_err(|e| String::from("don't have a number"));



// We can use `if let` to conditionally destructure a Result.

// Here we are specifically looking for an error to report.

if let Err(e) = maybe_number.as_ref() {

    eprintln!("error: {e}");

}



// Results and Options can be changed back and forth using `.ok`

let odd_only = maybe_number      // take `maybe_number`

    .ok()                        // transform it into an Option

    .filter(|n| n % 2 == 1)      // apply a filter

    .ok_or_else(||               // transform the Option back into a Result

        String::from("not odd!") // if the Option is None, use this String for the Err

    );



// `match` is commonly used when working with Results

match odd_only {

    Ok(odd) => println!("odd number: {odd}"),

    Err(e) => eprintln!("error: {e}"),

}

Explain
use std::error::Error;

use std::fs::File;

use std::io::{self, Read};

use std::path::Path;



// This function has 3 failure points and uses the question mark operator

// to automatically propagate appropriate errors.

fn read_num_using_questionmark(path: &Path) -> Result<u8, Box<dyn Error>> {

    // make a buffer

    let mut buffer = String::new();



    // Using the `?` will automatically give us an open file on

    // success, and automatically return a `Box<dyn Error>` on failure.

    let mut file = File::open(path)?;



    // We aren't concerned about the return value for this function, 

    // however we still need to handle the error with question mark.

    file.read_to_string(&mut buffer)?;



    // remove any whitespace

    let buffer = buffer.trim();



    // We wrap this function call in an `Ok` because `?` will

    // automatically unwrap an `Ok` variant, but our function

    // signature requires a `Result`.

    Ok(u8::from_str_radix(buffer, 10)?)

}



// Same function as above, but without using question mark.

// This function also demonstrates different error handling strategies.

fn read_num_no_questionmark(path: &Path) -> Result<u8, Box<dyn Error>> {

    // make a buffer

    let mut buffer = String::new();



    // possible error when opening file (type annotation shown for clarity)

    let file: Result<File, io::Error> = File::open(path);



    // match on `file` to see what happened

    match file {

        // when open was successful ...

        Ok(mut file) => {

            // ... read data into a buffer ...

            if let Err(e) = file.read_to_string(&mut buffer) {

                // ... if that fails, return a boxed Err

                return Err(Box::new(e));

            }

        }

        // failed to open file, return `dyn Error` using `.into()`

        Err(e) => return Err(e.into()),

    }



    // remove any whitespace (yay no failure point!)

    let buffer = buffer.trim();



    // convert to u8 while manually mapping a possible conversion error

    u8::from_str_radix(buffer, 10).map_err(|e| e.into())

}



// calling the function is the same regardless of technique chosen

let num: Result<u8, _> = read_num_using_questionmark(Path::new("num.txt"));

if num.is_ok() {        // `.is_ok` will tell us if we have an Ok variant

    println!("number was successfully read");

}



// use some combinators on the result

let num = num             // take `num`

    .map(|n| n + 1)       // map an `Ok` variant by adding 1 to the value

    .ok()                 // transform to an `Option`

    .and_then(|n|         // and then ...

        n.checked_mul(2)  // double the inner value (this returns an Option)

    )

    .ok_or_else(||        // transform back into `Result` ...

        // ... using this error message if the multiplication failed

        format!("doubling exceeds size of u8")

    );



// use `match` to print out the result on an appropriate output stream

match num {

    Ok(n) => println!("{n}"),

    Err(e) => eprintln!("{e}"),

}

Explain
// a target error type

enum JobError {

    Expired,

    Missing,

    Other(u8),

}



// similar implementation from previous example

impl From<u8> for JobError {

    fn from(code: u8) -> Self {

        match code {

            1 => Self::Expired,

            2 => Self::Missing,

            c => Self::Other(c),

        }

    }

}



// arbitrary structure

struct Job;



impl Job {

    // function that returns an error code as u8

    fn whoops(&self) -> Result<(), u8> {

        Err(2)

    }

}

// function potentially returns a JobError

fn execute_job(job: Job) -> Result<(), JobError> {

    // use question mark to convert potential errors into a JobError

    Ok(job.whoops()?)

}



let status = execute_job(Job); // JobError::Missing

Explain
// create a new vector ...

let nums = vec![1, 2, 3, 4, 5];

// ... then turn it into an iterator and multiply each element by 3 ...

let tripled = nums.iter().map(|n| n * 3);

// ... then filter out all the even numbers ...

let odds_only = tripled.filter(|n| n % 2 == 1);

// ... and finally collect the odd numbers into a new Vector

let new_vec: Vec<i32> = odds_only.collect();    // type annotation required



// same steps as above, but chaining it all together:

// create a new Vector

let nums = vec![1, 2, 3, 4, 5];

let tripled_odds_only = nums    // take the `nums` vector

    .iter()                     // then turn it into an iterator

    .filter_map(|n| {           // then perform a filter and map operation on each element

        let n = n * 3;          // multiply the element by 3

        if n % 2 == 1 {

            Some(n)             // keep if odd

        } else {

            None                // discard if even

        }

    })

    .collect::<Vec<i32>>();     // collect the remaining numbers into a Vector



// This example takes a vector of (x,y) points where all even indexes

// are the x-coordinates, and all odd indexes are y-coordinates and

// creates an iterator over tuples of the points.



// Points Vector: x, y, x, y, x, y, x, y, x, y 

let points = vec![0, 0, 2, 1, 4, 3, 6, 5, 8, 7];



// `step_by` will skip every other index; iteration starts at index 0

let x = points.iter().step_by(2);



// use `skip` to skip 1 element so we start at index 1

// then skip every other index starting from index 1

let y = points.iter().skip(1).step_by(2);



// `zip` takes two iterators and generates a new one by taking

// alternating elements from each iterator. `enumerate` provides

// the iteration count as an index

let points = x.zip(y).enumerate();

for (i, point) in points {

    println!("{i}: {point:?}");

    // 0: (0, 0)

    // 1: (2, 1)

    // 2: (4, 3)

    // 3: (6, 5)

    // 4: (8, 7)

}



// create a new Vector

let nums = vec![1, 2, 3];

let sum = nums      // take `nums`

    .iter()         // create an iterator

    .sum::<i32>();  // add all elements together and return an i32

assert_eq!(sum, 6);

Explain
// borrow a str

fn print(msg: &str) {

    println!("{msg}");

}



// borrow a str, return a slice of the borrowed str

fn trim(msg: &str) -> &str {

    msg.trim()

}



// borrow a str, return an owned String

fn all_caps(msg: &str) -> String {

    msg.to_ascii_uppercase()

}



// function takes ownership of `msg` and is responsible

// for destroying it

fn move_me(msg: String) {

    println!("{msg}");

    // `msg` destroyed

}



// borrow "foo"

print("foo");



// borrow " bar "; return a new slice

let trimmed: &str = trim(" bar ");      // "bar"



// borrow "baz"; return a new String

let cruise_control: String = all_caps("baz");   // "BAZ"



// create owned String

let foo: String = String::from("foo");

// Move the String (foo) into move_me function.

// The `move_me` function will destroy `foo` since

// ownership was transferred.

let moved = move_me(foo);



// `foo` no longer exists

// println!("{foo}");

// ERROR: `foo` was moved into `move_me`

Explain
// Use lifetimes to indicate borrowed data stored in structures.

// Both structures and enumerations can have multiple lifetimes.

struct Email<'a, 'b> {

    subject: &'a str,

    body: &'b str,

}



let sample_subject = String::from("cheat sheet");

let sample_body = String::from("lots of code");

// `sample_subject` and `sample_body` are required to stay in memory

// as long as `email` exists.

let email = Email {

    subject: &sample_subject,

    body: &sample_body,

};



// dbg!(sample_subject);

// dbg!(email);

// ERROR: cannot move `sample_subject` into dbg macro because

//        `email` still needs it

Explain
// Lifetime 'a indicates borrowed data stored in the enum.

// The compiler uses 'a to enforce the following:

//  1. &str data must exist prior to creating a `StrCompare`

//  2. &str data must still exist after destruction of `StrCompare`

#[derive(Debug)]

enum StrCompare<'a> {

    Equal,

    Longest(&'a str),

}



// determine which &str is longer

// Lifetime annotations indicate that both `a` and `b` are

// borrowed and they will both exist for the same amount of time.

fn longest<'s>(a: &'s str, b: &'s str) -> StrCompare<'s> {

    if a.len() > b.len() {

        StrCompare::Longest(a)

    } else if a.len() < b.len() {

        StrCompare::Longest(b)

    } else {

        StrCompare::Equal

    }

}



// ERROR: the following block will not compile (see comments)



// new scope: lifetime (1)

{

    let a = String::from("abc");       // lifetime (1)

    let longstring: StrCompare;        // lifetime (1)



    // new scope: lifetime (2)

    {

        let b = String::from("1234"); // lifetime (2)

        longstring = longest(&a, &b);

        // end scope; lifetime (2) data dropped (destroyed):

        // `b` no longer exists

    }



    // `b` was previously dropped, but might still be needed here

    // as part of the `StrCompare` enumeration

    println!("{longstring:?}");     // ERROR: `b` doesn't live long enough



    // lifetime (1) data dropped in reverse creation order:

    // `longstring` no longer exists

    // `a` no longer exists

}



// FIXED: `a` and `b` now have same lifetime



// new scope: lifetime (1)

{

    let a = String::from("abc");       // lifetime (1)

    let b = String::from("1234");      // lifetime (1)

    let longstring = longest(&a, &b);  // lifetime (1)

    println!("{longstring:?}");



    // lifetime (1) data dropped in reverse creation order:

    // `longstring` dropped

    // `b` dropped

    // `a` dropped

}

Explain
// create a new trait

trait Notify {

    // implementers must define this function

    fn notify(&self) -> &str;

}



struct Phone {

    txt: String,

}



struct Email {

    subject: String,

    body: String,

}



// implement the `Notify` trait for the `Phone` struct

impl Notify for Phone {

    fn notify(&self) -> &str {

        &self.txt

    }

}



// implement the `Notify` trait for the `Email` struct

impl Notify for Email {

    fn notify(&self) -> &str {

        &self.subject

    }

}



// create a new Phone

let phone = Phone {

    txt: String::from("foo"),

};



// create a new Email

let email = Email {

    subject: String::from("my email"),

    body: String::from("bar"),

};



phone.notify();     // "foo"

email.notify();     // "bar"

Explain
trait Compute {

    // associated type to be defined by an implementer

    type Target;

    // use Self::Target to refer to the associated type

    fn compute(&self, rhs: Self::Target) -> Self::Target;

}



struct Add(i32);

struct Sub(f32);



impl Compute for Add {

    // set the associated type to i32

    type Target = i32;

    fn compute(&self, rhs: Self::Target) -> Self::Target {

        self.0 + rhs

    }

}



impl Compute for Sub {

    // set the associated type to f32

    type Target = f32;

    fn compute(&self, rhs: Self::Target) -> Self::Target {

        self.0 - rhs

    }

}



let add = Add(1);

let two = add.compute(1);

let sub = Sub(1.0);

let zero = sub.compute(1.0);

Explain
// create a trait to refill some resource

trait Refill {

    fn refill(&mut self);

}



// some structures to work with

struct Player { health_points: i32 }

struct MagicWand { magic_points: i32 }

struct Vehicle { fuel_remaining: i32 }



// set the maximum values for the structures

impl Player { const MAX_HEALTH: i32 = 100; }

impl MagicWand { const MAX_MAGIC: i32 = 100; }

impl Vehicle { const MAX_FUEL: i32 = 300; }



// trait implementations for all 3 structures

impl Refill for Player {

    fn refill(&mut self) {

        self.health_points = Self::MAX_HEALTH;

    }

}

impl Refill for MagicWand {

    fn refill(&mut self) {

        self.magic_points = Self::MAX_MAGIC;

    }

}

impl Refill for Vehicle {

    fn refill(&mut self) {

        self.fuel_remaining = Self::MAX_FUEL;

    }

}



// instantiate some structures

let player = Player { health_points: 50 };

let wand = MagicWand { magic_points: 30 };

let vehicle = Vehicle { fuel_remaining: 0 };



// let objects = vec![player, wand, vehicle];

// ERROR: cannot have a Vector containing different types



// Type annotation is required here. `dyn` keyword indicates

// "dynamic dispatch" and is also required for trait objects.

let mut objects: Vec<Box<dyn Refill>> =

    vec![

        Box::new(player),                 // must be boxed

        Box::new(wand),

        Box::new(vehicle)

    ];



// iterate over the collection and refill all of the resources

for obj in objects.iter_mut() {

    obj.refill();

}

Explain
struct Foo {

    a: usize,

    b: usize,

}



// Default is available without `use`

impl Default for Foo {

    fn default() -> Self {

        Self { a: 0, b: 0 }

    }

}



// make a new Foo

let foo = Foo::default();



// make a new Foo with specific values set

// and use default values for the rest

let foo = Foo {

    a: 10,

    ..Default::default() // b: 0

};



// we might have a Foo ...

let maybe_foo: Option<Foo> = None;

// ... if not, use the default one

let definitely_foo = maybe_foo.unwrap_or_default();