AsRef in core::convert - Rust
Skip to main content AsRef core :: convert Trait AsRef 1.6.0 (const: unstable ) · Source pub trait AsRef<T: PointeeSized >: PointeeSized { // Required method fn as_ref (&self) -> &T ; } Expand description Used to do a cheap reference-to-reference conversion. This trait is similar to AsMut which is used for converting between mutable references. If you need to do a costly conversion it is better to implement From with type &T or write a custom function. § Relation to Borrow AsRef has the same signature as Borrow , but Borrow is different in a few aspects: Unlike AsRef , Borrow has a blanket impl for any T , and can be used to accept either a reference or a value. (See also note on AsRef ’s reflexibility below.) Borrow also requires that Hash , Eq and Ord for a borrowed value are equivalent to those of the owned value.
For this reason, if you want to borrow only a single field of a struct you can implement AsRef , but not Borrow . Note: This trait must not fail . If the conversion can fail, use a dedicated method which returns an Option<T> or a Result<T, E> . § Generic Implementations AsRef auto-dereferences if the inner type is a reference or a mutable reference (e.g.: foo.as_ref() will work the same if foo has type &mut Foo or &&mut Foo ).
Note that due to historic reasons, the above currently does not hold generally for all dereferenceable types , e.g. foo.as_ref() will not work the same as Box::new(foo).as_ref() . Instead, many smart pointers provide an as_ref implementation which simply returns a reference to the pointed-to value (but do not perform a cheap reference-to-reference conversion for that value). However, AsRef::as_ref should not be used for the sole purpose of dereferencing; instead ‘ Deref coercion’ can be used: let x = Box::new( 5i32 ); // Avoid this: // let y: &i32 = x.as_ref(); // Better just write: let y: & i32 = & x; Types which implement Deref should consider implementing AsRef<T> as follows: impl <T> AsRef<T> for SomeType where T: ?
Sized, <SomeType as Deref>::Target: AsRef<T>, { fn as_ref( & self ) -> & T { self .deref().as_ref() } } § Reflexivity Ideally, AsRef would be reflexive, i.e. there would be an impl<T: ?Sized> AsRef<T> for T with as_ref simply returning its argument unchanged. Such a blanket implementation is currently not provided due to technical restrictions of Rust’s type system (it would be overlapping with another existing blanket implementation for &T where T: AsRef<U> which allows AsRef to auto-dereference, see “Generic Implementations” above).
A trivial implementation of AsRef<T> for T must be added explicitly for a particular type T where needed or desired. Note, however, that not all types from std contain such an implementation, and those cannot be added by external code due to orphan rules. § Examples By using trait bounds we can accept arguments of different types as long as they can be converted to the specified type T . For example: By creating a generic function that takes an AsRef<str> we express that we want to accept all references that can be converted to &str as an argument.
Since both String and &str implement AsRef<str> we can accept both as input argument. fn is_hello<T: AsRef<str>>(s: T) { assert_eq! ( "hello" , s.as_ref()); } let s = "hello" ; is_hello(s); let s = "hello" .to_string(); is_hello(s); Required Methods § 1.0.0 (const: unstable ) · Source fn as_ref (&self) -> &T Converts this type into a shared reference of the (usually inferred) input type. Dyn Compatibility § This trait is dyn compatible .
In older versions of Rust, dyn compatibility was called "object safety". Implementors § Source § impl AsRef < ByteStr > for ByteStr Source § impl AsRef < ByteStr > for str 1.7.0 (const: unstable ) · Source § impl AsRef < CStr > for CStr Source § impl AsRef < LocalWaker > for Waker Source § impl AsRef <[ u8 ]> for ByteStr 1.0.0 (const: unstable ) · Source § impl AsRef <[ u8 ]> for str 1.0.0 (const: unstable ) · Source § impl AsRef < str > for str 1.0.0 (const: unstable ) · Source § impl<T, U: PointeeSized > AsRef <U> for &T where T: AsRef <U> + PointeeSized , 1.0.0 (const: unstable ) · Source § impl<T, U: PointeeSized > AsRef <U> for &mut T where T: AsRef <U> + PointeeSized , 1.95.0 · Source § impl<T, const N: usize > AsRef <[ Cell <T>; N ]> for Cell < [T; N] > 1.95.0 · Source § impl<T, const N: usize > AsRef <[ Cell <T>]> for Cell < [T; N] > 1.95.0 · Source § impl<T, const N: usize > AsRef <[ MaybeUninit <T>; N ]> for MaybeUninit < [T; N] > 1.95.0 · Source § impl<T, const N: usize > AsRef <[ MaybeUninit <T>]> for MaybeUninit < [T; N] > Source § impl<T, const N: usize > AsRef < [T; N] > for Simd <T, N> where T: SimdElement , Source § impl<T, const N: usize > AsRef < [T] > for Simd <T, N> where T: SimdElement , 1.0.0 (const: unstable ) · Source § impl<T, const N: usize > AsRef < [T] > for [T; N] 1.100.0 · Source § impl<T: ?
Sized > AsRef <T> for ! Source § impl<T> AsRef <T> for SyncView <T> where T: Sync + ? Sized , 1.95.0 · Source § impl<T> AsRef <[ Cell <T>]> for Cell < [T] > 1.13.0 · Source § impl<T> AsRef < [T] > for Iter <'_, T> 1.53.0 · Source § impl<T> AsRef < [T] > for IterMut <'_, T> 1.0.0 (const: unstable ) · Source § impl<T> AsRef < [T] > for [T]