Renamed "downcast_trait" to "try_as_dyn", added documentation, including recursion limit docs

Author: izagawd

library/core/src/any.rs

@@ -897,10 +897,45 @@ pub const fn type_name_of_val<T: ?Sized>(_val: &T) -> &'static str {
     type_name::<T>()
 }
 
-#[allow(missing_docs)]
+
+/// Attempts to view `T` as a reference to the trait object `U`.
+///
+/// Returns `Some(&U)` if the type `T` implements `U`, and `None` otherwise.
+///
+/// # Compile-time failures
+/// Determining whether `T` implements `U` requires trait resolution by the compiler.
+/// In some cases, that resolution can exceed the recursion limit,
+/// and compilation will fail *instead of* this function returning `None`.
+/// # Examples
+///
+/// ```rust
+/// #![feature(try_as_dyn)]
+///
+/// use core::any::try_as_dyn;
+///
+/// trait Animal {
+///     fn speak(&self) -> &'static str;
+/// }
+///
+/// struct Dog;
+/// impl Animal for Dog {
+///     fn speak(&self) -> &'static str { "woof" }
+/// }
+///
+/// struct Rock; // does not implement Animal
+///
+/// let dog = Dog;
+/// let rock = Rock;
+///
+/// let as_animal: Option<&dyn Animal> = try_as_dyn::<Dog, dyn Animal>(&dog);
+/// assert_eq!(as_animal.unwrap().speak(), "woof");
+///
+/// let not_an_animal: Option<&dyn Animal> = try_as_dyn::<Rock, dyn Animal>(&rock);
+/// assert!(not_an_animal.is_none());
+/// ```
 #[must_use]
-#[unstable(feature = "downcast_trait", issue = "144361")]
-pub const fn downcast_trait<
+#[unstable(feature = "try_as_dyn", issue = "144361")]
+pub const fn try_as_dyn<
     T: Any + 'static,
     U: ptr::Pointee<Metadata = ptr::DynMetadata<U>> + ?Sized + 'static,
 >(
@@ -918,10 +953,44 @@ pub const fn downcast_trait<
     }
 }
 
-#[allow(missing_docs)]
+/// Attempts to view `T` as a reference to the trait object `U`.
+///
+/// Returns `Some(&mut U)` if the type `T` implements `U`, and `None` otherwise.
+///
+/// # Compile-time failures
+/// Determining whether `T` implements `U` requires trait resolution by the compiler.
+/// In some cases, that resolution can exceed the recursion limit,
+/// and compilation will fail *instead of* this function returning `None`.
+/// # Examples
+///
+/// ```rust
+/// #![feature(try_as_dyn)]
+///
+/// use core::any::try_as_dyn;
+///
+/// trait Animal {
+///     fn speak(&self) -> &'static str;
+/// }
+///
+/// struct Dog;
+/// impl Animal for Dog {
+///     fn speak(&self) -> &'static str { "woof" }
+/// }
+///
+/// struct Rock; // does not implement Animal
+///
+/// let mut dog = Dog;
+/// let mut rock = Rock;
+///
+/// let as_animal: Option<&mut dyn Animal> = try_as_dyn_mut::<Dog, dyn Animal>(&mut dog);
+/// assert_eq!(as_animal.unwrap().speak(), "woof");
+///
+/// let not_an_animal: Option<&mut dyn Animal> = try_as_dyn_mut::<Rock, dyn Animal>(&mut rock);
+/// assert!(not_an_animal.is_none());
+/// ```
 #[must_use]
-#[unstable(feature = "downcast_trait", issue = "144361")]
-pub const fn downcast_trait_mut<
+#[unstable(feature = "try_as_dyn", issue = "144361")]
+pub const fn try_as_dyn_mut<
     T: Any + 'static,
     U: ptr::Pointee<Metadata = ptr::DynMetadata<U>> + ?Sized + 'static,
 >(

library/core/src/intrinsics/mod.rs

@@ -2660,6 +2660,11 @@ pub unsafe fn vtable_align(ptr: *const ()) -> usize;
 /// FIXME: write actual docs (ivarflakstad)
 /// The intrinsic will return the vtable of `t` through the lens of `U`.
 ///
+/// # Compile-time failures
+/// Determining whether `T` implements `U` requires trait resolution by the compiler.
+/// In some cases, that resolution can exceed the recursion limit,
+/// and compilation will fail *instead of* this function returning `None`.
+///
 /// # Safety
 ///
 /// `ptr` must point to a vtable.

tests/ui/any/downcast_trait.rs tests/ui/any/try_as_dyn.rstests/ui/any/downcast_trait.rs renamed to tests/ui/any/try_as_dyn.rs

@@ -1,11 +1,11 @@
 //@ run-pass
-#![feature(downcast_trait)]
+#![feature(try_as_dyn)]
 
 use std::fmt::Debug;
 
 // Look ma, no `T: Debug`
-fn downcast_debug_format<T: 'static>(t: &T) -> String {
-    match std::any::downcast_trait::<_, dyn Debug>(t) {
+fn debug_format_with_try_as_dyn<T: 'static>(t: &T) -> String {
+    match std::any::try_as_dyn::<_, dyn Debug>(t) {
         Some(d) => format!("{d:?}"),
         None => "default".to_string()
     }
@@ -19,11 +19,11 @@ fn main() {
         index: usize
     }
     let a = A { index: 42 };
-    let result = downcast_debug_format(&a);
+    let result = debug_format_with_try_as_dyn(&a);
     assert_eq!("A { index: 42 }", result);
 
     struct B {}
     let b = B {};
-    let result = downcast_debug_format(&b);
+    let result = debug_format_with_try_as_dyn(&b);
     assert_eq!("default", result);
 }

tests/ui/any/downcast_trait_err1.rs tests/ui/any/try_as_dyn_err1.rstests/ui/any/downcast_trait_err1.rs renamed to tests/ui/any/try_as_dyn_err1.rs

@@ -1,7 +1,7 @@
 //@ run-pass
-#![feature(downcast_trait)]
+#![feature(try_as_dyn)]
 
-use std::{any::downcast_trait, sync::OnceLock};
+use std::{any::try_as_dyn, sync::OnceLock};
 
 trait Trait {
     fn call(&self, x: &Box<i32>);
@@ -22,7 +22,7 @@ fn store(x: &'static Box<i32>) {
 fn main() {
     let data = Box::new(Box::new(1i32));
     let fn_ptr: fn(&'static Box<i32>) = store;
-    let dt = downcast_trait::<_, dyn Trait>(&fn_ptr);
+    let dt = try_as_dyn::<_, dyn Trait>(&fn_ptr);
     if let Some(dt) = dt {
         // unsound path
         dt.call(&*data);

tests/ui/any/downcast_trait_err2.rs tests/ui/any/try_as_dyn_err2.rstests/ui/any/downcast_trait_err2.rs renamed to tests/ui/any/try_as_dyn_err2.rs

@@ -1,6 +1,6 @@
 //@ run-pass
-#![feature(downcast_trait)]
-use std::{any::downcast_trait, sync::OnceLock};
+#![feature(try_as_dyn)]
+use std::{any::try_as_dyn, sync::OnceLock};
 
 trait Trait<T> {
     fn call(&self, t: T, x: &Box<i32>);
@@ -20,7 +20,7 @@ fn store(x: &'static Box<i32>) {
 
 fn main() {
     let data = Box::new(Box::new(1i32));
-    let dt = downcast_trait::<_, dyn Trait<fn(&'static Box<i32>)>>(&());
+    let dt = try_as_dyn::<_, dyn Trait<fn(&'static Box<i32>)>>(&());
     if let Some(dt) = dt {
         // unsound path
         dt.call(store, &*data);

tests/ui/any/downcast_trait_mut.rs tests/ui/any/try_as_dyn_mut.rstests/ui/any/downcast_trait_mut.rs renamed to tests/ui/any/try_as_dyn_mut.rs

@@ -1,11 +1,11 @@
 //@ run-pass
-#![feature(downcast_trait)]
+#![feature(try_as_dyn)]
 
 use std::fmt::{Error, Write};
 
 // Look ma, no `T: Write`
-fn downcast_mut_write<T: 'static>(t: &mut T, s: &str) -> Result<(), Error> {
-    match std::any::downcast_trait_mut::<_, dyn Write>(t) {
+fn try_as_dyn_mut_write<T: 'static>(t: &mut T, s: &str) -> Result<(), Error> {
+    match std::any::try_as_dyn_mut::<_, dyn Write>(t) {
         Some(w) => w.write_str(s),
         None => Ok(())
     }
@@ -15,6 +15,6 @@ fn downcast_mut_write<T: 'static>(t: &mut T, s: &str) -> Result<(), Error> {
 fn main() {
     let mut buf = "Hello".to_string();
 
-    downcast_mut_write(&mut buf, " world!").unwrap();
+    try_as_dyn_mut_write(&mut buf, " world!").unwrap();
     assert_eq!(buf, "Hello world!");
 }