Iterator

An iterator can be obtained from Enumerable:ITERATOR as well as from other places. An ITERATOR is a generic computer programming concept. In the general case it’s a variable type that allows you to get the value at a position in some collection, as well as increment to the next item in the collection in order to operate on all objects in the collection one at a time. In kOS it operates on Lists and most other collection types.

A loop using an Iterator on a List might look like this:

// Starting with a list that was built like this
SET MyList To LIST( "Hello", "Aloha", "Bonjour").

// It could be looped over like this
SET MyCurrent TO MyList:ITERATOR.
PRINT "before the first NEXT, position = " + MyCurrent:INDEX.
UNTIL NOT MyCurrent:NEXT {
    PRINT "Item at position " + MyCurrent:INDEX + " is [" + MyCurrent:VALUE + "].".
}

Which would result in this output:

before the first NEXT, position = -1.
Item at position 0 is [Hello].
Item at position 1 is [Aloha].
Item at position 2 is [Bonjour].

When you first create an iterator by using an ITERATOR suffix of some collection type like List, List, or even String, the initial position of the index is always -1, and the current value is always invalid. This represents a position just before the start of the list of items. Only after the first time NEXT is called does the value of VALUE become usable as the first thing in the collection.

If you want to restart an iteration you must call the :ITERATOR suffix of the collection again to obtain a new iterator. Older versions of kOS had a :RESET suffix but it was removed as it could not be supported on all types.

Members

structure Iterator
Members

Suffix

Type

Description

RESET

n/a

(This method has been removed)

NEXT

Boolean

Move iterator to the next item

ATEND

Boolean

Check if iterator is at the end of the list

INDEX

Scalar

Current index starting from zero

VALUE

varies

The object currently being pointed to

Iterator:RESET()
Returns

n/a

This suffix has been deleted from kOS.

Iterator:NEXT()
Returns

Boolean

Call this to move the iterator to the next item in the list. Returns true if there is such an item, or false if no such item exists because it’s already at the end of the list.

Iterator:ATEND
Access

Get only

Type

Boolean

Returns true if the iterator is at the end of the list and therefore cannot be “NEXTed”, false otherwise.

Iterator:INDEX
Access

Get only

Type

Scalar (integer)

Returns the numerical index of how far you are into the list, starting the counting at 0 for the first item in the list. The last item in the list is numbered N-1, where N is the number of items in the list.

Note

If you have just created the ITERATOR, then the value of Iterator:INDEX is -1. It only becomes 0 after the first call to Iterator:NEXT.

Iterator:VALUE
Access

Get only

Type

varies

Returns the thing stored at the current position in the list.