lesson 05: change text (#99)

Co-authored-by: Wojciech Przytuła <[email protected]>

Author: tonowak

content/lessons/05_types_reasoning/generics.rs

@@ -2,19 +2,19 @@
 
 use std::fmt::Debug;
 
-// generic enums
+// Generic enums.
 enum OurOption<T> {
     Some(T),
     None,
 }
 
-// generic structs
+// Generic structs.
 struct Tuple2<T, U> {
     x: T,
     y: U,
 }
 
-// generic implementation
+// Generic implementation.
 impl<T, U> Tuple2<T, U> {
     fn new(x: T, y: U) -> Self {
         Self { x, y }
@@ -26,7 +26,7 @@ struct Pair<T> {
     y: T,
 }
 
-// conditional implementation
+// Conditional implementation.
 impl<T: PartialOrd + Copy> Pair<T> {
     fn largest(&self) -> T {
         if self.x > self.y {
@@ -37,7 +37,7 @@ impl<T: PartialOrd + Copy> Pair<T> {
     }
 }
 
-// alternative syntax
+// Alternative syntax.
 impl<T> Pair<T>
 where
     T: PartialOrd + Copy,
@@ -51,19 +51,24 @@ where
     }
 }
 
-// Here information about the concrete underlying type is preserved.
+// The information about the concrete underlying type is preserved.
+// If I call it with a `String`, then I get back a `String`.
 fn cloning_machine<T: Clone + Debug>(item: &T) -> T {
     item.clone()
 }
 
-// Here information about the concrete underlying type is erased.
+// The information about the concrete underlying type is erased.
 // We can only either format or clone the result.
-fn erasing_cloning_machine1(item: &(impl Clone + Debug)) -> impl Clone + Debug {
+// If I call it with a `String`, then I'll only know that the return type
+// implements `Clone + Debug`.
+fn erasing_cloning_machine2<T: Clone + Debug>(item: &T) -> impl Clone + Debug {
     item.clone()
 }
 
-// Ditto.
-fn erasing_cloning_machine2<T: Clone + Debug>(item: &T) -> impl Clone + Debug {
+// The returned type behaves exactly the same as above (it's the same type, after all)
+// and the function has the same requirements for the `item` argument.
+// But inside the implementation of the function, we can't use `T` (it's not defined anywhere).
+fn erasing_cloning_machine1(item: &(impl Clone + Debug)) -> impl Clone + Debug {
     item.clone()
 }
 

content/lessons/05_types_reasoning/generics_fun.rs

@@ -21,7 +21,7 @@ impl Display for Bar {
 
 impl Default for Bar {
     fn default() -> Self {
-        Bar // well, we have no other choice
+        Bar // Well, we have no other choice.
     }
 }
 
@@ -30,6 +30,9 @@ impl DefaultishablyPrintable<i32> for Foo {}
 impl DefaultishablyPrintable<Bar> for Foo {}
 
 fn main() {
+    // By typing `Foo as DefaultishablyPrintable<i32>`,
+    // we tell the compiler to treat this `Foo` struct as
+    // only a `DefaultishablyPrintable<i32>` trait.
     <Foo as DefaultishablyPrintable<i32>>::defaultish_print();
     <Foo as DefaultishablyPrintable<Bar>>::defaultish_print();
 }

content/lessons/05_types_reasoning/index.md

@@ -1,9 +1,9 @@
 +++
 title = "Reasoning About Types"
-date = 2029-01-01
+date = 2025-10-20
 weight = 1
-[extra]   
-lesson_date = 2029-01-01
+[extra]
+lesson_date = 2025-10-23
 +++
 
 # Type traits
@@ -22,9 +22,11 @@ Trait definitions can also be provided with default implementations of behaviors
 
 ## What about _derive_?
 
-There is a trait-related thing we have used quite extensively and not explained yet, namely the `#[derive]` attribute. What it does is generate items (in our case a trait implementation) based on the given data definition (here a struct). Below you can find a list of derivable traits from the standard library. Writing derivation rules for user defined traits is also possible, but goes out of the scope of this lesson.
+There is a trait-related feature we have used quite extensively but not explained yet, namely the `#[derive]` attribute. When placed above a struct or enum, it tells the compiler to generate an implementation of certain traits automatically. For example, `#[derive(Debug)]` will cause the compiler to create the necessary `impl Debug for YourType { ... }` code behind the scenes, so that your type can be printed with `{:?}` in `println!`.
 
-Derivable traits:
+We'll learn about how to make it work with our own traits in the next lessons. For now, you can think of `derive` as a kind of code generator built into the compiler, which is especially useful when the implementation of a trait can be generalized for any type.
+
+Below you can find a list of derivable traits from the standard library.
 
 - Equality traits: `Eq`, `PartialEq` and comparison traits: `Ord` and `PartialOrd`. The `Partial-` versions exist because there are types which don't fulfill the reflexivity requirement of equality (`NaN != NaN`) or do not form a total order (` NaN < 0.0 == false` and `NaN >= 0.0 == false`).
 
@@ -34,15 +36,15 @@ Derivable traits:
 
 - `Default` - provides a zero-arg constructor function
 
-- `Debug` - provides a formatting of the value which can be used in debugging context. It should _NOT_ be implemented manually. In general, if it's possible to derive the `Debug`, there are no reasons against doing it.
+- `Debug` - provides a formatting of the value which can be used in debugging context. Because the `derive` attribute automatically implements a pretty way of formatting, it is discouraged to implement this trait manually. In general, if it's possible to derive the `Debug`, there are no reasons against doing it.
 
 ### When is it possible to derive a trait?
 
 When all fields of a struct/variants of an enum implement that trait.
 
 ### Should all traits always be derived if it is possible?
 
-No. Although it may be tempting to just slap `#[derive(Clone, Copy)]` everywhere, it would be counter-effective. For example, at some later point you might add a non-Copy field to the struct and your (or, what's worse, someone else's!) code would break. Another example: it makes little sense to use containers as keys in hashmaps or to compare tweets.
+No. Although it may be tempting to just slap `#[derive(Clone, Copy)]` everywhere, it would be counter-effective. For example, at some later point you might add a non-`Copy` field to the struct and your (or, what's worse, someone else's!) code would break. Another example: it makes little sense to use containers as keys in hashmaps or to compare tweets.
 
 # Generics
 
@@ -52,7 +54,7 @@ Suppose we want to find the largest element in a sequence and return it. Very mu
 
 Perfect, it works! Now only twenty more types to go...
 
-Fortunately, Rust gives us a way to avoid all this code duplication and generalize the types we're working on.
+Of course, Rust gives us a way to avoid all this code duplication and generalize the types we're working on.
 
 ```rust
 fn largest<T>(list: &[T]) -> T {
@@ -85,7 +87,7 @@ help: consider restricting type parameter `T`
   |             ++++++++++++++++++++++
 ```
 
-Since `T` can be of absolutely any type now, the compiler cannot be sure that operator `>` is defined. This aligns with what we wanted, as without comparing elements we don't have a notion of the largest one either. As always, the compiler comes to our aid:
+Since `T` can be of absolutely any type now, the compiler cannot be sure that operator `>` is defined. This aligns with what we wanted, as without comparing elements we don't have a notion of the largest one either. As always, the compiler messages come to our aid:
 
 ```rust
 fn largest<T: PartialOrd>(list: &[T]) -> T {
@@ -135,7 +137,7 @@ There's a lot more that we can do with generics:
 
 {{ include_code_sample(path="lessons/05_types_reasoning/generics.rs", language="rust") }}
 
-A bit more involved example:
+An example where we can specify which generic trait implementation we want to call:
 
 {{ include_code_sample(path="lessons/05_types_reasoning/generics_fun.rs", language="rust") }}
 
@@ -145,6 +147,7 @@ A bit more involved example:
 
 # Lifetimes
 
+Let's go into a completely different topic now.
 Going back to the lesson about ownership, if we try to compile the following code:
 
 ```rust
@@ -281,7 +284,7 @@ error[E0597]: `string2` does not live long enough
 
 ## Lifetime elision
 
-We now know how to explicitly write lifetime parameters, but you might recall that we don't always have to that. Indeed, Rust will first try to figure out the lifetimes itself, applying a set of predefined rules. We call this _lifetime elision_.
+We now know how to explicitly write lifetime parameters, but you might recall that we don't always have to do that. Indeed, Rust will first try to figure out the lifetimes itself, applying a set of predefined rules. We call this _lifetime elision_.
 
 {{ include_code_sample(path="lessons/05_types_reasoning/lifetimes_elision.rs", language="rust") }}
 
@@ -360,8 +363,12 @@ Example:
 
 - [Polymorphism in Rust](https://oswalt.dev/2021/06/polymorphism-in-rust/)
 
+# Optional reading
+
+- [Rust Blog - Precise capturing `use<..>` syntax](https://blog.rust-lang.org/2024/10/17/Rust-1.82.0/#precise-capturing-use-syntax)
+
 ## Assignment 3 (graded)
 
-[Passage Pathing](https://classroom.github.com/a/VTyPdlC2)
+[Passage Pathing](https://classroom.github.com/a/XVoSKs94)
 
-Deadline: 30.10.2024 23:59
+Deadline: per-group.

content/lessons/05_types_reasoning/static_dynamic_dispatch.rs

@@ -6,7 +6,7 @@ struct Dog;
 
 impl Speak for Dog {
     fn speak(&self) -> &'static str {
-        "Hau hau" // it's a Polish dog!
+        "Hau hau" // It's a Polish dog!
     }
 }
 
@@ -18,14 +18,14 @@ impl Speak for Human {
     }
 }
 
-// It works like templates in C++
-// A different function will be generated for each T during compilation
-// This process is called "monomorphization"
+// It works like templates in C++.
+// A different function will be generated for each T during compilation.
+// This process is called "monomorphization".
 fn static_dispatch<T: Speak>(speaking: &T) {
     println!("{}!", speaking.speak());
 }
 
-// Only one copy of that function will exist in the compiled binary
+// Only one copy of that function will exist in the compiled binary.
 fn dynamic_dispatch(speaking: &dyn Speak) {
     println!("{}!", speaking.speak());
 }
@@ -40,7 +40,7 @@ fn main() {
     dynamic_dispatch(&dog);
     dynamic_dispatch(&human);
 
-    // The observable behavior is identical
+    // The observable behavior is identical.
     // Static dispatch in general is a bit faster,
     // because there is no need to perform a "vtable lookup".
     // But it can also result in bigger binary sizes.