Merge pull request #15 from sb1752/chp8-clarity

sb1752 · web-flow · commit ab9183589021 · 2024-05-19T21:26:26.000-07:00
explain required vs provided trait methods based on feedback
diff --git a/08_traits_and_reading_bytes.md b/08_traits_and_reading_bytes.md
@@ -12,11 +12,44 @@ Notice how we're grabbing different ranges of `transaction_bytes`. We have to re
 
 One way to read a byte stream is to leverage Rust's standard library's [`Read`](https://doc.rust-lang.org/std/io/trait.Read.html) trait. The slice data type in Rust implements the `Read` trait. What does this mean? Well, as we will see, it gives us a method, `read`, which will read some bytes from the slice and then store that data into a array. When we call `read` again, it will start from where it left off. In other words, it keeps track of where we are in the stream and modifies the pointer as it reads. This means we don't need to keep track of any indexes.
 
-## Traits
+Let's walk through how this works at a high level with a quick example and then dive deeper into what traits are and how they work.
 
-We've mentioned traits a few times now, but haven't gone into detail about what they are and how they work. We'll get some more practice with them later on, but for now it's enough to understand that traits are a way to define shared behavior. You can think of them as a template for a particular behavior. For example, the `Read` trait provides a template for types that want to "read data". It lays out what to expect and what types of functions are available.
+In order to use a trait method we have to first bring it into scope with a `use` statement. In this case, we want to bring the `Read` trait into scope with `use std::io::Read`. The next thing we want to do is use the `read` method as intended based on the example from the [documentation](https://doc.rust-lang.org/std/io/trait.Read.html#examples).
 
-Let's take a closer look at [`Read` from the documentation](https://doc.rust-lang.org/std/io/trait.Read.html). It has a required method, `read`, which has the following function signature: `fn read(&mut self, buf: &mut [u8]) -> Result<usize>;`. 
+You can follow along with this example in [Rust Playground](https://play.rust-lang.org/?version=stable&mode=debug&edition=2021&gist=627e8e7c10d530819a80f189cedded13).
+```rust
+use std::io::Read;
+
+fn main() {
+    let mut bytes_slice: &[u8] = [1, 0, 0, 0, 2].as_slice();
+    let mut buffer = [0; 4];
+    bytes_slice.read(&mut buffer).unwrap();
+
+    let version = u32::from_le_bytes(buffer);
+
+    println!("Version: {}", version);
+}
+```
+
+The `mut` keyword before `bytes_slice` tells Rust the variable is mutable. If we don't provide that keyword in a variable declaration, then the compiler will complain that we're attempting to change an immutable variable, which is not allowed. 
+
+You might also notice the `&mut` keyword in the argument to the `read` method. This indicates that we're passing in `buffer` as a *mutable reference*. We'll talk more about this means in the next chapter so for now let's not worry about that nuance. 
+
+When we run this, it will print the following:
+```console
+Version: 1
+Bytes slice: [2]
+```
+
+And this is what we'd expect. The Version is `1`. And the `bytes_slice` variable has been updated and no longer contains the first 4 bytes. 
+
+You may notice that the way this works is that you have to first create an array with a fixed size. Calling `read` will then extract the number of bytes equal to the size of the array, store that into a buffer and then update our slice.
+
+## Traits Explanation
+
+So what are traits exactly? Traits are a way to define shared behavior. You can think of them as a template for a particular set of behaviors. For example, the `Read` trait provides a template for types that want to "read data". It lays out what to expect and what types of functions are available.
+
+Let's take a closer look at the `Read` trait [from the documentation](https://doc.rust-lang.org/std/io/trait.Read.html). It has a required method, `read`, which has the following function signature: `fn read(&mut self, buf: &mut [u8]) -> Result<usize>;`. 
 
 ```rust
 ...
@@ -28,9 +61,13 @@ pub trait Read {
 ...
 ```
 
-The functions themselves are not actually implemented with any logic. You'll notice there's no function body, just the signature. The types that implement this trait are expected to provide the function logic for each of these methods. So the trait is really just a template. 
+The `read` method itself is not actually implemented with any logic. You'll notice there's no function body, just the signature. The types that "implement" this trait are expected to provide the function logic for any *required* method, or trait methods that have no implementation.
+
+A trait can also provide other methods that a type can get access to once it has implemented the trait. These are known as *provided* methods and are considered *default* implementations since they can also be overwritten. You'll notice for example that there is a [`read_exact` method](https://doc.rust-lang.org/std/io/trait.Read.html#method.read_exact) which is implemented with a call to the [`default_read_exact`](https://doc.rust-lang.org/src/std/io/mod.rs.html#558) method.
 
-Now, if we look at the `slice` type from the documentation, we can see that it [*implements* `Read`](https://doc.rust-lang.org/std/primitive.slice.html#impl-Read-for-%26%5Bu8%5D) meaning it provides the function logic for the given trait template. Let's take a look at the [implementation](https://doc.rust-lang.org/src/std/io/impls.rs.html#235-250):
+As long as a type implements the `Read` trait by providing a `read` method, it will have access to these other *provided* methods. A type can also choose to override some or all of these *provided* methods as well and have its own implementations.
+
+Now if we look at the `slice` type from the documentation, we can see that it [*implements* the `Read` trait](https://doc.rust-lang.org/std/primitive.slice.html#impl-Read-for-%26%5Bu8%5D) and provides the function logic for the `read` method. Let's take a look at [the source code](https://doc.rust-lang.org/src/std/io/impls.rs.html#235-250):
 
 ```rust
 ...
@@ -58,54 +95,12 @@ impl Read for &[u8] {
 ...
 ```
 
-Don't worry if you don't understand how to read all of this just yet! Simply notice how we *implement* a trait with the `impl` keyword. So `impl Read for &[u8]` is the code block that provides the function logic for the trait. The other thing to notice is how the function signature matches the trait's function signature.
-
-The idea here is that different types, not just the `&[u8]` type can implement the `Read` trait and then be expected to have a similar behavior. The function logic itself for each type might differ, but they are expected to take in the same arguments, return the same type and generally do the same thing, which in this case is to read some data and modify `self` and the buffer. You might notice some patterns here that you are not yet familiar with, such as the `&mut` keyword and asterisk `*` before `self` at the bottom of the function. Don't worry, we'll go into more detail about what these mean in the next lesson.
-
-For now, let's experiment by following the second example from the [documentation for Read](https://doc.rust-lang.org/std/io/trait.Read.html#examples). We'll comment out our original code and experiment with these new lines:
-```rust
-fn main() {
-    let bytes_slice: &[u8] = [1, 0, 0, 0, 2].as_slice();
-    let mut buffer = [0; 4];
-    bytes_slice.read(&mut buffer).unwrap();
-
-    let version = u32::from_le_bytes(buffer);
-
-    println!("Version: {}", version);
-    println!("Bytes Slice: {:?}", bytes_slice);
-
-    // let version = read_version("010000000242d5c1d6f7308bbe95c0f6e1301dd73a8da77d2155b0773bc297ac47f9cd7380010000006a4730440220771361aae55e84496b9e7b06e0a53dd122a1425f85840af7a52b20fa329816070220221dd92132e82ef9c133cb1a106b64893892a11acf2cfa1adb7698dcdc02f01b0121030077be25dc482e7f4abad60115416881fe4ef98af33c924cd8b20ca4e57e8bd5feffffff75c87cc5f3150eefc1c04c0246e7e0b370e64b17d6226c44b333a6f4ca14b49c000000006b483045022100e0d85fece671d367c8d442a96230954cdda4b9cf95e9edc763616d05d93e944302202330d520408d909575c5f6976cc405b3042673b601f4f2140b2e4d447e671c47012103c43afccd37aae7107f5a43f5b7b223d034e7583b77c8cd1084d86895a7341abffeffffff02ebb10f00000000001976a9144ef88a0b04e3ad6d1888da4be260d6735e0d308488ac508c1e000000000017a91476c0c8f2fc403c5edaea365f6a284317b9cdf7258700000000");
-    // println!("Version: {}", version);
-}
-```
-
-Try running this now with `cargo run`. This fail to compile. You'll get a compile error that the `read` method is not found for `&[u8]`. This is because the trait implementations only become available when the trait is brought into scope with a `use` import. So you just need to add a `use std::io::Read;` line at the top. Let's add that and run this again.
-
-We'll get another compile error: 
-```rust
-error[E0596]: cannot borrow `bytes_slice` as mutable, as it is not declared as mutable
-  --> src/main.rs:12:5
-   |
-12 |     bytes_slice.read(&mut buffer).unwrap();
-   |     ^^^^^^^^^^^ cannot borrow as mutable
-   |
-help: consider changing this to be mutable
-   |
-10 |     let mut bytes_slice: &[u8] = [1, 0, 0, 0, 2].as_slice();
-   |         +++
-```
-
-This is a straightforward idea that we haven't talked about until now, but in Rust if any variable is going to be modified, we have to explicitly declare it as *mutable* with the `mut` keyword. This just means that the variable is allowed to change. The `read` method will attempt to modify our `bytes_slice` so we have to declare it as *mutable*. 
-
-Ok, if we add that and run it again, it should work and will print out the following:
-```shell
-Version: 1
-Bytes Slice: [2]
-```
+Don't worry if you don't understand what all of this means just yet! Simply notice how we *implement* a trait with the `impl` keyword. So `impl Read for &[u8]` is the code block that provides the function logic for the trait. The other thing to notice is how the function signature for `read` matches the trait's function signature.
 
-We converted the 4 bytes from the buffer into an unsigned 32-bit integer. And notice how the bytes slice has been modified after being read into the buffer. It no longer contains the first 4 elements, `[1, 0, 0, 0]`.
+The idea here is that different types, not just the `&[u8]` type can implement the `Read` trait by providing the function logic for any required method and then be expected to have similar behavior and get access to the trait's provided methods. 
+The function logic itself for each type might differ, but given the template they are expected to take in the same arguments, return the same type and generally do the same thing, which in this case is to read some data and modify `self` and the buffer.
 
-You may notice that the way this works is that you have to first create an array with a known size. Calling `read` will then extract the number of bytes equal to the size of the array, store that into our buffer and then modify our fat pointer reference to the underlying data.
+Again, you might notice some patterns in the code above that you are not yet familiar with, such as the `&mut` keyword and asterisk `*` before `self` at the bottom of the function. We'll go into more detail about what these mean in the next lesson.
 
 Let's now update our program to print out the version number leveraging the `Read` trait. We can convert the `transaction_bytes` `Vec` to a `slice` type using the `as_slice` method. Here is the modified `read_version` function.
 
@@ -129,12 +124,13 @@ fn main() {
 }
 ```
 
-And voila, this will print `Version: 1` as expected!
+And voila, this will print `Version: 1` as expected! Great job so far! 
 
-But this doesn't seem ideal. How do we grab the modified `bytes_slice` and continue decoding the transaction? What we probably want to do is pass in the `bytes_slice` into this function as an argument and continue using it in the `main` function. We'll talk more about that and associated Rust concepts of references and borrowing in the next section.
+How do we grab the modified `bytes_slice` and continue decoding the transaction? What we probably want to do is pass in the `bytes_slice` into this function as an argument and continue using it in the `main` function. We'll talk more about that and associated Rust concepts of references and borrowing in the next section.
 
 ### Quiz
-*Consider the following block of code in which we create a Vec and then attempt to print it out:*
+1. *Take another look at the `Read` trait and the implementation of the `Read` trait for a slice in the documentation. What are the required and provided methods for the trait? What provided methods are being overwritten by the slice?*
+2. *Consider the following block of code in which we create a Vec and then attempt to print it out:*
 ```rust
 fn main() {
     let vec: Vec::<u8> = vec![0, 0, 0, 0, 0];
diff --git a/09_00_mutable_references.md b/09_00_mutable_references.md
@@ -18,7 +18,7 @@ fn main() {
 
 Notice how we first decode the hex string to get a `vec` of bytes. We then convert that into a slice and then pass that into the `read_version` function.
 
-We'll now have to modify the `read_version` function in order to accept the correct argument. What do you think is the correct type for the the argument? Take a moment and then check back here.
+We'll now have to modify the `read_version` function to accept the correct argument. What do you think is the correct type for the the argument? Take a moment and then check back here.
 
 <hr/>
 
diff --git a/quiz_solutions/08_solution.md b/quiz_solutions/08_solution.md
@@ -1,7 +1,9 @@
 # 8 Solution
 
 ### Quiz
-*Consider the following block of code in which we create a Vec and then attempt to print it out:*
+1. *Take another look at the `Read` trait and the implementation of the `Read` trait for a slice in the documentation. What are the required and provided methods for the trait? What provided methods are being overwritten by the slice?*
+
+2. *Consider the following block of code in which we create a Vec and then attempt to print it out:*
 ```rust
 fn main() {
     let vec: Vec::<u8> = vec![0, 0, 0, 0, 0];
@@ -14,7 +16,9 @@ fn main() {
 *3. Try and implement the correct trait for Vec so that it can be printed for standard display purposes.*
 
 ### Solution
-If we run this and look at the compiler error, we'll get a better sense of what's going on here.
+1. According to the [`Read` trait documentation](https://doc.rust-lang.org/std/io/trait.Read.html), `read` is the only required method. The rest, `read_vectored`, `is_read_vectored`, `read_to_end`, `read_to_string`, `read_exact`, `read_buf`, `read_buf_exact`, `by_ref`, `bytes`, `chain`, and `take` are all provided methods with default implementations. The provided methods that the [slice](https://doc.rust-lang.org/src/std/io/impls.rs.html#233-323) overwrites are `read_vectored`, `is_read_vectored`, `read_to_end`, `read_to_string`, `read_exact` and `read_buf`. 
+
+2. If we run this and look at the compiler error, we'll get a better sense of what's going on here.
 ```console
    Compiling playground v0.0.1 (/playground)
 error[E0277]: `Vec<{integer}>` doesn't implement `std::fmt::Display`
@@ -38,7 +42,7 @@ pub trait Display {
 
 For now, if we wanted to print a `vec` we would have to use `{:?}` inside the println! string slice argument. This will print the `Debug` output and a `vec` does implement `Debug`. 
 
-Let's attempt to implement the `Display` trait for a `vec`:
+Let's attempt to implement the `Display` trait for a `vec` by implementing the required method `fmt`:
 ```rust
 use std::fmt;
 
@@ -58,4 +62,6 @@ fn main() {
 }
 ```
 
-The basic idea is that we leverage the `write!` macro which takes the `Formatter` instance and writes some information to it. If any step fails, an error will be returned. Otherwise, if we iterate through the vector and are able to write all values successfully we can simply return the `Ok(())` result. This might still be a bit confusing at this stage, so consider coming back to revisit this solution after you've gone through the course. 
+The basic idea is that we leverage the `write!` macro which takes the `Formatter` instance and writes some information to it. If any step fails, an error will be returned (we'll talk more about error handling and the `?` operator in chapter 19). If we iterate through the vector and are able to write all values successfully we can simply return the `Ok(())` result, which matches the the expected result type `fmt::Result`. 
+
+This might still be a bit confusing at this stage, so consider coming back to revisit this solution after you've gone through the course.
