001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.commons.collections4.iterators; 018 019import java.util.Iterator; 020import java.util.NoSuchElementException; 021import java.util.Objects; 022 023/** 024 * Decorates an iterator to support one-element lookahead while iterating. 025 * <p> 026 * The decorator supports the removal operation, but an {@link IllegalStateException} 027 * will be thrown if {@link #remove()} is called directly after a call to 028 * {@link #peek()} or {@link #element()}. 029 * 030 * @param <E> the type of elements returned by this iterator. 031 * @since 4.0 032 */ 033public class PeekingIterator<E> implements Iterator<E> { 034 035 /** 036 * Decorates the specified iterator to support one-element lookahead. 037 * <p> 038 * If the iterator is already a {@link PeekingIterator} it is returned directly. 039 * 040 * @param <E> the element type 041 * @param iterator the iterator to decorate 042 * @return a new peeking iterator 043 * @throws NullPointerException if the iterator is null 044 */ 045 public static <E> PeekingIterator<E> peekingIterator(final Iterator<? extends E> iterator) { 046 Objects.requireNonNull(iterator, "iterator"); 047 if (iterator instanceof PeekingIterator<?>) { 048 @SuppressWarnings("unchecked") // safe cast 049 final PeekingIterator<E> it = (PeekingIterator<E>) iterator; 050 return it; 051 } 052 return new PeekingIterator<>(iterator); 053 } 054 055 /** The iterator being decorated. */ 056 private final Iterator<? extends E> iterator; 057 058 /** Indicates that the decorated iterator is exhausted. */ 059 private boolean exhausted; 060 061 /** Indicates if the lookahead slot is filled. */ 062 private boolean slotFilled; 063 064 /** The current slot for lookahead. */ 065 private E slot; 066 067 /** 068 * Constructs a new instance. 069 * 070 * @param iterator the iterator to decorate 071 */ 072 public PeekingIterator(final Iterator<? extends E> iterator) { 073 this.iterator = iterator; 074 } 075 076 /** 077 * Returns the next element in iteration without advancing the underlying iterator. 078 * If the iterator is already exhausted, null will be returned. 079 * 080 * @return the next element from the iterator 081 * @throws NoSuchElementException if the iterator is already exhausted according to {@link #hasNext()} 082 */ 083 public E element() { 084 fill(); 085 if (exhausted) { 086 throw new NoSuchElementException(); 087 } 088 return slot; 089 } 090 091 private void fill() { 092 if (exhausted || slotFilled) { 093 return; 094 } 095 if (iterator.hasNext()) { 096 slot = iterator.next(); 097 slotFilled = true; 098 } else { 099 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}