uk.co.jezuk.mango
Class Iterators

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

public class Iterators

extends java.lang.Object

The Mango Library Iterator classes.

Version:

$Id: Iterators.java 118 2007-03-16 21:35:32Z jez $

Author:

Jez Higgins, jez@jezuk.co.uk

Method Summary

static java.util.Iterator	ArrayIterator(java.lang.Object[] array) Iterates over an array of objects.
static java.util.Iterator	BoundedIterator(java.util.Iterator iterator, int start, int end) A BoundedIterator enumerates of a subset of a collection, in the range [start, end).
static java.util.Iterator	BoundedIterator(java.util.List list, int start, int end)
static java.util.Iterator	NullIterator() A NullIterator iterates over nothing.
static java.util.Iterator	PredicatedIterator(java.util.Iterator iterator, Predicate predicate) Deprecated. see SelectingIterator(java.util.Iterator, uk.co.jezuk.mango.Predicate)
static java.util.Iterator	ReverseIterator(java.util.List 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 java.util.Iterator	SelectingIterator(java.util.Iterator iterator, Predicate predicate) A SelectingIterator enumerates only those elements of a collection that match the supplied Predicate.
static java.util.Iterator	SingletonIterator(java.lang.Object object) Iterates over a single object.
static java.util.Iterator	SkippingIterator(java.util.Iterator iterator, Predicate predicate) A SkippingIterator enumerates a sequence, stepping over the elements that match the supplied Predicate.
static java.util.Iterator	StringIterator(java.lang.String s) A StringIterator iterators over a String, returning each character in turn as a String of length 1.
static java.util.Iterator	TransformIterator(java.util.Iterator iterator, UnaryFunction transform) A TransfromIterator applies a UnaryFunction to each element in the sequence, returning the the function result at each step.

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 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 java.util.Iterator NullIterator()

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

BoundedIterator

public static java.util.Iterator BoundedIterator(java.util.Iterator iterator,
                                                 int start,
                                                 int end)

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

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.

BoundedIterator

public static java.util.Iterator BoundedIterator(java.util.List list,
                                                 int start,
                                                 int end)

PredicatedIterator

public static java.util.Iterator PredicatedIterator(java.util.Iterator iterator,
                                                    Predicate predicate)

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

SelectingIterator

public static java.util.Iterator SelectingIterator(java.util.Iterator iterator,
                                                   Predicate 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 java.util.Iterator interface, and is constructed by wrapping around an existing iterator.

SkippingIterator

public static java.util.Iterator SkippingIterator(java.util.Iterator iterator,
                                                  Predicate 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 java.util.Iterator ArrayIterator(java.lang.Object[] array)

Iterates over an array of objects.

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

SingletonIterator

public static java.util.Iterator SingletonIterator(java.lang.Object 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 java.util.Iterator interface, it provides a convienent way of passing a single object to an algorithm or other iterator consumer.

TransformIterator

public static java.util.Iterator TransformIterator(java.util.Iterator iterator,
                                                   UnaryFunction transform)

A TransfromIterator applies a UnaryFunction 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 java.util.Iterator ReverseIterator(java.util.List 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.