[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:

Statements that modify tbl,
Calls to advance(iter), or
Statements that terminate the loop.

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

The order in which entries are iterated by a TableIterator is unspecified.
If entries are added to a Table after a TableIterator is created then the TableIterator will not necessarily step through the new data entries.
The entry at the current position of a TableIterator should not be removed from the Table. The entry can be safely removed after advancing the TableIterator past the entry. Ignoring this restriction can result in unpredictable behavior, including segmentation faults.

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

TableIterator - TableIterator is the type name for declaring table iterator variables and parameters.

Public Functions