KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > uk > co > jezuk > mango > Iterators


1 package uk.co.jezuk.mango;
2
3 import uk.co.jezuk.mango.iterators.*;
4
5 /**
6  * The Mango Library Iterator classes.
7  *
8  * @author Jez Higgins, jez@jezuk.co.uk
9  * @version $Id: Iterators.java 105 2006-09-20 15:52:01Z jez $
10  */
11 public class Iterators
12 {
13   /**
14    * A <code>StringIterator</code> iterators over a String, returning each character in turn as a <code>String</code> of length 1.
15      * e.g. StringIterator("123") will return "1", "2", "3"
16    */
17     static public java.util.Iterator JavaDoc StringIterator(String JavaDoc s) { return new uk.co.jezuk.mango.iterators.StringIterator(s); }
18
19   /**
20    * A <code>NullIterator</code> iterates over nothing. That is, <code>hasNext</code>
21    * always returns <code>false</code>.
22    */
23   static public java.util.Iterator JavaDoc NullIterator() { return new uk.co.jezuk.mango.iterators.NullIterator(); }
24   
25   /**
26    * A <code>BoundedIterator</code> enumerates of a subset of a collection, in the
27    * range [<code>start</code>, <code>end</code>).
28    * <p>
29    * A conventional <code>java.util.Iterator</code>, obtained by a call to say
30    * <code>java.util.List.iterator()</code>, travels the entire sequence of the
31    * <code>java.util.Collection</code> it points to. It starts at the beginning
32    * and keeps on going until you hit the end or get bored.
33    * <p>
34    * A BoundedIterator enumerates of a subset of a collection, in the range [start, end) -
35    * a normal <code>java.util.Iterator</code> traverses [0, collection.size()). A
36    * <code>BoundedIterator</code> therefore allows you to pick out a sub-set without
37    * using <code>list.subList()</code> or equivalent.
38    */
39   static public java.util.Iterator JavaDoc BoundedIterator(java.util.Iterator JavaDoc iterator, int start, int end) { return new BoundedIterator(iterator, start, end); }
40   static public java.util.Iterator JavaDoc BoundedIterator(java.util.List JavaDoc list, int start, int end) { return new BoundedIterator(list, start, end); }
41
42   /**
43    * @deprecated see {@link #SelectingIterator}
44    */
45   static public java.util.Iterator JavaDoc PredicatedIterator(java.util.Iterator JavaDoc iterator, Predicate predicate) { return SelectingIterator(iterator, predicate); }
46
47   /**
48    * A <code>SelectingIterator</code> enumerates only those elements of a collection
49    * that match the supplied <code>Predicate</code>.
50    * <p>
51    * It takes a {@link Predicate} which encapsulates some test, and only
52    * returns those Objects in the sequence which pass the test.
53    * <p>
54    * Say you have a list of <code>String</code>s, myStringList and you're only
55    * interested in those that begin with 'S'. What you need is
56    *
57    * <pre>
58 Iterator iter = Iterators.SelectingIterator(myStringList.iterator(),
59                                        new {@link Predicate}() {
60                                            boolean test(Object o) {
61                                              String s = (String)o;
62                                              return s.charAt(0) == 'S';
63                                            }
64                                        });</pre>
65    * <p>
66    * A <code>SelectingIterator</code> implements the <code>java.util.Iterator</code> interface,
67    * and is constructed by wrapping around an existing iterator.
68    */
69   static public java.util.Iterator JavaDoc SelectingIterator(java.util.Iterator JavaDoc iterator, Predicate predicate) { return new SelectingIterator(iterator, predicate); }
70
71   /**
72    * A <code>SkippingIterator</code> enumerates a sequence,
73    * stepping over the elements
74    * that match the supplied <code>Predicate</code>.
75    * <p>
76    * Is it equivalent to <code>SelectingIterator(iter, Not(predicate))</code>
77    *
78    * @see #SelectingIterator
79    */
80   static public java.util.Iterator JavaDoc SkippingIterator(java.util.Iterator JavaDoc iterator, Predicate predicate) { return new SkippingIterator(iterator, predicate); }
81
82   /**
83    * Iterates over an array of objects.
84    * <p>
85    * An <code>ArrayIterator</code> puts a <code>java.util.Iterator</code> face on an
86    * object array, allowing it be treated as you would a <code>java.util.Collection.</code>
87    */
88   static public java.util.Iterator JavaDoc ArrayIterator(Object JavaDoc[] array) { return new ArrayIterator(array); }
89
90   /**
91    * Iterates over a single object.
92    * <p>
93    * Usually an iterator moves over some sequence. A <code>SingletonIterator</code> treats a
94    * single object as it if it were a list containing one object. Since <code>SingletonIterator</code>
95    * implements the <code>java.util.Iterator</code> interface, it provides a convienent way of
96    * passing a single object to an algorithm or other iterator consumer.
97    */
98   static public java.util.Iterator JavaDoc SingletonIterator(Object JavaDoc object) { return new SingletonIterator(object); }
99
100   /**
101    * A <code>TransfromIterator</code> applies a <code>{@link UnaryFunction}</code> to
102    * each element in the sequence, returning the the function result at each step.
103    * <p>
104    * Say you have a list of some complex type, and you want to find on by name.
105    * You could (caution! trivial example follows)
106    * <pre>
107      Iterator i = list.iterator();
108      while(i.hasNext()) {
109        MyComplexObject mco = (MyComplexObject)i.next();
110        if(mco.GetName().equals(theSearchName))
111          .. do something
112      }
113      // did I find it or not - do the right thing here
114      </pre>
115    * or you could
116    * <pre>
117      MyComplexObject mco = (MyComplexObject)Algorithms.find(
118                                 Iterators.TransformIterator(list.iterator(),
119                                                         Adapt.ArgumentMethod("GetName"),
120                                 theSearchName);
121      if(mco != null)
122        ... found!
123      else
124        ...
125      </pre>
126    */
127   static public java.util.Iterator JavaDoc TransformIterator(java.util.Iterator JavaDoc iterator, UnaryFunction transform) { return new TransformIterator(iterator, transform); }
128
129   //////////////////////////////////
130 private Iterators() { }
131 } // Iterator
132
Popular Tags