Taxonomy Categories:
Member Functions:
Interface Category:
API.
Inherits From:
None.
Inherited By:
None.
Purpose:
To automatically sequence through all coordinates of a grid, a TSimpleGrid can create a TGridIterator that does just that. A grid iterator has means for traversing through the grid by way of Seek operations. SeekFirst returns the first coordinate of the grid, SeekNext, the next, and SeekPrevious, the previous. Clients can also seek to a specific coordinate and proceed from there either backward or forward. To determine if a Seek operation has succeeded, clients should call SeekOK, which returns true if the last seek operation worked. Thus, Seek operations can be placed in a loop while monitoring SeekOK to determine when to exit the loop.
Access to grid items is order dependent. Therefore, GridIterators must specify the order in which items are traversed. This is done by setting a specific scan order in the iterator. It defaults to normal raster order. Iterators can be further qualified by giving them a range of items over which to iterate. This is done with a TPrimitiveRegion. To utilize the range, clients can call Seek operations InRange, for example, SeekFirstInRange, SeekNextInRange, SeekPreviousInRange, and SeekLastInRange. Items not within the range are automatically skipped by the iterator.
The iterator also returns the number of items contained in the grid or the number of items in the grid that are within the range. For convenience, grid elements can be easily converted to and from item numbers and coordinates.
If a range is not sequential, that is, its contents contain discontinuities, clients might want to seek to the Nth item in the range. To do this, clients can call SeekToNthInRange, which returns the Nth item that is within the range even though it might not be item N. Say, for example, that items 2 and 4 are in a range, then SeekNthInRange(1) will find the 2nd item within the range (remember counting starts at 0). SeekNthInRange(1) will thus return a coordinate corresponding to item 4 because it is the 1st item within the range. This can be verified by calling CoordinateToItem with the coordinate obtained from SeekNthInRange. This operation is important for sequencing through grids when it is desirable to number just those items in the range as opposed to all items in the grid.
A TSimpleGrid object can create any number of iterators for itself that can all be traversing over the same grid independently of each other and at the same time. Because each iterator can have different scan orders (and different ranges), the number of each item in the grid can change from iterator to iterator but the coordinates will not. TSimpleGrids and their iterators are not multithread safe, however.
Instantiation:
Always allocated on the heap unless a copy is made on the stack.
Deriving Classes:
This is a special purpose class not intended for deriving new classes. If necessary, its virtual functions could be overridden to change specific behavior, but it could not be used with a TSimpleGrid since TSimpleGrid creates and uses TGridIterator internally and this functionality could not be easily overridden.
Concurrency:
Not multithread safe.
Resource Use:
No special requirements.
TGridIterator (const TGridIterator &)
Interface Category:
API.
Purpose:
Copy constructor.
Calling Context:
Called to copy an object.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
virtual ~ TGridIterator ()
Interface Category:
API.
Purpose:
Destructor.
Calling Context:
Called to destroy an object.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TGridIterator::GetGridRange
virtual TPrimitiveRegion * GetGridRange ()
Interface Category:
API.
Purpose:
Returns the TPrimitiveRegion currently describing the elements of the grid that are within the range.
Calling Context:
Called to get the current range for an iterator.
Parameters:
Return Value:
Returns a grid range that is owned by the object.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TGridIterator::AdoptGridRange
virtual void AdoptGridRange (TPrimitiveRegion *)
Interface Category:
API.
Purpose:
Sets the provided region to become the new range for the grid iterator.
Calling Context:
Called to set a new range in an iterator.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TGridIterator::GetScanOrder
virtual TScanOrder * GetScanOrder ()
Interface Category:
API.
Purpose:
Returns the current scan order for the iterator.
Calling Context:
Called to get the current scan order.
Parameters:
Return Value:
Returns the scan order that is owned by this object.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TGridIterator::AdoptScanOrder
virtual void AdoptScanOrder (TScanOrder *)
Interface Category:
API.
Purpose:
Adopts the provided scan order as the new scan order for the grid iterator.
Calling Context:
Called to set a new scan order.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
virtual const TSimpleGrid * GetGrid () const
Interface Category:
API.
Purpose:
Returns the grid being iterated.
Calling Context:
Called to obtain the grid being iterated.
Parameters:
Return Value:
Returns the grid object that is not owned by the client.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
The iterator can cause other exceptions if the target grid has been deleted or otherwise made inaccessible.
Member Function: TGridIterator::GetGridSize
virtual TULongPair GetGridSize () const
Interface Category:
API.
Purpose:
Returns the size of the grid being iterated.
Calling Context:
Called to obtain the grid size.
Parameters:
Return Value:
Returns the grid size as a TULongPair.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
The iterator can cause other exceptions if the target grid has been deleted or otherwise made inaccessible.
Member Function: TGridIterator::GetCurrentItem
virtual unsigned long GetCurrentItem () const
Interface Category:
API.
Purpose:
Returns the current item being iterated.
Calling Context:
Called to get the current item if SeekOK is true.
Parameters:
Return Value:
Returns the current item number.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TGridIterator::GetCurrentCoordinate
virtual TULongPair GetCurrentCoordinate () const
Interface Category:
API.
Purpose:
Returns the coordinate of the item currently represented by the iteration.
Calling Context:
Called to get coordinate of current item if SeekOK is true.
Parameters:
Return Value:
Returns the current grid coordinate as a TULongPair.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
- virtual TULongPair Seek (unsigned long)
- virtual TULongPair Seek (const TULongPair & coordinate)
Interface Category:
API.
Purpose:
- Seeks to the element number.
- Seeks to the coordinate specified.
Calling Context:
- Called to seek to a specific element.
- Called to seek to a given coordinate.
Parameters:
- unsigned long -The desired item number.
- const TULongPair & coordinate -The coordinate to seek to.
Return Value:
Returns the coordinate of the desired element.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
The iterator can cause an exception if the target grid has been deleted or otherwise made inaccessible.
Member Function: TGridIterator::SeekFirst
virtual TULongPair SeekFirst ()
Interface Category:
API.
Purpose:
Seeks to the first element of the grid.
Calling Context:
Called to obtain the first element of the grid.
Parameters:
Return Value:
Returns the coordinate of the first element in the grid.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
The iterator can cause an exception if the target grid has been deleted or otherwise made inaccessible.
Member Function: TGridIterator::SeekLast
virtual TULongPair SeekLast ()
Interface Category:
API.
Purpose:
Seeks to the last element of the grid.
Calling Context:
Called to obtain the last element of the grid.
Parameters:
Return Value:
Returns the coordinate of the last element.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
The iterator can cause an exception if the target grid has been deleted or otherwise made inaccessible.
Member Function: TGridIterator::SeekNext
virtual TULongPair SeekNext ()
Interface Category:
API.
Purpose:
Given the current (valid) state of the iterator, seeks to the next logical element in the sequence, if there is one.
Calling Context:
Called to seek to the next logical element. It must be preceded by a valid seek operation.
Parameters:
Return Value:
Returns the coordinate of the next item.
Exceptions:
Throws TIteratorSyncException if no valid seek operation occurred prior to this call.
Concurrency:
Not multithread safe.
Other Considerations:
The iterator can cause an exception if the target grid has been deleted or otherwise made inaccessible.
Member Function: TGridIterator::SeekPrevious
virtual TULongPair SeekPrevious ()
Interface Category:
API.
Purpose:
Given the current (valid) state of the iterator, seeks to the previous logical element in the sequence, if there is one.
Calling Context:
Called to seek to the previous element. It must be preceded by a valid seek operation.
Parameters:
Return Value:
Returns the coordinate of the previous item.
Exceptions:
Throws TIteratorSyncException if no valid seek operation precedes this call.
Concurrency:
Not multithread safe.
Other Considerations:
The iterator can cause an exception if the target grid has been deleted or otherwise made inaccessible.
virtual bool SeekOK () const
Interface Category:
API.
Purpose:
Determines if the last attempted seek operation was successful.
Calling Context:
Called after any seek operation as many times as desired or to find out if a seek operation has been performed.
Parameters:
Return Value:
Returns true if the previous seek operation was successful.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TGridIterator::ItemToCoordinate
virtual TULongPair ItemToCoordinate (unsigned long) const
Interface Category:
API.
Purpose:
Converts the specified item number to a coordinate in the grid. If the item is outside the grid, the coordinate will be outside also.
Calling Context:
Called to obtain the coordinate of a particular item.
Parameters:
- unsigned long -The item number to convert.
Return Value:
Returns coordinate of the given item number.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
The iterator can cause an exception if the target grid has been deleted or otherwise made inaccessible.
Member Function: TGridIterator::CoordinateToItem
virtual unsigned long CoordinateToItem (const TULongPair & coordinate) const
Interface Category:
API.
Purpose:
Converts the specified coordinate to an item number. If the coordinate is outside the grid, the results are undefined.
Calling Context:
Called to obtain the item number of a particular coordinate.
Parameters:
- const TULongPair & coordinate -The coordinate to convert.
Return Value:
Returns the item number of the given coordinate.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
The iterator can cause an exception if the target grid has been deleted or otherwise made inaccessible.
Member Function: TGridIterator::SeekFirstInRange
virtual TULongPair SeekFirstInRange ()
Interface Category:
API.
Purpose:
Seeks to the first element within the range.
Calling Context:
Called to seek to the first element within the range.
Parameters:
Return Value:
Returns the coordinate of the first element in the range. Only valid if SeekOK() returns true.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
The iterator can cause an exception if the target grid has been deleted or otherwise made inaccessible.
Member Function: TGridIterator::SeekLastInRange
virtual TULongPair SeekLastInRange ()
Interface Category:
API.
Purpose:
Seeks to the last element that is within the range.
Calling Context:
Called to seek to the last element within the range.
Parameters:
Return Value:
Returns the coordinate of the last item in the range.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
The iterator can cause an exception if the target grid has been deleted or otherwise made inaccessible.
Member Function: TGridIterator::SeekNextInRange
virtual TULongPair SeekNextInRange ()
Interface Category:
API.
Purpose:
Given a current valid state of the iterator, seeks to the next item that is within the range, if there is one.
Calling Context:
Called to seek to the next element within the range. It must be preceded by another valid seek operation.
Parameters:
Return Value:
Returns the coordinate of the next item in the range.
Exceptions:
Throws TIteratorSyncException if a valid seek operation did not precede this call.
Concurrency:
Not multithread safe.
Other Considerations:
The iterator can cause an exception if the target grid has been deleted or otherwise made inaccessible.
Member Function: TGridIterator::SeekPreviousInRange
virtual TULongPair SeekPreviousInRange ()
Interface Category:
API.
Purpose:
Given a current valid state of the iterator, seeks to the previous item that is within the range.
Calling Context:
Called to seek to the previous element within the range. This call must be preceded by another valid seek operation.
Parameters:
Return Value:
Returns the coordinate of the previous item in the range.
Exceptions:
Throws TIteratorSyncException if another valid seek operation does not precede this one.
Concurrency:
Not multithread safe.
Other Considerations:
The iterator can cause an exception if the target grid has been deleted or otherwise made inaccessible.
Member Function: TGridIterator::SeekNthInRange
virtual TULongPair SeekNthInRange (unsigned long offset)
Interface Category:
API.
Purpose:
Considering only those elements within the range, seeks to the Nth item that is within the range, where n is given by the offset, and returns its coordinate.
Calling Context:
Called to seek to the Nth element within the range without knowing which one it is.
Parameters:
- unsigned long offset -The offset.
Return Value:
Returns the coordinate of the item corresponding to the Nth (or offset) item that is within the range.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
The iterator can cause an exception if the target grid has been deleted or otherwise made inaccessible.
Member Function: TGridIterator::GetItemCountInRange
virtual unsigned long GetItemCountInRange () const
Interface Category:
API.
Purpose:
Counts the number of items that are within the range.
Calling Context:
Called to count the number of items within the range.
Parameters:
Return Value:
Returns the number of items within the range.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TGridIterator::GetItemCount
virtual unsigned long GetItemCount () const
Interface Category:
API.
Purpose:
Gets the total number of items in the grid.
Calling Context:
Called to obtain the total number of items in the grid.
Parameters:
Return Value:
Returns the total number of items.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TGridIterator::operator=
TGridIterator & operator =(const TGridIterator &)
Interface Category:
API.
Purpose:
Assignment operator.
Calling Context:
Called when an object is assigned to another compatible object.
Parameters:
Return Value:
A non-const reference to the left-hand side object.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Click the icon to mail questions or corrections about this material to Taligent personnel.
Copyright©1995 Taligent,Inc. All rights reserved.