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.Iterator; 20 import java.util.NoSuchElementException; 21 import java.util.Objects; 22 23 /** 24 * Decorates an iterator to support one-element lookahead while iterating. 25 * <p> 26 * The decorator supports the removal operation, but an {@link IllegalStateException} 27 * will be thrown if {@link #remove()} is called directly after a call to 28 * {@link #peek()} or {@link #element()}. 29 * 30 * @param <E> the type of elements returned by this iterator. 31 * @since 4.0 32 */ 33 public class PeekingIterator<E> implements Iterator<E> { 34 35 /** 36 * Decorates the specified iterator to support one-element lookahead. 37 * <p> 38 * If the iterator is already a {@link PeekingIterator} it is returned directly. 39 * 40 * @param <E> the element type 41 * @param iterator the iterator to decorate 42 * @return a new peeking iterator 43 * @throws NullPointerException if the iterator is null 44 */ 45 public static <E> PeekingIterator<E> peekingIterator(final Iterator<? extends E> iterator) { 46 Objects.requireNonNull(iterator, "iterator"); 47 if (iterator instanceof PeekingIterator<?>) { 48 @SuppressWarnings("unchecked") // safe cast 49 final PeekingIterator<E> it = (PeekingIterator<E>) iterator; 50 return it; 51 } 52 return new PeekingIterator<>(iterator); 53 } 54 55 /** The iterator being decorated. */ 56 private final Iterator<? extends E> iterator; 57 58 /** Indicates that the decorated iterator is exhausted. */ 59 private boolean exhausted; 60 61 /** Indicates if the lookahead slot is filled. */ 62 private boolean slotFilled; 63 64 /** The current slot for lookahead. */ 65 private E slot; 66 67 /** 68 * Constructs a new instance. 69 * 70 * @param iterator the iterator to decorate 71 */ 72 public PeekingIterator(final Iterator<? extends E> iterator) { 73 this.iterator = iterator; 74 } 75 76 /** 77 * Returns the next element in iteration without advancing the underlying iterator. 78 * If the iterator is already exhausted, null will be returned. 79 * 80 * @return the next element from the iterator 81 * @throws NoSuchElementException if the iterator is already exhausted according to {@link #hasNext()} 82 */ 83 public E element() { 84 fill(); 85 if (exhausted) { 86 throw new NoSuchElementException(); 87 } 88 return slot; 89 } 90 91 private void fill() { 92 if (exhausted || slotFilled) { 93 return; 94 } 95 if (iterator.hasNext()) { 96 slot = iterator.next(); 97 slotFilled = true; 98 } else { 99 exhausted = true; 100 slot = null; 101 slotFilled = false; 102 } 103 } 104 105 @Override 106 public boolean hasNext() { 107 if (exhausted) { 108 return false; 109 } 110 return slotFilled || iterator.hasNext(); 111 } 112 113 @Override 114 public E next() { 115 if (!hasNext()) { 116 throw new NoSuchElementException(); 117 } 118 final E x = slotFilled ? slot : iterator.next(); 119 // reset the lookahead slot 120 slot = null; 121 slotFilled = false; 122 return x; 123 } 124 125 /** 126 * Returns the next element in iteration without advancing the underlying iterator. 127 * If the iterator is already exhausted, null will be returned. 128 * <p> 129 * Note: this method does not throw a {@link NoSuchElementException} if the iterator 130 * is already exhausted. If you want such a behavior, use {@link #element()} instead. 131 * <p> 132 * The rationale behind this is to follow the {@link java.util.Queue} interface 133 * which uses the same terminology. 134 * 135 * @return the next element from the iterator 136 */ 137 public E peek() { 138 fill(); 139 return exhausted ? null : slot; 140 } 141 142 /** 143 * {@inheritDoc} 144 * 145 * @throws IllegalStateException if {@link #peek()} or {@link #element()} has been called 146 * prior to the call to {@link #remove()} 147 */ 148 @Override 149 public void remove() { 150 if (slotFilled) { 151 throw new IllegalStateException("peek() or element() called before remove()"); 152 } 153 iterator.remove(); 154 } 155 156 }