Trait AsRef

Help

pub trait AsRef<T>where
    T: ?Sized,{
    // Required method
    fn as_ref(&self) -> &T;
}

Expand description

core Used to do a cheap reference-to-reference conversion.

Re-exported from core::convert:: .

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 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 · Source

fn as_ref(&self) -> &T

Converts this type into a shared reference of the (usually inferred) input type.

Trait Implementations§

§

impl ZReaderTrait for dyn AsRef<&[u8]>

§

fn get_byte(&self, index: usize) -> Option<&u8> ⓘ

Get a single byte which is at position index Read more

§

fn get_slice(&self, index: Range<usize>) -> Option<&[u8]> ⓘ

Get a slice of bytes from a range of start..end Read more

§

fn get_len(&self) -> usize

Get total length of the underlying buffer. Read more

Implementors§

1.0.0 (const: unstable) · Source§

impl AsRef<str> for Scheme

1.0.0 · Source§

Trait AsRefCopy item path

§Relation to Borrow

§Generic Implementations

§Reflexivity

§Examples

Required Methods§

fn as_ref(&self) -> &T

Trait Implementations§

impl ZReaderTrait for dyn AsRef<&[u8]>

fn get_byte(&self, index: usize) -> Option<&u8> ⓘ

fn get_slice(&self, index: Range<usize>) -> Option<&[u8]> ⓘ

fn get_len(&self) -> usize

Implementors§

impl AsRef<str> for str

impl AsRef<str> for PyBackedStr

impl AsRef<str> for HeaderName

impl AsRef<str> for Method

impl AsRef<str> for Authority

impl AsRef<str> for Scheme

impl AsRef<str> for devela::all::String

impl AsRef<ByteStr> for str

impl AsRef<ByteStr> for ByteStr

impl AsRef<ByteStr> for ByteString

impl AsRef<LocalWaker> for Waker

impl AsRef<ContentStyle> for ContentStyle

impl AsRef<Context> for devela::_dep::ffmpeg_the_third::codec::decoder::Audio

impl AsRef<Context> for Decoder

impl AsRef<Context> for Opened

impl AsRef<Context> for devela::_dep::ffmpeg_the_third::codec::decoder::Subtitle

impl AsRef<Context> for devela::_dep::ffmpeg_the_third::codec::decoder::Video

impl AsRef<Context> for devela::_dep::ffmpeg_the_third::codec::encoder::audio::Audio

impl AsRef<Context> for devela::_dep::ffmpeg_the_third::codec::encoder::Audio

impl AsRef<Context> for devela::_dep::ffmpeg_the_third::codec::encoder::Encoder

impl AsRef<Context> for devela::_dep::ffmpeg_the_third::codec::encoder::Subtitle

impl AsRef<Context> for devela::_dep::ffmpeg_the_third::codec::encoder::Video

impl AsRef<Context> for devela::_dep::ffmpeg_the_third::codec::encoder::subtitle::Subtitle

impl AsRef<Context> for devela::_dep::ffmpeg_the_third::codec::encoder::video::Video

impl AsRef<timespec> for TimeSpec

impl AsRef<timeval> for TimeVal

impl AsRef<SurfaceRef> for SurfaceRef

impl AsRef<SDL_FPoint> for FPoint

impl AsRef<SDL_FRect> for FRect

impl AsRef<SDL_Point> for Point

impl AsRef<SDL_Rect> for Rect

impl AsRef<BStr> for str

impl AsRef<BStr> for [u8]

impl AsRef<Bytes> for str

impl AsRef<Bytes> for [u8]

impl AsRef<CStr> for CStr

impl AsRef<CStr> for CString

impl AsRef<OsStr> for Component<'_>

impl AsRef<OsStr> for str

impl AsRef<OsStr> for devela::all::IterPath<'_>

impl AsRef<OsStr> for Components<'_>

impl AsRef<OsStr> for OsStr

impl AsRef<OsStr> for OsString

impl AsRef<OsStr> for Path

impl AsRef<OsStr> for PathBuf

impl AsRef<OsStr> for devela::all::String

impl AsRef<Path> for Cow<'_, OsStr>

impl AsRef<Path> for Component<'_>

impl AsRef<Path> for str

impl AsRef<Path> for devela::all::IterPath<'_>

impl AsRef<Path> for Components<'_>

impl AsRef<Path> for OsStr

impl AsRef<Path> for OsString

impl AsRef<Path> for Path

impl AsRef<Path> for PathBuf

impl AsRef<Path> for devela::all::String

impl AsRef<Uuid> for Braced

impl AsRef<Uuid> for Hyphenated

impl AsRef<Uuid> for Simple

impl AsRef<Uuid> for Urn

impl AsRef<Uuid> for Uuid

impl AsRef<[bool; 8]> for CodecFlags

impl AsRef<[f32; 2]> for Vec2

impl AsRef<[f32; 3]> for Vec3A

impl AsRef<[f32; 3]> for Vec3

impl AsRef<[f32; 4]> for Mat2

impl AsRef<[f32; 4]> for Quat

Trait AsRef

§Relation to `Borrow`