An iterator is a programming method by which one can loop (iterate) through things in a collection. (For example, an iterator might allow looping through all effects on a creature.) This is generally a means to process the collection one thing at a time. A high-level iterator, such as those provided by NWScript, typically handles all the bookkeeping behind the scenes, allowing the programmer to simply request the next thing, without having to keep track of what has already been processed.

In NWScript, an iterator is typically started with a command whose name starts with "GetFirst", then updated with the corresponding "GetNext" command. These commands return the things in the collection until all such things have been returned. Once the collection has been exhausted, the update (or initialization, if the collection is empty) returns an invalid value that can be tested for.

// Loop through the effects on oCreature.
effect eSearch = GetFirstEffect(oCreature); // Initialize the iterator
while ( GetIsEffectValid(eSearch) )         // Tests to see if the iterator is finished
    // Do something with eSearch.

    // Update the loop.
    eSearch = GetNextEffect(oCreature);     // Increment the iterator

Trying to nest iterators of the same type can confuse NWScript and lead to unintended results. This is often not an issue, but when it is, it can arise subtly: it can easily go unnoticed that an iterator loop calls a function whose implementation contains another iterator loop.

See also Edit