Struct reffers::aref::ARef

#[repr(C)]
pub struct ARef<'a, U: ?Sized> { /* fields omitted */ }

ARef - a reference that abstracts the owner completely.

ARef takes over where OwningRef ends, by abstracting the owner even further.

This makes it possible to return, say, an ARef<str> and have the caller drop the owner when done looking at it, without having to bother about whether the owner is a String, Rc<String>, a Ref<String>, or something else.

If you want an ARef that's restricted to Send types, use ARefs, and if you want an ARef that's restricted to Send + Sync types, use ARefss.

Oh, and it's repr(C), so it can be transferred over an FFI boundary (if its target is repr(C), too).

Example

use std::rc::Rc;
use reffers::ARef;

struct CountDown(pub Rc<String>);
impl CountDown {
    pub fn idx_to_str(&self, idx: u32) -> ARef<str> {
        match idx {
            0 => "Go!".into(),
            // We clone the Rc instead of the String
            // for performance,
            // then we map from &String to &str
            1 => ARef::new(self.0.clone()).map(|s| &**s),
            _ => format!("{}...", idx).into(),
        }
    }
}

let c = CountDown(Rc::new("Ready!".into()));
assert_eq!(&*c.idx_to_str(3), "3...");
assert_eq!(&*c.idx_to_str(2), "2...");
assert_eq!(&*c.idx_to_str(1), "Ready!");
assert_eq!(&*c.idx_to_str(0), "Go!");

Methods

impl<'a, U: Descend> ARef<'a, U>

pub fn descend_from(x: Self) -> ARef<'a, <U::Inner as Deref>::Target>

Descends from a ARef<RefCell> to a ARef (or RwLock, or Mutex etc)

Example

use std::sync::{Arc, RwLock};
use reffers::ARef;

let x = Arc::new(RwLock::new("Hello!"));
{
    let aref = ARef::new(x.clone());
    let hello = ARef::descend_from(aref);
    // The RwLock is now read locked
    assert_eq!(*hello, "Hello!");
    assert!(x.try_write().is_err());
}
// The lock is released when the ARef goes out of scope
assert!(x.try_write().is_ok());

pub fn try_descend_from(
    x: Self
) -> Result<ARef<'a, <U::Inner as Deref>::Target>, Self>

Descends from a ARef<RefCell> to a ARef (or RwLock, or Mutex etc)

Fails if the RefCell/RwLock/Mutex is busy (or poisoned).

impl<'a, U: ?Sized> ARef<'a, U>

pub fn new<O>(owner: O) -> Self where
    O: 'a + AReffic + Deref<Target = U>, 

Creates a new ARef from what the ARef points to.

Example

use std::rc::Rc;
use reffers::ARef;

let aref = ARef::new(Rc::new(43));
assert_eq!(*aref, 43);

pub fn map<V: ?Sized, F: FnOnce(&U) -> &V>(self, f: F) -> ARef<'a, V>

Maps the ARef's target to something reachable from the target.

Example

use reffers::ARef;

let aref: ARef<[u8]> = vec![0u8, 5, 7].into();
assert_eq!(*aref.map(|s| &s[1]), 5);

pub fn try_map<E, V: ?Sized, F: FnOnce(&U) -> Result<&V, E>>(
    self,
    f: F
) -> Result<ARef<'a, V>, E>

Like map, but with Result passthrough.

Example

use reffers::ARef;

let aref = ARef::<[u8]>::from(vec![0u8, 5, 7]);
assert_eq!(aref.try_map(|s| s.get(9).ok_or(())), Err(()));

Trait Implementations

impl<'a, U: ?Sized> Drop for ARef<'a, U>

fn drop(&mut self)

Executes the destructor for this type.

impl<'a, U: ?Sized> AsRef<U> for ARef<'a, U>

fn as_ref(&self) -> &U

Performs the conversion.

impl<'a, O: 'a + AReffic + Deref<Target = U>, U: ?Sized> From<O> for ARef<'a, U>

fn from(owner: O) -> Self

Performs the conversion.

impl<'a, U: ?Sized + Eq> Eq for ARef<'a, U>

impl<'a, U: ?Sized + Ord> Ord for ARef<'a, U>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

🔬 This is a nightly-only experimental API. (clamp)

Restrict a value to a certain interval.

impl<'a, U: ?Sized + PartialEq> PartialEq<ARef<'a, U>> for ARef<'a, U>

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Self) -> bool

This method tests for !=.

impl<'a, U: ?Sized + PartialOrd> PartialOrd<ARef<'a, U>> for ARef<'a, U>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Self) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Self) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Self) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Self) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<'a, U: Debug + ?Sized> Debug for ARef<'a, U>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<'a, U: ?Sized> Deref for ARef<'a, U>

type Target = U

The resulting type after dereferencing.

fn deref(&self) -> &U

Dereferences the value.

impl<'a, U: ?Sized + Hash> Hash for ARef<'a, U>

fn hash<H>(&self, state: &mut H) where
    H: Hasher, 

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given [Hasher].

impl<'a, U: ?Sized> Borrow<U> for ARef<'a, U>

fn borrow(&self) -> &U

Immutably borrows from an owned value.