commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From t.@apache.org
Subject svn commit: r1479760 - in /commons/proper/collections/trunk: ./ src/changes/ src/main/java/org/apache/commons/collections4/ src/main/java/org/apache/commons/collections4/iterators/ src/test/java/org/apache/commons/collections4/iterators/
Date Tue, 07 May 2013 05:12:07 GMT
Author: tn
Date: Tue May  7 05:12:06 2013
New Revision: 1479760

URL: http://svn.apache.org/r1479760
Log:
[COLLECTIONS-462] Added PeekingIterator. Thanks to Andy Seaborne

Added:
    commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/iterators/PeekingIterator.java
  (with props)
    commons/proper/collections/trunk/src/test/java/org/apache/commons/collections4/iterators/PeekingIteratorTest.java
  (with props)
Modified:
    commons/proper/collections/trunk/RELEASE-NOTES.txt
    commons/proper/collections/trunk/src/changes/changes.xml
    commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/IteratorUtils.java

Modified: commons/proper/collections/trunk/RELEASE-NOTES.txt
URL: http://svn.apache.org/viewvc/commons/proper/collections/trunk/RELEASE-NOTES.txt?rev=1479760&r1=1479759&r2=1479760&view=diff
==============================================================================
--- commons/proper/collections/trunk/RELEASE-NOTES.txt (original)
+++ commons/proper/collections/trunk/RELEASE-NOTES.txt Tue May  7 05:12:06 2013
@@ -62,6 +62,7 @@ Removed classes
 New classes
 -----------
 
+ o [COLLECTIONS-462] PeekingIterator - supports one-element lookahead during iteration. Thanks
to Andy Seaborne, Claude Warren.
  o [COLLECTIONS-432] CircularFifoQueue - analogous class to CircularFifoBuffer for the Queue
interface
                      PredicatedQueue - analogous class to PredicatedBuffer
                      TransformedQueue - analogous class to TransformedBuffer

Modified: commons/proper/collections/trunk/src/changes/changes.xml
URL: http://svn.apache.org/viewvc/commons/proper/collections/trunk/src/changes/changes.xml?rev=1479760&r1=1479759&r2=1479760&view=diff
==============================================================================
--- commons/proper/collections/trunk/src/changes/changes.xml (original)
+++ commons/proper/collections/trunk/src/changes/changes.xml Tue May  7 05:12:06 2013
@@ -22,6 +22,9 @@
   <body>
 
   <release version="4.0" date="TBA" description="Next release">
+    <action issue="COLLECTIONS-462" dev="tn" type="add" due-to="Andy Seaborne, Claude
Warren">
+      Added "PeekingIterator" decorator to support one-element lookahead during iteration.
+    </action>
     <action issue="COLLECTIONS-458" dev="sebb" type="remove">
       Removed unused class "AbstractUntypedCollectionDecorator&lt;E, D&gt;".
     </action>

Modified: commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/IteratorUtils.java
URL: http://svn.apache.org/viewvc/commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/IteratorUtils.java?rev=1479760&r1=1479759&r2=1479760&view=diff
==============================================================================
--- commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/IteratorUtils.java
(original)
+++ commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/IteratorUtils.java
Tue May  7 05:12:06 2013
@@ -50,6 +50,7 @@ import org.apache.commons.collections4.i
 import org.apache.commons.collections4.iterators.ObjectArrayIterator;
 import org.apache.commons.collections4.iterators.ObjectArrayListIterator;
 import org.apache.commons.collections4.iterators.ObjectGraphIterator;
+import org.apache.commons.collections4.iterators.PeekingIterator;
 import org.apache.commons.collections4.iterators.SingletonIterator;
 import org.apache.commons.collections4.iterators.SingletonListIterator;
 import org.apache.commons.collections4.iterators.TransformIterator;
@@ -801,6 +802,21 @@ public class IteratorUtils {
         return new NodeListIterator(node);
     }
 
+    // Peeking
+    //-----------------------------------------------------------------------
+
+    /**
+     * Gets an iterator that supports one-element lookahead.
+     *
+     * @param <E>  the element type
+     * @param iterator  the iterator to decorate, not null
+     * @return a peeking iterator
+     * @throws NullPointerException if the iterator is null
+     */
+    public static <E> Iterator<E> peekingIterator(final Iterator<? extends
E> iterator) {
+        return PeekingIterator.peekingIterator(iterator);
+    }
+
     // Views
     //-----------------------------------------------------------------------
     /**

Added: commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/iterators/PeekingIterator.java
URL: http://svn.apache.org/viewvc/commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/iterators/PeekingIterator.java?rev=1479760&view=auto
==============================================================================
--- commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/iterators/PeekingIterator.java
(added)
+++ commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/iterators/PeekingIterator.java
Tue May  7 05:12:06 2013
@@ -0,0 +1,160 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.collections4.iterators;
+
+import java.util.Iterator;
+import java.util.NoSuchElementException;
+
+/**
+ * Decorates an iterator to support one-element lookahead while iterating.
+ * <p>
+ * The decorator supports the removal operation, but an {@link IllegalStateException}
+ * will be thrown if {@link #remove()} is called directly after a call to
+ * {@link #peek()} or {@link #element()}.
+ *
+ * @since 4.0
+ * @version $Id$
+ */
+public class PeekingIterator<E> implements Iterator<E> {
+
+    /** The iterator being decorated. */
+    private final Iterator<? extends E> iterator;
+
+    /** Indicates that the decorated iterator is exhausted. */
+    private boolean exhausted = false;
+
+    /** Indicates if the lookahead slot is filled. */
+    private boolean slotFilled = false;
+
+    /** The current slot for lookahead. */
+    private E slot;
+
+    //-----------------------------------------------------------------------
+    /**
+     * Decorates the specified iterator to support one-element lookahead.
+     * <p>
+     * If the iterator is already a {@link PeekingIterator} it is returned directly.
+     *
+     * @param <E>  the element type
+     * @param iterator  the iterator to decorate
+     * @return a new peeking iterator
+     * @throws IllegalArgumentException if the iterator is null
+     */
+    public static <E> PeekingIterator<E> peekingIterator(final Iterator<?
extends E> iterator) {
+        if (iterator == null) {
+            throw new IllegalArgumentException("Iterator must not be null");
+        }
+        if (iterator instanceof PeekingIterator<?>) {
+            @SuppressWarnings("unchecked") // safe cast
+            final PeekingIterator<E> it = (PeekingIterator<E>) iterator;
+            return it;
+        }
+        return new PeekingIterator<E>(iterator);
+    }
+
+    //-----------------------------------------------------------------------
+
+    /**
+     * Constructor.
+     *
+     * @param iterator  the iterator to decorate
+     */
+    public PeekingIterator(final Iterator<? extends E> iterator) {
+        this.iterator = iterator;
+    }
+
+    private void fill() {
+        if (exhausted || slotFilled) {
+            return;
+        }
+        if (iterator.hasNext()) {
+            slot = iterator.next();
+            slotFilled = true;
+        } else {
+            exhausted = true;
+            slot = null;
+            slotFilled = false;
+        }
+    }
+
+    //-----------------------------------------------------------------------
+    public boolean hasNext() {
+        if (exhausted) {
+            return false;
+        }
+        return slotFilled ? true : iterator.hasNext();
+    }
+
+    /**
+     * Returns the next element in iteration without advancing the underlying iterator.
+     * If the iterator is already exhausted, null will be returned.
+     * <p>
+     * Note: this method does not throw a {@link NoSuchElementException} if the iterator
+     * is already exhausted. If you want such a behavior, use {@link #element()} instead.
+     * <p>
+     * The rationale behind this is to follow the {@link java.util.Queue} interface
+     * which uses the same terminology.
+     *
+     * @return the next element from the iterator
+     */
+    public E peek() {
+        fill();
+        return exhausted ? null : slot;
+    }
+
+    /**
+     * Returns the next element in iteration without advancing the underlying iterator.
+     * If the iterator is already exhausted, null will be returned.
+     *
+     * @return the next element from the iterator
+     * @throws NoSuchElementException if the iterator is already exhausted according to {@link
#hasNext()}
+     */
+    public E element() {
+        fill();
+        if (exhausted) {
+            throw new NoSuchElementException();
+        }
+        return slot;
+    }
+
+    public E next() {
+        if (!hasNext()) {
+            throw new NoSuchElementException();
+        }
+        final E x = slotFilled ? slot : iterator.next();
+        // reset the lookahead slot
+        slot = null;
+        slotFilled = false;
+        return x;
+    }
+
+    /**
+     * {@inheritDoc}
+     *
+     * @throws IllegalStateException if {@link #peek()} or {@link #element()} has been called
+     *   prior to the call to {@link #remove()}
+     */
+    public void remove() {
+        if (slotFilled) {
+            throw new IllegalStateException();
+        } else {
+            iterator.remove();
+        }
+    }
+
+}

Propchange: commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/iterators/PeekingIterator.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/iterators/PeekingIterator.java
------------------------------------------------------------------------------
    svn:keywords = Id Revision HeadURL

Propchange: commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/iterators/PeekingIterator.java
------------------------------------------------------------------------------
    svn:mime-type = text/plain

Added: commons/proper/collections/trunk/src/test/java/org/apache/commons/collections4/iterators/PeekingIteratorTest.java
URL: http://svn.apache.org/viewvc/commons/proper/collections/trunk/src/test/java/org/apache/commons/collections4/iterators/PeekingIteratorTest.java?rev=1479760&view=auto
==============================================================================
--- commons/proper/collections/trunk/src/test/java/org/apache/commons/collections4/iterators/PeekingIteratorTest.java
(added)
+++ commons/proper/collections/trunk/src/test/java/org/apache/commons/collections4/iterators/PeekingIteratorTest.java
Tue May  7 05:12:06 2013
@@ -0,0 +1,146 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.commons.collections4.iterators;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.Iterator;
+import java.util.List;
+import java.util.NoSuchElementException;
+
+import org.junit.Test;
+
+/**
+ * Tests the PeekingIterator.
+ *
+ * @version $Id$
+ */
+public class PeekingIteratorTest<E> extends AbstractIteratorTest<E> {
+
+    private String[] testArray = { "a", "b", "c" };
+
+    private List<E> testList;
+    
+    public PeekingIteratorTest(final String testName) {
+        super(testName);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @SuppressWarnings("unchecked")
+    @Override
+    protected void setUp() throws Exception {
+        super.setUp();
+        testList = new ArrayList<E>(Arrays.asList((E[]) testArray));
+    }
+
+    @Override
+    public Iterator<E> makeEmptyIterator() {
+        return PeekingIterator.peekingIterator(Collections.<E>emptyList().iterator());
+    }
+
+    @Override
+    public PeekingIterator<E> makeObject() {
+        return PeekingIterator.peekingIterator(testList.iterator());
+    }
+
+    @Override
+    public boolean supportsRemove() {
+        return true;
+    }
+
+    //-----------------------------------------------------------------------
+    
+    @Test
+    public void testEmpty() {
+        Iterator<E> it = makeEmptyIterator();
+        assertFalse(it.hasNext());
+    }
+
+    @Test
+    @SuppressWarnings("unchecked")
+    public void testSinglePeek() {
+        PeekingIterator<E> it = makeObject();
+        assertEquals("a", it.peek());
+        assertEquals("a", it.element());
+        validate(it, (E[]) testArray);
+    }
+
+    @Test
+    public void testMultiplePeek() {
+        PeekingIterator<E> it = makeObject();
+        assertEquals("a", it.peek());
+        assertEquals("a", it.peek());
+        assertEquals("a", it.next());
+        assertTrue(it.hasNext());
+        assertEquals("b", it.peek());
+        assertEquals("b", it.peek());
+        assertEquals("b", it.next());
+        assertTrue(it.hasNext());
+        assertEquals("c", it.peek());
+        assertEquals("c", it.peek());
+        assertEquals("c", it.next());
+        assertFalse(it.hasNext());
+    }
+    
+    @Test
+    public void testIteratorExhausted() {
+        PeekingIterator<E> it = makeObject();
+        it.next();
+        it.next();
+        it.next();
+        assertFalse(it.hasNext());
+        assertNull(it.peek());
+        
+        try {
+            it.element();
+            fail();
+        } catch (NoSuchElementException e) {
+            // expected
+        }
+    }
+
+    @Test
+    public void testIllegalRemove() {
+        PeekingIterator<E> it = makeObject();
+        it.next();
+        it.remove(); // supported
+        
+        assertTrue(it.hasNext());
+        assertEquals("b", it.peek());
+        
+        try {
+            it.remove();
+            fail();
+        } catch (IllegalStateException e) {
+            // expected
+        }
+    }
+
+    private void validate(Iterator<E> iter, E... items) {
+        for (E x : items) {
+            assertTrue(iter.hasNext());
+            assertEquals(x, iter.next());
+        }
+        assertFalse(iter.hasNext());
+    }
+
+}

Propchange: commons/proper/collections/trunk/src/test/java/org/apache/commons/collections4/iterators/PeekingIteratorTest.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: commons/proper/collections/trunk/src/test/java/org/apache/commons/collections4/iterators/PeekingIteratorTest.java
------------------------------------------------------------------------------
    svn:keywords = Id Revision HeadURL

Propchange: commons/proper/collections/trunk/src/test/java/org/apache/commons/collections4/iterators/PeekingIteratorTest.java
------------------------------------------------------------------------------
    svn:mime-type = text/plain



Mime
View raw message