001/* 002 * Copyright (C) 2008 The Guava Authors 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package com.google.common.collect; 018 019import com.google.common.annotations.GwtCompatible; 020import com.google.errorprone.annotations.CanIgnoreReturnValue; 021import com.google.errorprone.annotations.DoNotMock; 022import java.util.Iterator; 023import java.util.NoSuchElementException; 024import org.checkerframework.checker.nullness.qual.Nullable; 025 026/** 027 * An iterator that supports a one-element lookahead while iterating. 028 * 029 * <p>See the Guava User Guide article on <a href= 030 * "https://github.com/google/guava/wiki/CollectionHelpersExplained#peekingiterator">{@code 031 * PeekingIterator}</a>. 032 * 033 * @author Mick Killianey 034 * @since 2.0 035 */ 036@DoNotMock("Use Iterators.peekingIterator") 037@GwtCompatible 038@ElementTypesAreNonnullByDefault 039public interface PeekingIterator<E extends @Nullable Object> extends Iterator<E> { 040 /** 041 * Returns the next element in the iteration, without advancing the iteration. 042 * 043 * <p>Calls to {@code peek()} should not change the state of the iteration, except that it 044 * <i>may</i> prevent removal of the most recent element via {@link #remove()}. 045 * 046 * @throws NoSuchElementException if the iteration has no more elements according to {@link 047 * #hasNext()} 048 */ 049 @ParametricNullness 050 E peek(); 051 052 /** 053 * {@inheritDoc} 054 * 055 * <p>The objects returned by consecutive calls to {@link #peek()} then {@link #next()} are 056 * guaranteed to be equal to each other. 057 */ 058 @CanIgnoreReturnValue 059 @Override 060 @ParametricNullness 061 E next(); 062 063 /** 064 * {@inheritDoc} 065 * 066 * <p>Implementations may or may not support removal when a call to {@link #peek()} has occurred 067 * since the most recent call to {@link #next()}. 068 * 069 * @throws IllegalStateException if there has been a call to {@link #peek()} since the most recent 070 * call to {@link #next()} and this implementation does not support this sequence of calls 071 * (optional) 072 */ 073 @Override 074 void remove(); 075}