Package com.globalmentor.collections.iterators

Class Iterators

  • public class Iterators
extends java.lang.Object
    Various utilities to be used with iterators.
    Author:
    Garret Wilson
    See Also:
    Iterator

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.Iterable<?> EMPTY_ITERABLE
      The singleton immutable empty iterable.
      static java.util.Iterator<?> EMPTY_ITERATOR
      The singleton immutable empty iterator.

    • Constructor Summary

      Constructors 
      Constructor Description
      Iterators()  

    • Method Summary

      All Methods Static Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      static <E> JoinIterator<E> concat​(java.util.Iterator<E>... iterators)
      Returns an iterator concatenating the contents of multiple iterators.
      static <E> JoinIterator<E> concat​(java.util.Iterator<E> iterator, java.util.Enumeration<E> enumeration)
      Returns an iterator concatenating the contents of an iterator and an enumeration.
      static <E> JoinIterator<E> concat​(java.util.Iterator<E> iterator1, java.util.Iterator<E> iterator2)
      Returns an iterator concatenating the contents of two iterators.
      static <E> java.util.ListIterator<E> createCopy​(java.util.Iterator<E> iterator)
      Creates a copy of the iterator that contains the same data but will not reflect any modified values of the underlying collection.
      static <T> java.lang.Iterable<T> emptyIterable()  
      static <T> java.util.Iterator<T> emptyIterator()  
      static <E> java.util.Optional<E> findNext​(java.util.Iterator<E> iterator)
      Returns an Optional describing the first element of this iterator, or an empty Optional if the iterator is empty.
      static <E> E getNext​(java.util.Iterator<E> iterator)
      Deprecated.
      Migrate to findNext(Iterator).
      static <E> E[] toArray​(java.lang.Iterable<E> iterable, java.lang.Class<E> elementClass)
      Returns a copy of the contents of the iterable in a new array in iterator traversal order.
      static <E> E[] toArray​(java.util.Iterator<E> iterator, java.lang.Class<E> elementClass)
      Returns a copy of the contents of the iterator in a new array in iterator traversal order.
      static <E> java.util.Enumeration<E> toEnumeration​(java.util.Iterator<E> iterator)
      Converts an iterator to an enumeration, if it isn't already.
      static <E> java.lang.Iterable<E> toIterable​(java.util.Iterator<E> iterator)
      Returns a single-use iterable that returns the given iterator.
      static <E> java.util.Iterator<E> toIterator​(java.util.Enumeration<E> enumeration)
      Converts an enumeration to an iteration, if it isn't already.
      static <E> java.util.stream.Stream<E> toStream​(java.util.Iterator<E> iterator)
      Returns a stream providing access to the contents of the given iterator.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • EMPTY_ITERATOR

        public static final java.util.Iterator<?> EMPTY_ITERATOR
        The singleton immutable empty iterator.

      • EMPTY_ITERABLE

        public static final java.lang.Iterable<?> EMPTY_ITERABLE
        The singleton immutable empty iterable.

    • Constructor Detail

      • Iterators

        public Iterators()

    • Method Detail

      • emptyIterator

        public static final <T> java.util.Iterator<T> emptyIterator()
        Type Parameters:
        T - The type of the iterator.
        Returns:
        The immutable empty iterator.

      • emptyIterable

        public static final <T> java.lang.Iterable<T> emptyIterable()
        Type Parameters:
        T - The generic type of empty iterable to return.
        Returns:
        The immutable empty iterable.

      • concat

        public static <E> JoinIterator<E> concat​(@Nonnull
                                         java.util.Iterator<E> iterator1,
                                         @Nonnull
                                         java.util.Iterator<E> iterator2)
        Returns an iterator concatenating the contents of two iterators.

        Tip: The returned iterator can be used as an Iterator or an Enumeration.

        Type Parameters:
        E - The type of elements returned by the iterators.
        Parameters:
        iterator1 - The iterator the contents of which will appear first in the iteration.
        iterator2 - The iterator the contents of which will appear second in the iteration.
        Returns:
        An iterator that will return the contents of the two iterators in order.

      • concat

        @SafeVarargs
public static <E> JoinIterator<E> concat​(@Nonnull
                                         java.util.Iterator<E>... iterators)
        Returns an iterator concatenating the contents of multiple iterators.

        Tip: The returned iterator can be used as an Iterator or an Enumeration.

        Type Parameters:
        E - The type of elements returned by the iterators.
        Parameters:
        iterators - The iterators to concatenate.
        Returns:
        An iterator that will return the contents of the given iterators in order.
        Throws:
        java.lang.NullPointerException - if any of the given iterators is null.

      • concat

        public static <E> JoinIterator<E> concat​(@Nonnull
                                         java.util.Iterator<E> iterator,
                                         @Nonnull
                                         java.util.Enumeration<E> enumeration)
        Returns an iterator concatenating the contents of an iterator and an enumeration.

        Tip: The returned iterator can be used as an Iterator or an Enumeration.

        Type Parameters:
        E - The type of elements returned by the iterator and the enumeration.
        Parameters:
        iterator - An iterator the contents of which will appear first in the iteration.
        enumeration - An enumeration the contents of which will appear after that of the iterator.
        Returns:
        An iterator that will return the contents of the iterator and the enumeration in order.

      • createCopy

        public static <E> java.util.ListIterator<E> createCopy​(java.util.Iterator<E> iterator)
        Creates a copy of the iterator that contains the same data but will not reflect any modified values of the underlying collection. Creates a new collection, collects the values of the given iterator, then returns an iterator to the new collection.
        Type Parameters:
        E - The type of items that the iterator is set up to iterate.
        Parameters:
        iterator - The iterator to make a copy of.
        Returns:
        An iterator containing the same values as the given iterator but not reflecting the underlying values of the original collection.

      • getNext

        @Deprecated
public static <E> E getNext​(java.util.Iterator<E> iterator)
        Deprecated.
        Migrate to findNext(Iterator).
        Returns the next item from an iterator, or null if there is no next item. This differs from Iterator.next(), which throws an exception if there is no next item.
        Type Parameters:
        E - The type of items that the iterator is set up to iterate.
        Parameters:
        iterator - The iterator from which the next object should be retrieved.
        Returns:
        The next item of the iterator.
        See Also:
        Iterator.next()

      • findNext

        public static <E> java.util.Optional<E> findNext​(@Nonnull
                                                 java.util.Iterator<E> iterator)
        Returns an Optional describing the first element of this iterator, or an empty Optional if the iterator is empty.
        API Note:
        This method is equivalent to calling Iterator.next(), except an empty optional is returned rather than throwing an exception if there is no next item.
        Type Parameters:
        E - The type of elements returned by the iterator.
        Parameters:
        iterator - The iterator from which the next object should be retrieved.
        Returns:
        The next item of the iterator.
        See Also:
        Iterator.next(), Stream.findFirst()

      • toArray

        public static <E> E[] toArray​(java.util.Iterator<E> iterator,
                              java.lang.Class<E> elementClass)
        Returns a copy of the contents of the iterator in a new array in iterator traversal order.
        Type Parameters:
        E - The type of the iterator.
        Parameters:
        iterator - The iterator the contents of which to return as an array.
        elementClass - The class representing the type of elements returned by the iterable.
        Returns:
        A array containing the contents of the iterable.
        Throws:
        java.lang.NullPointerException - if the given iterator and/or element class is null.

      • toArray

        public static <E> E[] toArray​(java.lang.Iterable<E> iterable,
                              java.lang.Class<E> elementClass)
        Returns a copy of the contents of the iterable in a new array in iterator traversal order.
        Type Parameters:
        E - The type of the iterator.
        Parameters:
        iterable - The iterable the contents of which to return as an array.
        elementClass - The class representing the type of elements returned by the iterable.
        Returns:
        A array containing the contents of the iterable.
        Throws:
        java.lang.NullPointerException - if the given iterable and/or element class is null.

      • toEnumeration

        public static <E> java.util.Enumeration<E> toEnumeration​(@Nonnull
                                                         java.util.Iterator<E> iterator)
        Converts an iterator to an enumeration, if it isn't already.
        Type Parameters:
        E - the type of elements returned by the iterator.
        Parameters:
        iterator - The iterator to be converted to an enumeration.
        Returns:
        An enumeration delegating to the given iterator, or the iterator itself it is also an Enumeration.

      • toIterable

        public static <E> java.lang.Iterable<E> toIterable​(@Nonnull
                                                   java.util.Iterator<E> iterator)
        Returns a single-use iterable that returns the given iterator.

        Unlike most iterables, the returned iterable may only be iterated a single time.

        Type Parameters:
        E - the type of elements returned by the iterator.
        Parameters:
        iterator - The iterator to be converted to an iterable.
        Returns:
        A single-user iterable that returns the given iterator.

      • toIterator

        public static <E> java.util.Iterator<E> toIterator​(@Nonnull
                                                   java.util.Enumeration<E> enumeration)
        Converts an enumeration to an iteration, if it isn't already.
        Type Parameters:
        E - the type of elements returned by the enumeration.
        Parameters:
        enumeration - The enumeration to be converted to an iterator.
        Returns:
        An iterator delegating to the given enumeration, or the enumeration itself it is also an Iterator.

      • toStream

        public static <E> java.util.stream.Stream<E> toStream​(@Nonnull
                                                      java.util.Iterator<E> iterator)
        Returns a stream providing access to the contents of the given iterator.
        Type Parameters:
        E - The type of elements returned by the iterator.
        Parameters:
        iterator - The iterator to be converted to a stream.
        Returns:
        A stream that returns the contents of the given iterator.