commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From chtom...@apache.org
Subject [31/34] commons-collections git commit: PR: COLLECTIONS-331 Documented the requirement to use a comparator.
Date Tue, 11 Jul 2017 17:54:43 GMT
PR: COLLECTIONS-331
Documented the requirement to use a comparator.


git-svn-id: https://svn.apache.org/repos/asf/commons/proper/collections/branches/COLLECTIONS_3_2_BRANCH@1079587
13f79535-47bb-0310-9956-ffa450edef68


Project: http://git-wip-us.apache.org/repos/asf/commons-collections/repo
Commit: http://git-wip-us.apache.org/repos/asf/commons-collections/commit/ef4dd46d
Tree: http://git-wip-us.apache.org/repos/asf/commons-collections/tree/ef4dd46d
Diff: http://git-wip-us.apache.org/repos/asf/commons-collections/diff/ef4dd46d

Branch: refs/heads/COLLECTIONS_3_2_BRANCH
Commit: ef4dd46dbd48992830a94fcfc0a6d15f85bb1beb
Parents: 1c23c02
Author: Jochen Wiedmann <jochen@apache.org>
Authored: Tue Mar 8 22:31:49 2011 +0000
Committer: Jochen Wiedmann <jochen@apache.org>
Committed: Tue Mar 8 22:31:49 2011 +0000

----------------------------------------------------------------------
 .../iterators/CollatingIterator.java            | 35 +++++++++++++++-----
 .../iterators/TestCollatingIterator.java        | 22 ++++++++++++
 2 files changed, 49 insertions(+), 8 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/commons-collections/blob/ef4dd46d/src/java/org/apache/commons/collections/iterators/CollatingIterator.java
----------------------------------------------------------------------
diff --git a/src/java/org/apache/commons/collections/iterators/CollatingIterator.java b/src/java/org/apache/commons/collections/iterators/CollatingIterator.java
index 4451319..94c80da 100644
--- a/src/java/org/apache/commons/collections/iterators/CollatingIterator.java
+++ b/src/java/org/apache/commons/collections/iterators/CollatingIterator.java
@@ -60,8 +60,10 @@ public class CollatingIterator implements Iterator {
     // Constructors
     // ----------------------------------------------------------------------
     /**
-     * Constructs a new <code>CollatingIterator</code>.  Natural sort order
-     * will be used, and child iterators will have to be manually added 
+     * Constructs a new <code>CollatingIterator</code>. A comparator must be
+     * set by calling {@link #setComparator(Comparator)} before invoking
+     * {@link #hasNext()}, or {@link #next()} for the first time. Child
+     * iterators will have to be manually added using the
      * using the {@link #addIterator(Iterator)} method.
      */
     public CollatingIterator() {
@@ -73,7 +75,9 @@ public class CollatingIterator implements Iterator {
      * specified comparator for ordering.  Child iterators will have to be 
      * manually added using the {@link #addIterator(Iterator)} method.
      *
-     * @param comp  the comparator to use to sort, or null to use natural sort order
+     * @param comp the comparator to use to sort; must not be null,
+     *   unless you'll be invoking {@link #setComparator(Comparator)}
+     *   later on.
      */
     public CollatingIterator(final Comparator comp) {
         this(comp,2);
@@ -85,7 +89,9 @@ public class CollatingIterator implements Iterator {
      * capacity.  Child iterators will have to be 
      * manually added using the {@link #addIterator(Iterator)} method.
      *
-     * @param comp  the comparator to use to sort, or null to use natural sort order
+     * @param comp the comparator to use to sort; must not be null,
+     *   unless you'll be invoking {@link #setComparator(Comparator)}
+     *   later on.
      * @param initIterCapacity  the initial capacity for the internal list
      *    of child iterators
      */
@@ -99,7 +105,9 @@ public class CollatingIterator implements Iterator {
      * specified comparator to provide ordered iteration over the two
      * given iterators.
      *
-     * @param comp  the comparator to use to sort, or null to use natural sort order
+     * @param comp the comparator to use to sort; must not be null,
+     *   unless you'll be invoking {@link #setComparator(Comparator)}
+     *   later on.
      * @param a  the first child ordered iterator
      * @param b  the second child ordered iterator
      * @throws NullPointerException if either iterator is null
@@ -115,7 +123,9 @@ public class CollatingIterator implements Iterator {
      * specified comparator to provide ordered iteration over the array
      * of iterators.
      *
-     * @param comp  the comparator to use to sort, or null to use natural sort order
+     * @param comp the comparator to use to sort; must not be null,
+     *   unless you'll be invoking {@link #setComparator(Comparator)}
+     *   later on.
      * @param iterators  the array of iterators
      * @throws NullPointerException if iterators array is or contains null
      */
@@ -131,7 +141,9 @@ public class CollatingIterator implements Iterator {
      * specified comparator to provide ordered iteration over the collection
      * of iterators.
      *
-     * @param comp  the comparator to use to sort, or null to use natural sort order
+     * @param comp the comparator to use to sort; must not be null,
+     *   unless you'll be invoking {@link #setComparator(Comparator)}
+     *   later on.
      * @param iterators  the collection of iterators
      * @throws NullPointerException if the iterators collection is or contains null
      * @throws ClassCastException if the iterators collection contains an
@@ -196,7 +208,11 @@ public class CollatingIterator implements Iterator {
     }
 
     /**
-     * Sets the {@link Comparator} by which collation occurs.
+     * Sets the {@link Comparator} by which collation occurs. If you
+     * would like to use the natural sort order (or, in other words,
+     * if the elements in the iterators are implementing the
+     * {@link java.lang.Comparable} interface), then use the
+     * {@link org.apache.commons.collections.comparators.ComparableComparator}.
      * 
      * @throws IllegalStateException if iteration has started
      */
@@ -331,6 +347,9 @@ public class CollatingIterator implements Iterator {
                     leastObject = values.get(i);
                 } else {
                     Object curObject = values.get(i);
+                    if (comparator == null) {
+                        throw new NullPointerException("You must invoke setComparator() to
set a compator first.");
+                    }
                     if (comparator.compare(curObject,leastObject) < 0) {
                         leastObject = curObject;
                         leastIndex = i;

http://git-wip-us.apache.org/repos/asf/commons-collections/blob/ef4dd46d/src/test/org/apache/commons/collections/iterators/TestCollatingIterator.java
----------------------------------------------------------------------
diff --git a/src/test/org/apache/commons/collections/iterators/TestCollatingIterator.java
b/src/test/org/apache/commons/collections/iterators/TestCollatingIterator.java
index b844a7d..a108644 100644
--- a/src/test/org/apache/commons/collections/iterators/TestCollatingIterator.java
+++ b/src/test/org/apache/commons/collections/iterators/TestCollatingIterator.java
@@ -17,8 +17,10 @@
 package org.apache.commons.collections.iterators;
 
 import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.Comparator;
 import java.util.Iterator;
+import java.util.List;
 
 import junit.framework.Test;
 import junit.framework.TestSuite;
@@ -207,5 +209,25 @@ public class TestCollatingIterator extends AbstractTestIterator {
         assertEquals(expectedSize,(evens.size() + odds.size()));
     }   
 
+    public void testNullComparator() {
+        List l1 = Arrays.asList(new Integer[]{new Integer(1), new Integer(3), new Integer(5)});
+        List l2 = Arrays.asList(new Integer[]{new Integer(2), new Integer(4), new Integer(6)});
+
+        CollatingIterator collatingIterator1 = new CollatingIterator(null, l1.iterator(),
l2.iterator());
+        try {
+            collatingIterator1.next();
+        } catch (NullPointerException e) {
+            assertTrue(e.getMessage().startsWith("You must invoke setComparator"));
+        }
+
+        int i = 0;
+        CollatingIterator collatingIterator2 = new CollatingIterator(null, l1.iterator(),
l2.iterator());
+        collatingIterator2.setComparator(new ComparableComparator());
+        for ( ; collatingIterator2.hasNext(); i++ ) {
+            Integer n = (Integer)collatingIterator2.next();
+            assertEquals("wrong order", n.intValue(), i + 1);
+        }
+        assertEquals("wrong size", i, l1.size() + l2.size());
+    }
 }
 


Mime
View raw message