- Nixed CompoundIterator, made Collections.getMetaIterator() handle

elements in the passed in collection that are Iterators or Collections.
- Nixed SortedIterator, added variants of getSortedIterator() to
  Collections.
- Also added getUnmodifiableIterator() and getRandomIterator() to
  Collections.


git-svn-id: https://samskivert.googlecode.com/svn/trunk@1696 6335cc39-0255-0410-8fd6-9bcaacd3b74c

projects/samskivert/src/java/com/samskivert/util/Collections.java

@@ -15,14 +15,118 @@ import java.util.*;
 public class Collections
 {
     /**
-     * Returns an iterator that iterates over all the elements contained
+     * Returns an Iterator that iterates over all the elements contained
-     * within the collections within the specified collection.
+     * within the Collections within the specified Collection.
+     *
+     * @param metaCollection a collection of either other Collections and/or
+     * of Iterators.
      */
     public static Iterator getMetaIterator (Collection metaCollection)
     {
         return new MetaIterator(metaCollection);
     }
 
+    /**
+     * Get an Iterator over the supplied Collection that returns the
+     * elements in their natural order.
+     */
+    public static Iterator getSortedIterator (Collection coll)  
+    {
+        return getSortedIterator(coll.iterator(), Comparators.COMPARABLE);
+    }
+
+    /**
+     * Get an Iterator over the supplied Collection that returns the
+     * elements in the order dictated by the supplied Comparator.
+     */
+    public static Iterator getSortedIterator (Collection coll,
+                                              Comparator comparator)
+    {
+        return getSortedIterator(coll.iterator(), comparator);
+    }
+
+    /**
+     * Get an Iterator that returns the same elements returned by
+     * the supplied Iterator, but in their natural order.
+     */
+    public static Iterator getSortedIterator (Iterator itr)
+    {
+        return getSortedIterator(itr, Comparators.COMPARABLE);
+    }
+
+    /**
+     * Get an Iterator that returns the same elements returned by
+     * the supplied Iterator, but in the order dictated by the supplied
+     * Comparator.
+     */
+    public static Iterator getSortedIterator (Iterator itr,
+                                              Comparator comparator)
+    {
+        SortableArrayList list = new SortableArrayList();
+        while (itr.hasNext()) {
+            list.insertSorted(itr.next(), comparator);
+        }
+        return getUnmodifiableIterator(list);
+    }
+
+    /**
+     * Get an Iterator over the supplied Collection that returns
+     * the elements in a completely random order. Normally Iterators
+     * return elements in an undefined order, but it is usually the same
+     * between different invocations as long as the underlying Collection
+     * has not changed. This method mixes things up.
+     */
+    public static Iterator getRandomIterator (Collection c)
+    {
+        return getRandomIterator(c.iterator());
+    }
+
+    /**
+     * Get an Iterator that returns the same elements returned by
+     * the supplied Iterator, but in a completely random order.
+     */
+    public static Iterator getRandomIterator (Iterator itr)
+    {
+        ArrayList list = new ArrayList();
+        CollectionUtil.addAll(list, itr);
+        java.util.Collections.shuffle(list);
+        return getUnmodifiableIterator(list);
+    }
+
+    /**
+     * Get an Iterator that returns the elements in the supplied
+     * Collection but blocks removal.
+     */
+    public static Iterator getUnmodifiableIterator (Collection c)
+    {
+        return getUnmodifiableIterator(c.iterator());
+    }
+
+    /**
+     * Get an iterator that returns the same elements as the supplied
+     * iterator but blocks removal.
+     */
+    public static Iterator getUnmodifiableIterator (final Iterator itr)
+    {
+        return new Iterator() {
+            public boolean hasNext ()
+            {
+                return itr.hasNext();
+            }
+
+            public Object next ()
+            {
+                return itr.next();
+            }
+
+            public void remove ()
+            {
+                throw new UnsupportedOperationException(
+                    "Cannot remove from an UnmodifieableIterator!");
+            }
+        };
+    }
+
     /**
      * Returns a synchronized (thread-safe) int map backed by the
      * specified int map.  In order to guarantee serial access, it is
@@ -287,7 +391,21 @@ public class Collections
         {
             while ((_current == null) || (!_current.hasNext())) {
                 if (_meta.hasNext()) {
-                    _current = ((Collection) _meta.next()).iterator();
+                    Object o = _meta.next();
+                    if (o instanceof Iterator) {
+                        _current = (Iterator) o;
+                    // TODO: jdk1.5,
+                    // (obsoletes the Collection case, below)
+                    //} else if (o instanceof Iterable) {
+                    //    _current = ((Iterable) o).iterator();
+                    } else if (o instanceof Collection) {
+                        _current = ((Collection) o).iterator();
+                    } else {
+                        throw new IllegalArgumentException(
+                            "MetaIterator must be constructed with a " +
+                            "collection of Iterators or other collections.");
+                    }
+
                 } else {
                     return false;
                 }

projects/samskivert/src/java/com/samskivert/util/CompoundIterator.java

@@ -1,101 +0,0 @@
-//
-// $Id: CompoundIterator.java,v 1.2 2001/11/26 19:21:33 mdb Exp $
-//
-// samskivert library - useful routines for java programs
-// Copyright (C) 2001 Michael Bayne
-// 
-// This library is free software; you can redistribute it and/or modify it
-// under the terms of the GNU Lesser General Public License as published
-// by the Free Software Foundation; either version 2.1 of the License, or
-// (at your option) any later version.
-//
-// This library is distributed in the hope that it will be useful,
-// but WITHOUT ANY WARRANTY; without even the implied warranty of
-// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-// Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public
-// License along with this library; if not, write to the Free Software
-// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
-
-package com.samskivert.util;
-
-import java.util.Iterator;
-import java.util.NoSuchElementException;
-
-/**
- * Iterates over a collection of iterators, moving seamlessly from one
- * iterator to the next as the first runs out of elements. Iterators are
- * made available to the compound iterator via the succinct and functional
- * {@link IteratorProvider} interface.
- */
-public class CompoundIterator implements Iterator
-{
-    /** Used to obtain the set of iterators over which we will iterate. */
-    public static interface IteratorProvider
-    {
-        /**
-         * Returns the next iterator in the set. Should return null when
-         * we've run out of iterators.
-         */
-        public Iterator nextIterator ();
-    }
-
-    /**
-     * Constructs a compound iterator that will iterate over all of the
-     * iterators provided by the supplied provider, in turn.
-     */
-    public CompoundIterator (IteratorProvider provider)
-    {
-        _provider = provider;
-        // move to the first iterator
-        _iter = _provider.nextIterator();
-    }
-
-    // documentation inherited
-    public boolean hasNext ()
-    {
-        // keep trying iterators until we run out or find an element
-        while (_iter != null) {
-            if (_iter.hasNext()) {
-                return true;
-            } else {
-                _iter = _provider.nextIterator();
-            }
-        }
-
-        return false;
-    }
-
-    // documentation inherited
-    public Object next ()
-    {
-        // keep trying iterators until we run out or find an element
-        while (_iter != null) {
-            try {
-                return _iter.next();
-            } catch (NoSuchElementException nsee) {
-                // have to catch this and move to the next iterator
-                _iter = _provider.nextIterator();
-            }
-        }
-
-        throw new NoSuchElementException();
-    }
-
-    // documentation inherited
-    public void remove ()
-    {
-        if (_iter != null) {
-            _iter.remove();
-        } else {
-            throw new IllegalStateException();
-        }
-    }
-
-    /** Our provider of iterators. */
-    protected IteratorProvider _provider;
-
-    /** The iterator currently in use. */
-    protected Iterator _iter;
-}

projects/samskivert/src/java/com/samskivert/util/SortedIterator.java

@@ -1,78 +0,0 @@
-//
-// $Id: SortedIterator.java,v 1.1 2003/12/17 21:58:06 ray Exp $
-
-package com.samskivert.util;
-
-import java.util.Collection;
-import java.util.Comparator;
-import java.util.Iterator;
-
-/**
- * An iterator that returns the elements from another iterator into
- * some sorted order.
- */
-public class SortedIterator implements Iterator
-{
-    /**
-     * Construct a sorted iterator that iterates through the specified
-     * elements in natural order.
-     */
-    public SortedIterator (Iterator itr)
-    {
-        this(itr, Comparators.COMPARABLE);
-    }
-
-    /**
-     * Construct a sorted iterator that iterates through the specified
-     * elements in the order according to the specified comparator.
-     */
-    public SortedIterator (Iterator itr, Comparator comparator)
-    {
-        SortableArrayList list = new SortableArrayList();
-        while (itr.hasNext()) {
-            list.insertSorted(itr.next(), comparator);
-        }
-        _itr = list.iterator();
-    }
-
-    /**
-     * Construct a sorted iterator that iterates through the specified
-     * collection in natural order.
-     */
-    public SortedIterator (Collection c)
-    {
-        this(c.iterator());
-    }
-
-    /**
-     * Construct a sorted iterator that iterates through the specified
-     * collection in the order according to the specified comparator.
-     */
-    public SortedIterator (Collection c, Comparator comparator)
-    {
-        this(c.iterator(), comparator);
-    }
-
-    // documentation inherited from interface Iterator
-    public boolean hasNext ()
-    {
-        return _itr.hasNext();
-    }
-
-    // documentation inherited from interface Iterator
-    public Object next ()
-    {
-        return _itr.next();
-    }
-
-    // documentation inherited from interface Iterator
-    public void remove ()
-    {
-        // sadly, we cannot
-        throw new UnsupportedOperationException(
-            "Cannot remove from a SortedIterator");
-    }
-
-    /** The iterator we are a wrapper around. */
-    protected Iterator _itr;
-}