started with reiterators, iterator algorithms

pom.xml

@@ -66,6 +66,12 @@
 			<version>4.0.0</version>
 		</dependency>
 
+		<dependency>
+			<groupId>net.markenwerk</groupId>
+			<artifactId>commons-datastructures</artifactId>
+			<version>4.0.1</version>
+		</dependency>
+
 		<dependency>
 			<groupId>net.markenwerk</groupId>
 			<artifactId>commons-datastructures</artifactId>

src/main/java/net/markenwerk/commons/iterators/AbstractProtectedReiterator.java

@@ -0,0 +1,23 @@
+package net.markenwerk.commons.iterators;
+
+/**
+ * An {@link AbstractProtectedReiterator} is a base implementation for
+ * {@link ProtectedReiterator} that guarantees that every call to
+ * {@linkplain AbstractProtectedReiterator#remove()} throws an
+ * {@link UnsupportedOperationException}.
+ * 
+ * @param <Payload>
+ *            The payload type.
+ * @author Torsten Krause (tk at markenwerk dot net)
+ * @since 3.1.1
+ */
+public abstract class AbstractProtectedReiterator<Payload> extends AbstractProtectedIterator<Payload> implements
+		ProtectedReiterator<Payload> {
+
+	/**
+	 * Creates a new {@link AbstractProtectedReiterator}.
+	 */
+	protected AbstractProtectedReiterator() {
+	}
+
+}

src/main/java/net/markenwerk/commons/iterators/Iterators.java

@@ -0,0 +1,33 @@
+package net.markenwerk.commons.iterators;
+
+import java.util.Iterator;
+import java.util.NoSuchElementException;
+
+import net.markenwerk.commons.interfaces.Predicate;
+
+public abstract class Iterators {
+
+	private Iterators() {
+	}
+
+	public static <Payload> int firstIndexOf(Iterator<? extends Payload> iterator, int firstIndex,
+			Predicate<Payload> predicate) throws IllegalArgumentException, NoSuchElementException {
+		if (null == iterator) {
+			throw new IllegalArgumentException("The given iterator is null");
+		} else if (firstIndex < 0) {
+			throw new IllegalArgumentException("The given first index is negative: " + firstIndex);
+		} else if (null == predicate) {
+			throw new IllegalArgumentException("The given predicate is null");
+		}
+		int index = 0;
+		while (iterator.hasNext()) {
+			Payload payload = iterator.next();
+			if (index >= firstIndex && predicate.test(payload)) {
+				return index;
+			}
+			index += 1;
+		}
+		throw new NoSuchElementException("No payload value in the given iterator satisfies the given predicate");
+	}
+
+}

src/main/java/net/markenwerk/commons/iterators/ListIterator.java

@@ -0,0 +1,42 @@
+package net.markenwerk.commons.iterators;
+
+import java.util.List;
+import java.util.NoSuchElementException;
+
+public class ListIterator<Payload> implements Reiterator<Payload> {
+
+	private final java.util.ListIterator<Payload> iterator;
+
+	public ListIterator(List<Payload> list) throws IllegalArgumentException {
+		if (null == list) {
+			throw new IllegalArgumentException("The given list is null");
+		}
+		this.iterator = list.listIterator();
+	}
+
+	@Override
+	public boolean hasNext() {
+		return iterator.hasNext();
+	}
+
+	@Override
+	public Payload next() {
+		return iterator.next();
+	}
+
+	@Override
+	public boolean hasPrevious() {
+		return iterator.hasPrevious();
+	}
+
+	@Override
+	public Payload previous() throws NoSuchElementException {
+		return iterator.previous();
+	}
+
+	@Override
+	public void remove() throws UnsupportedOperationException, IllegalStateException {
+		iterator.remove();
+	}
+
+}

src/main/java/net/markenwerk/commons/iterators/ProtectedIterator.java

@@ -26,7 +26,8 @@
 /**
  * A {@link ProtectedIterator} is an {@link Iterator} that guarantees that every
  * call to {@linkplain ProtectedIterator#remove()} throws an
- * {@link UnsupportedOperationException} and doesn't alter the underlying data.
+ * {@link UnsupportedOperationException} and doesn't alter the underlying data
+ * structure.
  * 
  * <p>
  * {@link ProtectedIterator} is a marker interface.

src/main/java/net/markenwerk/commons/iterators/ProtectedReiterator.java

@@ -0,0 +1,50 @@
+/*
+ * Copyright (c) 2016 Torsten Krause, Markenwerk GmbH
+ * 
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+package net.markenwerk.commons.iterators;
+
+/**
+ * A {@link ProtectedReiterator} is a {@link Reiterator} that guarantees that
+ * every call to {@linkplain ProtectedReiterator#remove()} throws an
+ * {@link UnsupportedOperationException} and doesn't alter the underlying data
+ * structure.
+ * 
+ * <p>
+ * {@link ProtectedReiterator} is a marker interface.
+ * 
+ * @param <Payload>
+ *            The payload type.
+ * @author Torsten Krause (tk at markenwerk dot net)
+ * @since 3.1.1
+ */
+public interface ProtectedReiterator<Payload> extends ProtectedIterator<Payload>, Reiterator<Payload> {
+
+	/**
+	 * Always throws an {@link UnsupportedOperationException}.
+	 * 
+	 * @throws UnsupportedOperationException
+	 *             When trying to remove an element from an
+	 *             {@link ProtectedReiterator}.
+	 */
+	@Override
+	public void remove() throws UnsupportedOperationException;
+
+}

src/main/java/net/markenwerk/commons/iterators/ProtectingIterator.java

@@ -25,9 +25,9 @@
 import java.util.NoSuchElementException;
 
 /**
- * A {@link ProtectingIterator} is an {@link AbstractProtectedIterator} that
- * can be wrapped around a given {@link Iterator} and guarantees that every call
- * to {@linkplain ProtectedIterator#remove()} throws an
+ * A {@link ProtectingIterator} is an {@link AbstractProtectedIterator} that can
+ * be wrapped around a given {@link Iterator} and guarantees that every call to
+ * {@linkplain ProtectingIterator#remove()} throws an
  * {@link UnsupportedOperationException} and doesn't alter the underlying
  * {@link Iterator}.
  * 

src/main/java/net/markenwerk/commons/iterators/ProtectingReiterator.java

@@ -0,0 +1,79 @@
+/*
+ * Copyright (c) 2016 Torsten Krause, Markenwerk GmbH
+ * 
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+package net.markenwerk.commons.iterators;
+
+import java.util.Iterator;
+import java.util.NoSuchElementException;
+
+/**
+ * A {@link ProtectingReiterator} is an {@link AbstractProtectedIterator} that
+ * can be wrapped around a given {@link Reiterator} and guarantees that every
+ * call to {@linkplain ProtectingReiterator#remove()} throws an
+ * {@link UnsupportedOperationException} and doesn't alter the underlying
+ * {@link Iterator}.
+ * 
+ * @param <Payload>
+ *            The payload type.
+ * @author Torsten Krause (tk at markenwerk dot net)
+ * @since 3.1.1
+ */
+public final class ProtectingReiterator<Payload> extends AbstractProtectedReiterator<Payload> {
+
+	private final Reiterator<? extends Payload> iterator;
+
+	/**
+	 * Creates a new {@link ProtectingReiterator}.
+	 * 
+	 * @param iterator
+	 *            The {@link Reiterator} to iterate over.
+	 * 
+	 * @throws IllegalArgumentException
+	 *             If the given {@link Reiterator} is {@literal null}.
+	 */
+	public ProtectingReiterator(Reiterator<? extends Payload> iterator) throws IllegalArgumentException {
+		if (null == iterator) {
+			throw new IllegalArgumentException("The given iterator is null");
+		}
+		this.iterator = iterator;
+	}
+
+	@Override
+	public boolean hasNext() {
+		return iterator.hasNext();
+	}
+
+	@Override
+	public Payload next() throws NoSuchElementException {
+		return iterator.next();
+	}
+
+	@Override
+	public boolean hasPrevious() {
+		return iterator.hasPrevious();
+	}
+
+	@Override
+	public Payload previous() throws NoSuchElementException {
+		return iterator.previous();
+	}
+
+}

src/main/java/net/markenwerk/commons/iterators/Reiterator.java

@@ -0,0 +1,63 @@
+/*
+ * Copyright (c) 2016 Torsten Krause, Markenwerk GmbH
+ * 
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+package net.markenwerk.commons.iterators;
+
+import java.util.Iterator;
+import java.util.NoSuchElementException;
+
+public interface Reiterator<Payload> extends Iterator<Payload> {
+
+	/**
+	 * Returns whether this {@link Reiterator} has a previous element.
+	 *
+	 * @return Whether this {@link Reiterator} has a previous element.
+	 */
+	boolean hasPrevious();
+
+	/**
+	 * Returns the previous element.
+	 *
+	 * @return The previous element in the iteration.
+	 * @exception NoSuchElementException
+	 *                If this {@link Reiterator} has no previous element.
+	 */
+	Payload previous() throws NoSuchElementException;
+
+	/**
+	 * Removes the last returned (either by {@link Reiterator#next()} or by
+	 * {@link Reiterator#previous()}) payload value from the underlying data
+	 * structure.
+	 *
+	 * @exception UnsupportedOperationException
+	 *                If this {@link Reiterator} doesn't support element
+	 *                removal.
+	 * @exception IllegalStateException
+	 *                If neither {@link Reiterator#next()} nor
+	 *                {@link Reiterator#previous()} has been called or if
+	 *                {@link Reiterator#remove()} has already been called after
+	 *                the last call to {@link Reiterator#next()} or
+	 *                {@link Reiterator#previous()}.
+	 */
+	@Override
+	void remove() throws UnsupportedOperationException, IllegalStateException;
+
+}