Struct smart_access::AT

#[must_use]pub struct AT<CPS, List> { /* fields omitted */ }

A “reference” to some “location”.

With default Cps implementations (and with the detach feature disabled) every AT is usually a “path component” list of type

AT<&mut root, (..((((), I1), I2), I3) .. In)>

But beware! Starting with the version 0.5 there is a possibility of accidentally creating multilevel hierarchies like

AT<AT<&mut root, ((), I1)>, ((), I2)>

by using the at of Cps instead of its AT-override.

Moreover, the detach feature is now based on such nonflat structures.

Usage in function types

Though AT is exposed, it's strongly recommended to use impl Cps<View=T> as a return type of functions and Cps<View=T> bounds on their parameters.

But when needed (for example, due to some complex lifetimes), usage of AT can be facilitated by the path macro allowing one to write

AT<CPS, path!(I, J, K)>

instead of

AT<CPS, ((((), I), J), K)>

Detaching paths

Enabling detach feature allows one to detach ATs from their roots.

Without this feature only a single component can be detached:

use smart_access::Cps;

let mut foo = vec![vec![1,2], vec![3,4]];

let (foo_i, j) = foo.at(0).at(0).into();
assert!(foo_i.at(1).replace(5) == Some(2));

Note

Relevant only with the detach feature enabled.

If you pass a detached path to a function then you should use a Path: Attach<CPS::View, View=V> bound instead of a Cps<View=V> bound.

I.e.

fn replace_at<CPS: Cps, Path, V>(cps: CPS, path: Path, x: V) -> Option<V> where
    Path: Attach<CPS::View, View=V>,
{
    cps.attach(path).replace(x)
}

let mut vec = vec![1,2,3];

assert!(replace_at(&mut vec, detached_at(0), 4) == Some(1));
assert!(vec == vec![4,2,3]);

But sometimes an explicit AT can be useful (the example below is artificial and thus not very illuminating...):

use smart_access::*;

fn get_ij<CPS, U, V, W>(a_i: AT<CPS, path!(usize)>, j: usize) 
    -> impl Attach<W, View=V> where 
    CPS: Cps<View=W>,
    W: At<usize, View=U> + ?Sized,
    U: At<usize, View=V> + ?Sized,
    V: ?Sized,
{
    let (a,i) = a_i.into();
    let (_, path) = a.at(i).at(j).detach();

    path
}

let mut foo = vec![vec![1,2], vec![3,4]];
let path = get_ij(detached_at(1), 0);
 
assert!(foo.attach(path).replace(5) == Some(3));

Implementations

impl<CPS, List> AT<CPS, List>

pub fn at<Index, View: ?Sized>(self, i: Index) -> AT<CPS, (List, Index)> where
    AT<CPS, List>: Cps<View = View>,
    View: At<Index>, 

Override for at of Cps.

Preserves flat structure.

impl<CPS: Cps, List> AT<CPS, List>

pub fn detach(self) -> (CPS, DetachedPath<CPS::View, List>)

Detaches the path starting from the nearest detach point.

Present only on detach.

Usage example

use smart_access::Cps;

let mut foo = vec![vec![vec![0]]];
let mut bar = vec![vec![vec![0]]];

let (_, detached) = foo.at(0).at(0).at(0).detach();

// Detached paths are cloneable (if indices are cloneable)
let the_same_path = detached.clone();

bar.attach(the_same_path).replace(1);
assert!(foo == vec![vec![vec![0]]]);
assert!(bar == vec![vec![vec![1]]]);

foo.attach(detached).replace(2);
assert!(foo == vec![vec![vec![2]]]);
assert!(bar == vec![vec![vec![1]]]);
 
let (_, path) = bar.at(0).at(0).detach();
bar.attach(path.at(0)).replace(3);
assert!(bar == vec![vec![vec![3]]]);

Trait Implementations

impl<CPS: Clone, List: Clone> Clone for AT<CPS, List>

fn clone(&self) -> AT<CPS, List>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<CPS: Cps, Path> Cps for AT<CPS, Path> where
    Path: AtView<CPS::View>, 

access returns Some / None according to the rules described here

type View = Path::View

fn access<R, F>(self, f: F) -> Option<R> where
    F: FnOnce(&mut Self::View) -> R, 

Returns Some(f(..)) or None.

fn replace(self, new_val: Self::View) -> Option<Self::View> where
    Self::View: Sized, 

Equivalent to self.access(|x| std::mem::replace(x, new_val))

fn touch(self) -> Option<()>

Equivalent to self.access(|_| ())

fn at<Index>(self, i: Index) -> AT<Self, ((), Index)> where
    Self::View: At<Index>, 

“Moves in the direction” of the provided index.

fn batch_ct(self) -> CpsBatch<Self, ()>

Constructs a compile-time batch.

fn batch_rt<R>(
    self
) -> CpsBatch<Self, Vec<Box<dyn FnOnce(&mut Self::View, Option<R>) -> R>>>

Constructs a runtime batch.

fn attach<Path, V: ?Sized>(self, path: Path) -> AT<Self, Path::List> where
    Path: Attach<Self::View, View = V>, 

Attaches a detached path.

fn cut(self) -> AT<Self, ()>

Creates a new detach point.

impl<CPS: Debug, List: Debug> Debug for AT<CPS, List>

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

Formats the value using the given formatter.

impl<CPS, Prev, I> From<AT<CPS, (Prev, I)>> for (AT<CPS, Prev>, I)

AT can be broken apart to detach a single path component.

A more general attach/detach framework is accessible through the detach feature.

fn from(at: AT<CPS, (Prev, I)>) -> Self

Performs the conversion.