Apache
/
commons-collections
mirror of https://github.com/apache/commons-collections.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[COLLECTIONS-463] Add PushbackIterator. Thanks to Andy Seaborne. 

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/collections/trunk@1479763 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Thomas Neidhart 2013-05-07 05:28:39 +00:00
parent d16f842887
commit 54bbca8904
5 changed files with 251 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
RELEASE-NOTES.txt
View File

@ -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

3
src/changes/changes.xml
View File

@ -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>

18
src/main/java/org/apache/commons/collections4/IteratorUtils.java
View File

@ -51,6 +51,7 @@ 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.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
//-----------------------------------------------------------------------
/**

108
src/main/java/org/apache/commons/collections4/iterators/PushbackIterator.java Normal file
View File

@ -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();
}
}

121
src/test/java/org/apache/commons/collections4/iterators/PushbackIteratorTest.java Normal file
View File

@ -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());
}
}