Merge remote-tracking branch 'origin/slides/217-create_gnatstub_training_module' into slides/209-process_include_statements

Author: frank-at-adacore

contrib/rst_files_with_prelude.txt

@@ -11,3 +11,4 @@ courses/gnat_project_facility/*.rst
 courses/gnatcoverage/*.rst
 courses/rust_essentials/*.rst
 courses/comprehensive_rust_training/*.rst
+courses/misc_tools/*.rst

courses/comprehensive_rust_training/030_types_and_values.rst

@@ -41,4 +41,4 @@ Types And Values
 .. include:: 030_types_and_values/03_values.rst
 .. include:: 030_types_and_values/04_arithmetic.rst
 .. include:: 030_types_and_values/05_inference.rst
-.. include:: 030_types_and_values/06_exercise.rst
+.. include:: 030_types_and_values/99_lab.rst

courses/comprehensive_rust_training/030_types_and_values/06_exercise.rst courses/comprehensive_rust_training/030_types_and_values/99_lab.rst

@@ -3,7 +3,7 @@ Exercise: Fibonacci
 =====================
 
 ---------------------
-Exercise: Fibonacci
+Fibonacci Problem
 ---------------------
 
 The Fibonacci sequence begins with :rust:`[0,1]`. For n>1, the n'th
@@ -13,9 +13,9 @@ n-2'th Fibonacci numbers.
 Write a function :rust:`fib(n)` that calculates the n'th Fibonacci number.
 When will this function panic?
 
-::
+.. code:: rust
 
-   {{#include exercise.rs:fib}}
+   fn fib(n: u32) -> u32 {
        if n < 2 {
            // The base case.
            return todo!("Implement this");
@@ -25,4 +25,26 @@ When will this function panic?
        }
    }
 
-   {{#include exercise.rs:main}}
+   fn main() {
+       let n = 20;
+       println!("fib({n}) = {}", fib(n));
+   }
+
+---------------------
+Fibonacci Solution
+---------------------
+
+.. code:: rust
+
+   fn fib(n: u32) -> u32 {
+       if n < 2 {
+           return n;
+       } else {
+           return fib(n - 1) + fib(n - 2);
+       }
+   }
+
+   fn main() {
+       let n = 20;
+       println!("fib({n}) = {}", fib(n));
+   }

courses/comprehensive_rust_training/040_control_flow_basics.rst

@@ -43,4 +43,4 @@ Control Flow Basics
 .. include:: 040_control_flow_basics/05_blocks_and_scopes.rst
 .. include:: 040_control_flow_basics/06_functions.rst
 .. include:: 040_control_flow_basics/07_macros.rst
-.. include:: 040_control_flow_basics/08_exercise.rst
+.. include:: 040_control_flow_basics/99_lab.rst

courses/comprehensive_rust_training/040_control_flow_basics/08_exercise.rst courses/comprehensive_rust_training/040_control_flow_basics/99_lab.rst

@@ -3,7 +3,7 @@ Exercise: Collatz Sequence
 ============================
 
 ----------------------------
-Exercise: Collatz Sequence
+Collatz Sequence Problem
 ----------------------------
 
 The
@@ -28,12 +28,37 @@ For example, beginning with ``n1`` = 3:
 Write a function to calculate the length of the collatz sequence for a
 given initial :rust:`n`.
 
-::
+.. code:: rust
 
-   {{#include exercise.rs:collatz_length}}
+   /// Determine the length of the
+   /// collatz sequence beginning at `n`.
+   fn collatz_length(mut n: i32) -> u32 {
      todo!("Implement this")
    }
 
-   {{#include exercise.rs:tests}}
+   fn main() {
+       // should be 15
+       println!("Length: {}", collatz_length(11));
+   }
+
+----------------------------
+Collatz Sequence Solution
+----------------------------
 
-   {{#include exercise.rs:main}}
+.. code:: rust
+
+   /// Determine the length of the
+   /// collatz sequence beginning at `n`.
+   fn collatz_length(mut n: i32) -> u32 {
+       let mut len = 1;
+       while n > 1 {
+           n = if n % 2 == 0 { n / 2 } else { 3 * n + 1 };
+           len += 1;
+       }
+       len
+   }
+
+   fn main() {
+       // should be 15
+       println!("Length: {}", collatz_length(11));
+   }

courses/comprehensive_rust_training/050_tuples_and_arrays.rst

@@ -40,4 +40,4 @@ Tuples And Arrays
 .. include:: 050_tuples_and_arrays/02_tuples.rst
 .. include:: 050_tuples_and_arrays/03_iteration.rst
 .. include:: 050_tuples_and_arrays/04_destructuring.rst
-.. include:: 050_tuples_and_arrays/05_exercise.rst
+.. include:: 050_tuples_and_arrays/99_lab.rst

courses/comprehensive_rust_training/050_tuples_and_arrays/05_exercise.rst

@@ -0,0 +1,87 @@
+=========================
+Exercise: Nested Arrays
+=========================
+
+-------------------------
+Nested Arrays Problem
+-------------------------
+
+Arrays can contain other arrays:
+
+.. code:: rust
+
+   let array = [[1, 2, 3], [4, 5, 6], [7, 8, 9]];
+
+What is the type of this variable?
+
+Use an array such as the above to write a function :rust:`transpose` which
+will transpose a matrix (turn rows into columns):
+
+Transpose
+
+.. math::
+
+   \begin{bmatrix}
+      1 & 2 & 3 \\
+      4 & 5 & 6 \\
+      7 & 8 & 9
+   \end{bmatrix}
+
+into
+
+.. math::
+
+   \begin{bmatrix}
+      1 & 4 & 7 \\
+      2 & 5 & 8 \\
+      3 & 6 & 9
+   \end{bmatrix}
+
+Copy the code below to https://play.rust-lang.org/ and implement the
+function. This function only operates on 3x3 matrices.
+
+.. code:: rust
+
+   fn transpose(matrix: [[i32; 3]; 3]) -> [[i32; 3]; 3] {
+       todo!()
+   }
+
+   fn main() {
+       let matrix = [
+           [101, 102, 103], //  comment makes rustfmt add newline
+           [201, 202, 203],
+           [301, 302, 303],
+       ];
+
+       dbg!(matrix);
+       let transposed = transpose(matrix);
+       dbg!(transposed);
+   }
+
+-------------------------
+Nested Arrays Solution
+-------------------------
+
+.. code:: rust
+
+   fn transpose(matrix: [[i32; 3]; 3]) -> [[i32; 3]; 3] {
+       let mut result = [[0; 3]; 3];
+       for i in 0..3 {
+           for j in 0..3 {
+               result[j][i] = matrix[i][j];
+           }
+       }
+       result
+   }
+
+   fn main() {
+       let matrix = [
+           [101, 102, 103], //  comment makes rustfmt add newline
+           [201, 202, 203],
+           [301, 302, 303],
+       ];
+
+       dbg!(matrix);
+       let transposed = transpose(matrix);
+       dbg!(transposed);
+   }

courses/comprehensive_rust_training/050_tuples_and_arrays/99_lab.rst

@@ -41,4 +41,4 @@ References
 .. include:: 060_references/03_slices.rst
 .. include:: 060_references/04_strings.rst
 .. include:: 060_references/05_dangling.rst
-.. include:: 060_references/06_exercise.rst
+.. include:: 060_references/99_lab.rst

courses/comprehensive_rust_training/060_references.rst

@@ -0,0 +1,79 @@
+====================
+Exercise: Geometry
+====================
+
+--------------------
+Geometry Problem
+--------------------
+
+We will create a few utility functions for 3-dimensional geometry,
+representing a point as :rust:`[f64;3]`. It is up to you to determine the
+function signatures.
+
+::
+
+   // Calculate the magnitude of a vector by summing the squares of its coordinates
+   // and taking the square root. Use the `sqrt()` method to calculate the square
+   // root, like `v.sqrt()`.
+
+   fn magnitude(...) -> f64 {
+       todo!()
+   }
+
+   // Normalize a vector by calculating its magnitude and dividing all of its
+   // coordinates by that magnitude.
+
+   fn normalize(...) {
+       todo!()
+   }
+
+   // Use the following `main` to test your work.
+
+   fn main() {
+       println!("Magnitude of a unit vector: {}", magnitude(&[0.0, 1.0, 0.0]));
+
+       let mut v = [1.0, 2.0, 9.0];
+       println!("Magnitude of {v:?}: {}", magnitude(&v));
+       normalize(&mut v);
+       println!("Magnitude of {v:?} after normalization: {}", magnitude(&v));
+   }
+
+--------------------
+Geometry Solution
+--------------------
+
+.. code:: rust
+
+   /// Calculate the magnitude of the given vector.
+   fn magnitude(vector: &[f64; 3]) -> f64 {
+       let mut mag_squared = 0.0;
+       for coord in vector {
+           mag_squared += coord * coord;
+       }
+       mag_squared.sqrt()
+   }
+
+   /// Change the magnitude of the vector to 1.0 without changing its direction.
+   fn normalize(vector: &mut [f64; 3]) {
+       let mag = magnitude(vector);
+       for item in vector {
+           *item /= mag;
+       }
+   }
+
+   fn main() {
+       println!("Magnitude of a unit vector: {}", magnitude(&[0.0, 1.0, 0.0]));
+
+       let mut v = [1.0, 2.0, 9.0];
+       println!("Magnitude of {v:?}: {}", magnitude(&v));
+       normalize(&mut v);
+       println!("Magnitude of {v:?} after normalization: {}", magnitude(&v));
+   }
+
+------------------------
+Additional Information
+------------------------
+
+Note that in :rust:`normalize` we wrote :rust:`*item /= mag` to modify each element.
+
+This is because we’re iterating using a mutable reference to an array, which causes the :rust:`for` loop to give mutable references to each element.

courses/comprehensive_rust_training/060_references/06_exercise.rst

@@ -42,4 +42,4 @@ User Defined Types
 .. include:: 070_user_defined_types/04_aliases.rst
 .. include:: 070_user_defined_types/05_const.rst
 .. include:: 070_user_defined_types/06_static.rst
-.. include:: 070_user_defined_types/07_exercise.rst
+.. include:: 070_user_defined_types/99_lab.rst