001: // ============================================================================
002: // $Id: Iterators.java,v 1.44 2006/12/05 04:48:17 davidahall Exp $
003: // Copyright (c) 2003-2005 David A. Hall
004: // ============================================================================
005: // The contents of this file are subject to the Common Development and
006: // Distribution License (CDDL), Version 1.0 (the License); you may not use this
007: // file except in compliance with the License. You should have received a copy
008: // of the the License along with this file: if not, a copy of the License is
009: // available from Sun Microsystems, Inc.
010: //
011: // http://www.sun.com/cddl/cddl.html
012: //
013: // From time to time, the license steward (initially Sun Microsystems, Inc.) may
014: // publish revised and/or new versions of the License. You may not use,
015: // distribute, or otherwise make this file available under subsequent versions
016: // of the License.
017: //
018: // Alternatively, the contents of this file may be used under the terms of the
019: // GNU Lesser General Public License Version 2.1 or later (the "LGPL"), in which
020: // case the provisions of the LGPL are applicable instead of those above. If you
021: // wish to allow use of your version of this file only under the terms of the
022: // LGPL, and not to allow others to use your version of this file under the
023: // terms of the CDDL, indicate your decision by deleting the provisions above
024: // and replace them with the notice and other provisions required by the LGPL.
025: // If you do not delete the provisions above, a recipient may use your version
026: // of this file under the terms of either the CDDL or the LGPL.
027: //
028: // This library is distributed in the hope that it will be useful,
029: // but WITHOUT ANY WARRANTY; without even the implied warranty of
030: // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
031: // ============================================================================
032:
033: package net.sf.jga.util;
034:
035: import java.util.Collection;
036: import java.util.Comparator;
037: import java.util.Iterator;
038: import net.sf.jga.algorithms.Filter;
039: import net.sf.jga.algorithms.Find;
040: import net.sf.jga.algorithms.Merge;
041: import net.sf.jga.algorithms.Summarize;
042: import net.sf.jga.algorithms.Transform;
043: import net.sf.jga.algorithms.Unique;
044: import net.sf.jga.fn.BinaryFunctor;
045: import net.sf.jga.fn.UnaryFunctor;
046: import net.sf.jga.fn.algorithm.FindMismatch;
047: import net.sf.jga.fn.algorithm.ForEach;
048: import net.sf.jga.fn.arithmetic.Arithmetic;
049: import net.sf.jga.fn.arithmetic.ArithmeticFactory;
050: import net.sf.jga.fn.arithmetic.Minus;
051: import net.sf.jga.fn.arithmetic.Plus;
052: import net.sf.jga.fn.comparison.EqualTo;
053: import net.sf.jga.fn.comparison.Equality;
054: import net.sf.jga.fn.comparison.Less;
055: import net.sf.jga.fn.comparison.NotEqualTo;
056: import net.sf.jga.fn.logical.BinaryNegate;
057: import net.sf.jga.fn.logical.UnaryNegate;
058:
059: /**
060: * Facade for the Algorithms adapted from STL, defined to work primarily with
061: * iterators. These algorithms are adapted from STL, with modifications to be
062: * consistent with typical java practice. For example, typical STL algorithms
063: * are defined with pairs of iterators defining a half-open range over some
064: * implied collection. It works in C++ because the STL iterators can be
065: * compared for equality. Java iterators are not guaranteed to be comparable
066: * to each other by contract, so the same signatures wouldn't work.
067: * <p>
068: * Typically, where an STL algorithm would take a pair of iterators, this facade
069: * will take a single iterator and where an STL algorithm would return an
070: * iterator, we'll return an iterator. In this facade, the iterator returned
071: * will frequently be specialized in some way: either a ListIterator or one of
072: * the iterators defined in jga.
073: * <P>
074: * It is best to assume that all of the methods in this class may (but are not
075: * guaranteed to) advance the iterator argument. Also, once an iterator has
076: * been passed to one of the methods of this class, it should not be used
077: * again. On the other hand, unless otherwise noted, it is safe to pass the
078: * iterator returned by one of the methods in this class back to the method
079: * that returned it, or to any of the other methods.
080: * <p>
081: * Copyright © 2003-2005 David A. Hall
082: *
083: * @author <a href="mailto:davidahall@users.sf.net">David A. Hall</a>
084: */
085:
086: public class Iterators {
087:
088: // ----------------------------------------------------------------------
089: // Finding algorithms
090: // ----------------------------------------------------------------------
091:
092: /**
093: * Finds an arbitrary value in an iteration using the equals() method.
094: * @return an iterator based on the given iterator whose next() [if it
095: * hasNext()] will return the next instance of value in the iteration,
096: * using the equals() method of the value. If the value is not in the
097: * iteration, then the returned iterator's hasNext() will report false.
098: * @deprecated Use Find.find(Iterator, T) instead
099: */
100: static public <T> FindIterator<T> find(
101: Iterator<? extends T> iterator, T value) {
102: return (FindIterator<T>) Find.find(iterator, value);
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(
115: Iterator<? extends T> iterator, T value, Equality<T> eq) {
116: return (FindIterator<T>) Find.find(iterator, value, eq);
117: }
118:
119: /**
120: * Finds a value in a collection for which the given function returns TRUE.
121: * @return an iterator based on the given iterator whose next() [if it
122: * hasNext()] will return the next instance in the iteration for which the
123: * given function returns true. If the value is not in the
124: * iteration, then the returned iterator's hasNext() will report false.
125: * @deprecated Use Find.find(Iterator, BinaryFunctor) instead
126: */
127: static public <T> FindIterator<T> find(
128: Iterator<? extends T> iterator, UnaryFunctor<T, Boolean> fn) {
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: * Counts the number of occurrences of value in the iteration, using
148: * the given equality operator.
149: * @return the number of instances found
150: * @deprecated use Summarize.count(Iterator,Equality,T) instead
151: */
152: static public <T> long count(Iterator<? extends T> iterator,
153: Equality<T> eq, T value) {
154: return Summarize.count((Iterator<T>) iterator, eq, value);
155: }
156:
157: /**
158: * Counts the items in the collection for which the given function returns
159: * TRUE.
160: * @return the number of instances found
161: * @deprecated use Summarize.count(Iterator,UnaryFunctor) instead
162: */
163: static public <T> long count(Iterator<? extends T> iterator,
164: 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(
182: Iterator<? extends T> iterator) {
183: return (LookAheadIterator<T>) Find.findAdjacent(iterator);
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> findAdjacent(
196: Iterator<? extends T> iterator,
197: BinaryFunctor<T, T, Boolean> bf) {
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> findElement(
213: Iterator<? extends T> iterator,
214: Collection<? extends T> desired) {
215: return (FindIterator<T>) Find.findElement(iterator, desired);
216: }
217:
218: /**
219: * Finds any value from the given collection using the given functor to determine equivalence.
220: * Each item in the iteration will be compared to every item in the second collection using
221: * the given functor, stopping when the iteration is exhausted or when any pair returns TRUE.
222: * @return an iterator based on the given iterator whose next() [if it hasNext()] will return
223: * the first instance of any value in the second collection, where equivelency is determined
224: * by the given functor. If no such value is found in the iteration, then the returned iterator's
225: * hasNext() will report false.
226: * @deprecated use Find.findElement(Iterator,Collection) instead
227: */
228: static public <T> FindIterator<T> findElement(
229: Iterator<? extends T> i, Collection<? extends T> c,
230: BinaryFunctor<T, T, Boolean> eq) {
231: return (FindIterator<T>) Find.findElement(i, c, eq);
232: }
233:
234: // ----------------------------------------------------------------------
235: // SequenceMatch algorithms
236: // ----------------------------------------------------------------------
237:
238: /**
239: * Finds the given pattern in the iteration using the equals method.
240: * @return an iterator based on the given iterator whose next() [if it
241: * hasNext()] will return the first element of a sequence that matches
242: * the entire contents of the collection. If no such match is
243: * found in the iteration, then the returned iterator's hasNext()
244: * will report false. If the pattern is empty, then the iterator will not
245: * be advanced.
246: * @deprecated use Find.findSequence(Iterator,Collection) instead
247: */
248: static public <T> LookAheadIterator<T> match(
249: Iterator<? extends T> iterator,
250: Collection<? extends T> pattern) {
251: return (LookAheadIterator<T>) Find.findSequence(iterator,
252: pattern);
253: }
254:
255: /**
256: * Finds the given pattern in the collection using the given functor
257: * to determine equivalence.
258: * @return an iterator based on the given iterator whose next() [if it
259: * hasNext()] will return the first element of a sequence that matches
260: * the entire contents of the collection. If no such match is
261: * found in the iteration, then the returned iterator's hasNext()
262: * will report false. If the pattern is empty, then the iterator will not
263: * be advanced.
264: * @deprecated use Find.findSequence(Iterator,Collection,BinaryFunctor) instead
265: */
266: static public <T> LookAheadIterator<T> match(
267: Iterator<? extends T> i, Collection<? extends T> pattern,
268: BinaryFunctor<T, T, Boolean> eq) {
269: return (LookAheadIterator<T>) Find.findSequence(i, pattern, eq);
270: }
271:
272: /**
273: * Finds the point at which two collections differ, using NotEqualTo.
274: * @return an iterator based on the given iterator whose next() [if it
275: * hasNext()] will return the first element in the iteration that does
276: * not equal the corresponding element in the pattern. If the pattern
277: * matches the iteration but is longer, than the returned iterator's
278: * hasNext() will report false. If the pattern is empty, then the
279: * iteration is not advanced.
280: * @deprecated use Find.findMismatch(Iterator,Collection) instead
281: */
282: static public <T> LookAheadIterator<T> mismatch(
283: Iterator<? extends T> iterator,
284: Collection<? extends T> pattern) {
285: return (LookAheadIterator<T>) Find.findMismatch(iterator,
286: pattern);
287: }
288:
289: /**
290: * Finds the point at which two collections differ, using the given functor
291: * @return an iterator based on the given iterator whose next() [if it
292: * hasNext()] will return the first element in the iteration for which the
293: * given function returns TRUE when given the element and the corresponding
294: * element in the pattern. If the pattern matches the iteration but is
295: * longer, than the returned iterator's hasNext() will report false. If the
296: * pattern is empty, then the iteration is not advanced.
297: * @deprecated use Find.findMismatch(Iterator,Collection,BinaryFunctor) instead
298: */
299: static public <T> LookAheadIterator<T> mismatch(
300: Iterator<? extends T> iterator,
301: Collection<? extends T> pattern,
302: BinaryFunctor<T, T, Boolean> neq) {
303: return (LookAheadIterator<T>) Find.findMismatch(iterator,
304: pattern, neq);
305: }
306:
307: // ----------------------------------------------------------------------
308: // FindRepeated algorithms
309: // ----------------------------------------------------------------------
310:
311: /**
312: * Finds arbitrary length runs of a given value in an iteration using the
313: * equals() method. Runs of length zero are well-defined: every iteration
314: * begins with a run of length zero of all possible values.
315: * @return an iterator based on the given iterator whose next() [if it
316: * hasNext()] will return the first of n adjacent instances of value. If no
317: * run of values of the requested length exist in the iteration, then the
318: * returned iterator's hasNext() will report false.
319: * @deprecated use Find.findRepeated(ITerator,int,T) instead
320: */
321: static public <T> LookAheadIterator<T> findRepeated(
322: Iterator<? extends T> iterator, int n, T value) {
323: return (LookAheadIterator<T>) Find.findRepeated(iterator, n,
324: value);
325: }
326:
327: /**
328: * Finds arbitrary length runs of a given value in an iteration using the
329: * given equality operator. Runs of length zero are well-defined: every
330: * iteration begins with a run of length zero of all possible values.
331: * @return an iterator based on the given iterator whose next() [if it
332: * hasNext()] will return the first of n adjacent instances of value. If no
333: * run of values of the requested length exist in the iteration, then the
334: * returned iterator's hasNext() will report false.
335: * @deprecated use Find.findRepeated(Iterator,int,T,Equality) instead
336: */
337: static public <T> LookAheadIterator<T> findRepeated(
338: Iterator<? extends T> iterator, int n, T value,
339: Equality<T> eq) {
340: return (LookAheadIterator<T>) Find.findRepeated(iterator, n,
341: value, eq);
342: }
343:
344: /**
345: * Finds arbitrary length runs of a given value in an iteration for which the
346: * given function returns TRUE. Runs of length zero are well-defined: every
347: * iteration begins with a run of length zero of all possible values.
348: * @return an iterator based on the given iterator whose next() [if it
349: * hasNext()] will return the first of n adjacent instances of value. If no
350: * run of values of the requested length exist in the iteration, then the
351: * returned iterator's hasNext() will report false.
352: * @deprecated use Find.findRepeated(Iterator,int,UnaryFunctor) instead
353: */
354: static public <T> LookAheadIterator<T> findRepeated(
355: Iterator<? extends T> iterator, int n,
356: UnaryFunctor<T, Boolean> eq) {
357: return (LookAheadIterator<T>) Find
358: .findRepeated(iterator, n, eq);
359: }
360:
361: // ----------------------------------------------------------------------
362: // ForEach algorithms
363: // ----------------------------------------------------------------------
364:
365: /**
366: * Applies the given UnaryFunctor to every element in the iteration, and
367: * returns the Functor. This is useful when the Functor gathers information
368: * on each successive call.
369: * @return the functor, after it has been called once for every element
370: */
371: static public <T, R> UnaryFunctor<T, R> forEach(
372: Iterator<? extends T> iterator, UnaryFunctor<T, R> fn) {
373: new ForEach<T, R>(fn).fn(iterator);
374: return fn;
375: }
376:
377: // ----------------------------------------------------------------------
378: // Equality algorithms
379: // ----------------------------------------------------------------------
380:
381: /**
382: * Returns true if the two iterations are equal, using the Comparable
383: * interface to compare elements in the iterations.
384: * @return true if the two iterations are equal
385: */
386: static public <T extends Comparable/*@*/<? super T>/*@*/> boolean equal(
387: Iterator<? extends T> iterator1,
388: Iterator<? extends T> iterator2) {
389: return equal(iterator1, iterator2,
390: new ComparableComparator<T>());
391: }
392:
393: /**
394: * Returns true if the two iterations are equal, using the given Comparator
395: * to compare elements in the iterations.
396: * @return true if the two iterations are equal
397: */
398: static public <T> boolean equal(Iterator<? extends T> iterator1,
399: Iterator<? extends T> iterator2, Comparator<T> comp) {
400: IteratorComparator<T> comp2 = new IteratorComparator<T>(comp);
401: EqualTo<Iterator<? extends T>> eq = new EqualTo<Iterator<? extends T>>(
402: comp2);
403: return eq.p(iterator1, iterator2);
404: }
405:
406: /**
407: * Returns true if the two iterations are equal, using the given
408: * BinaryFunctor to compare elements in the iterations.
409: * @return true if the two iterations are equal
410: */
411: static public <T> boolean equal(Iterator<? extends T> iter1,
412: Iterator<? extends T> iter2, BinaryFunctor<T, T, Boolean> eq) {
413: while (iter1.hasNext() && iter2.hasNext()) {
414: if (!eq.fn(iter1.next(), iter2.next()).booleanValue())
415: return false;
416: }
417:
418: return iter1.hasNext() == iter2.hasNext();
419: }
420:
421: // ----------------------------------------------------------------------
422: // Iterator Comparison algorithms
423: // ----------------------------------------------------------------------
424:
425: /**
426: * Returns true if the first iterator is lexically less than the second,
427: * using the default comparison operation to compare the elements in each
428: * iterator.
429: * @return true if the first iteration is less than the second
430: */
431: static public <T extends Comparable/*@*/<? super T>/*@*/> boolean lessThan(
432: Iterator<? extends T> iter1, Iterator<? extends T> iter2) {
433: Comparator<T> comp1 = new ComparableComparator<T>();
434: IteratorComparator<T> comp2 = new IteratorComparator<T>(comp1);
435: return new Less<Iterator<? extends T>>(comp2).p(iter1, iter2);
436: }
437:
438: /**
439: * Returns true if the first iterator is lexically less than the second,
440: * using the given comparator to compare the elements in each iterator.
441: * @return true if the first iteration is less than the second
442: */
443: static public <T> boolean lessThan(Iterator<? extends T> iter1,
444: Iterator<? extends T> iter2, Comparator<T> comp) {
445: IteratorComparator<T> comp2 = new IteratorComparator<T>(comp);
446: return new Less<Iterator<? extends T>>(comp2).p(iter1, iter2);
447: }
448:
449: /**
450: * Returns true if the first iterator is lexically less than the second,
451: * using the given operator to compare the elements in each iterator. The
452: * first is less than the second if it is not longer than the second and if
453: * the first corresponding element that is not equal is less.
454: * @return true if the first iteration is less than the second
455: */
456: static public <T> boolean lessThan(Iterator<? extends T> i1,
457: Iterator<? extends T> i2,
458: final BinaryFunctor<T, T, Boolean> lt) {
459: IteratorComparator<T> comp = new IteratorComparator<T>(
460: new Comparator<T>() {
461: public int compare(T x, T y) {
462: return lt.fn(x, y).booleanValue() ? -1 : lt.fn(
463: y, x).booleanValue() ? 1 : 0;
464: }
465: });
466:
467: return new Less<Iterator<? extends T>>(comp).p(i1, i2);
468: }
469:
470: // ----------------------------------------------------------------------
471: // Minimum/Maximum algorithms
472: // ----------------------------------------------------------------------
473:
474: /**
475: * Finds the minimum value in an iteration using the natural ordering of
476: * the iterator's elements.
477: * @return the minimum value found in the iteration
478: * @deprecated use Summarize.min(Iterator)
479: */
480: static public <T extends Comparable/*@*/<? super T>/*@*/> T minimumValue(
481: Iterator<? extends T> iterator) {
482: return Summarize.min(iterator);
483: }
484:
485: /**
486: * Finds the minimum value in an iteration using the given comparator.
487: * @return the minimum value found in the iteration
488: * @deprecated use Summarize.min(Iterator, Comparator)
489: */
490: static public <T> T minimumValue(Iterator<? extends T> iterator,
491: Comparator<T> comp) {
492: return Summarize.min(iterator, comp);
493: }
494:
495: /**
496: * Finds the minimum value in an iteration using the given functor to
497: * compare elements. The functor is presumed to return the lesser of
498: * its two arguments.
499: * @return the minimum value found in the iteration
500: * @deprecated use Summarize.min(Iterator, BinaryFunctor);
501: */
502: static public <T> T minimumValue(Iterator<? extends T> iterator,
503: BinaryFunctor<T, T, T> bf) {
504: return Summarize.min((Iterator<T>) iterator, bf);
505: }
506:
507: /**
508: * Finds the maximum value in an iteration using the natural ordering of
509: * the iterator's elements.
510: * @return the maximum value found in the iteration
511: * @deprecated use Summarize.max(Iterator)
512: */
513: static public <T extends Comparable/*@*/<? super T>/*@*/> T maximumValue(
514: Iterator<? extends T> iterator) {
515: return Summarize.max(iterator);
516: }
517:
518: /**
519: * Finds the maximum value in an iteration using the given comparator.
520: * @return the maximum value found in the iteration
521: * @deprecated use Summarize.max(Iterator, Comparator)
522: */
523: static public <T> T maximumValue(Iterator<? extends T> iterator,
524: Comparator<T> comp) {
525: return Summarize.max(iterator, comp);
526: }
527:
528: /**
529: * Finds the maximum value in an iteration using the given functor to
530: * compare elements. The functor is presumed to return the lesser of
531: * its two arguments.
532: * @return the maximum value found in the iteration
533: * @deprecated use Summarize.max(Iterator,BinaryFunctor)
534: */
535: static public <T> T maximumValue(Iterator<? extends T> iterator,
536: BinaryFunctor<T, T, T> bf) {
537: return Summarize.max((Iterator<T>) iterator, bf);
538: }
539:
540: // ----------------------------------------------------------------------
541: // Accumulate algorithms
542: // ----------------------------------------------------------------------
543:
544: /**
545: * Adds each number in the iterator, returning the sum.
546: * @return the final sum. If the iterator is empty, then zero is
547: * returned
548: * @deprecated use Summarize.sum(Class,Iterator)
549: */
550: static public <T extends Number> T accumulate(Class<T> numtype,
551: Iterator<T> iterator) {
552: return Summarize.sum(numtype, iterator);
553: }
554:
555: /**
556: * Applies the binary functor to each number in the iterator, returning
557: * the final result. Along with each number is passed the result of the
558: * previous call of the functor (or zero for the first call to the functor).
559: * The elements in the iterator are always passed in the 2nd postion.
560: * @return the final result. If the iterator is empty, then zero is
561: * returned
562: * @deprecated use Summarize.accumulate(Iterator,BinaryFunctor) or
563: * Summarize.accumulate(Iterator,T,BinaryFunctor), passing an
564: * appropriate starting value (typically 0 or 1).
565: */
566: static public <T extends Number> T accumulate(Class<T> numtype,
567: Iterator<T> iterator, BinaryFunctor<T, T, T> bf) {
568: Arithmetic<T> _math = ArithmeticFactory.getArithmetic(numtype);
569: if (_math == null) {
570: throw new IllegalArgumentException();
571: }
572:
573: return Summarize.accumulate(iterator, _math.zero(), bf);
574: }
575:
576: /**
577: * Applies the binary functor to each element in the iterator, returning
578: * the final result. Along with each element is passed the result of the
579: * previous call of the functor (or the initial value for the first call
580: * to the functor). The elements in the iteration are always passed in the
581: * 2nd postion.
582: * @return the final result. If the iteration is empty, then the initial
583: * value is returned
584: * @deprecated use Summarize.accumulate(Iterator,T,BinaryFunctor)
585: */
586: static public <T> T accumulate(Iterator<T> iterator, T initial,
587: BinaryFunctor<T, T, T> bf) {
588: return Summarize.accumulate(iterator, initial, bf);
589: }
590:
591: // ----------------------------------------------------------------------
592: // Transform algorithms
593: // ----------------------------------------------------------------------
594:
595: /**
596: * Applies the UnaryFunctor to each element in the input, returning an
597: * iterator over the results.
598: * @return an iterator based on the given iterator that will return the
599: * results obtained when passing each element of the input iteration to the
600: * given unary functor.
601: * @deprecated the return type will be changed to Transform.TransformIterator
602: * in a future release. Use Transform.transform(Iterator,UnaryFunctor)
603: */
604: static public <T, R> TransformIterator<T, R> transform(
605: Iterator<? extends T> iter, UnaryFunctor<T, R> uf) {
606: return (TransformIterator<T, R>) Transform.transform(iter, uf);
607: }
608:
609: /**
610: * Applies the BinaryFunctor to corresponding elements of the two input
611: * iterators, and returns an iterator over the results. The resulting
612: * iterator will have the same number of elements as the shorter of the two
613: * input iterations.
614: * @return an iterator that will return the results obtained when passing
615: * each pair of corresponding elements of the input iterations to the
616: * given binary functor.
617: * @deprecated the return type will be changed to Transform.BinaryIterator
618: * in a future release. Use Transform.transform(Iterator,Iterator,BinaryFunctor)
619: */
620: static public <T1, T2, R> TransformBinaryIterator<T1, T2, R> transform(
621: Iterator<? extends T1> i1, Iterator<? extends T2> i2,
622: BinaryFunctor<T1, T2, R> bf) {
623: return (TransformBinaryIterator<T1, T2, R>) Transform
624: .transform(i1, i2, bf);
625: }
626:
627: // ----------------------------------------------------------------------
628: // replaceAll algorithms
629: // ----------------------------------------------------------------------
630:
631: /**
632: * Tests each element in an iterator, replacing those for which the test is
633: * true with the replacement value.
634: * @deprecated use Transform.replace(Iterator, UnaryFunctor, T) instead
635: */
636: static public <T> Iterator<T> replaceAll(
637: Iterator<? extends T> iter, UnaryFunctor<T, Boolean> test,
638: T value) {
639: return Transform.replace((Iterator<T>) iter, test, value);
640: }
641:
642: // ----------------------------------------------------------------------
643: // Filtering algorithms
644: // ----------------------------------------------------------------------
645:
646: /**
647: * Filters an arbitrary value from an iteration using the equals() method.
648: * @return an iterator based on the given iterator that will return not
649: * include elements equal to the given value
650: * @deprecated the return type will be changed to Filter.FilterIterator in
651: * a future release. Use Filter.removeAll(Iterator,T)
652: */
653: static public <T> FilterIterator<T> removeAll(
654: Iterator<? extends T> iterator, T value) {
655: return (FilterIterator<T>) Filter.remove(iterator, value);
656: }
657:
658: /**
659: * Filters an arbitrary value from an iteration using the given Equality
660: * operator.
661: * @return an iterator based on the given iterator that will not include
662: * elements that are equal to the value using the given Equality
663: * @deprecated the return type will be changed to Filter.FilterIterator in
664: * a future release. Use Filter.removeAll(Iterator,T,Equality)
665: */
666: static public <T> FilterIterator<T> removeAll(
667: Iterator<? extends T> iterator, T value, Equality<T> eq) {
668: return (FilterIterator<T>) Filter.remove(iterator, value, eq);
669: }
670:
671: /**
672: * Filters values from an iteration for which the given function returns
673: * TRUE.
674: * @return an iterator based on the given iterator that will not include
675: * elements that pass the given test.
676: * @deprecated the return type will be changed to Filter.FilterIterator in
677: * a future release. Use Filter.removeAll(Iterator,UnaryFunctor)
678: */
679: static public <T> FilterIterator<T> removeAll(
680: Iterator<? extends T> iterator, UnaryFunctor<T, Boolean> eq) {
681: return (FilterIterator<T>) Filter.remove(iterator, eq);
682: }
683:
684: // ----------------------------------------------------------------------
685: // unique algorithms
686: // ----------------------------------------------------------------------
687:
688: /**
689: * Skips duplicate values in the given iteration.
690: * @return an iterator based on the given iterator that will not return the
691: * same element twice in succession
692: * @deprecated in the next release, the return type will change to Unique.UniqueIterator.
693: * Use Unique.unique(Iterator)
694: */
695: static public <T> UniqueIterator<T> unique(
696: Iterator<? extends T> iterator) {
697: return (UniqueIterator<T>) Unique.unique(iterator);
698: }
699:
700: /**
701: * Skips duplicate values in the given iteration.
702: * @return an iterator based on the given iterator that will not return the
703: * same element twice in succession, using the given functor to compare
704: * elements
705: * @deprecated in the next release, the return type will change to Unique.UniqueIterator.
706: * Use Unique.unique(Iterator,BinaryFunctor)
707: */
708: static public <T> UniqueIterator<T> unique(
709: Iterator<? extends T> iterator,
710: BinaryFunctor<T, T, Boolean> eq) {
711: return (UniqueIterator<T>) Unique.unique(iterator, eq);
712: }
713:
714: // ----------------------------------------------------------------------
715: // merge algorithms
716: // ----------------------------------------------------------------------
717:
718: /**
719: * Merges two iterations together. Walks both iterators, choosing the
720: * lesser of the two current values.
721: * @return an iterator based on the two input iterators that contains their
722: * merged contents
723: * @deprecated in a future release, the return type will change to Merge.MergeIterator.
724: * Use Merge.merge(Iterator,Iterator)
725: */
726: static public <T extends Comparable/*@*/<? super T>/*@*/> MergeIterator<T> merge(
727: Iterator<? extends T> iter1, Iterator<? extends T> iter2) {
728: return (MergeIterator<T>) Merge.merge(iter1, iter2);
729: }
730:
731: /**
732: * Merges two iterations together using the given comparator. Walks both
733: * iterators, choosing the lesser of the two current values.
734: * @return an iterator based on the two input iterators that contains their
735: * merged contents
736: * @deprecated in a future release, the return type will change to Merge.MergeIterator.
737: * Use Merge.merge(Iterator,Iterator,Comparator) instead
738: */
739: static public <T> MergeIterator<T> merge(
740: Iterator<? extends T> iter1, Iterator<? extends T> iter2,
741: Comparator<T> comp) {
742: return (MergeIterator<T>) Merge.merge(iter1, iter2, comp);
743: }
744:
745: // ----------------------------------------------------------------------
746: // adjacent diff algorithms
747: // ----------------------------------------------------------------------
748:
749: /**
750: * @return an iterator containing the arithemetic difference between succesive
751: * pairs of numbers
752: * @deprecated in a future release, the return type will change to
753: * Transform.AdjacentIterator. use Transform.transform(Iterator,new Minus(type)),
754: */
755:
756: static public <T extends Number> TransformAdjacentIterator<T, T> adjacentDiff(
757: Class<T> type, Iterator<? extends T> iter) {
758: return (TransformAdjacentIterator<T, T>) Transform.transform(
759: iter, new Minus<T>(type));
760: }
761: }
|