uk.co.jezuk.mango
Class Iterators

java.lang.Object
  uk.co.jezuk.mango.Iterators

public class Iterators
extends java.lang.Object

The Mango Library Iterators

Author:

Jez Higgins, jez@jezuk.co.uk

Method Summary

static <T> java.util.Iterator<T>	ArrayIterator(T[] array) Iterates over an array of objects.
static <T> java.util.Iterator<T>	BoundedIterator(java.util.Iterator<? extends T> iterator, int start, int end) A BoundedIterator enumerates of a subset of a collection, in the range [start, end).
static <T> java.util.Iterator<T>	BoundedIterator(java.util.List<? extends T> list, int start, int end)
static <T> java.util.Iterator<T>	ChainIterator(java.lang.Object... iterables) ChainIterator creates an iterator which will traverse each of the iterables in turn.
static <T> java.util.Iterator<T>	GeneratorIterator(Generator<? extends T> generator) GeneratorIterator puts an iterator face onto a Generator object.
static <T> java.util.Iterator<T>	NullIterator() A NullIterator iterates over nothing.
static <T> java.util.Iterator<T>	ReverseIterator(java.util.List<? extends T> list) A ReverseIterator traverses a list from the end to the beginning, rather than the conventional beginning to end traversal your normal every day iterator performs.
static <T> java.util.Iterator<T>	SelectingIterator(java.util.Iterator<T> iterator, Predicate<? super T> predicate) A SelectingIterator enumerates only those elements of a collection that match the supplied Predicate.
static <T> java.util.Iterator<T>	SingletonIterator(T object) Iterates over a single object.
static <T> java.util.Iterator<T>	SkippingIterator(java.util.Iterator<T> iterator, Predicate<? super T> predicate) A SkippingIterator enumerates a sequence, stepping over the elements that match the supplied Predicate.
static java.util.Iterator<java.lang.String>	StringIterator(java.lang.String s) A StringIterator iterators over a String, returning each character in turn as a String of length 1.
static <T> java.util.List<java.util.Iterator<T>>	TeeIterator(java.util.Iterator<T> iterator, int count) TeeIterator creates any number of copies of an iterator, each of which can be iterated seperately.
static <T,R> java.util.Iterator<R>	TransformIterator(java.util.Iterator<T> iterator, Function<? super T,R> transform) A TransfromIterator applies a Function to each element in the sequence, returning the the function result at each step.
static <T> java.util.Iterator<java.util.List<T>>	ZipIterator(java.lang.Object... iterables)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

StringIterator

public static java.util.Iterator<java.lang.String> StringIterator(java.lang.String s)

A StringIterator iterators over a String, returning each character in turn as a String of length 1. e.g. StringIterator("123") will return "1", "2", "3"

NullIterator

public static <T> java.util.Iterator<T> NullIterator()

A NullIterator iterates over nothing. That is, hasNext always returns false.

BoundedIterator

public static <T> java.util.Iterator<T> BoundedIterator(java.util.Iterator<? extends T> iterator,
                                                        int start,
                                                        int end)

A BoundedIterator enumerates of a subset of a collection, in the range [start, end).

A conventional 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 Iterator traverses [0, collection.size()). A BoundedIterator therefore allows you to pick out a sub-set without using list.subList() or equivalent.

BoundedIterator

public static <T> java.util.Iterator<T> BoundedIterator(java.util.List<? extends T> list,
                                                        int start,
                                                        int end)

SelectingIterator

public static <T> java.util.Iterator<T> SelectingIterator(java.util.Iterator<T> iterator,
                                                          Predicate<? super T> predicate)

A SelectingIterator enumerates only those elements of a collection that match the supplied Predicate.

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're only interested in those that begin with 'S'. What you need is

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

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

SkippingIterator

public static <T> java.util.Iterator<T> SkippingIterator(java.util.Iterator<T> iterator,
                                                         Predicate<? super T> predicate)

A SkippingIterator enumerates a sequence, stepping over the elements that match the supplied Predicate.

Is it equivalent to SelectingIterator(iter, Not(predicate))

See Also:

SelectingIterator(java.util.Iterator, uk.co.jezuk.mango.Predicate)

ArrayIterator

public static <T> java.util.Iterator<T> ArrayIterator(T[] array)

Iterates over an array of objects.

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

SingletonIterator

public static <T> java.util.Iterator<T> SingletonIterator(T object)

Iterates over a single object.

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 Iterator interface, it provides a convienent way of passing a single object to an algorithm or other iterator consumer.

TransformIterator

public static <T,R> java.util.Iterator<R> TransformIterator(java.util.Iterator<T> iterator,
                                                            Function<? super T,R> transform)

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

Say you have a list of some complex type, and you want to find on by name. You could (caution! trivial example follows)

     Iterator i = list.iterator();
     while(i.hasNext()) {
       MyComplexObject mco = (MyComplexObject)i.next();
       if(mco.GetName().equals(theSearchName)) 
         .. do something
     }
     // did I find it or not - do the right thing here
     

or you could

     MyComplexObject mco = (MyComplexObject)Algorithms.find(
                                Iterators.TransformIterator(list.iterator(), 
                                                        Adapt.ArgumentMethod("GetName"),
                                theSearchName);
     if(mco != null) 
       ... found!
     else 
       ...
     

ReverseIterator

public static <T> java.util.Iterator<T> ReverseIterator(java.util.List<? extends T> list)

A ReverseIterator traverses a list from the end to the beginning, rather than the conventional beginning to end traversal your normal every day iterator performs.

ChainIterator

public static <T> java.util.Iterator<T> ChainIterator(java.lang.Object... iterables)

ChainIterator creates an iterator which will traverse each of the iterables in turn. When one is 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.

ZipIterator

public static <T> java.util.Iterator<java.util.List<T>> ZipIterator(java.lang.Object... iterables)

TeeIterator

public static <T> java.util.List<java.util.Iterator<T>> TeeIterator(java.util.Iterator<T> iterator,
                                                                    int count)

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.

GeneratorIterator

public static <T> java.util.Iterator<T> GeneratorIterator(Generator<? extends T> generator)

GeneratorIterator puts an iterator face onto a Generator object.