Iterables


1   // ============================================================================
2   // $Id: Iterables.java,v 1.18 2006/09/02 03:10:33 davidahall Exp $
3   // Copyright (c) 2004-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.Arrays  ;
36  import java.util.Collection  ;
37  import java.util.Comparator  ;
38  import java.util.Iterator  ;
39  import net.sf.jga.algorithms.Filter;
40  import net.sf.jga.algorithms.Merge;
41  import net.sf.jga.algorithms.Transform;
42  import net.sf.jga.algorithms.Unique;
43  import net.sf.jga.fn.BinaryFunctor;
44  import net.sf.jga.fn.UnaryFunctor;
45  
46  import static net.sf.jga.util.ArrayUtils.*;
47  
48  /**
49   * Facade for the Iterators in this package, supporting the new forloop syntax.
50   * Only iterators that perform their service during the hasNext()/next()
51   * sequence are given in this facade.  Iterators that augment to the basic
52   * Iterator interface, (e.g., CachingIterator) are not included.
53   * <p>
54   * Copyright &copy; 2004-2005  David A. Hall
55   * @author <a HREF="mailto:davidahall@users.sf.net">David A. Hall</a>
56   */
57  
58  public class Iterables {
59      /**
60       * Returns iterators that point to the next instance in an iterable that
61       * meets the condition described in the functor.
62       */
63      static public <T> Iterable  <Iterator  <? extends T>>
64      findAll(Iterable  <? extends T> i, UnaryFunctor<Iterator  <? extends T>, ? extends Iterator  <T>> fn) {
65          return new FindAllIterator<T>(i.iterator(), fn);
66      }
67  
68      
69      /**
70       * Returns iterators that point to the next instance in an iterable that
71       * meets the condition described in the functor.
72       */
73      static public <T> Iterable  <Iterator  <? extends T>>
74      findAll(T[] ts, UnaryFunctor<Iterator  <? extends T>, ? extends Iterator  <T>> fn) {
75          return new FindAllIterator<T>(iterate(ts), fn);
76      }
77  
78      
79      /**
80       * Returns only elements for which the predicate is true
81       * @deprecated use Filter.filter(Iterable,UnaryFunctor) instead
82       */
83      static public <T> Iterable  <T> filter(Iterable  <? extends T> i, UnaryFunctor<T,Boolean  > pred) {
84          return Filter.filter(i, pred);
85      }
86  
87      
88      /**
89       * Returns only elements for which the predicate is true
90       * @deprecated use Filter.filter(T[], UnaryFunctor) instead
91       */
92      static public <T> Iterable  <T> filter(T[] ts, UnaryFunctor<T,Boolean  > pred) {
93          return Filter.filter(ts, pred);
94      }
95  
96      
97      /**
98       * Returns all elements of both iterables, always choosing the lesser of the
99       * two current elements.
100      * @deprecated use Merge.merge(Iterable,Iterable) instead
101      */
102     static public <T extends Comparable  /*EA2.2:*/<T>/**/> Iterable  <T>
103     merge(Iterable  <? extends T> i1, Iterable  <? extends T> i2) {
104         return Merge.merge(i1, i2);
105     }
106 
107  
108     /**
109      * Returns all elements of both arrays, always choosing the lesser of the
110      * two current elements.
111      * @deprecated use Merge.merge(T[],T[]) instead
112      */
113     static public <T extends Comparable  /*EA2.2:*/<T>/**/> Iterable  <T> merge(T[] ts1, T[] ts2) {
114         return Merge.merge(ts1, ts2);
115     }
116 
117  
118     /**
119      * Returns all elements of both iterables, always choosing the lesser of the
120      * two current elements.
121      * @deprecated use Merge.merge(Iterable,Iterable,Comparator) instead
122      */
123     static public <T> Iterable  <T>
124     merge(Iterable  <? extends T> i1,Iterable  <? extends T> i2,Comparator  <T> comp) {
125         return Merge.merge(i1, i2, comp);
126     }
127 
128  
129     /**
130      * Returns all elements of both arrays, always choosing the lesser of the
131      * two current elements.
132      * @deprecated use Merge.merge(T[],T[],Comparator) instead
133      */
134     static public <T> Iterable  <T> merge(T[] ts1, T[] ts2, Comparator  <T> comp) {
135         return Merge.merge(ts1, ts2, comp);
136     }
137 
138  
139     /**
140      * Returns all elements of both iterables, using the given predicate to
141      * choose which element to return.  If the predicate is true, choose the
142      * current element of the first iterable, otherwise choose the current
143      * element of the second iterable.  When one is exhausted, returns elements
144      * remaining in the other.
145      * @deprecated use Merge.merge(Iterable,Iterable,BinaryFunctor) instead
146      */
147     static public <T> Iterable  <T>
148     merge(Iterable  <? extends T> i1, Iterable  <? extends T> i2, BinaryFunctor<T,T,Boolean  > fn) {
149         return Merge.merge(i1, i2, fn);
150     }
151 
152  
153     /**
154      * Returns all elements of both arrays, using the given predicate to
155      * choose which element to return.  If the predicate is true, choose the
156      * current element of the first iterable, otherwise choose the current
157      * element of the second iterable.  When one is exhausted, returns elements
158      * remaining in the other.
159      * @deprecated use Merge.merge(T[],T[],BinaryFunctor) instead
160      */
161     static public <T> Iterable  <T> merge(T[] ts1, T[] ts2, BinaryFunctor<T,T,Boolean  > fn) {
162         return Merge.merge(ts1, ts2, fn);
163     }
164 
165     
166     /**
167      * Returns the results of applying the given functor to each element in turn.
168      * @deprecated use Transform.transform(Iterable,UnaryFunctor) instead
169      */
170     static public <T,R> Iterable  <R> transform(Iterable  <? extends T> i, UnaryFunctor<T,R> fn) {
171         return Transform.transform(i, fn);
172     }
173 
174     
175     /**
176      * Returns the results of applying the given functor to each element in turn.
177      * @deprecated use Transform.transform(T[],UnaryFunctor) instead
178      */
179     static public <T,R> Iterable  <R> transform(T[] ts, UnaryFunctor<T,R> fn) {
180         return Transform.transform(ts, fn);
181     }
182 
183     
184     /**
185      * Returns the results of applying the given functor to corresponding elements.
186      * @deprecated use Transform.transform(Iterable,Iterable,BinaryFunctor) instead
187      */
188     static public <T1,T2,R> Iterable  <R>
189     transform(Iterable  <? extends T1> i1, Iterable  <? extends T2>i2, BinaryFunctor<T1,T2,R> fn) {
190         return Transform.transform(i1, i2, fn);
191     }
192 
193     
194     /**
195      * Returns the results of applying the given functor to corresponding elements.
196      * @deprecated use Transform.transform(T1[],T2[],BinaryFunctor) instead
197      */
198     static public <T1,T2,R> Iterable  <R> transform(T1[] ts1, T2[] ts2, BinaryFunctor<T1,T2,R> fn) {
199         return Transform.transform(ts1, ts2, fn);
200     }
201 
202     
203     /**
204      * Returns the results of applying the given functor to succesive pairs of elements.
205      * @deprecated use Transform.transform(Iterable,BinaryFunctor) instead
206      */
207     static public <T,R> Iterable  <R> transform(Iterable  <? extends T> i, BinaryFunctor<T,T,R> fn) {
208         return Transform.transform(i, fn);
209     }
210 
211     
212     /**
213      * Returns the results of applying the given functor to succesive pairs of elements.
214      * @deprecated use Transform.transform(T[],BinaryFunctor) instead
215      */
216     static public <T,R> Iterable  <R> transform(T[] ts, BinaryFunctor<T,T,R> fn) {
217         return Transform.transform(ts, fn);
218     }
219 
220     
221     /**
222      * Returns unduplicated results: will not return the same value twice in
223      * succession.  This version uses T.equals() to test for equality.
224      * @deprecated use Unique.unique(Iterable) instead
225      */
226     static public <T> Iterable  <T> unique(Iterable  <? extends T> i) {
227         return Unique.unique(i);
228     }
229 
230     
231     /**
232      * Returns unduplicated results: will not return the same value twice in
233      * succession.  This version uses T.equals() to test for equality.
234      * @deprecated use Unique.unique(T[]) instead
235      */
236     static public <T> Iterable  <T> unique(T[] ts) {
237         return Unique.unique(ts);
238     }
239 
240     
241     /**
242      * Returns unduplicated results: will not return the same value twice in
243      * succession, as determined by the given predicate.  The predicate should
244      * return true when the adjacent items are the same.
245      * @deprecated use Unique.unique(Iterable,BinaryFunctor) instead
246      */
247     static public <T> Iterable  <T> unique(Iterable  <? extends T> i, BinaryFunctor<T,T,Boolean  > eq) {
248         return Unique.unique(i, eq);
249     }
250 
251     
252     /**
253      * Returns unduplicated results: will not return the same value twice in
254      * succession, as determined by the given predicate.  The predicate should
255      * return true when the adjacent items are the same.
256      * @deprecated use Unique.unique(T[],BinaryFunctor) instead
257      */
258     static public <T> Iterable  <T> unique(T[] ts, BinaryFunctor<T,T,Boolean  > eq) {
259         return Unique.unique(ts, eq);
260     }
261 
262     
263     /**
264      * Adds all of the elements of the iterable to the collection.  If
265      * necessary and possible, the collection will be enlarged: if enlarging
266      * the collection is not possible, then the runtime exception thrown.
267      * Augmentation of the Collection.addAll(Collection) API method.
268      * @deprecated use CollectionUtils.addAll
269      */
270     static public <T> boolean addAll(Collection  <? super T> cout, Iterable  <T> iter) {
271         return CollectionUtils.addAll(cout, iter.iterator());
272     }
273 
274     
275     /**
276      * Adds all of the elements of the array to the collection.  If
277      * necessary and possible, the collection will be enlarged: if enlarging
278      * the collection is not possible, then the runtime exception thrown.
279      * Augmentation of the Collection.addAll(Collection) API method.
280      * @deprecated use CollectionUtils.addAll
281      */
282     static public <T> boolean addAll(Collection  <? super T> cout, T[] ts) {
283         return CollectionUtils.addAll(cout, ts);
284     }
285     
286     /**
287      * Adds all of the elements of the iterable to the collection, and returns
288      * the collection.  If necessary and possible, the collection will be enlarged:
289      * if enlarging the collection is not possible, then the runtime exception thrown.
290      * Augmentation of the Collection.addAll(Collection) API method.
291      * @deprecated use CollectionUtils.append
292      */
293     static public <T> Collection  <? super T> append(Collection  <? super T> cout, Iterable  <T> iter) {
294         return CollectionUtils.append(cout, iter.iterator());
295     }
296 
297     
298     /**
299      * Adds all of the elements of the array to the collection and returns the
300      * collection.  If necessary and possible, the collection will be enlarged:
301      * if enlarging the collection is not possible, then the runtime exception
302      * thrown.  Augmentation of the Collection.addAll(Collection) API method.
303      * @deprecated use CollectionUtils.append
304      */
305     static public <T> Collection  <? super T> append(Collection  <? super T> cout, T[] ts) {
306         return CollectionUtils.append(cout, ts);
307     }
308 }
309
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags