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


1 // ============================================================================
2 // $Id: Algorithms.java,v 1.43 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 package net.sf.jga.util;
33
34 import java.util.Collection ;
35 import java.util.Comparator ;
36 import java.util.Iterator ;
37 import java.util.List ;
38 import java.util.ListIterator ;
39 import net.sf.jga.algorithms.Find;
40 import net.sf.jga.algorithms.Filter;
41 import net.sf.jga.algorithms.Merge;
42 import net.sf.jga.algorithms.Summarize;
43 import net.sf.jga.algorithms.Transform;
44 import net.sf.jga.algorithms.Unique;
45 import net.sf.jga.fn.BinaryFunctor;
46 import net.sf.jga.fn.UnaryFunctor;
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.Plus;
51 import net.sf.jga.fn.comparison.EqualTo;
52 import net.sf.jga.fn.comparison.Equality;
53 import net.sf.jga.fn.comparison.NotEqualTo;
54 import net.sf.jga.fn.logical.BinaryNegate;
55 import net.sf.jga.fn.logical.UnaryNegate;
56
57 /**
58  * Facade for the Algorithms adapted from STL, defined to work primarily with
59  * collections. These algorithms are adapted from STL, with modifications to be
60  * consistent with typical java practice. For example, typical STL algorithms
61  * are defined with pairs of iterators defining a half-open range over some
62  * implied collection. It works in C++ because the STL iterators can be compared
63  * for equality. Java iterators are not guaranteed to be comparable to each
64  * other by contract, so the same signatures wouldn't work.
65  * <p>
66  * Typically, where an STL algorithm would take a pair of iterators, we'll take
67  * a collection. Where an STL algorithm would return an iterator, we'll return
68  * an iterator. Note that it will always be java.lang.Iterator when using
69  * this class: for some of the more powerful uses, use the Iterators class,
70  * which will often return an implementation of Iterator that is tailored for
71  * the semantics of the algorithm that was called.
72  * <p>
73  * The algorithms in this class and the same set of algorithms in the Iterators
74  * class will always return the same results when called with identical
75  * arguments.
76  * <p>
77  * Copyright &copy; 2003-2005 David A. Hall
78  *
79  * @author <a HREF="mailto:davidahall@users.sf.net">David A. Hall</a>
80  */
81
82 public class Algorithms {
83
84     // ----------------------------------------------------------------------
85 // Finding algorithms
86 // ----------------------------------------------------------------------
87
88     /**
89      * Finds an arbitrary value in a collection using the equals() method.
90      * @return an iterator from the collection whose next() [if it hasNext()]
91      * will return the first instance of the value. If the value is not in the
92      * collection, then the returned iterator's hasNext() will report false.
93      * @deprecated use Find.find() instead
94      */
95     static public <T> Iterator <T> find(Collection <? extends T> collection, T value) {
96         return Find.find(collection, value);
97     }
98
99     /**
100      * Finds an arbitrary value in a collection using the given Equality
101      * operator.
102      * @return an iterator from the collection whose next() [if it hasNext()]
103      * will return the first instance of the value. If the value is not in the
104      * collection, then the returned iterator's hasNext() will report false.
105      * @deprecated use Find.find() instead
106      */
107     static public <T> Iterator <T> find(Collection <? extends T> collection, T value, Equality<T> eq){
108         return Find.find(collection, value, eq);
109     }
110
111     
112     /**
113      * Finds a value in a collection for which the given function returns TRUE.
114      * @return an iterator from the collection whose next() [if it hasNext()]
115      * will return the first instance of the value. If the value is not in the
116      * collection, then the returned iterator's hasNext() will report false.
117      * @deprecated use Find.find() instead
118      */
119     static public <T> Iterator <T>
120     find(Collection <? extends T> collection, UnaryFunctor<T,Boolean > fn)
121     {
122         return Find.find(collection, fn);
123     }
124  
125     // ----------------------------------------------------------------------
126 // Counting algorithms
127 // ----------------------------------------------------------------------
128
129     /**
130      * Counts the number of occurrences of value in the collection, using the
131      * equals() method of the value
132      * @return the number of instances found
133      * @deprecated use Summarize.count(Iterable,T)
134      */
135     static public <T> long count(Collection <? extends T> collection, T value) {
136         return Summarize.count(collection, value);
137     }
138
139     /**
140      * Counts the number of occurrences of value in the collection, using the
141      * given equality operator.
142      * @return the number of instances found
143      * @deprectaed use Summarize.count(Iterable,Equality,T)
144      */
145     static public <T> long count(Collection <? extends T> collection, Equality<T> eq, T value) {
146         return Summarize.count(collection,eq,value);
147     }
148
149     
150     /**
151      * Counts the items in the collection for which the given function returns
152      * true.
153      * @return the number of instances found
154      * @deprecated use Summarize.count(Iterable,UnaryFunctor)
155      */
156     static public <T> long count(Collection <? extends T> collection, UnaryFunctor<T,Boolean > eq) {
157         return Summarize.count(collection,eq);
158     }
159
160     // ----------------------------------------------------------------------
161 // Adjacent Find algorithms
162 // ----------------------------------------------------------------------
163
164     /**
165      * Finds adjacent pairs of equivalent values in a collection using the
166      * equals() method.
167      * @return an iterator from the collection whose next() [if it hasNext()]
168      * will return the first of a pair of adjacent values. If no pair of values
169      * exists in the collection, then the returned iterator's hasNext() will
170      * report false.
171      * @deprecated use Find.findAdjacent(Iterable) instead
172      */
173     static public <T> Iterator <T> findAdjacent(Collection <? extends T> collection) {
174         return Find.findAdjacent(collection);
175     }
176
177     
178     /**
179      * Finds adjacent pairs of equivalent values in a collection for which the
180      * given function returns TRUE.
181      * @return an iterator from the collection whose next() [if it hasNext()]
182      * will return the first of a pair of adjacent values. If no pair of values
183      * exists in the collection, then the returned iterator's hasNext() will
184      * report false.
185      * @deprecated use Find.findAdjacnet(Iterable, BinaryFunctor) instead
186      */
187     static public <T> Iterator <T>
188     findAdjacent(Collection <? extends T> c, BinaryFunctor<T,T,Boolean > bf)
189     {
190         return Find.findAdjacent(c, bf);
191     }
192
193     // ----------------------------------------------------------------------
194 // FindElement algorithms
195 // ----------------------------------------------------------------------
196
197     /**
198      * Finds any value from the given collection using the collection's contains() method.
199      * @return an iterator from the first collection whose next() [if it hasNext()] will return
200      * the first instance of any value found in the second collection. If no such value is
201      * found in the first collection, then the returned iterator's hasNext() will report false.
202      * @deprecated use Find.findElement(Iterable,Collection) instead
203      */
204     static public <T> Iterator <T>
205     findElement(Collection <? extends T> c, Collection <? extends T> desired)
206     {
207         return Find.findElement(c, desired);
208     }
209
210     
211     /**
212      * Finds any value from the given collection using the given functor to determine equivalence.
213      * Each item in the first collection will be compared to every item in the second collection
214      * using the given functor, stopping when the first collection is exhausted or when any
215      * pair returns TRUE.
216      * @return an iterator from the first collection whose next() [if it hasNext()] will return
217      * the first instance of any value in the second collection, where equivelency is determined
218      * by the given functor. If no such value is found in the first collection, then the returned
219      * iterator's hasNext() will report false.
220      * @deprecated use Find.findElement(Iterable,Collection,BinaryFunctor) instead
221      */
222     static public <T> Iterator <T>
223     findElement(Collection <? extends T> c, Collection <? extends T> desired,
224                 BinaryFunctor<T,T,Boolean > fn)
225     {
226         return Find.findElement(c, desired, fn);
227     }
228
229     // ----------------------------------------------------------------------
230 // SequenceMatch algorithms
231 // ----------------------------------------------------------------------
232
233     /**
234      * Finds the given pattern in the collection using the equals method.
235      * @return an iterator from the first collection whose next() [if it
236      * hasNext()] will return the first element of a sequence that matches
237      * the entire contents of the second collection. If no such match is
238      * found in the first collection, then the returned iterator's hasNext()
239      * will report false. If the pattern is empty, then the iterator points
240      * to the first element in the collection.
241      * @deprecated use Find.findSequence(Iterable,Collection) instead
242      */
243     static public <T> Iterator <T> match(Collection <? extends T> c, Collection <? extends T> pattern) {
244         return Find.findSequence(c, pattern);
245     }
246
247
248     /**
249      * Finds the given pattern in the collection using the given functor
250      * to determine equivalence.
251      * @return an iterator from the first collection whose next() [if it
252      * hasNext()] will return the first element of a sequence that matches
253      * the entire contents of the second collection. If no such match is
254      * found in the first collection, then the returned iterator's hasNext()
255      * will report false. If the pattern is empty, then the iterator points
256      * to the first element in the collection.
257      * @deprecated use Find.findSequence(Iterable,Collection,BinaryFunctor) instead
258      */
259     static public <T> Iterator <T>
260     match(Collection <? extends T> c, Collection <? extends T> pattern, BinaryFunctor<T,T,Boolean > eq){
261         return Find.findSequence(c, pattern, eq);
262     }
263
264     
265     /**
266      * Finds the point at which two collections differ, using NotEqualTo.
267      * @return an iterator from the first collection whose next() [if it
268      * hasNext()] will return the first element in the collection that does
269      * not equal the corresponding element in the pattern. If the pattern
270      * matches the collection but is longer, than the returned iterator's
271      * hasNext() will report false. If the pattern is empty, then the iterator
272      * points to the first element in the collection.
273      * @deprecated use Find.findMismatch(Iterable,Collection) instead
274      */
275     static public <T> Iterator <T>
276     mismatch(Collection <? extends T> c, Collection <? extends T> pattern)
277     {
278         return Find.findMismatch(c, pattern);
279     }
280
281     
282     /**
283      * Finds the point at which two collections differ, using the given functor
284      * @return an iterator from the first collection whose next() [if it
285      * hasNext()] will return the first element in the collection for which the
286      * given function returns TRUE when given the element and the correspondind
287      * element in the pattern. If the pattern matches the collection but is
288      * longer, than the returned iterator's hasNext() will report false. If the
289      * pattern is empty, then the iterator points to the first element in the
290      * collection.
291      * @deprecated use Find.findMismatch(Iterable,Pattern,BinaryFunctor) instead
292      */
293     static public <T> Iterator <T>
294     mismatch(Collection <? extends T> c, Collection <? extends T> pattern,
295              BinaryFunctor<T,T,Boolean > neq)
296     {
297         return Find.findMismatch(c, pattern, neq);
298     }
299
300     // ----------------------------------------------------------------------
301 // FindRepeated algorithms
302 // ----------------------------------------------------------------------
303
304     /**
305      * Finds arbitrary length runs of a given value in a collection using the
306      * equals() method. Runs of length zero are well-defined: every iteration
307      * begins with a run of length zero of all possible values.
308      * @return an iterator from the collection whose next() [if it hasNext()]
309      * will return the first of n adjacent instances of value. If no run of
310      * values of the requested length exist in the collection, then the returned
311      * iterator's hasNext() will report false.
312      * @deprecated use Find.findRepeated(Iterable,int,T) instead
313      */
314     static public <T> Iterator <T> findRepeated(Collection <? extends T> c, int n, T value) {
315         return Find.findRepeated(c, n, value);
316     }
317
318     
319     /**
320      * Finds arbitrary length runs of a given value in a collection using the
321      * given Equality operator. Runs of length zero are well-defined: every
322      * iteration begins with a run of length zero of all possible values.
323      * @return an iterator from the collection whose next() [if it hasNext()]
324      * will return the first of n adjacent instances of value. If no run of
325      * values of the requested length exist in the collection, then the returned
326      * iterator's hasNext() will report false.
327      * @deprecated use Find.findRepeated(Iterable,int,T,Equality) instead
328      */
329     static public <T> Iterator <T>
330     findRepeated(Collection <? extends T> c, int n, T value, Equality<T> eq)
331     {
332         return Find.findRepeated(c, n, value, eq);
333     }
334
335     
336     /**
337      * Finds arbitrary length runs of values in a collection for which the given
338      * functor returns TRUE. Runs of length zero are well-defined: every
339      * iteration begins with a run of length zero of all possible values.
340      * @return an iterator from the collection whose next() [if it hasNext()]
341      * will return the first of n adjacent instances of value. If no run of
342      * values of the requested length exist in the collection, then the returned
343      * iterator's hasNext() will report false.
344      * @deprecated use Find.findRepeated(Iterable,int,T,UnaryFunctor) instead
345      */
346     static public <T> Iterator <T>
347     findRepeated(Collection <? extends T> c, int n, UnaryFunctor<T, Boolean > eq)
348     {
349         return Find.findRepeated(c, n, eq);
350     }
351  
352     // ----------------------------------------------------------------------
353 // ForEach algorithms
354 // ----------------------------------------------------------------------
355
356     /**
357      * Applies the given UnaryFunctor to every element in the collection, and
358      * returns the Functor. This is useful when the Functor gathers information
359      * on each successive call.
360      * @return the functor, after it has been called once for every element
361      */
362     static public <T,R> UnaryFunctor<T,R> forEach(Collection <? extends T> c,UnaryFunctor<T,R> fn) {
363         new ForEach<T,R>(fn).fn(c.iterator());
364         return fn;
365     }
366
367
368     // ----------------------------------------------------------------------
369 // Collection Equality algorithms
370 // ----------------------------------------------------------------------
371
372     /**
373      * Returns true if the two collections are equal.
374      * @return true if the two collections are equal
375      */
376     static public <T> boolean equal(Collection <? extends T> c1, Collection <? extends T> c2) {
377         return new EqualTo<Collection <? extends T>>().p(c1,c2);
378     }
379
380     
381     /**
382      * Returns true if the two collections are equal, using the given comparator
383      * to compare the elements in each collection
384      * @return true if the two collections are equal.
385      */
386     static public <T> boolean
387     equal(Collection <? extends T> c1, Collection <? extends T> c2, Comparator <T> comp) {
388         return Iterators.equal(c1.iterator(), c2.iterator(), comp);
389     }
390
391     
392    /**
393     * Returns true if the two collections are equal, using the given functor
394     * to compare the elements in each collection. The functor is expected to
395     * evaluate its two argments and return true if they are "equal", therefore
396     * this method returns true if the iterations contain the same number of
397     * elements and if the functor returns true for all pairs of elements.
398     * @return true if the two collections are equal
399     */
400     static public <T> boolean
401     equal(Collection <? extends T> c1, Collection <? extends T> c2, BinaryFunctor<T,T,Boolean > eq) {
402         return Iterators.equal(c1.iterator(), c2.iterator(), eq);
403     }
404                                  
405     // ----------------------------------------------------------------------
406 // Collection Comparison algorithms
407 // ----------------------------------------------------------------------
408
409     /**
410      * Returns true if the first collection is lexically less than the second,
411      * using the default comparison operation to compare the elements in each
412      * collection.
413      * @return true if c1 < c2
414      */
415     static public <T extends Comparable /*@*/<? super T>/*@*/> boolean
416     lessThan(Collection <? extends T> c1, Collection <? extends T> c2) {
417         return Iterators.lessThan(c1.iterator(), c2.iterator());
418     }
419
420     
421     /**
422      * Returns true if the first collection is lexically less than the second,
423      * using the given comparator to compare the elements in each collection.
424      * @return true if c1 < c2
425      */
426     static public <T> boolean
427     lessThan(Collection <? extends T> c1, Collection <? extends T> c2, Comparator <T> comp) {
428         return Iterators.lessThan(c1.iterator(), c2.iterator(), comp);
429     }
430
431     
432     /**
433      * Returns true if the first collection is lexically less than the second,
434      * using the given operator to compare the elements in each collection. The
435      * first is less than the second if it is not longer than the second and if
436      * the first corresponding element that is not equal is less.
437      * @return true if c1 < c2
438      */
439     static public <T> boolean
440     lessThan(Collection <? extends T> c1, Collection <? extends T> c2, BinaryFunctor<T,T,Boolean > lt) {
441         return Iterators.lessThan(c1.iterator(), c2.iterator(), lt);
442     }
443                                  
444     // ----------------------------------------------------------------------
445 // Minimum/Maximum algorithms
446 // ----------------------------------------------------------------------
447
448     /**
449      * Finds the position of the minimum value in a collection using the natural
450      * ordering of the collection's elements.
451      * @return an iterator from the collection whose next() [if it hasNext()]
452      * will return the first instance of the minimum value in the collection.
453      * If the collection is empty, then the returned iterator's hasNext() will
454      * report false.
455      */
456     static public <T extends Comparable /*@*/<? super T>/*@*/> Iterator <T>
457     minimum(Collection <? extends T> c)
458     {
459         return Find.find(c, Summarize.min(c));
460     }
461
462     
463     /**
464      * Finds the position of the minimum value in a collection using the given
465      * comparator.
466      * @return an iterator from the collection whose next() [if it hasNext()]
467      * will return the first instance of the minimum value in the collection.
468      * If the collection is empty, then the returned iterator's hasNext() will
469      * report false.
470      */
471     static public <T> Iterator <T> minimum(Collection <? extends T> c, Comparator <T> comp) {
472         return Find.find(c, Summarize.min(c,comp));
473     }
474
475     
476     /**
477      * Finds the position of the minimum value in a collection using the given
478      * functor to compare elements. The functor is presumed to return the lesser
479      * of its two arguments.
480      * @return an iterator from the collection whose next() [if it hasNext()]
481      * will return the first instance of the minimum value in the collection.
482      * If the collection is empty, then the returned iterator's hasNext() will
483      * report false.
484      */
485     static public <T> Iterator <T> minimum(Collection <? extends T> c, BinaryFunctor<T,T,T> bf) {
486         return Find.find(c, Summarize.min(c,bf));
487     }
488
489     
490     /**
491      * Finds the minimum value in a collection using the natural ordering of
492      * the collection's elements.
493      * @return the minimum value found in the collection
494      * @deprecated use Summarize.min(Iterable)
495      */
496     static public <T extends Comparable /*@*/<? super T>/*@*/> T
497     minimumValue(Collection <? extends T> c)
498     {
499         return Summarize.min(c);
500     }
501
502     
503     /**
504      * Finds the minimum value in a collection using the given comparator.
505      * @return the minimum value found in the collection
506      * @deprecated use Summarize.min(Iterable,Comparator)
507      */
508     static public <T> T minimumValue(Collection <? extends T> c, Comparator <T> comp) {
509         return Summarize.min(c,comp);
510     }
511
512     
513     /**
514      * Finds the minimum value in a collection using the given functor to
515      * compare elements. The functor is presumed to return the lesser of
516      * its two arguments.
517      * @return the minimum value found in the collection
518      * @deprecated use Summarize.min(Iterable,BinaryFunctor)
519      */
520     static public <T> T minimumValue(Collection <? extends T> c, BinaryFunctor<T,T,T> bf) {
521         return Summarize.min(c,bf);
522     }
523
524     
525     /**
526      * Finds the position of the maximum value in a collection using the natural
527      * ordering of the collection's elements.
528      * @return an iterator from the collection whose next() [if it hasNext()]
529      * will return the first instance of the maximum value in the collection.
530      * If the collection is empty, then the returned iterator's hasNext() will
531      * report false.
532      */
533     static public <T extends Comparable /*@*/<? super T>/*@*/> Iterator <T>
534     maximum(Collection <? extends T> c)
535     {
536         return Find.find(c, Summarize.max(c));
537     }
538
539     
540     /**
541      * Finds the position of the maximum value in a collection using the given
542      * comparator.
543      * @return an iterator from the collection whose next() [if it hasNext()]
544      * will return the first instance of the maximum value in the collection.
545      * If the collection is empty, then the returned iterator's hasNext() will
546      * report false.
547      */
548     static public <T > Iterator <T> maximum(Collection <? extends T> c, Comparator <T> comp) {
549         return Find.find(c, Summarize.max(c,comp));
550     }
551
552
553     /**
554      * Finds the position of the maximum value in a collection using the given
555      * functor to compare elements. The functor is presumed to return the
556      * greater of its two arguments.
557      * @return an iterator from the collection whose next() [if it hasNext()]
558      * will return the first instance of the maximum value in the collection.
559      * If the collection is empty, then the returned iterator's hasNext() will
560      * report false.
561      */
562     static public <T> Iterator <T> maximum(Collection <? extends T> c, BinaryFunctor<T,T,T> bf) {
563         return Find.find(c, Summarize.max(c, bf));
564     }
565
566     
567     /**
568      * Finds the maximum value in a collection using the natural ordering of
569      * the collection's elements.
570      * @return the maximum value found in the collection
571      * @deprecated use Summarize.max(Iterable)
572      */
573     static public <T extends Comparable /*@*/<? super T>/*@*/> T
574     maximumValue(Collection <? extends T> c)
575     {
576         return Summarize.max(c);
577     }
578
579     
580     /**
581      * Finds the maximum value in a collection using the given comparator.
582      * @return the maximum value found in the collection
583      * @deprecated use Summarize.max(Iterable,Comparator)
584      */
585     static public <T> T maximumValue(Collection <? extends T> c, Comparator <T> comp) {
586         return Summarize.max(c,comp);
587     }
588
589     
590     /**
591      * Finds the maximum value in a collection using the given functor to
592      * compare elements. The functor is presumed to return the greater of
593      * its two arguments.
594      * @return the maximum value found in the collection
595      * @deprecated use Summarize(Iterable,BinaryFunctor)
596      */
597     static public <T> T maximumValue(Collection <? extends T> c, BinaryFunctor<T,T,T> fn) {
598         return Summarize.max(c,fn);
599     }
600
601     // ----------------------------------------------------------------------
602 // Accumulate algorithms
603 // ----------------------------------------------------------------------
604
605     /**
606      * Adds each number in the collection, returning the sum.
607      * @return the final sum. If the collection is empty, then zero is
608      * returned
609      * @deprecated use Summarize.sum(Class,Iterable)
610      */
611     static public <T extends Number > T accumulate(Class <T> type, Collection <T> c) {
612         return Summarize.sum(type, c);
613     }
614
615
616     /**
617      * Applies the binary functor to each number in the collection, returning
618      * the final result. Along with each number is passed the result of the
619      * previous call of the functor (or zero for the first call to the functor).
620      * The elements in the collection are always passed in the 2nd postion.
621      * @return the final result. If the collection is empty, then zero is
622      * returned
623      * @deprecated use Summarize.accumulate(Iterable,BinaryFunctor) or
624      * Summarize.accumulate(Iterable,T,BinaryFunctor), passing an
625      * appropriate starting value (typically 0 or 1).
626      */
627     static public <T extends Number > T
628     accumulate(Class <T> type, Collection <T> c, BinaryFunctor<T,T,T> fn)
629     {
630          Arithmetic<T> _math = ArithmeticFactory.getArithmetic(type);
631          if (_math == null) {
632              throw new IllegalArgumentException ();
633          }
634         
635         return Summarize.accumulate(c, _math.zero(), fn);
636     }
637
638     
639     /**
640      * Applies the binary functor to each element in the collection, returning
641      * the final result. Along with each element is passed the result of the
642      * previous call of the functor (or the initial value for the first call
643      * to the functor). The elements in the collection are always passed in the
644      * 2nd postion.
645      * @return the final result. If the collection is empty, then the initial
646      * value is returned
647      * @deprecated use Summarize.accumulate(Iterable,T,BinaryFunctor)
648      */
649     static public <T> T accumulate(Collection <T> c, T initial, BinaryFunctor<T,T,T> fn) {
650         return Summarize.accumulate(c, initial, fn);
651     }
652
653     // ----------------------------------------------------------------------
654 // Transform algorithms
655 // ----------------------------------------------------------------------
656
657     /**
658      * Applies the UnaryFunctor to each element in the list, and replaces
659      * each element with the result. This method would, in an ideal world,
660      * belong in the Collections class, as its signature is more like the
661      * algorithm methods in that class than in Algorithms.
662      */
663     static public <T> void transform(List <T> lin, UnaryFunctor<T,T> uf) {
664         // NOTE: can't be covariant, as it both reads from the list and writes
665 // to it (effectively)
666 ListIterator <T> liter = lin.listIterator();
667         while(liter.hasNext()) {
668             liter.set(uf.fn(liter.next()));
669         }
670     }
671
672     
673     /**
674      * Applies the UnaryFunctor to each element in the input collection, and
675      * appends the result to the output collection. The output collection will
676      * generally grow as a result of this operation (in contrast with the STL
677      * transform operation, which will not by itself change the size of the
678      * output collection)
679      * @deprecated use Transform.transform(Iterable,UnaryFunctor,Collection)
680      */
681     static public <T,R> Collection <? super R>
682     transformCopy(Collection <? extends T> cin, Collection <? super R> cout, UnaryFunctor<T,R> uf)
683     {
684         return Transform.transform( cin, uf, cout);
685     }
686
687     
688     /**
689      * Applies the BinaryFunctor to corresponding elements of the two input
690      * collections, and appends the result to the output collection. The
691      * output collection will generally grow as a result of this operation (in
692      * contrast with the STL transform operation, which will not by itself
693      * change the size of the output collection)
694      * @deprecated use Transform.transform(Iterable,Iterable,BinaryFunctor,Collection)
695      */
696     static public <T1,T2,R> Collection <? super R>
697     transformCopy(Collection <? extends T1> c1, Collection <? extends T2> c2,
698                   Collection <? super R> cout, BinaryFunctor<T1,T2,R> bf)
699     {
700         return Transform.transform((Collection <T1>)c1, (Collection <T2>)c2, bf, cout);
701     }
702     
703     // ----------------------------------------------------------------------
704 // replaceAll algorithms
705 // ----------------------------------------------------------------------
706
707     /**
708      * Tests each element in the list, and replaces elements that pass with
709      * the given value. This method would, in an ideal world, belong in the
710      * Collections class, as its signature is more like the algorithm methods
711      * in that class than in Algorithms.
712      */
713     static public <T> void replaceAll(List <T> lin, UnaryFunctor<T,Boolean > uf, T value) {
714         // NOTE: can't be covariant, as it both reads from the list and writes
715 // to it (effectively)
716 ListIterator <T> liter = lin.listIterator();
717         while(liter.hasNext()) {
718             if (uf.fn(liter.next()).booleanValue()) {
719                 liter.set(value);
720             }
721         }
722     }
723
724     
725     /**
726      * Copies each element in the input collection to the output collection,
727      * except that those elements that pass the given test are replaced with the
728      * constant value.
729      * @deprecated use Transform.replace(Iterable,UnaryFunctor,T,Collection)
730      */
731     static public <T,R> Collection <? super T>
732     replaceAllCopy(Collection <? extends T> cin, Collection <? super T> cout,
733                    UnaryFunctor<T,Boolean > test,T value)
734     {
735         return Transform.replace(cin, test, value, cout);
736     }
737
738     // ----------------------------------------------------------------------
739 // filter algorithms
740 // ----------------------------------------------------------------------
741
742     /**
743      * removes all instances of the given element from the list
744      */
745     static public <T> void removeAll(List <? extends T> lin, T value) {
746         removeAll(lin, new EqualTo<T>().bind2nd(value));
747     }
748
749     
750     /**
751      * removes all instances of the given element from the list
752      */
753     static public <T> void removeAll(List <? extends T> lin, T value, Equality<T> eq) {
754         removeAll(lin, eq.bind2nd(value));
755     }
756
757     
758     /**
759      * removes all elements from the list for which the functor returns TRUE
760      */
761     static public <T> void removeAll(List <? extends T> lin, UnaryFunctor<T,Boolean > uf) {
762         ListIterator <? extends T> liter = lin.listIterator();
763         while (liter.hasNext()) {
764             if (uf.fn(liter.next()).booleanValue()) {
765                 liter.remove();
766             }
767         }
768     }
769
770     
771     /**
772      * Copies each element in the input collection except those equal to the
773      * given value to the output collection,
774      * @deprecated use Fitler.remove(Iterable,T,Collection);
775      */
776     static public <T> Collection <? super T>
777     removeAllCopy(Collection <? extends T> cin, Collection <? super T> cout, T value) {
778         return Filter.remove(cin, value, cout);
779     }
780
781     
782     /**
783      * Copies each element in the input collection except those equal to the
784      * given value (using the given Equality operator) to the output collection,
785      * @deprecated use Filter.remove(Iterable,T,Equality,Collection);
786      */
787     static public <T> Collection <? super T>
788     removeAllCopy(Collection <? extends T> cin, Collection <? super T> cout, T value, Equality<T> eq) {
789         return Filter.remove(cin, value, eq, cout);
790     }
791
792     
793     /**
794      * Copies each element in the input collection except those for which the
795      * given function returns TRUE to the output collection.
796      * @deprecated use Filter.remove(Iterable,UnaryFunctor,Collection)
797      */
798     static public <T> Collection <? super T>
799     removeAllCopy(Collection <? extends T> cin, Collection <? super T> cout,
800                   UnaryFunctor<T,Boolean > pred)
801     {
802         return Filter.remove(cin, pred, cout);
803     }
804
805     // ----------------------------------------------------------------------
806 // unique algorithms
807 // ----------------------------------------------------------------------
808
809     /**
810      * removes all adjacent duplicate values in the given list, using equals()
811      * to compare adjacent elements
812      */
813     static public <T> void unique(List <? extends T> lin) {
814         unique(lin, new EqualTo<T>());
815     }
816
817     
818     /**
819      * removes all adjacent duplicate values in the given list, using the given
820      * functor to compare adjacent elements
821      */
822     static public <T> void unique(List <? extends T> lin, BinaryFunctor<T,T,Boolean > eq) {
823         ListIterator <? extends T> liter = lin.listIterator();
824
825         T last = null;
826         // skip the first element, if there is one
827 if (liter.hasNext())
828             last = liter.next();
829
830         while (liter.hasNext()) {
831             T next = liter.next();
832             if (eq.fn(last, next).booleanValue()) {
833                 liter.remove();
834             }
835             else {
836                 last = next;
837             }
838         }
839     }
840
841     
842     /**
843      * Copies the elements from the input collection to the output collection,
844      * skipping adjacent duplicate elements.
845      * @deprecated use Unique.unique(Iterable,Collection)
846      */
847     static public <T, CT extends Collection <? super T>> CT
848     uniqueCopy(Collection <? extends T> cin, CT cout) {
849         return Unique.unique(cin, cout);
850     }
851
852     
853     /**
854      * Copies the elements from the input collection to the output collection,
855      * skipping adjacent duplicate elements.
856      * @deprecated use Unique.unique(Iterable,BinaryFunctor,Collection)
857      */
858     static public <T, CT extends Collection <? super T>> CT
859     uniqueCopy (Collection <? extends T> cin, CT cout, BinaryFunctor<T,T,Boolean > eq) {
860         return Unique.unique(cin, eq, cout);
861     }
862     
863     // ----------------------------------------------------------------------
864 // merge algorithms
865 // ----------------------------------------------------------------------
866
867     /**
868      * merges two collections, appending values to the output collection
869      * @deprecated use Merge.merge(Iterable,Iterable,Collection)
870      */
871     static public <T extends Comparable /*@*/<? super T>/*@*/> Collection <? super T>
872     mergeCopy (Collection <? extends T> cin1, Collection <? extends T> cin2,
873                Collection <? super T> cout)
874     {
875         return Merge.merge(cin1, cin2, cout);
876     }
877
878     
879     /**
880      * merges two collections using the given comparator, appending values to
881      * the output collection
882      * @deprecated use Merge.merge(Iterable,Iterable,Comparator,Collection)
883      */
884     static public <T> Collection <? super T>
885     mergeCopy (Collection <? extends T> cin1, Collection <? extends T> cin2,
886                Collection <? super T> cout, Comparator <T> comp)
887     {
888         return Merge.merge(cin1, cin2, comp, cout);
889     }
890
891
892     // ----------------------------------------------------------------------
893 // utilities (deprecated: moved to CollectionUtils)
894 // ----------------------------------------------------------------------
895
896     /**
897      * Adds all of the elements of the iterator to the collection. If necessary and possible,
898      * the collection will be enlarged: if enlarging the collection is not possible, then a
899      * runtime exception will be thrown. This is an augmentation of the
900      * Collection.addAll(Collection) API method.
901      * @returns true if the state of the collection was changed.
902      * @deprecated use CollectionUtils.addAll
903      */
904     static public <T> boolean addAll(Collection <? super T> cout, Iterator <T> iter) {
905         return CollectionUtils.addAll(cout, iter);
906     }
907
908     /**
909      * Adds all of the elements of the iterator to the collection and returns the collection.
910      * If necessary and possible, the collection will be enlarged: if enlarging the collection
911      * is not possible, then a runtime exception is thrown.
912      * @deprecated use CollectionUtils.append
913      */
914     static public <T,TCollection extends Collection <? super T>> TCollection
915     append(TCollection cout, Iterator <T> iter)
916     {
917         return CollectionUtils.append(cout, iter);
918     }
919
920
921     /**
922      * Adds all of the arguments to the collection and returns the collection. If necessary
923      * and possible, the collection will be enlarged: if enlarging the collection is not
924      * possible, then the runtime exception thrown. A similar method exists in Java 1.5,
925      * although it returns boolean rather than the collection.
926      * @deprecated use CollectionUtils.append
927      */
928     static public <T,TCollection extends Collection <? super T>> TCollection
929     append(TCollection cout, T... values)
930     {
931         return CollectionUtils.append(cout, values);
932     }
933 }
934

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags