Merge pull request #51 from extendr/dev

Add intro to Rust

Author: JosiahParry

_quarto.yml

@@ -12,14 +12,18 @@ website:
   repo-actions: [edit, issue]
 
   navbar:
-    logo: /images/ferRis.png
+    logo: /images/feRris.png
     left:
       - text: "Get Started"
         href: get-started.qmd
-      - text: "User Guide"
-        href: user-guide/index.qmd
-      - text: "API"
-        href: https://extendr.github.io/extendr/extendr_api/
+      - text: Documentation
+        menu:
+          - text: "Rust crate docs"
+            href: "https://extendr.github.io/extendr/extendr_api/"
+          - text: "rextendr package"
+            href: https://extendr.github.io/rextendr/dev/
+          - user-guide/index.qmd
+          - intro-rust/index.qmd
       - text: "Blog"
         href: blog/index.qmd
     right:
@@ -29,6 +33,28 @@ website:
         href: https://discord.gg/7hmApuc
 
   sidebar:
+    - title: "Rust for R Developers"
+      style: "floating"
+      collapse-level: 1
+      contents:
+        - intro-rust/index.qmd
+        - intro-rust/why-rust.qmd
+        - intro-rust/hello-world.qmd
+        - intro-rust/types.qmd
+        - intro-rust/fizz-buzz.qmd
+        - intro-rust/collections.qmd
+        - intro-rust/for-loops.qmd
+        - intro-rust/mutability.qmd
+        - intro-rust/mutable-vectors.qmd
+        - intro-rust/is-odd.qmd
+        - intro-rust/references-slices.qmd
+        - intro-rust/iterators.qmd
+        - intro-rust/iter-map.qmd
+        - intro-rust/structs.qmd
+        - intro-rust/struct-methods.qmd
+        - intro-rust/enums.qmd
+        - intro-rust/options.qmd
+
     - title: "User Guide"
       collapse-level: 1
       style: "floating"
@@ -62,7 +88,7 @@ format:
   html:
     html-table-processing: none
     theme: css/_bootswatch.scss
-    toc: false
+    toc: true
     include-in-header:
       - text: |
           <script type="text/javascript" src="/js/breadcrumb-fix.js"></script>

get-started.qmd

@@ -1,6 +1,6 @@
 ---
 title: "Get Started"
-anchor-sections: false
+toc: false
 ---
 
 To build R packages with **extendr**, you need to have the right tools.

intro-rust/collections.qmd

@@ -0,0 +1,101 @@
+# Arrays and Vectors
+
+::: callout-tip
+
+## Objective
+
+Learn how to store multiple values of the same type in arrays and vectors. Understand the difference between arrays and vectors.
+:::
+
+
+## Arrays
+
+Arrays in Rust are fixed in size and hold values of the same type. Since the size is known ahead of time, it makes them fast but inflexible.
+
+```rust
+fn main() {
+    let arr = [10, 20, 30, 40];
+    println!("Array: {:?}", arr);
+}
+```
+
+::: callout-note
+The `{:?}` syntax is used for a [**Debug**](https://doc.rust-lang.org/std/fmt/trait.Debug.html) representation of a variable. Using `{}` is used for [**Displaying**](https://doc.rust-lang.org/std/fmt/trait.Display.html) data.
+
+More often than not, using `{:?}` will be your best option.
+:::
+
+* Arrays use square brackets: `[1, 2, 3]`
+* Their size is known at compile time.
+* You can't add or remove elements.
+* Mostly used when performance is critical and size is known.
+
+The type of an array is specified as `[type; length]`, e.g.
+
+```rust
+let arr: [i32; 4] = [10, 20, 30, 40];
+```
+
+## Vectors
+
+Vectors are like growable arrays. They are much more common in everyday Rust code. To create a vector with known values, use the `vec![]` macro. Like an array, they must all be the same type.
+
+```rust
+fn main() {
+    let v = vec![1, 2, 3, 4, 5];
+    println!("Vector: {:?}", v);
+}
+```
+
+The type of a vector is specified using `Vec<T>` where `T` is shorthand for any type.
+
+An empty vector can be created using `Vec::new()` or `vec![]`. If creating an empty vector, the type must be inferred or made explicit. Vectors also have **methods**. Two handy ones are `.len()` for length, and `.is_empty()` (equivalent of `.len() == 0`)
+
+
+
+::: callout-important
+## Cannot compile
+```rust
+fn main() {
+    let x = Vec::new();
+    println!("x is empty: {}", x.is_empty());
+}
+```
+:::
+
+This cannot compile because the type of `x` is not known. Rust can infer the type if the vector is used elsewhere where the type is known. To make it compile we must specify the type.
+
+```rust
+fn main() {
+    let x: Vec<f64> = Vec::new();
+    println!("x is empty: {}", x.is_empty());
+}
+````
+
+
+## Exercise
+
+- Create an array of 4 integers and print it.
+- Create a vector with 5 numbers and print it using `{:?}`.
+- Compare the length of the array and the vector.
+- Bonus: create an empty i32 vector.
+
+### Solution
+
+<details>
+<summary>View solution</summary>
+
+```rust
+fn main() {
+    let arr = [1, 2, 3, 4];
+    println!("Array: {:?}", arr);
+
+    let v = vec![10, 20, 30, 40, 50];
+    println!("Vector: {:?}", v);
+
+    // Bonus:
+    let v = vec![42_i32; 0];
+}
+```
+
+</details>

intro-rust/enums.qmd

@@ -0,0 +1,192 @@
+# Enum(eration)s
+
+::: callout-tip
+## Objective
+
+Understand what `enum`s are and when you may want to use one.
+
+:::
+
+Oftentimes a variable can only take on a small number of values. This is when an **enumeration** (enum) would be useful.
+
+`enum`s are values that can only take on a select few **variants**. They are defined using the `enum` keyword.
+
+
+
+## Enums in R
+
+We use enums _all the time_ in R and almost exclusively as function arguments.
+
+::: aside
+The tidyverse design style guide has a great section on enums. See [enumerate options](https://design.tidyverse.org/enumerate-options.html#whats-the-pattern).
+:::
+
+```r
+args(cor)
+```
+```r
+function(
+  x, y = NULL, use = "everything",
+  method = c("pearson", "kendall", "spearman") # 👈🏼 enum!
+)
+```
+
+::: aside
+I've written about this in more detail in my blog post [Enums in R: towards type safe R](https://josiahparry.com/posts/2023-11-10-enums-in-r/)
+:::
+
+### Example
+
+For example, it may make sense to create an `enum` that specifies a possible shape.
+
+```rust
+enum Shape {
+    Triangle,
+    Rectangle,
+    Pentagon,
+    Hexagon,
+}
+```
+
+## Variant-specific behavior
+
+The `Shape` enum can take on only one of those 4 **variants**. An enum is created using the format `EnumName::Variant`.
+
+How do we actually determine behavior based on a variant? This is done using **pattern matching**.
+
+The keyword `match` lets us perform an action based on an enum's variant. It works by listing each variant and the behavior to that happens when that variant is matched.
+
+The pattern match format uses the syntax `Enum::Variant => action`. When using `match` each variant much be _enumerated_:
+
+::: aside
+`=>` is often referred to as "fat arrow." But if you say "chompky" I'll also get it.
+:::
+
+```rust
+match my_shape {
+    Shape::Triangle => todo!(),
+    Shape::Rectangle => todo!(),
+    Shape::Pentagon => todo!(),
+    Shape::Hexagon => todo!(),
+}
+```
+
+::: callout-tip
+todo!() is a placeholder that can be used to make the compiler happy
+:::
+
+
+### Example
+
+For example we may want to print the number of verticies of a shape:
+
+```rust
+let my_shape = Shape::Triangle;
+
+match my_shape {
+    Shape::Triangle => println!("A triangle has 3 vertices"),
+    Shape::Rectangle => println!("A rectangle has 4 vertices"),
+    Shape::Pentagon => println!("A pentagon has 5 vertices"),
+    Shape::Hexagon => println!("A hexagon has 6 vertices"),
+}
+```
+
+## Wildcard matching
+
+Sometimes we want to customize behavior on only a subset of variants. We can use a catch all in the match statement `_ =>` use the underscore to signify "everything else".
+
+```rust
+match my_shape {
+    Shape::Hexagon => println!("Hexagons are the bestagons"),
+    _ => println!("Every other polygon is mid"),
+}
+```
+
+## Enums can `impl`, too
+
+Enums can have methods too just like a struct using `impl` keyword
+
+```rust
+impl Shape {
+    fn is_bestagon(&self) -> bool {
+        match self {
+            Self::Hexagon => true,
+            _ => false
+        }
+    }
+}
+```
+
+
+## Exercise 1
+
+- Create an enum called `Measure` with two variants `Euclidean` and `Haversine`
+- Create a method called `ndim()` which returns `2` for `Euclidean` and `3` for `Haversine`
+
+<details>
+    <summary>View solution</summary>
+
+```rust
+enum Measure {
+    Euclidean,
+    Haversine,
+}
+
+impl Measure {
+    fn ndim(&self) -> i32 {
+        match self {
+            Self::Euclidean => 2,
+            Self::Haversine => 3
+        }
+    }
+}
+```
+
+</details>
+
+## Exercise 2
+
+
+- Create a new method `distance()` for `Point` struct that returns an `f64`
+  - Arguments: `&self`, `destination: &Self`, `measure: &Measure`
+- When `measure` is `Euclidean` use the `euclidean_distance()` method
+- When the variant is `Haversine` use the `haversine_distance()` method
+
+The haversine method is defined as:
+
+<details>
+<summary>Code for `haversine_distance()` </summary>
+```rust
+impl Point {
+    fn haversine_distance(&self, destination: &Self) -> f64 {
+        let radius = 6_371_008.7714; // Earth's mean radius in meters
+        let theta1 = self.y.to_radians(); // Latitude of point 1
+        let theta2 = destination.y.to_radians(); // Latitude of point 2
+        let delta_theta = (destination.y - self.y).to_radians(); // Delta Latitude
+        let delta_lambda = (destination.x - self.x).to_radians(); // Delta Longitude
+
+        let a = (delta_theta / 2f64).sin().powi(2)
+            + theta1.cos() * theta2.cos() * (delta_lambda / 2f64).sin().powi(2);
+
+        2f64 * a.sqrt().asin() * radius
+    }
+}
+```
+
+</details>
+
+
+<details>
+<summary>View solution</summary>
+```rust
+
+impl Point {
+    // Demonstrates using pattern matching an enum
+    fn distance(&self, destination: &Self, measure: &Measure) -> f64 {
+        match measure {
+            Measure::Euclidean => self.euclidean_distance(destination),
+            Measure::Haversine => self.haversine_distance(destination),
+        }
+    }
+}
+```