https://projects.eclipse.org/projects/ee4j.jersey/jersey-common: Jersey core common packages (Eclipse Foundation) 
/*
 * Copyright (C) 2007 The Guava Authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.glassfish.jersey.internal.guava;

import java.util.Arrays;
import java.util.Collection;
import java.util.Collections;
import java.util.Iterator;
import java.util.NoSuchElementException;
import java.util.Objects;
import java.util.function.Function;
import java.util.function.Predicate;

import static org.glassfish.jersey.internal.guava.Preconditions.checkArgument;
import static org.glassfish.jersey.internal.guava.Preconditions.checkNotNull;
import static org.glassfish.jersey.internal.guava.Preconditions.checkState;
import static org.glassfish.jersey.internal.guava.Predicates.in;


This class contains static utility methods that operate on or return objects of type Iterator. Except as noted, each method has a corresponding Iterable-based method in the Iterables class. 


Performance notes: Unless otherwise noted, all of the iterators
produced in this class are lazy, which means that they only advance
the backing iteration when absolutely necessary.



See the Guava User Guide section on  Iterators.

Author:Kevin Bourrillion, Jared Levy
Since:2.0 (imported from Google Collections Library)
/**
 * This class contains static utility methods that operate on or return objects
 * of type {@link Iterator}. Except as noted, each method has a corresponding
 * {@link Iterable}-based method in the {@link Iterables} class.
 * <p>
 * <p><i>Performance notes:</i> Unless otherwise noted, all of the iterators
 * produced in this class are <i>lazy</i>, which means that they only advance
 * the backing iteration when absolutely necessary.
 * <p>
 * <p>See the Guava User Guide section on <a href=
 * "http://code.google.com/p/guava-libraries/wiki/CollectionUtilitiesExplained#Iterables">
 * {@code Iterators}</a>.
 *
 * @author Kevin Bourrillion
 * @author Jared Levy
 * @since 2.0 (imported from Google Collections Library)
 */
public final class Iterators {
    private static final UnmodifiableListIterator<Object> EMPTY_LIST_ITERATOR
            = new UnmodifiableListIterator<Object>() {
        @Override
        public boolean hasNext() {
            return false;
        }

        @Override
        public Object next() {
            throw new NoSuchElementException();
        }

        @Override
        public boolean hasPrevious() {
            return false;
        }

        @Override
        public Object previous() {
            throw new NoSuchElementException();
        }

        @Override
        public int nextIndex() {
            return 0;
        }

        @Override
        public int previousIndex() {
            return -1;
        }
    };
    private static final Iterator<Object> EMPTY_MODIFIABLE_ITERATOR =
            new Iterator<Object>() {
                @Override
                public boolean hasNext() {
                    return false;
                }

                @Override
                public Object next() {
                    throw new NoSuchElementException();
                }

                @Override
                public void remove() {
                    CollectPreconditions.checkRemove(false);
                }
            };

    private Iterators() {
    }

    
Returns the empty iterator.



The Iterable equivalent of this method is of.of(). 
Deprecated:Use ImmutableSet.<T>of().iterator() instead; or for Java 7 or later, Collections.emptyIterator. This method is scheduled for removal in May 2016.
/**
     * Returns the empty iterator.
     * <p>
     * <p>The {@link Iterable} equivalent of this method is {@link
     * ImmutableSet#of()}.
     *
     * @deprecated Use {@code ImmutableSet.<T>of().iterator()} instead; or for
     * Java 7 or later, {@link Collections#emptyIterator}. This method is
     * scheduled for removal in May 2016.
     */
    @Deprecated
    public static <T> UnmodifiableIterator<T> emptyIterator() {
        return emptyListIterator();
    }

    
Returns the empty iterator.



The Iterable equivalent of this method is of.of(). 
/**
     * Returns the empty iterator.
     * <p>
     * <p>The {@link Iterable} equivalent of this method is {@link
     * ImmutableSet#of()}.
     */
    // Casting to any type is safe since there are no actual elements.
    @SuppressWarnings("unchecked")
    private static <T> UnmodifiableListIterator<T> emptyListIterator() {
        return (UnmodifiableListIterator<T>) EMPTY_LIST_ITERATOR;
    }

    
Returns the empty Iterator that throws IllegalStateException instead of UnsupportedOperationException on a call to Iterator.remove(). 
/**
     * Returns the empty {@code Iterator} that throws
     * {@link IllegalStateException} instead of
     * {@link UnsupportedOperationException} on a call to
     * {@link Iterator#remove()}.
     */
    // Casting to any type is safe since there are no actual elements.
    @SuppressWarnings("unchecked")
    static <T> Iterator<T> emptyModifiableIterator() {
        return (Iterator<T>) EMPTY_MODIFIABLE_ITERATOR;
    }

    
Returns an unmodifiable view of iterator. 
/**
     * Returns an unmodifiable view of {@code iterator}.
     */
    public static <T> UnmodifiableIterator<T> unmodifiableIterator(
            final Iterator<T> iterator) {
        checkNotNull(iterator);
        if (iterator instanceof UnmodifiableIterator) {
            return (UnmodifiableIterator<T>) iterator;
        }
        return new UnmodifiableIterator<T>() {
            @Override
            public boolean hasNext() {
                return iterator.hasNext();
            }

            @Override
            public T next() {
                return iterator.next();
            }
        };
    }

    
Returns the number of elements remaining in iterator. The iterator will be left exhausted: its hasNext() method will return false. 
/**
     * Returns the number of elements remaining in {@code iterator}. The iterator
     * will be left exhausted: its {@code hasNext()} method will return
     * {@code false}.
     */
    public static int size(Iterator<?> iterator) {
        int count = 0;
        while (iterator.hasNext()) {
            iterator.next();
            count++;
        }
        return count;
    }

    
Traverses an iterator and removes every element that belongs to the provided collection. The iterator will be left exhausted: its hasNext() method will return false. 
Params:
  • removeFrom –       the iterator to (potentially) remove elements from
  • elementsToRemove – the elements to remove
Returns:true if any element was removed from iterator
/**
     * Traverses an iterator and removes every element that belongs to the
     * provided collection. The iterator will be left exhausted: its
     * {@code hasNext()} method will return {@code false}.
     *
     * @param removeFrom       the iterator to (potentially) remove elements from
     * @param elementsToRemove the elements to remove
     * @return {@code true} if any element was removed from {@code iterator}
     */
    public static boolean removeAll(
            Iterator<?> removeFrom, Collection<?> elementsToRemove) {
        return removeIf(removeFrom, in(elementsToRemove));
    }

    
Removes every element that satisfies the provided predicate from the iterator. The iterator will be left exhausted: its hasNext() method will return false. 
Params:
  • removeFrom – the iterator to (potentially) remove elements from
  • predicate –  a predicate that determines whether an element should
                  be removed
Returns:true if any elements were removed from the iterator
Since:2.0
/**
     * Removes every element that satisfies the provided predicate from the
     * iterator. The iterator will be left exhausted: its {@code hasNext()}
     * method will return {@code false}.
     *
     * @param removeFrom the iterator to (potentially) remove elements from
     * @param predicate  a predicate that determines whether an element should
     *                   be removed
     * @return {@code true} if any elements were removed from the iterator
     * @since 2.0
     */
    public static <T> boolean removeIf(
            Iterator<T> removeFrom, Predicate<? super T> predicate) {
        checkNotNull(predicate);
        boolean modified = false;
        while (removeFrom.hasNext()) {
            if (predicate.test(removeFrom.next())) {
                removeFrom.remove();
                modified = true;
            }
        }
        return modified;
    }

    
Determines whether two iterators contain equal elements in the same order. More specifically, this method returns true if iterator1 and iterator2 contain the same number of elements and every element of iterator1 is equal to the corresponding element of iterator2. 


Note that this will modify the supplied iterators, since they will have
been advanced some number of elements forward.

/**
     * Determines whether two iterators contain equal elements in the same order.
     * More specifically, this method returns {@code true} if {@code iterator1}
     * and {@code iterator2} contain the same number of elements and every element
     * of {@code iterator1} is equal to the corresponding element of
     * {@code iterator2}.
     * <p>
     * <p>Note that this will modify the supplied iterators, since they will have
     * been advanced some number of elements forward.
     */
    public static boolean elementsEqual(
            Iterator<?> iterator1, Iterator<?> iterator2) {
        while (iterator1.hasNext()) {
            if (!iterator2.hasNext()) {
                return false;
            }
            Object o1 = iterator1.next();
            Object o2 = iterator2.next();
            if (!Objects.equals(o1, o2)) {
                return false;
            }
        }
        return !iterator2.hasNext();
    }

    
Adds all elements in iterator to collection. The iterator will be left exhausted: its hasNext() method will return false. 
Returns:true if collection was modified as a result of this operation
/**
     * Adds all elements in {@code iterator} to {@code collection}. The iterator
     * will be left exhausted: its {@code hasNext()} method will return
     * {@code false}.
     *
     * @return {@code true} if {@code collection} was modified as a result of this
     * operation
     */
    public static <T> boolean addAll(
            Collection<T> addTo, Iterator<? extends T> iterator) {
        checkNotNull(addTo);
        checkNotNull(iterator);
        boolean wasModified = false;
        while (iterator.hasNext()) {
            wasModified |= addTo.add(iterator.next());
        }
        return wasModified;
    }

    
Returns true if every element returned by iterator satisfies the given predicate. If iterator is empty, true is returned. 
/**
     * Returns {@code true} if every element returned by {@code iterator}
     * satisfies the given predicate. If {@code iterator} is empty, {@code true}
     * is returned.
     */
    public static <T> boolean all(
            Iterator<T> iterator, Predicate<? super T> predicate) {
        checkNotNull(predicate);
        while (iterator.hasNext()) {
            T element = iterator.next();
            if (!predicate.test(element)) {
                return false;
            }
        }
        return true;
    }

    
Returns the index in iterator of the first element that satisfies the provided predicate, or -1 if the Iterator has no such elements. 


More formally, returns the lowest index i such that predicate.apply(Iterators.get(iterator, i)) returns true, or -1 if there is no such index. 


If -1 is returned, the iterator will be left exhausted: its hasNext() method will return false. Otherwise, the iterator will be set to the element which satisfies the predicate. 
Since:2.0
/**
     * Returns the index in {@code iterator} of the first element that satisfies
     * the provided {@code predicate}, or {@code -1} if the Iterator has no such
     * elements.
     * <p>
     * <p>More formally, returns the lowest index {@code i} such that
     * {@code predicate.apply(Iterators.get(iterator, i))} returns {@code true},
     * or {@code -1} if there is no such index.
     * <p>
     * <p>If -1 is returned, the iterator will be left exhausted: its
     * {@code hasNext()} method will return {@code false}.  Otherwise,
     * the iterator will be set to the element which satisfies the
     * {@code predicate}.
     *
     * @since 2.0
     */
    private static <T> int indexOf(
            Iterator<T> iterator, Predicate<? super T> predicate) {
        checkNotNull(predicate, "predicate");
        for (int i = 0; iterator.hasNext(); i++) {
            T current = iterator.next();
            if (predicate.test(current)) {
                return i;
            }
        }
        return -1;
    }

    
Returns an iterator that applies function to each element of 
fromIterator. 


The returned iterator supports remove() if the provided iterator does. After a successful remove() call, fromIterator no longer contains the corresponding element. 
/**
     * Returns an iterator that applies {@code function} to each element of {@code
     * fromIterator}.
     * <p>
     * <p>The returned iterator supports {@code remove()} if the provided iterator
     * does. After a successful {@code remove()} call, {@code fromIterator} no
     * longer contains the corresponding element.
     */
    public static <F, T> Iterator<T> transform(final Iterator<F> fromIterator,
                                               final Function<? super F, ? extends T> function) {
        checkNotNull(function);
        return new TransformedIterator<F, T>(fromIterator) {
            @Override
            T transform(F from) {
                return function.apply(from);
            }
        };
    }

    
Returns the next element in iterator or defaultValue if the iterator is empty. The Iterables analog to this method is Iterables.getFirst. 
Params:
  • defaultValue – the default value to return if the iterator is empty
Returns:the next element of iterator or the default value
Since:7.0
/**
     * Returns the next element in {@code iterator} or {@code defaultValue} if
     * the iterator is empty.  The {@link Iterables} analog to this method is
     * {@link Iterables#getFirst}.
     *
     * @param defaultValue the default value to return if the iterator is empty
     * @return the next element of {@code iterator} or the default value
     * @since 7.0
     */
    public static <T> T getNext(Iterator<? extends T> iterator, T defaultValue) {
        return iterator.hasNext() ? iterator.next() : defaultValue;
    }

    
Deletes and returns the next value from the iterator, or returns null if there is no such value. 
/**
     * Deletes and returns the next value from the iterator, or returns
     * {@code null} if there is no such value.
     */
    static <T> T pollNext(Iterator<T> iterator) {
        if (iterator.hasNext()) {
            T result = iterator.next();
            iterator.remove();
            return result;
        } else {
            return null;
        }
    }

    // Methods only in Iterators, not in Iterables

    
Clears the iterator using its remove method.

/**
     * Clears the iterator using its remove method.
     */
    static void clear(Iterator<?> iterator) {
        checkNotNull(iterator);
        while (iterator.hasNext()) {
            iterator.next();
            iterator.remove();
        }
    }

    
Returns an iterator containing the elements of array in order. The returned iterator is a view of the array; subsequent changes to the array will be reflected in the iterator. 


Note: It is often preferable to represent your data using a collection type, for example using Arrays.asList(Object[]), making this method unnecessary. 


The Iterable equivalent of this method is either Arrays.asList(Object[]), copyOf.copyOf(Object[])}, or of.of. 
/**
     * Returns an iterator containing the elements of {@code array} in order. The
     * returned iterator is a view of the array; subsequent changes to the array
     * will be reflected in the iterator.
     * <p>
     * <p><b>Note:</b> It is often preferable to represent your data using a
     * collection type, for example using {@link Arrays#asList(Object[])}, making
     * this method unnecessary.
     * <p>
     * <p>The {@code Iterable} equivalent of this method is either {@link
     * Arrays#asList(Object[])}, {@link ImmutableList#copyOf(Object[])}},
     * or {@link ImmutableList#of}.
     */
    public static <T> UnmodifiableIterator<T> forArray(final T... array) {
        return forArray(array, 0, array.length, 0);
    }

    
Returns a list iterator containing the elements in the specified range of array in order, starting at the specified index. 


The Iterable equivalent of this method is 
Arrays.asList(array).subList(offset, offset + length).listIterator(index). 
/**
     * Returns a list iterator containing the elements in the specified range of
     * {@code array} in order, starting at the specified index.
     * <p>
     * <p>The {@code Iterable} equivalent of this method is {@code
     * Arrays.asList(array).subList(offset, offset + length).listIterator(index)}.
     */
    static <T> UnmodifiableListIterator<T> forArray(
            final T[] array, final int offset, int length, int index) {
        checkArgument(length >= 0);
        int end = offset + length;

        // Technically we should give a slightly more descriptive error on overflow
        Preconditions.checkPositionIndexes(offset, end, array.length);
        Preconditions.checkPositionIndex(index, length);
        if (length == 0) {
            return emptyListIterator();
        }

    /*
     * We can't use call the two-arg constructor with arguments (offset, end)
     * because the returned Iterator is a ListIterator that may be moved back
     * past the beginning of the iteration.
     */
        return new AbstractIndexedListIterator<T>(length, index) {
            @Override
            protected T get(int index) {
                return array[offset + index];
            }
        };
    }

    
Returns an iterator containing only value. 


The Iterable equivalent of this method is Collections.singleton. 
/**
     * Returns an iterator containing only {@code value}.
     * <p>
     * <p>The {@link Iterable} equivalent of this method is {@link
     * Collections#singleton}.
     */
    public static <T> UnmodifiableIterator<T> singletonIterator(
            final T value) {
        return new UnmodifiableIterator<T>() {
            boolean done;

            @Override
            public boolean hasNext() {
                return !done;
            }

            @Override
            public T next() {
                if (done) {
                    throw new NoSuchElementException();
                }
                done = true;
                return value;
            }
        };
    }

    
Returns a PeekingIterator backed by the given iterator. 


Calls to the peek method with no intervening calls to 
next do not affect the iteration, and hence return the same object each time. A subsequent call to next is guaranteed to return the same object again. For example: 
 
<p>
  PeekingIterator<String> peekingIterator =
      Iterators.peekingIterator(Iterators.forArray("a", "b"));
  String a1 = peekingIterator.peek(); // returns "a"
  String a2 = peekingIterator.peek(); // also returns "a"
  String a3 = peekingIterator.next(); // also returns "a"




Any structural changes to the underlying iteration (aside from those performed by the iterator's own PeekingIterator.remove() method) will leave the iterator in an undefined state. 


The returned iterator does not support removal after peeking, as explained by PeekingIterator.remove(). 


Note: If the given iterator is already a PeekingIterator, it might be returned to the caller, although this is neither
guaranteed to occur nor required to be consistent.  For example, this
method might choose to pass through recognized implementations of PeekingIterator when the behavior of the implementation is known to meet the contract guaranteed by this method. 


There is no Iterable equivalent to this method, so use this method to wrap each individual iterator as it is generated. 
Params:
  • iterator – the backing iterator. The PeekingIterator assumes ownership of this iterator, so users should cease making direct calls to it after calling this method.
Returns:a peeking iterator backed by that iterator. Apart from the additional PeekingIterator.peek() method, this iterator behaves exactly the same as iterator.
/**
     * Returns a {@code PeekingIterator} backed by the given iterator.
     * <p>
     * <p>Calls to the {@code peek} method with no intervening calls to {@code
     * next} do not affect the iteration, and hence return the same object each
     * time. A subsequent call to {@code next} is guaranteed to return the same
     * object again. For example: <pre>   {@code
     * <p>
     *   PeekingIterator<String> peekingIterator =
     *       Iterators.peekingIterator(Iterators.forArray("a", "b"));
     *   String a1 = peekingIterator.peek(); // returns "a"
     *   String a2 = peekingIterator.peek(); // also returns "a"
     *   String a3 = peekingIterator.next(); // also returns "a"}</pre>
     * <p>
     * <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.
     * <p>
     * <p>The returned iterator does not support removal after peeking, as
     * explained by {@link PeekingIterator#remove()}.
     * <p>
     * <p>Note: If the given iterator is already a {@code PeekingIterator},
     * it <i>might</i> be returned to the caller, although this is neither
     * guaranteed to occur nor required to be consistent.  For example, this
     * method <i>might</i> choose to pass through recognized implementations of
     * {@code PeekingIterator} when the behavior of the implementation is
     * known to meet the contract guaranteed by this method.
     * <p>
     * <p>There is no {@link Iterable} equivalent to this method, so use this
     * method to wrap each individual iterator as it is generated.
     *
     * @param iterator the backing iterator. The {@link PeekingIterator} assumes
     *                 ownership of this iterator, so users should cease making direct calls
     *                 to it after calling this method.
     * @return a peeking iterator backed by that iterator. Apart from the
     * additional {@link PeekingIterator#peek()} method, this iterator behaves
     * exactly the same as {@code iterator}.
     */
    public static <T> PeekingIterator<T> peekingIterator(
            Iterator<? extends T> iterator) {
        if (iterator instanceof PeekingImpl) {
            // Safe to cast <? extends T> to <T> because PeekingImpl only uses T
            // covariantly (and cannot be subclassed to add non-covariant uses).
            @SuppressWarnings("unchecked")
            PeekingImpl<T> peeking = (PeekingImpl<T>) iterator;
            return peeking;
        }
        return new PeekingImpl<T>(iterator);
    }

    
Implementation of PeekingIterator that avoids peeking unless necessary.

/**
     * Implementation of PeekingIterator that avoids peeking unless necessary.
     */
    private static class PeekingImpl<E> implements PeekingIterator<E> {

        private final Iterator<? extends E> iterator;
        private boolean hasPeeked;
        private E peekedElement;

        public PeekingImpl(Iterator<? extends E> iterator) {
            this.iterator = checkNotNull(iterator);
        }

        @Override
        public boolean hasNext() {
            return hasPeeked || iterator.hasNext();
        }

        @Override
        public E next() {
            if (!hasPeeked) {
                return iterator.next();
            }
            E result = peekedElement;
            hasPeeked = false;
            peekedElement = null;
            return result;
        }

        @Override
        public void remove() {
            checkState(!hasPeeked, "Can't remove after you've peeked at next");
            iterator.remove();
        }

        @Override
        public E peek() {
            if (!hasPeeked) {
                peekedElement = iterator.next();
                hasPeeked = true;
            }
            return peekedElement;
        }
    }
}