12.10 Sequence iterators

Sequence iterators are convenience constructs for iterating through statements in a sequence. Given a sequence SEQ, here is a typical use of gimple sequence iterators:

gimple_stmt_iterator gsi;

for (gsi = gsi_start (seq); !gsi_end_p (gsi); gsi_next (&gsi))
  {
    gimple g = gsi_stmt (gsi);
    /* Do something with gimple statement G.  */
  }

Backward iterations are possible:

        for (gsi = gsi_last (seq); !gsi_end_p (gsi); gsi_prev (&gsi))

Forward and backward iterations on basic blocks are possible with gsi_start_bb and gsi_last_bb.

In the documentation below we sometimes refer to enum gsi_iterator_update. The valid options for this enumeration are:

Below is a list of the functions used to manipulate and use statement iterators.

GIMPLE function: gimple_stmt_iterator gsi_start (gimple_seq seq)

Return a new iterator pointing to the sequence SEQ’s first statement. If SEQ is empty, the iterator’s basic block is NULL. Use gsi_start_bb instead when the iterator needs to always have the correct basic block set.

GIMPLE function: gimple_stmt_iterator gsi_start_bb (basic_block bb)

Return a new iterator pointing to the first statement in basic block BB.

GIMPLE function: gimple_stmt_iterator gsi_last (gimple_seq seq)

Return a new iterator initially pointing to the last statement of sequence SEQ. If SEQ is empty, the iterator’s basic block is NULL. Use gsi_last_bb instead when the iterator needs to always have the correct basic block set.

GIMPLE function: gimple_stmt_iterator gsi_last_bb (basic_block bb)

Return a new iterator pointing to the last statement in basic block BB.

GIMPLE function: bool gsi_end_p (gimple_stmt_iterator i)

Return TRUE if at the end of I.

GIMPLE function: bool gsi_one_before_end_p (gimple_stmt_iterator i)

Return TRUE if we’re one statement before the end of I.

GIMPLE function: void gsi_next (gimple_stmt_iterator *i)

Advance the iterator to the next gimple statement.

GIMPLE function: void gsi_prev (gimple_stmt_iterator *i)

Advance the iterator to the previous gimple statement.

GIMPLE function: gimple gsi_stmt (gimple_stmt_iterator i)

Return the current stmt.

GIMPLE function: gimple_stmt_iterator gsi_after_labels (basic_block bb)

Return a block statement iterator that points to the first non-label statement in block BB.

GIMPLE function: gimple * gsi_stmt_ptr (gimple_stmt_iterator *i)

Return a pointer to the current stmt.

GIMPLE function: basic_block gsi_bb (gimple_stmt_iterator i)

Return the basic block associated with this iterator.

GIMPLE function: gimple_seq gsi_seq (gimple_stmt_iterator i)

Return the sequence associated with this iterator.

GIMPLE function: void gsi_remove (gimple_stmt_iterator *i, bool remove_eh_info)

Remove the current stmt from the sequence. The iterator is updated to point to the next statement. When REMOVE_EH_INFO is true we remove the statement pointed to by iterator I from the EH tables. Otherwise we do not modify the EH tables. Generally, REMOVE_EH_INFO should be true when the statement is going to be removed from the IL and not reinserted elsewhere.

Links the sequence of statements SEQ before the statement pointed by iterator I. MODE indicates what to do with the iterator after insertion (see enum gsi_iterator_update above).

Links statement G before the statement pointed-to by iterator I. Updates iterator I according to MODE.

Links sequence SEQ after the statement pointed-to by iterator I. MODE is as in gsi_insert_after.

Links statement G after the statement pointed-to by iterator I. MODE is as in gsi_insert_after.

GIMPLE function: gimple_seq gsi_split_seq_after (gimple_stmt_iterator i)

Move all statements in the sequence after I to a new sequence. Return this new sequence.

GIMPLE function: gimple_seq gsi_split_seq_before (gimple_stmt_iterator *i)

Move all statements in the sequence before I to a new sequence. Return this new sequence.

GIMPLE function: void gsi_replace (gimple_stmt_iterator *i, gimple stmt, bool update_eh_info)

Replace the statement pointed-to by I to STMT. If UPDATE_EH_INFO is true, the exception handling information of the original statement is moved to the new statement.

GIMPLE function: void gsi_insert_before (gimple_stmt_iterator *i, gimple stmt, enum gsi_iterator_update mode)

Insert statement STMT before the statement pointed-to by iterator I, update STMT’s basic block and scan it for new operands. MODE specifies how to update iterator I after insertion (see enum gsi_iterator_update).

GIMPLE function: void gsi_insert_seq_before (gimple_stmt_iterator *i, gimple_seq seq, enum gsi_iterator_update mode)

Like gsi_insert_before, but for all the statements in SEQ.

GIMPLE function: void gsi_insert_after (gimple_stmt_iterator *i, gimple stmt, enum gsi_iterator_update mode)

Insert statement STMT after the statement pointed-to by iterator I, update STMT’s basic block and scan it for new operands. MODE specifies how to update iterator I after insertion (see enum gsi_iterator_update).

GIMPLE function: void gsi_insert_seq_after (gimple_stmt_iterator *i, gimple_seq seq, enum gsi_iterator_update mode)

Like gsi_insert_after, but for all the statements in SEQ.

GIMPLE function: gimple_stmt_iterator gsi_for_stmt (gimple stmt)

Finds iterator for STMT.

GIMPLE function: void gsi_move_after (gimple_stmt_iterator *from, gimple_stmt_iterator *to)

Move the statement at FROM so it comes right after the statement at TO.

GIMPLE function: void gsi_move_before (gimple_stmt_iterator *from, gimple_stmt_iterator *to)

Move the statement at FROM so it comes right before the statement at TO.

GIMPLE function: void gsi_move_to_bb_end (gimple_stmt_iterator *from, basic_block bb)

Move the statement at FROM to the end of basic block BB.

GIMPLE function: void gsi_insert_on_edge (edge e, gimple stmt)

Add STMT to the pending list of edge E. No actual insertion is made until a call to gsi_commit_edge_inserts() is made.

GIMPLE function: void gsi_insert_seq_on_edge (edge e, gimple_seq seq)

Add the sequence of statements in SEQ to the pending list of edge E. No actual insertion is made until a call to gsi_commit_edge_inserts() is made.

GIMPLE function: basic_block gsi_insert_on_edge_immediate (edge e, gimple stmt)

Similar to gsi_insert_on_edge+gsi_commit_edge_inserts. If a new block has to be created, it is returned.

GIMPLE function: void gsi_commit_one_edge_insert (edge e, basic_block *new_bb)

Commit insertions pending at edge E. If a new block is created, set NEW_BB to this block, otherwise set it to NULL.

GIMPLE function: void gsi_commit_edge_inserts (void)

This routine will commit all pending edge insertions, creating any new basic blocks which are necessary.