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 java.util.Iterator; 022import java.util.NoSuchElementException; 023 024/** 025 * An iterator that supports a one-element lookahead while iterating. 026 * 027 * <p>See the Guava User Guide article on <a href= 028 * "https://github.com/google/guava/wiki/CollectionHelpersExplained#peekingiterator"> {@code 029 * PeekingIterator}</a>. 030 * 031 * @author Mick Killianey 032 * @since 2.0 033 */ 034@GwtCompatible 035public interface PeekingIterator<E> extends Iterator<E> { 036 /** 037 * Returns the next element in the iteration, without advancing the iteration. 038 * 039 * <p>Calls to {@code peek()} should not change the state of the iteration, except that it 040 * <i>may</i> prevent removal of the most recent element via {@link #remove()}. 041 * 042 * @throws NoSuchElementException if the iteration has no more elements according to {@link 043 * #hasNext()} 044 */ 045 E peek(); 046 047 /** 048 * {@inheritDoc} 049 * 050 * <p>The objects returned by consecutive calls to {@link #peek()} then {@link #next()} are 051 * guaranteed to be equal to each other. 052 */ 053 @CanIgnoreReturnValue 054 @Override 055 E next(); 056 057 /** 058 * {@inheritDoc} 059 * 060 * <p>Implementations may or may not support removal when a call to {@link #peek()} has occurred 061 * since the most recent call to {@link #next()}. 062 * 063 * @throws IllegalStateException if there has been a call to {@link #peek()} since the most recent 064 * call to {@link #next()} and this implementation does not support this sequence of calls 065 * (optional) 066 */ 067 @Override 068 void remove(); 069}