ROSE  0.9.10.54
Classes | Public Member Functions | Protected Attributes | List of all members
RoseAst::iterator Class Reference

Description

AST iterator.

This is an STL-compliant forward iterator for traversing AST nodes in depth-first pre-order. The withoutNullValues and withNullValues functions control whether the traversal follows null child pointers (the default is that null pointers are not followed). Entire subtrees can be exluded from traversal with the skipSubtreeOnForward function.

The iterator also provides a number of auxiliary functions for querying some structural properties of the AST w.r.t. the position in the traversal (e.g., is_at_first_child, is_at_last_child, is_at_root, parent, etc.).

Note
Comparison of iterators is also correct for null values. Only if two iterators refer to the same (identical) null value, they are equal, otherwise they are not. If they refer to different null values they are different. Hence, different null values in the AST are treated like different nodes. This is necessary to allow STL algorithms to work properly on the AST.

Definition at line 56 of file RoseAst.h.

#include <RoseAst.h>

Collaboration diagram for RoseAst::iterator:
Collaboration graph
[legend]

Public Member Functions

 iterator ()
 Default constructor. More...
 
 iterator (SgNode *x)
 Construct an iterator pointing to a particular AST node. More...
 
bool operator== (const iterator &x) const
 Test iterator equality. More...
 
bool operator!= (const iterator &x) const
 Test iterator inequality. More...
 
SgNodeoperator* () const
 Dereference an iterator. More...
 
void skipChildrenOnForward ()
 Cause children to be skipped on the next advancement. More...
 
SgNodeparent () const
 Parent AST node relative to the iteration. More...
 
bool is_at_root () const
 Test whether iterator is pointing to root node of AST to be traversed. More...
 
bool is_at_first_child () const
 Test whether iterator is at the first child of its parent. More...
 
bool is_at_last_child () const
 Test whether iterator as at the last child of its parent. More...
 
bool is_past_the_end () const
 
std::string current_node_id () const
 
std::string parent_node_id () const
 
void print_top_element () const
 
int stack_size () const
 Depth of traversal. More...
 
iteratoroperator++ ()
 Advance the iterator. More...
 
iterator operator++ (int)
 Advance the iterator. More...
 
iteratorwithoutNullValues ()
 Mode to enable or disable skipping null child pointers. More...
 
iteratorwithNullValues ()
 Mode to enable or disable skipping null child pointers. More...
 

Protected Attributes

SgNode_startNode
 
bool _skipChildrenOnForward
 
bool _withNullValues
 

Constructor & Destructor Documentation

RoseAst::iterator::iterator ( )

Default constructor.

Constructs an iterator that compares equal to the end iterator.

RoseAst::iterator::iterator ( SgNode x)

Construct an iterator pointing to a particular AST node.

Member Function Documentation

bool RoseAst::iterator::operator== ( const iterator x) const

Test iterator equality.

Two iterators are equal if they point to the same node or they're both end iterators. Two iterators that are pointing to null nodes are equal if and only if they refer to the same (identical) null value. If they refer to different null values they are different. Hence, different null values in the AST are treated like different nodes. This is necessary to allow STL algorithms to work.

Additionally, even if two iterators are pointing to the same AST node they will be equal only if they're in the same skipChildrenOnForward state.

bool RoseAst::iterator::operator!= ( const iterator x) const

Test iterator inequality.

This is just a convenince function that inverts the test for equality.

SgNode* RoseAst::iterator::operator* ( ) const

Dereference an iterator.

Dereference an iterator to obtain the AST node to which it points. Dereferencing an end iterator will throw an std::out_of_range exception. If null AST pointers are being followed, the return value can be a null node (see withNullValues and withoutNullValues).

iterator& RoseAst::iterator::operator++ ( )

Advance the iterator.

Advances the iterator to the next AST node in a depth-first pre-order search. If the skipChildrenOnForward flag is set then all children of the current node are skipped and the skipChildrenOnForward flag is cleared. If the withoutNullValues flag is set, then all null child pointers are skipped but that flag is not cleared.

iterator RoseAst::iterator::operator++ ( int  )

Advance the iterator.

Advances the iterator to the next AST node in a depth-first pre-order search. If the skipChildrenOnForward flag is set then all children of the current node are skipped and the skipChildrenOnForward flag is cleared. If the withoutNullValues flag is set, then all null child pointers are skipped but that flag is not cleared.

void RoseAst::iterator::skipChildrenOnForward ( )

Cause children to be skipped on the next advancement.

This function marks the iterator so that it's next increment operator will advance over the current node's children without visiting them. The children are skipped only for the immediate next forward iteration (this is useful when used in the iterator idiom). This function is specific to tree iteration and allows to take tree structure into account although we are traversing the tree nodes as a sequence.

iterator& RoseAst::iterator::withoutNullValues ( )

Mode to enable or disable skipping null child pointers.

The withoutNullValues mode causes the iterator to skip over null child pointers, while the withNullValues mode causse null child pointers to be followed followed. The mode affects subsequent advancement of the iterator, not its current value. In other words, in the withNullValues mode the iterator dereference operator will always return non-null values after its next increment. The default mode is withoutNullValues.

The function returns this iterator and can therefore be called together with begin, like this:

iterator& RoseAst::iterator::withNullValues ( )

Mode to enable or disable skipping null child pointers.

The withoutNullValues mode causes the iterator to skip over null child pointers, while the withNullValues mode causse null child pointers to be followed followed. The mode affects subsequent advancement of the iterator, not its current value. In other words, in the withNullValues mode the iterator dereference operator will always return non-null values after its next increment. The default mode is withoutNullValues.

The function returns this iterator and can therefore be called together with begin, like this:

SgNode* RoseAst::iterator::parent ( ) const

Parent AST node relative to the iteration.

Returns the parent relative to the current iterator position, which might differ from the get_parent property of the current node. For instance, parent can return a non-null pointer when the current node is null.

bool RoseAst::iterator::is_at_root ( ) const

Test whether iterator is pointing to root node of AST to be traversed.

Returns true if and only if the current node of this iterator is also the root of the searched subtree.

bool RoseAst::iterator::is_at_first_child ( ) const

Test whether iterator is at the first child of its parent.

Returns true if the current node of this iterator is the first child of the parent node. This is useful when we want to print the iterated AST as term (with braces), allowing us to query whether we need to print an opening brace.

bool RoseAst::iterator::is_at_last_child ( ) const

Test whether iterator as at the last child of its parent.

Returns true if the current node of this iterator is the last child of the parent node. This is useful when we want to print the iterated AST as term (with braces), allowing us to query whether we need to print a closing brace.

int RoseAst::iterator::stack_size ( ) const

Depth of traversal.


The documentation for this class was generated from the following file: