1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 package org.apache.commons.collections4.iterators; 18 19 import java.util.ArrayDeque; 20 import java.util.Deque; 21 import java.util.Iterator; 22 import java.util.Objects; 23 24 /** 25 * Decorates an iterator to support pushback of elements. 26 * <p> 27 * The decorator stores the pushed back elements in a LIFO manner: the last element 28 * that has been pushed back, will be returned as the next element in a call to {@link #next()}. 29 * <p> 30 * The decorator does not support the removal operation. Any call to {@link #remove()} will 31 * result in an {@link UnsupportedOperationException}. 32 * 33 * @param <E> the type of elements returned by this iterator. 34 * @since 4.0 35 */ 36 public class PushbackIterator<E> implements Iterator<E> { 37 38 /** 39 * Decorates the specified iterator to support one-element lookahead. 40 * <p> 41 * If the iterator is already a {@link PushbackIterator} it is returned directly. 42 * 43 * @param <E> the element type 44 * @param iterator the iterator to decorate 45 * @return a new peeking iterator 46 * @throws NullPointerException if the iterator is null 47 */ 48 public static <E> PushbackIterator<E> pushbackIterator(final Iterator<? extends E> iterator) { 49 Objects.requireNonNull(iterator, "iterator"); 50 if (iterator instanceof PushbackIterator<?>) { 51 @SuppressWarnings("unchecked") // safe cast 52 final PushbackIterator<E> it = (PushbackIterator<E>) iterator; 53 return it; 54 } 55 return new PushbackIterator<>(iterator); 56 } 57 58 /** The iterator being decorated. */ 59 private final Iterator<? extends E> iterator; 60 61 /** The LIFO queue containing the pushed back items. */ 62 private final Deque<E> items = new ArrayDeque<>(); 63 64 /** 65 * Constructs a new instance. 66 * 67 * @param iterator the iterator to decorate 68 */ 69 public PushbackIterator(final Iterator<? extends E> iterator) { 70 this.iterator = iterator; 71 } 72 73 @Override 74 public boolean hasNext() { 75 return !items.isEmpty() || iterator.hasNext(); 76 } 77 78 @Override 79 public E next() { 80 return !items.isEmpty() ? items.pop() : iterator.next(); 81 } 82 83 /** 84 * Push back the given element to the iterator. 85 * <p> 86 * Calling {@link #next()} immediately afterwards will return exactly this element. 87 * 88 * @param item the element to push back to the iterator 89 */ 90 public void pushback(final E item) { 91 items.push(item); 92 } 93 94 /** 95 * This iterator will always throw an {@link UnsupportedOperationException}. 96 * 97 * @throws UnsupportedOperationException always 98 */ 99 @Override 100 public void remove() { 101 throw new UnsupportedOperationException(); 102 } 103 104 }