Overview

The RoseCursor class can traverse objects within a design or design section. Cursors traverse a design "in place" using an internal index. Traversing with a cursor is always more space and time efficient than calling findObjects(), which must build a list of pointers.

The cursor class can return all objects in a design or section. It can return all objects in a particular type of section, such as the contents of all data sections. It can return objects of a particular type, including or excluding all subtypes. Applications can also provide a type filter for additional control over the type of objects returned.

See Searching for Objects by Type for more discussion on traversals. The RoseTypesCursor is a subtype that can iterate over several different types in a single loop.

RoseConstCursor class

class RoseConstCursor : public RoseCursor { ... };

The RoseConstCursor class is subtype of RoseCursor, for use with constant data (no pnew, delete, or moves). This is safe to use in multiple threads. The default RoseCursor is not thread safe because it builds certain structures to deal with object addition and deletion.

The RoseConstCursor class has the same member functions and behaves like RoseCursor in all other respects.

RoseConstCursor objs;
RoseObject * obj;

objs.traverse (design);
objs.domain (ROSE_DOMAIN(some_type));

while ((obj=objs.next()) != 0) {

      // read-only traversal of a design
}

ap_context()

RoseAPContext * ap_context();

void ap_context(
	RoseAPContext * apc
	);

Cursors are able to select objects based on a number of criteria. The ap_context() function gets and sets one of these criteria. If an AP context is provided, the cursor will only return objects from a design section associated with the context. By default, the context is set to null and this selection criterion is disabled.

domain()

RoseDomain * domain();

void domain(
	RoseDomain * domain
	);

The domain() function specifies the type of object the cursor will return. During a traversal, the cursor tests the type of objects using the RoseObject::isa() function, so the cursor will also return instances of subtypes of the domain. The exact() function can be used to exclude instances of subtypes. If the domain is null, the cursor will return objects of any type.

Changing the type of object, either with this function or exact(), will reset the cursor back to the start as if rewind() was called.

Example

The following code traverses a design and returns the Point objects within it. Note the use of ROSE_CAST() to convert the return pointer from a RoseObject to a Point.

RoseCursor objs;
RoseObject * obj;

objs.traverse (design); 
objs.domain (ROSE_DOMAIN (Point));
while (obj = objs.next()) {
    Point * pt = ROSE_CAST (Point, obj);
    ... 
}

An application can traverse all entity instances by specifying the RoseStructure type. This excludes all list (RoseAggregate) and select (RoseUnion) objects.

See Also

EXPRESS Data Dictionary; ROSE_CAST(); RoseObject::isa(); RoseCursor::exact()

exact()

void exact(
	RoseDomain * domain
	);
/PRE>

The exact() function specifies the type of object the cursor will return. During a traversal, the cursor tests the type of objects by direct equality comparison, so the cursor will only return instances of the exact domain. Use the domain() function insteacd if you also want instances of subtypes.

Changing the type of object, either with this function or domain(), will reset the cursor back to the start as if rewind() was called.

Example

The following code fragment traverses the object in a design and returns only exact instances of the Point domain.

RoseCursor objs;
RoseObject * obj;

objs.traverse (design); 
objs.exact (ROSE_DOMAIN (Point));
while (obj = objs.next()) {
    Point * pt = ROSE_CAST (Point, obj);
    ... 
}

See Also

EXPRESS Data Dictionary; RoseCursor::domain()

fastforward()

void fastforward();

The fastforward() function is used for traversing objects in reverse order. This function changes the position of the cursor so that the previous() function will return the very last object. The next() function will return null. See traverse() for examples.

next()

RoseObject * next(); 

The next() function returns the next available object, and advances the cursor. When there are no more objects, this returns null. See traverse() for examples.

nextMarked() / nextUnmarked()

RoseObject * nextMarked (RoseMark m = ROSE_MARK_CURRENT);
RoseObject * nextUnmarked (RoseMark m = ROSE_MARK_CURRENT);

The nextMarked() and nextUnmarked() functions behave like the next() function, but also consider whether each object has been marked by the rose_mark_set() function. The nextMarked() function returns objects that have been visited, while nextUnmarked() returns objects that have not been visited. This function is only useful within a rose_mark_begin() / rose_mark_end() block.

Example

The following code fragment traverses all objects in a design. The body of the loop might follow attributes and mark additional objects. The loop guard condition uses nextUnmarked() to make sure that the loop does not work on the an object more than once.

RoseCursor objs;
RoseObject * obj;

objs.traverse (design); 
while (obj = objs.nextUnmarked()) {
    ... 
    /* mark some attributes with visit() */
    obj-> getObject ("some_att")-> visit();
    ... 
}

See Also

Marking Objects During Traversal; rose_mark_begin(); rose_mark_end(); rose_mark_set()

previous()

RoseObject * previous();

The previous() function returns the current object and moves the cursor to the previous object. Once the cursor reaches the first object, calls to previous() will return null. See traverse() for examples.

rewind()

void rewind();

The rewind() function is useful for traversing objects multiple times. This function sets the position of the cursor to the beginning of the objects so that the next() function returns the first object. The previous() function will return null. See traverse() for examples.

section_type()

RoseDesignSectionType section_type();

void section_type(
	RoseDesignSectionType typ
	);

Cursors are able to select objects based on a number of criteria. The section_type() function gets and sets one of these criteria. When an cursor is traversing an entire design, it will only return objects from a design section matching the section type. By default, the section type is set to ROSE_SECTION_DATA, so a cursor will return objects from every data section.

To traverse every sections in a design (header, data, and system sections), set the section type to ROSE_SECTION_ANY.

See Also

RoseDesignSectionType

size()

unsigned size();

The size() function computes the number of objects matched by the cursors current selection criteria. This function can be called at any time and does not change the state of the cursor.

NOTE

Do not use this function for loop guard conditions because object creation, deletion, or moves during the traversal could change number of objects returned by a cursor. The proper technique is to look for a null return from next() to signal no more objects.

Example

RoseCursor objs;

objs.traverse (design);
objs.domain (ROSE_DOMAIN(point));
printf ("num of points (plus subtypes): %d\n", objs.size());

objs.exact (ROSE_DOMAIN(point));
printf ("num of points (no subtypes): %d\n", objs.size());

traverse()

void traverse(
	RoseDesign * design
	); 

void traverse(
	RoseDesignSection * section
	);

The traverse() function specifies the collection of objects that the cursor will examine. The function accepts either a RoseDesign or a RoseDesignSection. When a section is specified, the cursor will iterate over all of the objects in that one section. When a design is specified, the cursor will iterate over all sections matching some criteria. By default this iterates over all data sections in the design. Other criteria can be specified using the section_type() or ap_context() functions.

Example

The following example traverses all data objects in a design and then uses the rewind() function to traverse them again.

RoseCursor objs;
RoseObject * obj;

objs.traverse (design); 
while ((obj=objs.next()) != 0) {
    /* do some operations */
}

objs.rewind();
while ((obj=objs.next()) != 0) {
    /* do them again */
}

The following code fragment uses the fastforward() and previous() functions to traverse the design in a reverse order.

RoseCursor objs;
RoseObject * obj;

objs.traverse (design); 
objs.fastforward();
while ((obj=objs.previous()) != 0) {
    /* do some operations */
}

type_filter()

RoseCursorTypeFilter type_filter();

void type_filter(
	RoseCursorTypeFilter f
	);

typedef int (*RoseCursorTypeFilter)(
	RoseCursor * cursor,
	RoseDomain * candidate_type
	);

The type_filter() function can be used for more sophisticated traversal operations. An application can specify a pointer to a function that determines whether the cursor should return objects of a particular type. The filter function takes a pointer to the cursor and a pointer to a domain to be tested. The cursor calls this function once for every type of object in a design section. The function should return a non-zero value if instances of the candidate type should be returned by the cursor.

Example

When using the domain() function to specify a search type, the cursor uses a filter that tests types using RoseDomain::typeIsa(). Note how the function must get the search domain from the cursor.

int cursor_isa (
    RoseCursor * cursor, 
    RoseDomain * candidate
    )
{
    return (candidate-> typeIsa (cursor-> domain()));
}