Extend rust reference with a section about subtyping

1 files changed, 20 insertions, 0 deletions

diff --git a/src/doc/reference.md b/src/doc/reference.md
index 8d1b93ce3c8..68c17c04079 100644
--- a/src/doc/reference.md
+++ b/src/doc/reference.md
@@ -3608,6 +3608,26 @@ The notation `&self` is a shorthand for `self: &Self`. In this case,
 in the impl, `Self` refers to the value of type `String` that is the
 receiver for a call to the method `make_string`.
 
+## Subtyping
+
+Subtyping is implicit and can occur at any stage in type checking or
+inference. Subtyping in Rust is very restricted and occurs only due to
+variance with respect to lifetimes and between types with higher ranked
+lifetimes. If we were to erase lifetimes from types, then the only subtyping
+would be due to type equality.
+
+Consider the following example: string literals always have `'static`
+lifetime. Nevertheless, we can assign `s` to `t`:
+
+```
+fn bar<'a>() {
+    let s: &'static str = "hi";
+    let t: &'a str = s;
+}
+```
+Since `'static` "lives longer" than `'a`, `&'static str` is a subtype of
+`&'a str`.
+
 # Special traits
 
 Several traits define special evaluation behavior.