*
 * <p>See the Guava User Guide article on <a href=
 * "https://github.com/google/guava/wiki/CollectionHelpersExplained#peekingiterator">{@code
 * PeekingIterator}</a>.
 *
 * @author Mick Killianey
 * @since 2.0
 */
@DoNotMock("Use Iterators.peekingIterator")
@GwtCompatible
public interface PeekingIterator<E extends @Nullable Object> extends Iterator<E> {
  /**

    Iterator<?> iterator = list.iterator();
    PeekingIterator<?> peekingIterator = peekingIterator(iterator);

    assertThrows(NoSuchElementException.class, () -> peekingIterator.peek());
  }

  public void testPeekDoesntChangeIteration() {
    List<?> list = Lists.newArrayList("A", "B", "C");
    Iterator<?> iterator = list.iterator();
    PeekingIterator<?> peekingIterator = peekingIterator(iterator);

    Iterator<?> iterator = list.iterator();
    PeekingIterator<?> peekingIterator = peekingIterator(iterator);

    assertThrows(NoSuchElementException.class, () -> peekingIterator.peek());
  }

  public void testPeekDoesntChangeIteration() {
    List<?> list = Lists.newArrayList("A", "B", "C");
    Iterator<?> iterator = list.iterator();
    PeekingIterator<?> peekingIterator = peekingIterator(iterator);

 *
 * <h2>Other</h2>
 *
 * <ul>
 *   <li>{@link EvictingQueue}
 *   <li>{@link Interner}, {@link Interners}
 *   <li>{@link MapMaker}
 *   <li>{@link MinMaxPriorityQueue}
 *   <li>{@link PeekingIterator}
 * </ul>
 */
@CheckReturnValue
@NullMarked
package com.google.common.collect;

import com.google.errorprone.annotations.CheckReturnValue;