*
 * <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);

   * String a1 = peekingIterator.peek(); // returns "a"
   * String a2 = peekingIterator.peek(); // also returns "a"
   * String a3 = peekingIterator.next(); // also returns "a"
   * }
   *
   * <p>Any structural changes to the underlying iteration (aside from those performed by the
   * iterator's own {@link PeekingIterator#remove()} method) will leave the iterator in an undefined
   * state.

          // All collections are immutable empty. So safe for any type parameter.
          .put(Iterator.class, ImmutableSet.of().iterator())
          .put(PeekingIterator.class, peekingIterator(ImmutableSet.of().iterator()))
          .put(ListIterator.class, ImmutableList.of().listIterator())
          .put(Iterable.class, ImmutableSet.of())
          .put(Collection.class, ImmutableList.of())

 *
 * <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;

          // All collections are immutable empty. So safe for any type parameter.
          .put(Iterator.class, ImmutableSet.of().iterator())
          .put(PeekingIterator.class, peekingIterator(ImmutableSet.of().iterator()))
          .put(ListIterator.class, ImmutableList.of().listIterator())
          .put(Iterable.class, ImmutableSet.of())
          .put(Collection.class, ImmutableList.of())

  public void testPeekingIteratorShortCircuit() {
    Iterator<String> nonpeek = Lists.newArrayList("a", "b", "c").iterator();
    PeekingIterator<String> peek = peekingIterator(nonpeek);
    assertNotSame(peek, nonpeek);
    assertSame(peek, peekingIterator(peek));
    assertSame(peek, peekingIterator((Iterator<String>) peek));
  }

  public void testMergeSorted_stable_issue5773Example() {

    public ImmutableRangeSet<C> build() {
      ImmutableList.Builder<Range<C>> mergedRangesBuilder =
          new ImmutableList.Builder<>(ranges.size());
      sort(ranges, rangeLexOrdering());
      PeekingIterator<Range<C>> peekingItr = peekingIterator(ranges.iterator());
      while (peekingItr.hasNext()) {
        Range<C> range = peekingItr.next();
        while (peekingItr.hasNext()) {
          Range<C> nextRange = peekingItr.peek();

import com.google.common.collect.ListMultimap;
import com.google.common.collect.MapDifference;
import com.google.common.collect.Multimap;
import com.google.common.collect.Multiset;
import com.google.common.collect.PeekingIterator;
import com.google.common.collect.Range;
import com.google.common.collect.RowSortedTable;
import com.google.common.collect.SetMultimap;
import com.google.common.collect.SortedMapDifference;