[an error occurred while processing this directive]

TableIterator Module Client Specifications


Purpose

The TableIterator module provides a mechanism for constructing loops that step through the entries in a Table (see Table Module Client Specifications).

Client Data Model

In order to understand a TableIterator, you can view a Table as having positions for each entry, and one additional position that is not associated with any entry. An initialized TableIterator for a Table can be obtained as the returned value from iteratorFor(). At any time after initialization, the state of a TableIterator refers to one of the table positions, called its current position. When more() returns true, it means that the current position is associated with an entry, which is called the current entry. The current position can be moved from one entry to another by calling advance(). The key and data for the current entry can be obtained as returned values from currentKey() and currentData().

When more() returns false, the current position is not associated with any entry. This happens only after each entry of the Table has been the current entry exactly once. When a TableIterator is no longer needed, its resources can be released by calling freeTableIterator().

The following loop structure illustrates how TableIterators are normally used.

    for (iter = iteratorFor(tbl); more(iter); advance(iter)) {
	perform an operation with the current entry of iter
    }
    freeTableIterator(iter);
In the body of this loop, the current entry is accessed with currentKey(tbl) and currentData(tbl). The loop is guaranteed to perform the operation once with each entry of tbl provided that the body of the loop does not contain any of the following:
Error handling policy
The functions currentKey(), currentData(), and advance() have preconditions that more() is true. Violations of these preconditions result in an error message followed by program termination.
Module Limitations

Importing Information

The TableIterator module is a submodule of the Table module. It is automatically imported whenever the Table module is imported. See Table Module Client Specifications.

Public Data Types

Public Functions

Creation and Release
Iterator Positioning
Current Entry Access
[an error occurred while processing this directive]