Auto merge of #87515 - crlf0710:trait_upcasting_part2, r=bjorn3

Trait upcasting coercion (part2)

This is the second part of trait upcasting coercion implementation.

Currently this is blocked on #86264 .

The third part might be implemented using unsafety checking

r? `@bjorn3`

1 files changed, 27 insertions, 0 deletions

diff --git a/src/doc/unstable-book/src/language-features/trait-upcasting.md b/src/doc/unstable-book/src/language-features/trait-upcasting.md
new file mode 100644
index 00000000000..3697ae38f9d
--- /dev/null
+++ b/src/doc/unstable-book/src/language-features/trait-upcasting.md
@@ -0,0 +1,27 @@
+# `trait_upcasting`
+
+The tracking issue for this feature is: [#65991]
+
+[#65991]: https://github.com/rust-lang/rust/issues/65991
+
+------------------------
+
+The `trait_upcasting` feature adds support for trait upcasting coercion. This allows a
+trait object of type `dyn Bar` to be cast to a trait object of type `dyn Foo`
+so long as `Bar: Foo`.
+
+```rust,edition2018
+#![feature(trait_upcasting)]
+#![allow(incomplete_features)]
+
+trait Foo {}
+
+trait Bar: Foo {}
+
+impl Foo for i32 {}
+
+impl<T: Foo + ?Sized> Bar for T {}
+
+let bar: &dyn Bar = &123;
+let foo: &dyn Foo = bar;
+```