You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by tn...@apache.org on 2013/05/07 07:12:07 UTC
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/
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<E, D>".
</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