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:28:39 UTC
svn commit: r1479763 - 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:28:39 2013
New Revision: 1479763
URL: http://svn.apache.org/r1479763
Log:
[COLLECTIONS-463] Add PushbackIterator. Thanks to Andy Seaborne.
Added:
commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/iterators/PushbackIterator.java (with props)
commons/proper/collections/trunk/src/test/java/org/apache/commons/collections4/iterators/PushbackIteratorTest.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=1479763&r1=1479762&r2=1479763&view=diff
==============================================================================
--- commons/proper/collections/trunk/RELEASE-NOTES.txt (original)
+++ commons/proper/collections/trunk/RELEASE-NOTES.txt Tue May 7 05:28:39 2013
@@ -62,6 +62,7 @@ Removed classes
New classes
-----------
+ o [COLLECTIONS-463] PushbackIterator - supports pushback of elements during iteration. Thanks to Andy Seaborne, Claude Warren.
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
Modified: commons/proper/collections/trunk/src/changes/changes.xml
URL: http://svn.apache.org/viewvc/commons/proper/collections/trunk/src/changes/changes.xml?rev=1479763&r1=1479762&r2=1479763&view=diff
==============================================================================
--- commons/proper/collections/trunk/src/changes/changes.xml (original)
+++ commons/proper/collections/trunk/src/changes/changes.xml Tue May 7 05:28:39 2013
@@ -22,6 +22,9 @@
<body>
<release version="4.0" date="TBA" description="Next release">
+ <action issue="COLLECTIONS-463" dev="tn" type="add" due-to="Andy Seaborne, Claude Warren">
+ Added "PushbackIterator" decorator to support pushback of elements during iteration.
+ </action>
<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>
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=1479763&r1=1479762&r2=1479763&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:28:39 2013
@@ -51,6 +51,7 @@ import org.apache.commons.collections4.i
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.PushbackIterator;
import org.apache.commons.collections4.iterators.SingletonIterator;
import org.apache.commons.collections4.iterators.SingletonListIterator;
import org.apache.commons.collections4.iterators.TransformIterator;
@@ -814,11 +815,28 @@ public class IteratorUtils {
* @param iterator the iterator to decorate, not null
* @return a peeking iterator
* @throws NullPointerException if the iterator is null
+ * @since 4.0
*/
public static <E> Iterator<E> peekingIterator(final Iterator<? extends E> iterator) {
return PeekingIterator.peekingIterator(iterator);
}
+ // Pushback
+ //-----------------------------------------------------------------------
+
+ /**
+ * Gets an iterator that supports pushback of elements.
+ *
+ * @param <E> the element type
+ * @param iterator the iterator to decorate, not null
+ * @return a pushback iterator
+ * @throws NullPointerException if the iterator is null
+ * @since 4.0
+ */
+ public static <E> Iterator<E> pushbackIterator(final Iterator<? extends E> iterator) {
+ return PushbackIterator.pushbackIterator(iterator);
+ }
+
// Views
//-----------------------------------------------------------------------
/**
Added: commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/iterators/PushbackIterator.java
URL: http://svn.apache.org/viewvc/commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/iterators/PushbackIterator.java?rev=1479763&view=auto
==============================================================================
--- commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/iterators/PushbackIterator.java (added)
+++ commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/iterators/PushbackIterator.java Tue May 7 05:28:39 2013
@@ -0,0 +1,108 @@
+/*
+ * 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 org.apache.commons.collections4.ArrayStack;
+
+/**
+ * Decorates an iterator to support pushback of elements.
+ * <p>
+ * The decorator stores the pushed back elements in a LIFO manner: the last element
+ * that has been pushed back, will be returned as the next element in a call to {@link #next()}.
+ * <p>
+ * The decorator does not support the removal operation. Any call to {@link #remove()} will
+ * result in an {@link UnsupportedOperationException}.
+ *
+ * @since 4.0
+ * @version $Id$
+ */
+@SuppressWarnings("deprecation") // replace ArrayStack with ArrayDeque when moving to Java 6
+public class PushbackIterator<E> implements Iterator<E> {
+
+ /** The iterator being decorated. */
+ private final Iterator<? extends E> iterator;
+
+ /** The LIFO queue containing the pushed back items. */
+ private ArrayStack<E> items = new ArrayStack<E>();
+
+ //-----------------------------------------------------------------------
+ /**
+ * 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> PushbackIterator<E> pushbackIterator(final Iterator<? extends E> iterator) {
+ if (iterator == null) {
+ throw new IllegalArgumentException("Iterator must not be null");
+ }
+ if (iterator instanceof PushbackIterator<?>) {
+ @SuppressWarnings("unchecked") // safe cast
+ final PushbackIterator<E> it = (PushbackIterator<E>) iterator;
+ return it;
+ }
+ return new PushbackIterator<E>(iterator);
+ }
+
+ //-----------------------------------------------------------------------
+
+ /**
+ * Constructor.
+ *
+ * @param iterator the iterator to decorate
+ */
+ public PushbackIterator(final Iterator<? extends E> iterator) {
+ super();
+ this.iterator = iterator;
+ }
+
+ /**
+ * Push back the given element to the iterator.
+ * <p>
+ * Calling {@link #next()} immediately afterwards will return exactly this element.
+ *
+ * @param item the element to push back to the iterator
+ */
+ public void pushback(final E item) {
+ items.push(item);
+ }
+
+ public boolean hasNext() {
+ return !items.isEmpty() ? true : iterator.hasNext();
+ }
+
+ public E next() {
+ return !items.isEmpty() ? items.pop() : iterator.next();
+ }
+
+ /**
+ * This iterator will always throw an {@link UnsupportedOperationException}.
+ *
+ * @throws UnsupportedOperationException always
+ */
+ public void remove() {
+ throw new UnsupportedOperationException();
+ }
+
+}
Propchange: commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/iterators/PushbackIterator.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/iterators/PushbackIterator.java
------------------------------------------------------------------------------
svn:keywords = Id Revision HeadURL
Propchange: commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/iterators/PushbackIterator.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: commons/proper/collections/trunk/src/test/java/org/apache/commons/collections4/iterators/PushbackIteratorTest.java
URL: http://svn.apache.org/viewvc/commons/proper/collections/trunk/src/test/java/org/apache/commons/collections4/iterators/PushbackIteratorTest.java?rev=1479763&view=auto
==============================================================================
--- commons/proper/collections/trunk/src/test/java/org/apache/commons/collections4/iterators/PushbackIteratorTest.java (added)
+++ commons/proper/collections/trunk/src/test/java/org/apache/commons/collections4/iterators/PushbackIteratorTest.java Tue May 7 05:28:39 2013
@@ -0,0 +1,121 @@
+/*
+ * 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 org.junit.Test;
+
+/**
+ * Tests the PushbackIterator.
+ *
+ * @version $Id$
+ */
+public class PushbackIteratorTest<E> extends AbstractIteratorTest<E> {
+
+ private String[] testArray = { "a", "b", "c" };
+
+ private List<E> testList;
+
+ public PushbackIteratorTest(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 PushbackIterator.pushbackIterator(Collections.<E> emptyList().iterator());
+ }
+
+ @Override
+ public PushbackIterator<E> makeObject() {
+ return PushbackIterator.pushbackIterator(testList.iterator());
+ }
+
+ @Override
+ public boolean supportsRemove() {
+ return false;
+ }
+
+ // -----------------------------------------------------------------------
+
+ @Test
+ public void testNormalIteration() {
+ PushbackIterator<E> iter = makeObject();
+ assertEquals("a", iter.next());
+ assertEquals("b", iter.next());
+ assertEquals("c", iter.next());
+ assertFalse(iter.hasNext());
+ }
+
+ @Test
+ @SuppressWarnings("unchecked")
+ public void testImmediatePushback() {
+ PushbackIterator<E> iter = makeObject();
+ iter.pushback((E) "x");
+ assertEquals("x", iter.next());
+ assertEquals("a", iter.next());
+ validate(iter, "b", "c");
+ }
+
+ @Test
+ @SuppressWarnings("unchecked")
+ public void testDelayedPushback() {
+ PushbackIterator<E> iter = makeObject();
+ assertEquals("a", iter.next());
+ iter.pushback((E) "x");
+ assertEquals("x", iter.next());
+ assertEquals("b", iter.next());
+ validate(iter, "c");
+ }
+
+ @Test
+ @SuppressWarnings("unchecked")
+ public void testMultiplePushback() {
+ PushbackIterator<E> iter = makeObject();
+ assertEquals("a", iter.next());
+ iter.pushback((E) "x");
+ iter.pushback((E) "y");
+ assertEquals("y", iter.next());
+ assertEquals("x", iter.next());
+ assertEquals("b", iter.next());
+ validate(iter, "c");
+ }
+
+ private void validate(Iterator<E> iter, Object... items) {
+ for (final Object 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/PushbackIteratorTest.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: commons/proper/collections/trunk/src/test/java/org/apache/commons/collections4/iterators/PushbackIteratorTest.java
------------------------------------------------------------------------------
svn:keywords = Id Revision HeadURL
Propchange: commons/proper/collections/trunk/src/test/java/org/apache/commons/collections4/iterators/PushbackIteratorTest.java
------------------------------------------------------------------------------
svn:mime-type = text/plain