Struct MutRefStackWithData 

pub struct MutRefStackWithData<'root, T: ?Sized, U: 'root> { /* private fields */ }

Implementations

impl<'root, T: ?Sized, U> MutRefStackWithData<'root, T, U>

pub fn new(root: &'root mut T, additional_data: U) -> Self

Create a new MutRefStack from a mutable reference to the root of a recursive data structure.

Examples found in repository

examples/forest.rs (lines 17-23)

pub fn preorder_traverse<T, F: FnMut(&mut T, usize)>(tree: &mut Forest<T>, mut callback: F) {
    struct TraversalState {
        next_index: usize,
        depth: usize,
    }
    let mut cursor = MutRefStackWithData::new(
        &mut *tree.roots,
        TraversalState {
            next_index: 0,
            depth: 0,
        },
    );
    loop {
        let Ok(_) = cursor.move_with(|element, state| {
            if state.next_index >= element.len() {
                MoveDecision::Ascend
            } else {
                callback(&mut element[state.next_index].data, state.depth);
                let decision = MoveDecision::Descend(
                    &mut *element[state.next_index].children,
                    TraversalState {
                        next_index: 0,
                        depth: state.depth + 1,
                    },
                );
                state.next_index += 1;
                decision
            }
        }) else {
            break;
        };
    }
}

pub fn top(&self) -> (&T, &U)

Obtain a shared reference to the top of the stack.

pub fn top_mut(&mut self) -> (&mut T, &mut U)

Obtain a mutable reference to the top of the stack.

pub fn is_at_root(&self) -> bool

Is this MutRefStack currently at its root?

pub fn descend_with( &mut self, f: impl for<'node, 'addl> FnOnce(&'node mut T, &'addl mut U) -> Option<(&'node mut T, U)>, ) -> Option<(&mut T, &mut U)>

Descend into the recursive data structure, returning a mutable reference to the new top element. Rust’s borrow checker enforces that the closure cannot inject any lifetime (other than 'static), because the closure must work for any lifetime 'node.

pub fn inject_with( &mut self, f: impl for<'node, 'addl> FnOnce(&'node mut T, &'addl mut U) -> Option<(&'root mut T, U)>, ) -> Option<(&mut T, &mut U)>

Inject a new reference to the top of the stack. The reference still must live as long as the root of the stack.

pub fn ascend(&mut self) -> Option<((&mut T, &mut U), U)>

Ascend back up from the recursive data structure, returning a mutable reference to the new top element, if it changed. If we are not currently at the root, ascend and return a reference to the new top, a reference to the new top’s additional data, and the old top’s additional data. If we are already the root, returns None (the top is the root and does not change).

pub fn ascend_while<P>( &mut self, predicate: P, ) -> ((&mut T, &mut U), impl IntoIterator<Item = U>)

where P: FnMut(&mut T, &mut U) -> bool,

Ascend back up from the recursive data structure while the given closure returns true, returning a mutable reference to the new top element. If we are not currently at the root, and the predicate returns true, ascend and continue. If we are already at the root, or if the predicate returned false, returns a reference to the top element.

pub fn move_with( &mut self, f: impl for<'node, 'addl> FnOnce(&'node mut T, &'addl mut U) -> MoveDecision<'root, 'node, T, U>, ) -> Result<((&mut T, &mut U), Option<U>), MoveError>

Ascend from, descend from, inject a new top, or stay at the current node, based on the return value of the closure.

Examples found in repository

examples/forest.rs (lines 25-40)

pub fn preorder_traverse<T, F: FnMut(&mut T, usize)>(tree: &mut Forest<T>, mut callback: F) {
    struct TraversalState {
        next_index: usize,
        depth: usize,
    }
    let mut cursor = MutRefStackWithData::new(
        &mut *tree.roots,
        TraversalState {
            next_index: 0,
            depth: 0,
        },
    );
    loop {
        let Ok(_) = cursor.move_with(|element, state| {
            if state.next_index >= element.len() {
                MoveDecision::Ascend
            } else {
                callback(&mut element[state.next_index].data, state.depth);
                let decision = MoveDecision::Descend(
                    &mut *element[state.next_index].children,
                    TraversalState {
                        next_index: 0,
                        depth: state.depth + 1,
                    },
                );
                state.next_index += 1;
                decision
            }
        }) else {
            break;
        };
    }
}

pub fn into_top(self) -> &'root mut T

Return reference to the top element of this stack, forgetting about the stack entirely.