Trait Cursor

pub trait Cursor {
    // Required methods
    fn position(&self) -> CursorPosition;
    fn set_position(&mut self, pos: CursorPosition);
    fn srcloc(&self) -> SourceLoc;
    fn set_srcloc(&mut self, srcloc: SourceLoc);
    fn layout(&self) -> &Layout;
    fn layout_mut(&mut self) -> &mut Layout;

    // Provided methods
    fn with_srcloc(self, srcloc: SourceLoc) -> Self
       where Self: Sized { ... }
    fn at_position(self, pos: CursorPosition) -> Self
       where Self: Sized { ... }
    fn at_inst(self, inst: Inst) -> Self
       where Self: Sized { ... }
    fn at_first_insertion_point(self, block: Block) -> Self
       where Self: Sized { ... }
    fn at_first_inst(self, block: Block) -> Self
       where Self: Sized { ... }
    fn at_last_inst(self, block: Block) -> Self
       where Self: Sized { ... }
    fn after_inst(self, inst: Inst) -> Self
       where Self: Sized { ... }
    fn at_top(self, block: Block) -> Self
       where Self: Sized { ... }
    fn at_bottom(self, block: Block) -> Self
       where Self: Sized { ... }
    fn current_block(&self) -> Option<Block> { ... }
    fn current_inst(&self) -> Option<Inst> { ... }
    fn goto_after_inst(&mut self, inst: Inst) { ... }
    fn goto_inst(&mut self, inst: Inst) { ... }
    fn goto_first_insertion_point(&mut self, block: Block) { ... }
    fn goto_first_inst(&mut self, block: Block) { ... }
    fn goto_last_inst(&mut self, block: Block) { ... }
    fn goto_top(&mut self, block: Block) { ... }
    fn goto_bottom(&mut self, block: Block) { ... }
    fn next_block(&mut self) -> Option<Block> { ... }
    fn prev_block(&mut self) -> Option<Block> { ... }
    fn next_inst(&mut self) -> Option<Inst> { ... }
    fn prev_inst(&mut self) -> Option<Inst> { ... }
    fn insert_inst(&mut self, inst: Inst) { ... }
    fn remove_inst(&mut self) -> Inst { ... }
    fn remove_inst_and_step_back(&mut self) -> Inst { ... }
    fn insert_block(&mut self, new_block: Block) { ... }
}

All cursor types implement the Cursor which provides common navigation operations.

Required Methods

fn position(&self) -> CursorPosition

Get the current cursor position.

fn set_position(&mut self, pos: CursorPosition)

Set the current position.

fn srcloc(&self) -> SourceLoc

Get the source location that should be assigned to new instructions.

fn set_srcloc(&mut self, srcloc: SourceLoc)

Set the source location that should be assigned to new instructions.

fn layout(&self) -> &Layout

Borrow a reference to the function layout that this cursor is navigating.

fn layout_mut(&mut self) -> &mut Layout

Borrow a mutable reference to the function layout that this cursor is navigating.

Provided Methods

fn with_srcloc(self, srcloc: SourceLoc) -> Self

where Self: Sized,

Exchange this cursor for one with a set source location.

This is intended to be used as a builder method:

fn edit_func(func: &mut Function, srcloc: SourceLoc) {
    let mut pos = FuncCursor::new(func).with_srcloc(srcloc);

    // Use `pos`...
}

fn at_position(self, pos: CursorPosition) -> Self

where Self: Sized,

Rebuild this cursor positioned at pos.

fn at_inst(self, inst: Inst) -> Self

where Self: Sized,

Rebuild this cursor positioned at inst.

This is intended to be used as a builder method:

fn edit_func(func: &mut Function, inst: Inst) {
    let mut pos = FuncCursor::new(func).at_inst(inst);

    // Use `pos`...
}

fn at_first_insertion_point(self, block: Block) -> Self

where Self: Sized,

Rebuild this cursor positioned at the first insertion point for block. This differs from at_first_inst in that it doesn’t assume that any instructions have been inserted into block yet.

This is intended to be used as a builder method:

fn edit_func(func: &mut Function, block: Block) {
    let mut pos = FuncCursor::new(func).at_first_insertion_point(block);

    // Use `pos`...
}

fn at_first_inst(self, block: Block) -> Self

where Self: Sized,

Rebuild this cursor positioned at the first instruction in block.

This is intended to be used as a builder method:

fn edit_func(func: &mut Function, block: Block) {
    let mut pos = FuncCursor::new(func).at_first_inst(block);

    // Use `pos`...
}

fn at_last_inst(self, block: Block) -> Self

where Self: Sized,

Rebuild this cursor positioned at the last instruction in block.

This is intended to be used as a builder method:

fn edit_func(func: &mut Function, block: Block) {
    let mut pos = FuncCursor::new(func).at_last_inst(block);

    // Use `pos`...
}

fn after_inst(self, inst: Inst) -> Self

where Self: Sized,

Rebuild this cursor positioned after inst.

This is intended to be used as a builder method:

fn edit_func(func: &mut Function, inst: Inst) {
    let mut pos = FuncCursor::new(func).after_inst(inst);

    // Use `pos`...
}

fn at_top(self, block: Block) -> Self

where Self: Sized,

Rebuild this cursor positioned at the top of block.

This is intended to be used as a builder method:

fn edit_func(func: &mut Function, block: Block) {
    let mut pos = FuncCursor::new(func).at_top(block);

    // Use `pos`...
}

fn at_bottom(self, block: Block) -> Self

where Self: Sized,

Rebuild this cursor positioned at the bottom of block.

This is intended to be used as a builder method:

fn edit_func(func: &mut Function, block: Block) {
    let mut pos = FuncCursor::new(func).at_bottom(block);

    // Use `pos`...
}

fn current_block(&self) -> Option<Block>

Get the block corresponding to the current position.

fn current_inst(&self) -> Option<Inst>

Get the instruction corresponding to the current position, if any.

fn goto_after_inst(&mut self, inst: Inst)

Go to the position after a specific instruction, which must be inserted in the layout. New instructions will be inserted after inst.

fn goto_inst(&mut self, inst: Inst)

Go to a specific instruction which must be inserted in the layout. New instructions will be inserted before inst.

fn goto_first_insertion_point(&mut self, block: Block)

Go to the position for inserting instructions at the beginning of block, which unlike goto_first_inst doesn’t assume that any instructions have been inserted into block yet.

fn goto_first_inst(&mut self, block: Block)

Go to the first instruction in block.

fn goto_last_inst(&mut self, block: Block)

Go to the last instruction in block.

fn goto_top(&mut self, block: Block)

Go to the top of block which must be inserted into the layout. At this position, instructions cannot be inserted, but next_inst() will move to the first instruction in block.

fn goto_bottom(&mut self, block: Block)

Go to the bottom of block which must be inserted into the layout. At this position, inserted instructions will be appended to block.

fn next_block(&mut self) -> Option<Block>

Go to the top of the next block in layout order and return it.

• If the cursor wasn’t pointing at anything, go to the top of the first block in the function.
• If there are no more blocks, leave the cursor pointing at nothing and return None.

Examples

The next_block() method is intended for iterating over the blocks in layout order:

fn edit_func(func: &mut Function) {
    let mut cursor = FuncCursor::new(func);
    while let Some(block) = cursor.next_block() {
        // Edit block.
    }
}

fn prev_block(&mut self) -> Option<Block>

Go to the bottom of the previous block in layout order and return it.

• If the cursor wasn’t pointing at anything, go to the bottom of the last block in the function.
• If there are no more blocks, leave the cursor pointing at nothing and return None.

Examples

The prev_block() method is intended for iterating over the blocks in backwards layout order:

fn edit_func(func: &mut Function) {
    let mut cursor = FuncCursor::new(func);
    while let Some(block) = cursor.prev_block() {
        // Edit block.
    }
}

fn next_inst(&mut self) -> Option<Inst>

Move to the next instruction in the same block and return it.

• If the cursor was positioned before a block, go to the first instruction in that block.
• If there are no more instructions in the block, go to the After(block) position and return None.
• If the cursor wasn’t pointing anywhere, keep doing that.

This method will never move the cursor to a different block.

Examples

The next_inst() method is intended for iterating over the instructions in a block like this:

fn edit_block(func: &mut Function, block: Block) {
    let mut cursor = FuncCursor::new(func).at_top(block);
    while let Some(inst) = cursor.next_inst() {
        // Edit instructions...
    }
}

The loop body can insert and remove instructions via the cursor.

Iterating over all the instructions in a function looks like this:

fn edit_func(func: &mut Function) {
    let mut cursor = FuncCursor::new(func);
    while let Some(block) = cursor.next_block() {
        while let Some(inst) = cursor.next_inst() {
            // Edit instructions...
        }
    }
}

fn prev_inst(&mut self) -> Option<Inst>

Move to the previous instruction in the same block and return it.

• If the cursor was positioned after a block, go to the last instruction in that block.
• If there are no more instructions in the block, go to the Before(block) position and return None.
• If the cursor wasn’t pointing anywhere, keep doing that.

This method will never move the cursor to a different block.

Examples

The prev_inst() method is intended for iterating backwards over the instructions in an block like this:

fn edit_block(func: &mut Function, block: Block) {
    let mut cursor = FuncCursor::new(func).at_bottom(block);
    while let Some(inst) = cursor.prev_inst() {
        // Edit instructions...
    }
}

fn insert_inst(&mut self, inst: Inst)

Insert an instruction at the current position.

• If pointing at an instruction, the new instruction is inserted before the current instruction.
• If pointing at the bottom of a block, the new instruction is appended to the block.
• Otherwise panic.

In either case, the cursor is not moved, such that repeated calls to insert_inst() causes instructions to appear in insertion order in the block.

fn remove_inst(&mut self) -> Inst

Remove the instruction under the cursor.

The cursor is left pointing at the position following the current instruction.

Return the instruction that was removed.

fn remove_inst_and_step_back(&mut self) -> Inst

Remove the instruction under the cursor.

The cursor is left pointing at the position preceding the current instruction.

Return the instruction that was removed.

fn insert_block(&mut self, new_block: Block)

Insert a block at the current position and switch to it.

As far as possible, this method behaves as if the block header were an instruction inserted at the current position.

• If the cursor is pointing at an existing instruction, the current block is split in two and the current instruction becomes the first instruction in the inserted block.
• If the cursor points at the bottom of a block, the new block is inserted after the current one, and moved to the bottom of the new block where instructions can be appended.
• If the cursor points to the top of a block, the new block is inserted above the current one.
• If the cursor is not pointing at anything, the new block is placed last in the layout.

This means that it is always valid to call this method, and it always leaves the cursor in a state that will insert instructions into the new block.

Implementors

impl<'f> Cursor for FuncCursor<'f>