A collection container, or simply container, is a list of either collections or iterators. A collection container iterator (or container iterator) is an iterator over a collection container. A container iterator contains only iterators. If its container has a child that is an iterator, then the container iterator uses that child directly. If the container has a child collection, then the container iterator gets an iterator from the collection.
When next() is called on a container iterator, it calls
next() on each of its children. When does
hasNext() return false for the iterator? There are two options,
which can be set by the iterator's done policy. When the policy is
all, then false is returned only when all children return
false. When the policy is any, then false is returned when any
child returns false. The default done policy is all.
Different types of iterators can derive from container iterator, with different behaviors as described below. A function is an iterator that derives from container iterator.
A counter iterator is a container iterator that generates its first iterator until done. Then it resets it, generates the second once, and regenerates the first until done. This process continues until all iterators are done. For example, the values generated by two iterators over the list ints[0,2] would be (0,0), (0,1), (0,2), (1,0), (1,1), (1,2), (2,0), (2,1), (2,2).
A container iterator returns the values generated by its iterators. If there is only one value, it is returned as a value object as usual. If there is more than one value, they are returned in a value list. To enhance performance, creating this list can be disabled if it is not needed, and container.nextValue() returns null. Otherwise the value list contains the next value from each iterator. The order of the values in the list is the same as order of the the iterators in the container.