1 /* 2 * Copyright (C) 2008 The Guava Authors 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.google.common.collect; 18 19 import com.google.common.annotations.GwtCompatible; 20 import com.google.errorprone.annotations.CanIgnoreReturnValue; 21 import com.google.errorprone.annotations.DoNotMock; 22 import java.util.Iterator; 23 import java.util.NoSuchElementException; 24 import org.checkerframework.checker.nullness.qual.Nullable; 25 26 /** 27 * An iterator that supports a one-element lookahead while iterating. 28 * 29 * <p>See the Guava User Guide article on <a href= 30 * "https://github.com/google/guava/wiki/CollectionHelpersExplained#peekingiterator">{@code 31 * PeekingIterator}</a>. 32 * 33 * @author Mick Killianey 34 * @since 2.0 35 */ 36 @DoNotMock("Use Iterators.peekingIterator") 37 @GwtCompatible 38 @ElementTypesAreNonnullByDefault 39 public interface PeekingIterator<E extends @Nullable Object> extends Iterator<E> { 40 /** 41 * Returns the next element in the iteration, without advancing the iteration. 42 * 43 * <p>Calls to {@code peek()} should not change the state of the iteration, except that it 44 * <i>may</i> prevent removal of the most recent element via {@link #remove()}. 45 * 46 * @throws NoSuchElementException if the iteration has no more elements according to {@link 47 * #hasNext()} 48 */ 49 @ParametricNullness peek()50 E peek(); 51 52 /** 53 * {@inheritDoc} 54 * 55 * <p>The objects returned by consecutive calls to {@link #peek()} then {@link #next()} are 56 * guaranteed to be equal to each other. 57 */ 58 @CanIgnoreReturnValue 59 @Override 60 @ParametricNullness next()61 E next(); 62 63 /** 64 * {@inheritDoc} 65 * 66 * <p>Implementations may or may not support removal when a call to {@link #peek()} has occurred 67 * since the most recent call to {@link #next()}. 68 * 69 * @throws IllegalStateException if there has been a call to {@link #peek()} since the most recent 70 * call to {@link #next()} and this implementation does not support this sequence of calls 71 * (optional) 72 */ 73 @Override remove()74 void remove(); 75 } 76