docs: clarify AsRef and AsMut exercise

exercises/23_conversions/README.md

@@ -11,6 +11,11 @@ The traits are the following:
 - `TryFrom` and `TryInto` covered in [`conversions4`](conversions4.rs)
 - `AsRef` and `AsMut` covered in [`conversions5`](conversions5.rs)
 
+`AsRef` and `AsMut` are useful when a function only needs to borrow a value in
+another form. For example, a function accepting `T: AsRef<str>` can work with
+both a string slice and an owned `String` without requiring separate
+implementations for each type.
+
 Furthermore, the `std::str` module offers a trait called [`FromStr`](https://doc.rust-lang.org/std/str/trait.FromStr.html) which helps with converting strings into target types via the `parse` method on strings. If properly implemented for a given type `Person`, then `let p: Person = "Mark,20".parse().unwrap()` should both compile and run without panicking.
 
 These should be the main ways ***within the standard library*** to convert data into your desired types.

exercises/23_conversions/conversions5.rs

@@ -1,22 +1,27 @@
-// AsRef and AsMut allow for cheap reference-to-reference conversions. Read more
+// `AsRef` and `AsMut` let a function accept different input types while
-// about them at https://doc.rust-lang.org/std/convert/trait.AsRef.html and
+// borrowing the value it needs. For example, both `&str` and `String` can be
-// https://doc.rust-lang.org/std/convert/trait.AsMut.html, respectively.
+// viewed as `&str`, and both `u32` and `Box<u32>` can be viewed as `&mut u32`.
+// Read more about them at https://doc.rust-lang.org/std/convert/trait.AsRef.html
+// and https://doc.rust-lang.org/std/convert/trait.AsMut.html, respectively.
 
-// Obtain the number of bytes (not characters) in the given argument
+// Obtain the number of bytes (not characters) in the given argument. The
-// (`.len()` returns the number of bytes in a string).
+// `AsRef<str>` bound allows this function to work with both `&str` and `String`.
+// (`.len()` returns the number of bytes in a string.)
 // TODO: Add the `AsRef` trait appropriately as a trait bound.
 fn byte_counter<T>(arg: T) -> usize {
     arg.as_ref().len()
 }
 
-// Obtain the number of characters (not bytes) in the given argument.
+// Obtain the number of characters (not bytes) in the given argument. Reuse the
+// same `AsRef<str>` bound so this function also accepts `&str` and `String`.
 // TODO: Add the `AsRef` trait appropriately as a trait bound.
 fn char_counter<T>(arg: T) -> usize {
     arg.as_ref().chars().count()
 }
 
-// Squares a number using `as_mut()`.
+// Square a number through a mutable reference. The `AsMut<u32>` bound allows
-// TODO: Add the appropriate trait bound.
+// this function to work with values such as `Box<u32>` as well as `u32`.
+// TODO: Add the `AsMut<u32>` trait bound.
 fn num_sq<T>(arg: &mut T) {
     // TODO: Implement the function body.
 }

solutions/23_conversions/conversions5.rs

@@ -1,19 +1,24 @@
-// AsRef and AsMut allow for cheap reference-to-reference conversions. Read more
+// `AsRef` and `AsMut` let a function accept different input types while
-// about them at https://doc.rust-lang.org/std/convert/trait.AsRef.html and
+// borrowing the value it needs. For example, both `&str` and `String` can be
-// https://doc.rust-lang.org/std/convert/trait.AsMut.html, respectively.
+// viewed as `&str`, and both `u32` and `Box<u32>` can be viewed as `&mut u32`.
+// Read more about them at https://doc.rust-lang.org/std/convert/trait.AsRef.html
+// and https://doc.rust-lang.org/std/convert/trait.AsMut.html, respectively.
 
-// Obtain the number of bytes (not characters) in the given argument
+// Obtain the number of bytes (not characters) in the given argument. The
-// (`.len()` returns the number of bytes in a string).
+// `AsRef<str>` bound allows this function to work with both `&str` and `String`.
+// (`.len()` returns the number of bytes in a string.)
 fn byte_counter<T: AsRef<str>>(arg: T) -> usize {
     arg.as_ref().len()
 }
 
-// Obtain the number of characters (not bytes) in the given argument.
+// Obtain the number of characters (not bytes) in the given argument. Reuse the
+// same `AsRef<str>` bound so this function also accepts `&str` and `String`.
 fn char_counter<T: AsRef<str>>(arg: T) -> usize {
     arg.as_ref().chars().count()
 }
 
-// Squares a number using `as_mut()`.
+// Square a number through a mutable reference. The `AsMut<u32>` bound allows
+// this function to work with values such as `Box<u32>` as well as `u32`.
 fn num_sq<T: AsMut<u32>>(arg: &mut T) {
     let arg = arg.as_mut();
     *arg *= *arg;