@@ -3599,6 +3599,147 @@ The notation `&self` is a shorthand for `self: &Self`. In this case,
3599
3599
in the impl, ` Self ` refers to the value of type ` String ` that is the
3600
3600
receiver for a call to the method ` make_string ` .
3601
3601
3602
+ ## Subtyping
3603
+
3604
+ Subtyping is implicit and can occur at any stage in type checking or
3605
+ inference. Subtyping in Rust is very restricted and occurs only due to
3606
+ variance with respect to lifetimes and between types with higher ranked
3607
+ lifetimes. If we were to erase lifetimes from types, then the only subtyping
3608
+ would be due to type equality.
3609
+
3610
+ Consider the following example: string literals always have ` 'static `
3611
+ lifetime. Nevertheless, we can assign ` s ` to ` t ` :
3612
+
3613
+ ```
3614
+ fn bar<'a>() {
3615
+ let s: &'static str = "hi";
3616
+ let t: &'a str = s;
3617
+ }
3618
+ ```
3619
+ Since ` 'static ` "lives longer" than ` 'a ` , ` &'static str ` is a subtype of
3620
+ ` &'a str ` .
3621
+
3622
+ ## Type coercions
3623
+
3624
+ Coercions are defined in [ RFC401] . A coercion is implicit and has no syntax.
3625
+
3626
+ [ RFC401 ] : https://github.com/rust-lang/rfcs/blob/master/text/0401-coercions.md
3627
+
3628
+ ### Coercion sites
3629
+
3630
+ A coercion can only occur at certain coercion sites in a program; these are
3631
+ typically places where the desired type is explicit or can be dervied by
3632
+ propagation from explicit types (without type inference). Possible coercion
3633
+ sites are:
3634
+
3635
+ * ` let ` statements where an explicit type is given.
3636
+
3637
+ In ` let _: U = e; ` , ` e ` is coerced to have type ` U ` .
3638
+
3639
+ * ` static ` and ` const ` statements (similar to ` let ` statements).
3640
+
3641
+ * arguments for function calls.
3642
+
3643
+ The value being coerced is the
3644
+ actual parameter and it is coerced to the type of the formal parameter. For
3645
+ example, let ` foo ` be defined as ` fn foo(x: U) { ... } ` and call it as
3646
+ ` foo(e); ` . Then ` e ` is coerced to have type ` U ` ;
3647
+
3648
+ * instantiations of struct or variant fields.
3649
+
3650
+ Assume we have a `struct
3651
+ Foo { x: U }` and instantiate it as ` Foo { x: e }` . Then ` e` is coerced to
3652
+ have type ` U ` .
3653
+
3654
+ * function results (either the final line of a block if it is not semicolon
3655
+ terminated or any expression in a ` return ` statement).
3656
+
3657
+ In `fn foo() -> U { e }`, `e` is coerced to to have type `U`.
3658
+
3659
+ If the expression in one of these coercion sites is a coercion-propagating
3660
+ expression, then the relevant sub-expressions in that expression are also
3661
+ coercion sites. Propagation recurses from these new coercion sites.
3662
+ Propagating expressions and their relevant sub-expressions are:
3663
+
3664
+ * array literals, where the array has type ` [U; n] ` . Each sub-expression in
3665
+ the array literal is a coercion site for coercion to type ` U ` .
3666
+
3667
+ * array literals with repeating syntax, where the array has type ` [U; n] ` . The
3668
+ repeated sub-expression is a coercion site for coercion to type ` U ` .
3669
+
3670
+ * tuples, where a tuple is a coercion site to type ` (U_0, U_1, ..., U_n) ` .
3671
+ Each sub-expression is a coercion site to the respective type, e.g. the
3672
+ zeroth sub-expression is a coercion site to type ` U_0 ` .
3673
+
3674
+ * parenthesised sub-expressions (` (e) ` ). If the expression has type ` U ` , then
3675
+ the sub-expression is a coercion site to ` U ` .
3676
+
3677
+ * blocks. If a block has type ` U ` , then the last expression in the block (if
3678
+ it is not semicolon-terminated) is a coercion site to ` U ` . This includes
3679
+ blocks which are part of control flow statements, such as ` if ` /` else ` , if
3680
+ the block has a known type.
3681
+
3682
+ ### Coercion types
3683
+
3684
+ Coercion is allowed between the following types:
3685
+
3686
+ * ` T ` to ` U ` if ` T ` is a subtype of ` U ` (* reflexive case* ).
3687
+
3688
+ * ` T_1 ` to ` T_3 ` where ` T_1 ` coerces to ` T_2 ` and ` T_2 ` coerces to ` T_3 `
3689
+ (* transitive case* ).
3690
+
3691
+ Note that this is not fully supported yet
3692
+
3693
+ * ` &mut T ` to ` &T ` .
3694
+
3695
+ * ` *mut T ` to ` *const T ` .
3696
+
3697
+ * ` &T ` to ` *const T ` .
3698
+
3699
+ * ` &mut T ` to ` *mut T ` .
3700
+
3701
+ * ` &T ` to ` &U ` if ` T ` implements ` Deref<Target = U> ` . For example:
3702
+
3703
+ ``` rust
3704
+ use std :: ops :: Deref ;
3705
+
3706
+ struct CharContainer {
3707
+ value : char
3708
+ }
3709
+
3710
+ impl Deref for CharContainer {
3711
+ type Target = char ;
3712
+
3713
+ fn deref <'a >(& 'a self ) -> & 'a char {
3714
+ & self . value
3715
+ }
3716
+ }
3717
+
3718
+ fn foo (arg : & char ) {}
3719
+
3720
+ fn main () {
3721
+ let x = & mut CharContainer { value : 'y' };
3722
+ foo (x ); // &mut CharContainer is coerced to &char.
3723
+ }
3724
+ ```
3725
+ * ` &mut T ` to ` &mut U ` if ` T ` implements ` DerefMut<Target = U> ` .
3726
+
3727
+ * TyCtor(` T ` ) to TyCtor(coerce_inner(` T ` )), where TyCtor(` T ` ) is one of
3728
+ - ` &T `
3729
+ - ` &mut T `
3730
+ - ` *const T `
3731
+ - ` *mut T `
3732
+ - ` Box<T> `
3733
+
3734
+ and where
3735
+ - coerce_inner(` [T, ..n] ` ) = ` [T] `
3736
+ - coerce_inner(` T ` ) = ` U ` where ` T ` is a concrete type which implements the
3737
+ trait ` U ` .
3738
+
3739
+ In the future, coerce_inner will be recursively extended to tuples and
3740
+ structs. In addition, coercions from sub-traits to super-traits will be
3741
+ added. See [ RFC401] for more details.
3742
+
3602
3743
# Special traits
3603
3744
3604
3745
Several traits define special evaluation behavior.
0 commit comments