Extension traits

src/SUMMARY.md

@@ -437,6 +437,11 @@
     - [Semantic Confusion](idiomatic/leveraging-the-type-system/newtype-pattern/semantic-confusion.md)
     - [Parse, Don't Validate](idiomatic/leveraging-the-type-system/newtype-pattern/parse-don-t-validate.md)
     - [Is It Encapsulated?](idiomatic/leveraging-the-type-system/newtype-pattern/is-it-encapsulated.md)
+  - [Extension Traits](idiomatic/leveraging-the-type-system/extension-traits.md)
+    - [Extending Foreign Types](idiomatic/leveraging-the-type-system/extension-traits/extending-foreign-types.md)
+    - [Method Resolution Conflicts](idiomatic/leveraging-the-type-system/extension-traits/method-resolution-conflicts.md)
+    - [Extending Other Traits](idiomatic/leveraging-the-type-system/extension-traits/extending-other-traits.md)
+    - [Trait Method Conflicts](idiomatic/leveraging-the-type-system/extension-traits/trait-method-conflicts.md)
 
 ---
 

src/idiomatic/leveraging-the-type-system/extension-traits.md

@@ -0,0 +1,37 @@
+---
+minutes: 5
+---
+
+# Extension Traits
+
+In Rust, you can't define new inherent methods for foreign types.
+
+```rust,compile_fail
+// 🛠️❌
+impl &'_ str {
+    pub fn is_palindrome(&self) -> bool {
+        self.chars().eq(self.chars().rev())
+    }
+}
+```
+
+You can use the **extension trait pattern** to work around this limitation.
+
+<details>
+
+- Compile the example to show the compiler error that's emitted.
+
+  Highlight how the compiler error message nudges you towards the extension
+  trait pattern.
+
+- Explain how many type-system restrictions in Rust aim to prevent _ambiguity_.
+
+  If you were allowed to define new inherent methods on foreign types, there
+  would need to be a mechanism to disambiguate between distinct inherent methods
+  with the same name.
+
+  In particular, adding a new inherent method to a library type could cause
+  errors in downstream code if the name of the new method conflicts with an
+  inherent method that's been defined in the consuming crate.
+
+</details>

src/idiomatic/leveraging-the-type-system/extension-traits/extending-foreign-types.md

@@ -0,0 +1,80 @@
+---
+minutes: 15
+---
+
+# Extending Foreign Types
+
+An **extension trait** is a local trait definition whose primary purpose is to
+attach new methods to foreign types.
+
+```rust
+mod ext {
+    pub trait StrExt {
+        fn is_palindrome(&self) -> bool;
+    }
+
+    impl StrExt for &str {
+        fn is_palindrome(&self) -> bool {
+            self.chars().eq(self.chars().rev())
+        }
+    }
+}
+
+// Bring the extension trait into scope..
+pub use ext::StrExt as _;
+// ..then invoke its methods as if they were inherent methods
+assert!("dad".is_palindrome());
+assert!(!"grandma".is_palindrome());
+```
+
+<details>
+
+- The `Ext` suffix is conventionally attached to the name of extension traits.
+
+  It communicates that the trait is primarily used for extension purposes, and
+  it is therefore not intended to be implemented outside the crate that defines
+  it.
+
+  Refer to the ["Extension Trait" RFC][1] as the authoritative source for naming
+  conventions.
+
+- The trait implementation for the chosen foreign type must belong to the same
+  crate where the trait is defined, otherwise you'll be blocked by Rust's
+  [_orphan rule_][2].
+
+- The extension trait must be in scope when its methods are invoked.
+
+  Comment out the `use` statement in the example to show the compiler error
+  that's emitted if you try to invoke an extension method without having the
+  corresponding extension trait in scope.
+
+- The `as _` syntax reduces the likelihood of naming conflicts when multiple
+  traits are imported. It is conventionally used when importing extension
+  traits.
+
+- Some students may be wondering: does the extension trait pattern provide
+  enough value to justify the additional boilerplate? Wouldn't a free function
+  be enough?
+
+  Show how the same example could be implemented using an `is_palindrome` free
+  function, with a single `&str` input parameter:
+
+  ```rust
+  fn is_palindrome(s: &str) -> bool {
+      s.chars().eq(s.chars().rev())
+  }
+  ```
+
+  A bespoke extension trait might be an overkill if you want to add a single
+  method to a foreign type. Both a free function and an extension trait will
+  require an additional import, and the familiarity of the method calling syntax
+  may not be enough to justify the boilerplate of a trait definition.
+
+  Nonetheless, extension methods can be **easier to discover** than free
+  functions. In particular, language servers (e.g. `rust-analyzer`) will suggest
+  extension methods if you type `.` after an instance of the foreign type.
+
+</details>
+
+[1]: https://rust-lang.github.io/rfcs/0445-extension-trait-conventions.html
+[2]: https://github.com/rust-lang/rfcs/blob/master/text/2451-re-rebalancing-coherence.md#what-is-coherence-and-why-do-we-care

src/idiomatic/leveraging-the-type-system/extension-traits/extending-other-traits.md

@@ -0,0 +1,86 @@
+---
+minutes: 15
+---
+
+# Extending Other Traits
+
+Extension traits can attach new methods to _all_ implementors of a given trait:
+
+```rust
+mod ext {
+    use std::fmt::Display;
+
+    pub trait DisplayExt {
+        fn quoted(&self) -> String;
+    }
+
+    impl<T: Display> DisplayExt for T {
+        fn quoted(&self) -> String {
+            format!("'{}'", self)
+        }
+    }
+}
+
+pub use ext::DisplayExt as _;
+
+assert_eq!("dad".quoted(), "'dad'");
+assert_eq!(4.quoted(), "'4'");
+assert_eq!(true.quoted(), "'true'");
+```
+
+<details>
+
+- Highlight how we added new behaviour to _multiple_ distinct types at once.
+  `.quoted()` can be called on string slices, numbers and booleans since they
+  all implement the `Display` trait.
+
+  This flavour of the extension trait pattern is built on top of
+  [_blanket implementations_][1].
+
+  Blanket implementations allow us to implement a trait for a generic type `T`,
+  as long as it satisfies the trait bounds specified in the `impl` block. In
+  this case, the only requirement is that `T` implements the `Display` trait.
+
+- Conventionally, the extension trait is named after the trait it extends,
+  following by the `Ext` suffix. In the example above, `DisplayExt`.
+
+- There are entire libraries aimed at extending foundational traits with new
+  functionality.
+
+  [`itertools`] provides a wide range of iterator adapters and utilities via the
+  [`Itertools`] trait. [`futures`] provides [`FutureExt`] to extend the
+  [`Future`] trait.
+
+## More To Explore
+
+- Extension traits can be used by libraries to distinguish between stable and
+  experimental methods.
+
+  Stable methods are part of the trait definition.
+
+  Experimental methods are provided via an extension trait defined in a
+  different library, with a less restrictive stability policy. Some utility
+  methods are then "promoted" to the core trait definition once they have been
+  proven useful and their design has been refined.
+
+- Extension traits can be used to split a [dyn-incompatible trait][2] in two:
+
+  - A **dyn-compatible core**, restricted to the methods that satisfy
+    dyn-compatibility requirements.
+  - An **extension trait**, containing the remaining methods that are not
+    dyn-compatible. (e.g., methods with a generic parameter).
+
+- Concrete types that implement the core trait will be able to invoke all
+  methods, thanks to the blanket impl for the extension trait. Trait objects
+  (`dyn CoreTrait`) will be able to invoke all methods on the core trait as well
+  as those on the extension trait that don't require `Self: Sized`.
+
+</details>
+
+[1]: https://doc.rust-lang.org/stable/reference/glossary.html#blanket-implementation
+[`itertools`]: https://docs.rs/itertools/latest/itertools/
+[`Itertools`]: https://docs.rs/itertools/latest/itertools/trait.Itertools.html
+[`futures`]: https://docs.rs/futures/latest/futures/
+[`FutureExt`]: https://docs.rs/futures/latest/futures/future/trait.FutureExt.html
+[`Future`]: https://docs.rs/futures/latest/futures/future/trait.Future.html
+[2]: https://doc.rust-lang.org/reference/items/traits.html#r-items.traits.dyn-compatible

src/idiomatic/leveraging-the-type-system/extension-traits/method-resolution-conflicts.md

@@ -0,0 +1,79 @@
+---
+minutes: 15
+---
+
+# Method Resolution Conflicts
+
+What happens when you have a name conflict between an inherent method and an
+extension method?
+
+```rust
+mod ext {
+    pub trait StrExt {
+        fn trim_ascii(&self) -> &str;
+    }
+
+    impl StrExt for &str {
+        fn trim_ascii(&self) -> &str {
+            self.trim_start_matches(|c: char| c.is_ascii_whitespace())
+        }
+    }
+}
+
+pub use ext::StrExt;
+// Which `trim_ascii` method is invoked?
+// The one from `StrExt`? Or the inherent one from `str`?
+assert_eq!(" dad ".trim_ascii(), "dad");
+```
+
+<details>
+
+- The foreign type may, in a newer version, add a new inherent method with the
+  same name of our extension method.
+
+  Survey the class: what do the students think will happen in the example above?
+  Will there be a compiler error? Will one of the two methods be given higher
+  priority? Which one?
+
+  Add a `panic!("Extension trait")` in the body of `StrExt::trim_ascii` to
+  clarify which method is being invoked.
+
+- [Inherent methods have higher priority than trait methods][1], _if_ they have
+  the same name and the **same receiver**, e.g. they both expect `&self` as
+  input. The situation becomes more nuanced if the use a **different receiver**,
+  e.g. `&mut self` vs `&self`.
+
+  Change the signature of `StrExt::trim_ascii` to
+  `fn trim_ascii(&mut self) -> &str` and modify the invocation accordingly:
+
+  ```rust
+  assert_eq!((&mut " dad ").trim_ascii(), "dad");
+  ```
+
+  Now `StrExt::trim_ascii` is invoked, rather than the inherent method, since
+  `&mut self` has a higher priority than `&self`, the one used by the inherent
+  method.
+
+  Point the students to the Rust reference for more information on
+  [method resolution][2]. An explanation with more extensive examples can be
+  found in [an open PR to the Rust reference][3].
+
+- Avoid naming conflicts between extension trait methods and inherent methods.
+  Rust's method resolution algorithm is complex and may surprise users of your
+  code.
+
+## More to explore
+
+- The interaction between the priority search used by Rust's method resolution
+  algorithm and automatic `Deref`ering can be used to emulate
+  [specialization][4] on the stable toolchain, primarily in the context of
+  macro-generated code. Check out ["Autoref Specialization"][5] for the specific
+  details.
+
+</details>
+
+[1]: https://doc.rust-lang.org/stable/reference/expressions/method-call-expr.html#r-expr.method.candidate-search
+[2]: https://doc.rust-lang.org/stable/reference/expressions/method-call-expr.html
+[3]: https://github.com/rust-lang/reference/pull/1725
+[4]: https://github.com/rust-lang/rust/issues/31844
+[5]: https://github.com/dtolnay/case-studies/blob/master/autoref-specialization/README.md

src/idiomatic/leveraging-the-type-system/extension-traits/trait-method-conflicts.md

@@ -0,0 +1,62 @@
+---
+minutes: 5
+---
+
+# Trait Method Conflicts
+
+What happens when you have a name conflict between two different trait methods
+implemented for the same type?
+
+```rust,compile_fail
+mod ext {
+    pub trait Ext1 {
+        fn is_palindrome(&self) -> bool;
+    }
+
+    pub trait Ext2 {
+        fn is_palindrome(&self) -> bool;
+    }
+
+    impl Ext1 for &str {
+        fn is_palindrome(&self) -> bool {
+            self.chars().eq(self.chars().rev())
+        }
+    }
+
+    impl Ext2 for &str {
+        fn is_palindrome(&self) -> bool {
+            self.chars().eq(self.chars().rev())
+        }
+    }
+}
+
+pub use ext::Ext1;
+pub use ext::Ext2;
+
+// Which method is invoked?
+// The one from `Ext1`? Or the one from `Ext2`?
+assert!("dad".is_palindrome());
+```
+
+<details>
+
+- The extended trait may, in a newer version, add a new trait method with the
+  same name of our extension method.
+
+  Survey the class: what do the students think will happen in the example above?
+  Will there be a compiler error? Will one of the two methods be given higher
+  priority? Which one?
+
+- The compiler rejects the code because it cannot determine which method to
+  invoke. Neither `Ext1` nor `Ext2` has a higher priority than the other.
+
+  To resolve this conflict, you must specify which trait you want to use. For
+  example, you can call `Ext1::is_palindrome("dad")` or
+  `Ext2::is_palindrome("dad")`.
+
+  For methods with more complex signatures, you may need to use a more explicit
+  [fully-qualified syntax][1].
+
+</details>
+
+[1]: https://doc.rust-lang.org/reference/expressions/call-expr.html#disambiguating-function-calls