Java > Open Source Codes > net > sf > jga > util > Iterators


1 // ============================================================================
2 // $Id: Iterators.java,v 1.44 2006/12/05 04:48:17 davidahall Exp $
3 // Copyright (c) 2003-2005 David A. Hall
4 // ============================================================================
5 // The contents of this file are subject to the Common Development and
6 // Distribution License (CDDL), Version 1.0 (the License); you may not use this
7 // file except in compliance with the License. You should have received a copy
8 // of the the License along with this file: if not, a copy of the License is
9 // available from Sun Microsystems, Inc.
10 //
11 // http://www.sun.com/cddl/cddl.html
12 //
13 // From time to time, the license steward (initially Sun Microsystems, Inc.) may
14 // publish revised and/or new versions of the License. You may not use,
15 // distribute, or otherwise make this file available under subsequent versions
16 // of the License.
17 //
18 // Alternatively, the contents of this file may be used under the terms of the
19 // GNU Lesser General Public License Version 2.1 or later (the "LGPL"), in which
20 // case the provisions of the LGPL are applicable instead of those above. If you
21 // wish to allow use of your version of this file only under the terms of the
22 // LGPL, and not to allow others to use your version of this file under the
23 // terms of the CDDL, indicate your decision by deleting the provisions above
24 // and replace them with the notice and other provisions required by the LGPL.
25 // If you do not delete the provisions above, a recipient may use your version
26 // of this file under the terms of either the CDDL or the LGPL.
27 //
28 // This library is distributed in the hope that it will be useful,
29 // but WITHOUT ANY WARRANTY; without even the implied warranty of
30 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
31 // ============================================================================
32
33 package net.sf.jga.util;
34
35 import java.util.Collection ;
36 import java.util.Comparator ;
37 import java.util.Iterator ;
38 import net.sf.jga.algorithms.Filter;
39 import net.sf.jga.algorithms.Find;
40 import net.sf.jga.algorithms.Merge;
41 import net.sf.jga.algorithms.Summarize;
42 import net.sf.jga.algorithms.Transform;
43 import net.sf.jga.algorithms.Unique;
44 import net.sf.jga.fn.BinaryFunctor;
45 import net.sf.jga.fn.UnaryFunctor;
46 import net.sf.jga.fn.algorithm.FindMismatch;
47 import net.sf.jga.fn.algorithm.ForEach;
48 import net.sf.jga.fn.arithmetic.Arithmetic;
49 import net.sf.jga.fn.arithmetic.ArithmeticFactory;
50 import net.sf.jga.fn.arithmetic.Minus;
51 import net.sf.jga.fn.arithmetic.Plus;
52 import net.sf.jga.fn.comparison.EqualTo;
53 import net.sf.jga.fn.comparison.Equality;
54 import net.sf.jga.fn.comparison.Less;
55 import net.sf.jga.fn.comparison.NotEqualTo;
56 import net.sf.jga.fn.logical.BinaryNegate;
57 import net.sf.jga.fn.logical.UnaryNegate;
58
59 /**
60  * Facade for the Algorithms adapted from STL, defined to work primarily with
61  * iterators. These algorithms are adapted from STL, with modifications to be
62  * consistent with typical java practice. For example, typical STL algorithms
63  * are defined with pairs of iterators defining a half-open range over some
64  * implied collection. It works in C++ because the STL iterators can be
65  * compared for equality. Java iterators are not guaranteed to be comparable
66  * to each other by contract, so the same signatures wouldn't work.
67  * <p>
68  * Typically, where an STL algorithm would take a pair of iterators, this facade
69  * will take a single iterator and where an STL algorithm would return an
70  * iterator, we'll return an iterator. In this facade, the iterator returned
71  * will frequently be specialized in some way: either a ListIterator or one of
72  * the iterators defined in jga.
73  * <P>
74  * It is best to assume that all of the methods in this class may (but are not
75  * guaranteed to) advance the iterator argument. Also, once an iterator has
76  * been passed to one of the methods of this class, it should not be used
77  * again. On the other hand, unless otherwise noted, it is safe to pass the
78  * iterator returned by one of the methods in this class back to the method
79  * that returned it, or to any of the other methods.
80  * <p>
81  * Copyright &copy; 2003-2005 David A. Hall
82  *
83  * @author <a HREF="mailto:davidahall@users.sf.net">David A. Hall</a>
84  */
85
86 public class Iterators {
87
88     // ----------------------------------------------------------------------
89 // Finding algorithms
90 // ----------------------------------------------------------------------
91
92     /**
93      * Finds an arbitrary value in an iteration using the equals() method.
94      * @return an iterator based on the given iterator whose next() [if it
95      * hasNext()] will return the next instance of value in the iteration,
96      * using the equals() method of the value. If the value is not in the
97      * iteration, then the returned iterator's hasNext() will report false.
98      * @deprecated Use Find.find(Iterator, T) instead
99      */
100     static public <T> FindIterator<T> find (Iterator <? extends T> iterator, T value) {
101         return (FindIterator<T>) Find.find(iterator, value);
102     }
103
104
105     /**
106      * Finds an arbitrary value in an iteration using the given Equality
107      * operator.
108      * @return an iterator based on the given iterator whose next() [if it
109      * hasNext()] will return the next instance of value in the iteration, using
110      * the given equality operator. If the value is not in the
111      * iteration, then the returned iterator's hasNext() will report false.
112      * @deprecated Use Find.find(Iterator, T, Equality) instead
113      */
114     static public <T> FindIterator<T> find (Iterator <? extends T> iterator, T value, Equality<T> eq){
115         return (FindIterator<T>) Find.find(iterator, value, eq);
116     }
117  
118     /**
119      * Finds a value in a collection for which the given function returns TRUE.
120      * @return an iterator based on the given iterator whose next() [if it
121      * hasNext()] will return the next instance in the iteration for which the
122      * given function returns true. If the value is not in the
123      * iteration, then the returned iterator's hasNext() will report false.
124      * @deprecated Use Find.find(Iterator, BinaryFunctor) instead
125      */
126     static public <T> FindIterator<T>
127     find (Iterator <? extends T> iterator, UnaryFunctor<T,Boolean > fn)
128     {
129         return (FindIterator<T>) Find.find(iterator, fn);
130     }
131
132     // ----------------------------------------------------------------------
133 // Counting algorithms
134 // ----------------------------------------------------------------------
135
136     /**
137      * Counts the number of occurrences of value in the iteration,
138      * using the equals() method of the value.
139      * @return the number of instances found
140      * @deprecated use Summarize.count(Iterator,T) instead
141      */
142     static public <T> long count (Iterator <? extends T> iterator, T value) {
143         return Summarize.count((Iterator <T>) iterator, value);
144     }
145
146     
147     /**
148      * Counts the number of occurrences of value in the iteration, using
149      * the given equality operator.
150      * @return the number of instances found
151      * @deprecated use Summarize.count(Iterator,Equality,T) instead
152      */
153     static public <T> long count(Iterator <? extends T> iterator, Equality<T> eq, T value) {
154         return Summarize.count((Iterator <T>) iterator, eq, value);
155     }
156
157     
158     /**
159      * Counts the items in the collection for which the given function returns
160      * TRUE.
161      * @return the number of instances found
162      * @deprecated use Summarize.count(Iterator,UnaryFunctor) instead
163      */
164     static public <T> long count (Iterator <? extends T> iterator, UnaryFunctor<T,Boolean > eq) {
165         return Summarize.count((Iterator <T>) iterator, eq);
166     }
167
168     // ----------------------------------------------------------------------
169 // Adjacent Find algorithms
170 // ----------------------------------------------------------------------
171
172     /**
173      * Finds adjacent pairs of equivalent values in an iteration using the
174      * equals() method.
175      * @return an iterator based on the given iterator whose next() [if it
176      * hasNext()] will return the first of a pair of adjacent values. If no
177      * pair of values exists in the iteration, then the returned iterator's
178      * hasNext() will report false.
179      * @deprecated use Find.findAdjacent(Iterator) instead
180      */
181     static public <T> LookAheadIterator<T> findAdjacent(Iterator <? extends T> iterator) {
182         return (LookAheadIterator<T>) Find.findAdjacent(iterator);
183     }
184
185     
186     /**
187      * Finds adjacent pairs of equivalent values in an iteration for which the
188      * given function returns TRUE.
189      * @return an iterator based on the given iterator whose next() [if it
190      * hasNext()] will return the first of a pair of adjacent values. If no
191      * pair of values exists in the iteration, then the returned iterator's
192      * hasNext() will report false.
193      * @deprecated use Find.findAdjacent(Iterator,BinaryFunctor) instead
194      */
195     static public <T> LookAheadIterator<T>
196     findAdjacent(Iterator <? extends T> iterator, BinaryFunctor<T,T,Boolean > bf)
197     {
198         return (LookAheadIterator<T>) Find.findAdjacent(iterator, bf);
199     }
200
201     // ----------------------------------------------------------------------
202 // FindElement algorithms
203 // ----------------------------------------------------------------------
204
205     /**
206      * Finds any value from the given collection using the collection's contains() method.
207      * @return an iterator based on the given iterator whose next() [if it hasNext()] will return
208      * the first instance of any value found in the second collection. If no such value is found
209      * in the iteration, then the returned iterator's hasNext() will report false.
210      * @deprecated use Find.findElement(Iterator,Collection) instead
211      */
212     static public <T> FindIterator<T>
213     findElement(Iterator <? extends T> iterator, Collection <? extends T> desired)
214     {
215         return (FindIterator<T>) Find.findElement(iterator, desired);
216     }
217
218     
219     /**
220      * Finds any value from the given collection using the given functor to determine equivalence.
221      * Each item in the iteration will be compared to every item in the second collection using
222      * the given functor, stopping when the iteration is exhausted or when any pair returns TRUE.
223      * @return an iterator based on the given iterator whose next() [if it hasNext()] will return
224      * the first instance of any value in the second collection, where equivelency is determined
225      * by the given functor. If no such value is found in the iteration, then the returned iterator's
226      * hasNext() will report false.
227      * @deprecated use Find.findElement(Iterator,Collection) instead
228      */
229     static public <T> FindIterator<T>
230     findElement(Iterator <? extends T> i, Collection <? extends T> c, BinaryFunctor<T,T,Boolean > eq)
231     {
232         return (FindIterator<T>) Find.findElement(i, c,eq);
233     }
234
235     // ----------------------------------------------------------------------
236 // SequenceMatch algorithms
237 // ----------------------------------------------------------------------
238
239     /**
240      * Finds the given pattern in the iteration using the equals method.
241      * @return an iterator based on the given iterator whose next() [if it
242      * hasNext()] will return the first element of a sequence that matches
243      * the entire contents of the collection. If no such match is
244      * found in the iteration, then the returned iterator's hasNext()
245      * will report false. If the pattern is empty, then the iterator will not
246      * be advanced.
247      * @deprecated use Find.findSequence(Iterator,Collection) instead
248      */
249     static public <T> LookAheadIterator<T>
250     match(Iterator <? extends T> iterator, Collection <? extends T> pattern)
251     {
252         return (LookAheadIterator<T>) Find.findSequence(iterator, pattern);
253     }
254
255     
256     /**
257      * Finds the given pattern in the collection using the given functor
258      * to determine equivalence.
259      * @return an iterator based on the given iterator whose next() [if it
260      * hasNext()] will return the first element of a sequence that matches
261      * the entire contents of the collection. If no such match is
262      * found in the iteration, then the returned iterator's hasNext()
263      * will report false. If the pattern is empty, then the iterator will not
264      * be advanced.
265      * @deprecated use Find.findSequence(Iterator,Collection,BinaryFunctor) instead
266      */
267     static public <T> LookAheadIterator<T>
268     match(Iterator <? extends T> i, Collection <? extends T> pattern, BinaryFunctor<T,T,Boolean > eq)
269     {
270         return (LookAheadIterator<T>) Find.findSequence(i, pattern, eq);
271     }
272
273     
274     /**
275      * Finds the point at which two collections differ, using NotEqualTo.
276      * @return an iterator based on the given iterator whose next() [if it
277      * hasNext()] will return the first element in the iteration that does
278      * not equal the corresponding element in the pattern. If the pattern
279      * matches the iteration but is longer, than the returned iterator's
280      * hasNext() will report false. If the pattern is empty, then the
281      * iteration is not advanced.
282      * @deprecated use Find.findMismatch(Iterator,Collection) instead
283      */
284     static public <T> LookAheadIterator<T>
285     mismatch(Iterator <? extends T> iterator, Collection <? extends T> pattern)
286     {
287         return (LookAheadIterator<T>) Find.findMismatch(iterator, pattern);
288     }
289
290     
291     /**
292      * Finds the point at which two collections differ, using the given functor
293      * @return an iterator based on the given iterator whose next() [if it
294      * hasNext()] will return the first element in the iteration for which the
295      * given function returns TRUE when given the element and the corresponding
296      * element in the pattern. If the pattern matches the iteration but is
297      * longer, than the returned iterator's hasNext() will report false. If the
298      * pattern is empty, then the iteration is not advanced.
299      * @deprecated use Find.findMismatch(Iterator,Collection,BinaryFunctor) instead
300      */
301     static public <T> LookAheadIterator<T>
302     mismatch(Iterator <? extends T> iterator, Collection <? extends T> pattern,
303              BinaryFunctor<T, T, Boolean > neq)
304     {
305         return (LookAheadIterator<T>) Find.findMismatch(iterator, pattern, neq);
306     }
307
308     // ----------------------------------------------------------------------
309 // FindRepeated algorithms
310 // ----------------------------------------------------------------------
311
312     /**
313      * Finds arbitrary length runs of a given value in an iteration using the
314      * equals() method. Runs of length zero are well-defined: every iteration
315      * begins with a run of length zero of all possible values.
316      * @return an iterator based on the given iterator whose next() [if it
317      * hasNext()] will return the first of n adjacent instances of value. If no
318      * run of values of the requested length exist in the iteration, then the
319      * returned iterator's hasNext() will report false.
320      * @deprecated use Find.findRepeated(ITerator,int,T) instead
321      */
322     static public <T> LookAheadIterator<T>
323     findRepeated (Iterator <? extends T> iterator, int n, T value)
324     {
325         return (LookAheadIterator<T>) Find.findRepeated(iterator, n, value);
326     }
327
328     
329     /**
330      * Finds arbitrary length runs of a given value in an iteration using the
331      * given equality operator. Runs of length zero are well-defined: every
332      * iteration begins with a run of length zero of all possible values.
333      * @return an iterator based on the given iterator whose next() [if it
334      * hasNext()] will return the first of n adjacent instances of value. If no
335      * run of values of the requested length exist in the iteration, then the
336      * returned iterator's hasNext() will report false.
337      * @deprecated use Find.findRepeated(Iterator,int,T,Equality) instead
338      */
339     static public <T> LookAheadIterator<T>
340     findRepeated (Iterator <? extends T> iterator, int n, T value, Equality<T> eq)
341     {
342         return (LookAheadIterator<T>) Find.findRepeated(iterator, n, value, eq);
343     }
344
345     
346     /**
347      * Finds arbitrary length runs of a given value in an iteration for which the
348      * given function returns TRUE. Runs of length zero are well-defined: every
349      * iteration begins with a run of length zero of all possible values.
350      * @return an iterator based on the given iterator whose next() [if it
351      * hasNext()] will return the first of n adjacent instances of value. If no
352      * run of values of the requested length exist in the iteration, then the
353      * returned iterator's hasNext() will report false.
354      * @deprecated use Find.findRepeated(Iterator,int,UnaryFunctor) instead
355      */
356     static public <T> LookAheadIterator<T>
357     findRepeated (Iterator <? extends T> iterator, int n, UnaryFunctor<T,Boolean > eq)
358     {
359         return (LookAheadIterator<T>) Find.findRepeated(iterator, n, eq);
360     }
361
362     // ----------------------------------------------------------------------
363 // ForEach algorithms
364 // ----------------------------------------------------------------------
365
366     /**
367      * Applies the given UnaryFunctor to every element in the iteration, and
368      * returns the Functor. This is useful when the Functor gathers information
369      * on each successive call.
370      * @return the functor, after it has been called once for every element
371      */
372     static public <T,R> UnaryFunctor<T,R>
373     forEach(Iterator <? extends T> iterator, UnaryFunctor<T,R> fn)
374     {
375         new ForEach<T,R>(fn).fn(iterator);
376         return fn;
377     }
378
379     
380     // ----------------------------------------------------------------------
381 // Equality algorithms
382 // ----------------------------------------------------------------------
383
384     /**
385      * Returns true if the two iterations are equal, using the Comparable
386      * interface to compare elements in the iterations.
387      * @return true if the two iterations are equal
388      */
389     static public <T extends Comparable /*@*/<? super T>/*@*/> boolean
390     equal(Iterator <? extends T> iterator1, Iterator <? extends T> iterator2)
391     {
392         return equal(iterator1, iterator2, new ComparableComparator<T>());
393     }
394
395     
396     /**
397      * Returns true if the two iterations are equal, using the given Comparator
398      * to compare elements in the iterations.
399      * @return true if the two iterations are equal
400      */
401     static public <T> boolean
402     equal(Iterator <? extends T> iterator1, Iterator <? extends T> iterator2, Comparator <T> comp)
403     {
404         IteratorComparator<T> comp2 = new IteratorComparator<T>(comp);
405         EqualTo<Iterator <? extends T>> eq =
406             new EqualTo<Iterator <? extends T>>(comp2);
407         return eq.p(iterator1, iterator2);
408     }
409
410     
411     /**
412      * Returns true if the two iterations are equal, using the given
413      * BinaryFunctor to compare elements in the iterations.
414      * @return true if the two iterations are equal
415      */
416     static public <T> boolean
417     equal(Iterator <? extends T> iter1, Iterator <? extends T> iter2, BinaryFunctor<T,T,Boolean > eq)
418     {
419         while (iter1.hasNext() && iter2.hasNext()) {
420             if (!eq.fn(iter1.next(),iter2.next()).booleanValue())
421                 return false;
422         }
423
424         return iter1.hasNext() == iter2.hasNext();
425     }
426
427     
428     // ----------------------------------------------------------------------
429 // Iterator Comparison algorithms
430 // ----------------------------------------------------------------------
431
432     /**
433      * Returns true if the first iterator is lexically less than the second,
434      * using the default comparison operation to compare the elements in each
435      * iterator.
436      * @return true if the first iteration is less than the second
437      */
438     static public <T extends Comparable /*@*/<? super T>/*@*/> boolean
439     lessThan(Iterator <? extends T> iter1, Iterator <? extends T> iter2)
440     {
441         Comparator <T> comp1 = new ComparableComparator<T>();
442         IteratorComparator<T> comp2 = new IteratorComparator<T>(comp1);
443         return new Less<Iterator <? extends T>>(comp2).p(iter1, iter2);
444     }
445
446     
447     /**
448      * Returns true if the first iterator is lexically less than the second,
449      * using the given comparator to compare the elements in each iterator.
450      * @return true if the first iteration is less than the second
451      */
452     static public <T> boolean
453     lessThan(Iterator <? extends T> iter1, Iterator <? extends T> iter2, Comparator <T> comp)
454     {
455         IteratorComparator<T> comp2 = new IteratorComparator<T>(comp);
456         return new Less<Iterator <? extends T>>(comp2).p(iter1, iter2);
457     }
458
459     
460     /**
461      * Returns true if the first iterator is lexically less than the second,
462      * using the given operator to compare the elements in each iterator. The
463      * first is less than the second if it is not longer than the second and if
464      * the first corresponding element that is not equal is less.
465      * @return true if the first iteration is less than the second
466      */
467     static public <T> boolean
468     lessThan(Iterator <? extends T> i1, Iterator <? extends T> i2, final BinaryFunctor<T,T,Boolean > lt)
469     {
470         IteratorComparator<T> comp =
471             new IteratorComparator<T>(new Comparator <T>() {
472                 public int compare(T x,T y) {
473                     return lt.fn(x,y).booleanValue() ? -1 :
474                            lt.fn(y,x).booleanValue() ? 1 : 0;
475                 }
476             });
477         
478         return new Less<Iterator <? extends T>>(comp).p(i1, i2);
479     }
480
481     
482     // ----------------------------------------------------------------------
483 // Minimum/Maximum algorithms
484 // ----------------------------------------------------------------------
485
486     /**
487      * Finds the minimum value in an iteration using the natural ordering of
488      * the iterator's elements.
489      * @return the minimum value found in the iteration
490      * @deprecated use Summarize.min(Iterator)
491      */
492     static public <T extends Comparable /*@*/<? super T>/*@*/> T
493     minimumValue(Iterator <? extends T> iterator)
494     {
495         return Summarize.min(iterator);
496     }
497
498     
499     /**
500      * Finds the minimum value in an iteration using the given comparator.
501      * @return the minimum value found in the iteration
502      * @deprecated use Summarize.min(Iterator, Comparator)
503      */
504     static public <T> T minimumValue(Iterator <? extends T> iterator, Comparator <T> comp) {
505         return Summarize.min(iterator, comp);
506     }
507
508     
509     /**
510      * Finds the minimum value in an iteration using the given functor to
511      * compare elements. The functor is presumed to return the lesser of
512      * its two arguments.
513      * @return the minimum value found in the iteration
514      * @deprecated use Summarize.min(Iterator, BinaryFunctor);
515      */
516     static public <T> T minimumValue(Iterator <? extends T> iterator, BinaryFunctor<T,T,T> bf) {
517         return Summarize.min((Iterator <T>) iterator, bf);
518     }
519
520     
521     /**
522      * Finds the maximum value in an iteration using the natural ordering of
523      * the iterator's elements.
524      * @return the maximum value found in the iteration
525      * @deprecated use Summarize.max(Iterator)
526     */
527     static public <T extends Comparable /*@*/<? super T>/*@*/> T
528     maximumValue(Iterator <? extends T> iterator)
529     {
530         return Summarize.max(iterator);
531     }
532
533     
534     /**
535      * Finds the maximum value in an iteration using the given comparator.
536      * @return the maximum value found in the iteration
537      * @deprecated use Summarize.max(Iterator, Comparator)
538      */
539     static public <T> T maximumValue(Iterator <? extends T> iterator, Comparator <T> comp) {
540         return Summarize.max(iterator, comp);
541     }
542
543     
544     /**
545      * Finds the maximum value in an iteration using the given functor to
546      * compare elements. The functor is presumed to return the lesser of
547      * its two arguments.
548      * @return the maximum value found in the iteration
549      * @deprecated use Summarize.max(Iterator,BinaryFunctor)
550      */
551     static public <T> T maximumValue(Iterator <? extends T> iterator, BinaryFunctor<T,T,T> bf) {
552         return Summarize.max((Iterator <T>)iterator,bf);
553     }
554
555     // ----------------------------------------------------------------------
556 // Accumulate algorithms
557 // ----------------------------------------------------------------------
558
559     /**
560      * Adds each number in the iterator, returning the sum.
561      * @return the final sum. If the iterator is empty, then zero is
562      * returned
563      * @deprecated use Summarize.sum(Class,Iterator)
564      */
565     static public <T extends Number > T accumulate(Class <T> numtype, Iterator <T> iterator) {
566         return Summarize.sum(numtype, iterator);
567     }
568
569     
570     /**
571      * Applies the binary functor to each number in the iterator, returning
572      * the final result. Along with each number is passed the result of the
573      * previous call of the functor (or zero for the first call to the functor).
574      * The elements in the iterator are always passed in the 2nd postion.
575      * @return the final result. If the iterator is empty, then zero is
576      * returned
577      * @deprecated use Summarize.accumulate(Iterator,BinaryFunctor) or
578      * Summarize.accumulate(Iterator,T,BinaryFunctor), passing an
579      * appropriate starting value (typically 0 or 1).
580      */
581     static public <T extends Number > T
582     accumulate(Class <T> numtype, Iterator <T> iterator, BinaryFunctor<T,T,T> bf)
583     {
584          Arithmetic<T> _math = ArithmeticFactory.getArithmetic(numtype);
585          if (_math == null) {
586              throw new IllegalArgumentException ();
587          }
588         
589          return Summarize.accumulate(iterator, _math.zero(), bf);
590     }
591
592     
593     /**
594      * Applies the binary functor to each element in the iterator, returning
595      * the final result. Along with each element is passed the result of the
596      * previous call of the functor (or the initial value for the first call
597      * to the functor). The elements in the iteration are always passed in the
598      * 2nd postion.
599      * @return the final result. If the iteration is empty, then the initial
600      * value is returned
601      * @deprecated use Summarize.accumulate(Iterator,T,BinaryFunctor)
602      */
603     static public <T> T accumulate(Iterator <T> iterator, T initial, BinaryFunctor<T,T,T> bf)
604     {
605         return Summarize.accumulate(iterator, initial, bf);
606     }
607     
608     // ----------------------------------------------------------------------
609 // Transform algorithms
610 // ----------------------------------------------------------------------
611
612     /**
613      * Applies the UnaryFunctor to each element in the input, returning an
614      * iterator over the results.
615      * @return an iterator based on the given iterator that will return the
616      * results obtained when passing each element of the input iteration to the
617      * given unary functor.
618      * @deprecated the return type will be changed to Transform.TransformIterator
619      * in a future release. Use Transform.transform(Iterator,UnaryFunctor)
620      */
621     static public <T,R> TransformIterator<T,R>
622     transform(Iterator <? extends T> iter, UnaryFunctor<T,R> uf)
623     {
624         return (TransformIterator<T,R>) Transform.transform(iter, uf);
625     }
626
627     
628     /**
629      * Applies the BinaryFunctor to corresponding elements of the two input
630      * iterators, and returns an iterator over the results. The resulting
631      * iterator will have the same number of elements as the shorter of the two
632      * input iterations.
633      * @return an iterator that will return the results obtained when passing
634      * each pair of corresponding elements of the input iterations to the
635      * given binary functor.
636      * @deprecated the return type will be changed to Transform.BinaryIterator
637      * in a future release. Use Transform.transform(Iterator,Iterator,BinaryFunctor)
638      */
639     static public <T1,T2,R> TransformBinaryIterator<T1,T2,R>
640     transform(Iterator <? extends T1> i1, Iterator <? extends T2> i2, BinaryFunctor<T1,T2,R> bf)
641     {
642         return (TransformBinaryIterator<T1,T2,R>) Transform.transform(i1, i2, bf);
643     }
644     
645     // ----------------------------------------------------------------------
646 // replaceAll algorithms
647 // ----------------------------------------------------------------------
648
649     /**
650      * Tests each element in an iterator, replacing those for which the test is
651      * true with the replacement value.
652      * @deprecated use Transform.replace(Iterator, UnaryFunctor, T) instead
653      */
654     static public <T> Iterator <T>
655     replaceAll(Iterator <? extends T> iter, UnaryFunctor<T,Boolean > test, T value)
656     {
657         return Transform.replace((Iterator <T>) iter, test, value);
658     }
659
660
661     // ----------------------------------------------------------------------
662 // Filtering algorithms
663 // ----------------------------------------------------------------------
664
665     /**
666      * Filters an arbitrary value from an iteration using the equals() method.
667      * @return an iterator based on the given iterator that will return not
668      * include elements equal to the given value
669      * @deprecated the return type will be changed to Filter.FilterIterator in
670      * a future release. Use Filter.removeAll(Iterator,T)
671      */
672     static public <T> FilterIterator<T>
673     removeAll (Iterator <? extends T> iterator, T value)
674     {
675         return (FilterIterator<T>) Filter.remove(iterator, value);
676     }
677
678     
679     /**
680      * Filters an arbitrary value from an iteration using the given Equality
681      * operator.
682      * @return an iterator based on the given iterator that will not include
683      * elements that are equal to the value using the given Equality
684      * @deprecated the return type will be changed to Filter.FilterIterator in
685      * a future release. Use Filter.removeAll(Iterator,T,Equality)
686      */
687     static public <T> FilterIterator<T>
688     removeAll (Iterator <? extends T> iterator, T value, Equality<T> eq)
689     {
690         return (FilterIterator<T>) Filter.remove(iterator, value, eq);
691     }
692
693     
694     /**
695      * Filters values from an iteration for which the given function returns
696      * TRUE.
697      * @return an iterator based on the given iterator that will not include
698      * elements that pass the given test.
699      * @deprecated the return type will be changed to Filter.FilterIterator in
700      * a future release. Use Filter.removeAll(Iterator,UnaryFunctor)
701      */
702     static public <T> FilterIterator<T>
703     removeAll (Iterator <? extends T> iterator, UnaryFunctor<T,Boolean > eq)
704     {
705         return (FilterIterator<T>) Filter.remove(iterator, eq);
706     }
707
708     // ----------------------------------------------------------------------
709 // unique algorithms
710 // ----------------------------------------------------------------------
711
712     /**
713      * Skips duplicate values in the given iteration.
714      * @return an iterator based on the given iterator that will not return the
715      * same element twice in succession
716      * @deprecated in the next release, the return type will change to Unique.UniqueIterator.
717      * Use Unique.unique(Iterator)
718      */
719     static public <T> UniqueIterator<T> unique(Iterator <? extends T> iterator) {
720         return (UniqueIterator<T>) Unique.unique(iterator);
721     }
722
723     
724     /**
725      * Skips duplicate values in the given iteration.
726      * @return an iterator based on the given iterator that will not return the
727      * same element twice in succession, using the given functor to compare
728      * elements
729      * @deprecated in the next release, the return type will change to Unique.UniqueIterator.
730      * Use Unique.unique(Iterator,BinaryFunctor)
731      */
732     static public <T> UniqueIterator<T>
733     unique(Iterator <? extends T> iterator, BinaryFunctor<T,T,Boolean > eq)
734     {
735         return (UniqueIterator<T>) Unique.unique(iterator, eq);
736     }
737     
738     // ----------------------------------------------------------------------
739 // merge algorithms
740 // ----------------------------------------------------------------------
741
742     /**
743      * Merges two iterations together. Walks both iterators, choosing the
744      * lesser of the two current values.
745      * @return an iterator based on the two input iterators that contains their
746      * merged contents
747      * @deprecated in a future release, the return type will change to Merge.MergeIterator.
748      * Use Merge.merge(Iterator,Iterator)
749      */
750     static public <T extends Comparable /*@*/<? super T>/*@*/> MergeIterator<T>
751     merge (Iterator <? extends T> iter1, Iterator <? extends T> iter2)
752     {
753         return (MergeIterator<T>) Merge.merge(iter1, iter2);
754     }
755
756     
757     /**
758      * Merges two iterations together using the given comparator. Walks both
759      * iterators, choosing the lesser of the two current values.
760      * @return an iterator based on the two input iterators that contains their
761      * merged contents
762      * @deprecated in a future release, the return type will change to Merge.MergeIterator.
763      * Use Merge.merge(Iterator,Iterator,Comparator) instead
764      */
765     static public <T> MergeIterator<T>
766     merge (Iterator <? extends T> iter1, Iterator <? extends T> iter2, Comparator <T> comp)
767     {
768         return (MergeIterator<T>) Merge.merge(iter1, iter2, comp);
769     }
770     
771     // ----------------------------------------------------------------------
772 // adjacent diff algorithms
773 // ----------------------------------------------------------------------
774
775     /**
776      * @return an iterator containing the arithemetic difference between succesive
777      * pairs of numbers
778      * @deprecated in a future release, the return type will change to
779      * Transform.AdjacentIterator. use Transform.transform(Iterator,new Minus(type)),
780      */
781
782     static public <T extends Number > TransformAdjacentIterator<T,T>
783     adjacentDiff(Class <T> type, Iterator <? extends T> iter)
784     {
785         return (TransformAdjacentIterator<T,T>) Transform.transform(iter, new Minus<T>(type));
786     }
787 }
788

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags