Package com.globalmentor.collections.iterators

Class Iterators

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

  • Constructor Details

    • Iterators

      public Iterators()

  • Method Details

    • emptyIterator

      @Deprecated public static final <T> Iterator<T> emptyIterator()
      Deprecated.
      to be removed in favor of Collections.emptyIterator().
      Type Parameters:
      T - The type of the iterator.
      Returns:
      The immutable empty iterator.

    • emptyIterable

      @Deprecated public static final <T> Iterable<T> emptyIterable()
      Deprecated.
      to be removed in favor of Collections.emptySet().
      Type Parameters:
      T - The generic type of empty iterable to return.
      Returns:
      The immutable empty iterable.

    • concat

      public static <E> JoinIterator<E> concat(@Nonnull Iterator<E> iterator1, @Nonnull Iterator<E> iterator2)
      Returns an iterator concatenating the contents of two iterators.
      API Note:
      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 Iterator<E>... iterators)
      Returns an iterator concatenating the contents of multiple iterators.
      API Note:
      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:
      NullPointerException - if any of the given iterators is null.

    • concat

      public static <E> JoinIterator<E> concat(@Nonnull Iterator<E> iterator, @Nonnull Enumeration<E> enumeration)
      Returns an iterator concatenating the contents of an iterator and an enumeration.
      API Note:
      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> ListIterator<E> createCopy(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.

    • findNext

      public static <E> Optional<E> findNext(@Nonnull 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:
      An Optional describing the first element of this iterator, or an empty Optional if the iterator is empty.
      See Also:

    • findOnly

      public static <E> Optional<E> findOnly(@Nonnull Iterator<E> iterator)
      Returns an Optional describing the first and only element of this iterator, or an empty Optional if the iterator is empty.
      Implementation Specification:
      This implementation delegates to findOnly(Iterator, Supplier).
      Type Parameters:
      E - The type of elements returned by the iterator.
      Parameters:
      iterator - The iterator from which the only object should be retrieved.
      Returns:
      An Optional describing the only element of this iterator, or an empty Optional if the iterator is empty.
      Throws:
      IllegalArgumentException - if the given stream has more than one element.
      See Also:

    • findOnly

      public static <E, X extends RuntimeException> Optional<E> findOnly(@Nonnull Iterator<E> iterator, @Nonnull Supplier<X> manyElementsExceptionSupplier)
      Returns an Optional describing the first and only element of this iterator, or an empty Optional if the iterator is empty.
      Type Parameters:
      E - The type of elements returned by the iterator.
      X - The type of exception to be thrown if there are many elements.
      Parameters:
      iterator - The iterator from which the only object should be retrieved.
      manyElementsExceptionSupplier - The strategy for creating an exception to throw if more than one element is present.
      Returns:
      An Optional describing the only element of this iterator, or an empty Optional if the iterator is empty.
      Throws:
      RuntimeException - if the given stream has more than one element.
      See Also:

    • getOnly

      public static <E> E getOnly(@Nonnull Iterator<E> iterator)
      Retrieves the one and only one element expected to be in the iterator.
      Type Parameters:
      E - The type of element in the iterator.
      Parameters:
      iterator - The iterator from which the only element will be retrieved.
      Returns:
      The one and only one element in the iterator.
      Throws:
      NoSuchElementException - if the iterator has no more elements
      IllegalArgumentException - if the given iterator has more than one element.

    • getOnly

      public static <E, X extends RuntimeException> E getOnly(@Nonnull Iterator<E> iterator, @Nonnull Supplier<X> manyElementsExceptionSupplier)
      Retrieves the one and only one element expected to be in the iterator.
      Type Parameters:
      E - The type of element in the iterator.
      X - The type of exception to be thrown if there are many elements.
      Parameters:
      iterator - The iterator from which only element will be retrieved.
      manyElementsExceptionSupplier - The strategy for creating an exception to throw if more than one element is present.
      Returns:
      The one and only one element in the iterator.
      Throws:
      NoSuchElementException - if the iterator has no more elements
      RuntimeException - if the given stream has more than one element.

    • reverse

      public static <E> Iterator<E> reverse(@Nonnull ListIterator<E> listIterator)
      Reverses a given list iterator by returning a new iterator that iterates in the opposite direction, starting at the present iteration location.
      API Note:
      This method does not initially change the present iteration location. If it is desired to start at the other end of the iterator, the iterator's position must be changed before calling this method—for example by calling: while(listIterator.hasNext()) listIterator.next();. Nevertheless what is normally desired is to provide a reversed order Iterable of a List, and for this Lists.reversing(List) should be used, which can create and place the list iterator at the end of the list in a more efficient manner.
      Type Parameters:
      E - The type of element in the iterator.
      Parameters:
      listIterator - The list iterator to be iterated in reverse order.
      Returns:
      An iterator view that iterates the given list iterator, but in reverse order.
      See Also:

    • toArray

      public static <E> E[] toArray(Iterator<E> iterator, 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:
      NullPointerException - if the given iterator and/or element class is null.

    • toArray

      public static <E> E[] toArray(Iterable<E> iterable, 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:
      NullPointerException - if the given iterable and/or element class is null.

    • toEnumeration

      public static <E> Enumeration<E> toEnumeration(@Nonnull 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> Iterable<E> toIterable(@Nonnull Iterator<E> iterator)
      Returns a single-use iterable that returns the given iterator.
      API Note:
      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> Iterator<E> toIterator(@Nonnull 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> Stream<E> toStream(@Nonnull 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.