Iterators

Iteration is the process of stepping through a sequence of values. An iterator is an entity that provides such a sequence of values, one at a time. In SenseTalk, lists and ranges can both be used as iterators. In addition, you can create your own custom iterator objects. There are several ways that you can step through each of the values supplied by an iterator and work with each one in turn.

Iterating Using Repeat With Each

When you need to work with each value supplied by an iterator and perform some actions with that value, use a repeat with each loop. For example, here's a loop that uses each value from a list:

To iterate over all of the values in a range, use repeat with each just as you would with a list:

Iterating Using Each Expressions

When you need to process each value (or a selected set of values) from a list or other iterator to produce a list of result values, an each expression can be very effective. The result of an each expression is always a list. See Each Expressions.

Iterating Using NextValue

The nextValue() function will return the next sequential value from an iterator. When the sequence is exhausted and no more values are available from that iterator, the special constant value end is returned.

When iterating over the properties of a property list outside of a repeat loop, nextKey can be used to retrieve the next key, nextValue to retrieve the next value, or nextKeyValue to retrieve the next (key,value) pair. CurrentKey, currentValue, and currentKeyValue can be used to obtain the corresponding value for the current property without advancing the iteration.

Modifying Iteration Using CurrentIndex

Both lists and ranges have a currentIndex property. When a list or range is first created, the value of the currentIndex is zero. It is also reset to zero at the start of a repeat with each loop or an each expression for that iterator.

During iteration, the currentIndex property is incremented each time a value is retrieved from the iterator. The iterator's currentIndex can be accessed to determine the item number of the current value in the source list or range.

What's more, the currentIndex can be changed to alter the course of iteration. For example, this repeat loop will only display the odd numbers in the range:

Changing a List During Iteration

While iterating over the items in a list using repeat with each, an each expression, or the nextValue function, SenseTalk uses the currentIndex property of the list to keep track of the iteration. Whenever items are inserted, deleted, or replaced in a list, the currentIndex property is adjusted appropriately to reflect the change. So it is possible to add, remove, or replace items in a list during iteration without causing problems.

Custom Iterators

Lists and ranges are the most common sources used as iterators. You can also create a custom iterator by making a script or object with a nextValue handler that returns the next value in a sequence. The values returned can be anything, and the implementation may be as simple as returning the nextValue from a list that is a property of the object, or may be the next result calculated from some internal state maintained by the object. Iterators of this type are sometimes called "generators" because they generate values one at a time as needed.

To be used as an iterator, there are few rules an object must follow. First, it must have an objectType of "iterator". This tells SenseTalk to call the object's nextValue handler to obtain each value for a repeat with each loop or an each expression. Second, of course, it must have a nextValue handler to supply each value in the sequence. The nextValue handler should return the value end when the end of the sequence has been reached and no more values are available. If it doesn't do this, a repeat loop should include an exit repeat statement to break out of the loop at some point or it will continue forever. An each expression should not be used with an iterator that doesn't eventually return end.

In addition to a nextValue handler, a custom iterator may optionally also have a startIteration handler. If present, this handler will be called before nextValue is called by either a repeat with each loop or an each expression to allow the iterator to set up any initial conditions, or to reset its state following any earlier iteration.

Here is an example of a custom iterator that generates values from the Fibonacci sequence, in which each value is the sum of the two preceding values (note that although the Fibonacci sequence is infinite, this iterator only returns the values up to ten thousand, allowing it to be used with an each expression):

Property Lists as Iterators

You also can use a property list as an iterator. When iterating in a repeat loop, the property list supplies each key and its value as a list of two items. An object that defines its own iteration (objects with an objectType of "iterator") use their own iteration; objects with a different objectType iterate over the (key,value) pairs for their properties.

Passing an Iterator As a Parameter

An iterator can be passed as a parameter to another script or handler. It is passed with its current state intact, including the value of the currentIndex property of a list or range, and any properties of a custom iterator. So if the local script has been using values one at a time from the iterator (by using nextValue), the called script can continue using later values in the sequence.

Keep in mind that SenseTalk ordinarily makes copies of any parameter values, so the called script will receive its own copy of the iterator. To share the iterator so that both the local and the called scripts will be using a single sequence of values from the iterator, pass the iterator by reference. For example:

Without the "@" to pass takeANumber by reference, the final call to takeANumber's nextValue would return 3 instead of 5. By passing a reference here, both scripts share the same sequence of values rather than splitting off a copy to the called script.

The is an iterator operator can be used to test whether a value (such as a parameter that was received) can be iterated:

Restarting Iteration

To restart iteration over a range or list beginning with the first value again, set its currentIndex to zero. The next time you access its nextValue, the first value in the range or list will be returned.

Some custom iterators may provide a mechanism for starting iteration again, and some may not. A custom iterator that is designed to be reusable by repeat with each loops and each expressions should implement a startIteration handler that can be called to reset it. Other custom iterators may implement a currentIndex property that can be reset just as you would for a list or range. But neither of those is required in a basic iterator.

Assigned List Values

Lists in SenseTalk grow dynamically as items are inserted or values are assigned to items beyond the previous extent of the list. This allows values to be assigned to items that may be widely dispersed in a list, as in this example:

The list in this example has 26 items, although only 4 of them have assigned values. The other items are empty. Iterating over the items of this list will access all 26 items. In some cases it may be useful to be able to access only those list items that have explicitly been assigned a value. The nextAssignedValue function does this. It works like the nextValue function, but instead of simply incrementing the currentIndex property by 1 and returning the value at that index, it advances the currentIndex to the next item in the list that has an assigned value and returns that value. So, continuing the example above:

Since both the nextValue and nextAssignedValue functions advance the currentIndex property of the list, you can mix calls to the two functions to obtain either the next sequential value of the list (whether assigned or not) or the next assigned value of the list after the current index as needed.

 

This topic was last updated on August 19, 2021, at 03:30:51 PM.

Eggplantsoftware.com | Documentation Home | User Forums | Support | Copyright © 2022 Eggplant