Mango provides twelve new iterators

All the iterators implement java.util.Iterator. They are all constructed using factory static methods on the Iterators class.

Array Iterator

An Array Iterator puts a java.util.Iterator face on an object array, allowing it be treated as you would a java.util.Collection.

[Javadoc]

Bounded Iterator

A conventional java.util.Iterator, obtained by a call to say java.util.List.iterator(), travels the entire sequence of the java.util.Collection it points to. It starts at the beginning and keeps on going until you hit the end or get bored.

A BoundedIterator enumerates of a subset of a collection, in the range [start, end) - a normal java.util.Iterator traverses [0, collection.size()). A BoundedIterator therefore allows you to pick out a sub-set without using list.subList() or equivalent.

A BoundedIterator implements the java.util.Iterator interface, and can be constructed by wrapping around an existing iterator. There's also a version which is optimized for java.util.Lists.

[Javadoc]

Chain Iterator

A ChainIterator creates an Iterator which will traverse each of any number of iterables in turn. When all the elements of one are exhausted it moves to the next, and so on, until all are exhausted. The ChainIterator can operate over other iterators, lists, arrays, individual objects, or any combination thereof. It allows you to treat a number of sequences as a single sequence.

Null Iterator

The Null Object pattern in iterator form, the Null Iterator operators over a null sequence. In reality this means its hasNext method always returns false.

Reverse Iterator

Operates over a List, returning the last element and proceeding to the first. While a java.util.ListIterator does provide this facility, its hasPrevious/previous call sequence is obviously not interoperable with your everyday java.util.Iterator. The Reverse Iterator is.

Selecting Iterator

A SelectingIterator picks out selected elements from a sequence. It takes a Predicate which encapsulates some test, and only returns those Objects in the sequence which pass the test.

Say you have a list of strings, myStringList and you are only interested in those that begin with 'S'. What you need is

Iterator<String> iter = Mango.SelectingIterator(myStringList.iterator(), 
                                       new Predicate<String>() {
                                           boolean test(String s) {
                                             return s.charAt(0) == 'S';
                                           }
                                       });

A SelectingIterator implements the java.util.Iterator interface, and is constructed by wrapping around an existing iterator.

[Javadoc]

Singleton Iterator

Usually an iterator moves over some sequence. A SingletonIterator treats a single object as it if it were a list containing one object. Since SingletonIterator implements the java.util.Iterator interface, it provides a convenient way of passing a single object to an algorithm or other iterator consumer.

[Javadoc]

Skipping Iterator

A SkippingIterator enumerates a sequence, stepping over the elements that match the supplied Predicate. Is it equivalent to SelectingIterator(iter, Not(predicate))

[Javadoc]

String Iterator

Iterates over a String, returning each character in turn.

Tee Iterator

TeeIterator creates any number of copies of an iterator, each of which can be iterated seperately. The source iterator does not have to modified at all, nor does it have to be cloneable. The TeeIterator will buffer as necessary so may require significant additional memory.

Transform Iterator

A TransformIterator applies a UnaryFunction to each element in the sequence, returning the function result at each step.

Say you have a list of some complex type, and you want to print their names You could (caution! trivial example follows)

     Iterator i = list.iterator();
     while(i.hasNext()) {
       MyComplexObject mco = (MyComplexObject)i.next();
       System.out.println(mco.getName());
     }
or you could
     Iterator i = Iterators.TransformIterator(list.iterator(), 
                                        Adapt.ArgumentMethod("GetName"));
     while(i.hasNext()) 
         System.out.println(i.next());

[Javadoc]

Zip Iterator

A ZipIterator gather elements from any number of other iterables. It advances each of the iterable sequences in lock-stop. The iteration ends as soon as any of the sequences is exhausted.


Jez Higgins