Module com.jongsoft.lang
Package com.jongsoft.lang.collection

Interface Iterator<T>

  • Type Parameters:
    T - the type contained in the iterator
    All Superinterfaces:
    Foldable<T>, java.lang.Iterable<T>, java.util.Iterator<T>, java.io.Serializable, Streamable<T>, Traversable<T>, Value<T>
    public interface Iterator<T>
extends java.util.Iterator<T>, Traversable<T>
    An extension on the default Iterator that adds utility operations to easily manipulate the iterator or locate elements inside it.
    Since:
    0.0.3

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      static <T> Iterator<T> concat​(Iterator<T>... iterators)
      Combine multiple iterator instances into one big iterator.
      Iterator<T> filter​(java.util.function.Predicate<T> predicate)
      Filter out an element if it does not match the supplied predicate.
      default Optional<T> first​(java.util.function.Predicate<T> predicate)
      Find the first match in the elements using the provided Predicate.
      default <U> U foldLeft​(U start, java.util.function.BiFunction<? super U,​? super T,​? extends U> combiner)
      Folds the elements from the left, starting with the start value and combining the result by successively calling the combiner operation.
      default <U> U foldRight​(U start, java.util.function.BiFunction<? super T,​? super U,​? extends U> combiner)
      Folds the elements from the right, starting with the start value and combining the result by successively calling the combiner.
      default T get()
      This operation is a convenience method for the Iterator.next().
      default boolean isSingleValued()
      Is this instance single-valued or not.
      default Iterator<T> iterator()  
      default Optional<T> last​(java.util.function.Predicate<T> predicate)
      Find the last match in the Iterator using the provided Predicate.
      default <U> Iterator<U> map​(java.util.function.Function<T,​U> mapper)
      Perform a mapping operation on the elements in the stream.
      default T reduceLeft​(java.util.function.BiFunction<? super T,​? super T,​? extends T> reducer)
      Reduce the collection from the left, starting with the first element in the collection and successively calling the reducer until there are no more elements.
      void reset()
      Move the iterator back to the first element in the sequence.
      default java.lang.Object[] toNativeArray()
      Create a primitive array of the elements contained within the iterator.

      • Methods inherited from interface java.lang.Iterable

        forEach, spliterator

      • Methods inherited from interface java.util.Iterator

        forEachRemaining, hasNext, next, remove

    • Method Detail

      • filter

        Iterator<T> filter​(java.util.function.Predicate<T> predicate)
        Description copied from interface: Streamable
        Filter out an element if it does not match the supplied predicate. This operation will iterate over all elements and return a new set containing only the elements where the predicate returns true for.
        Specified by:
        filter in interface Streamable<T>
        Specified by:
        filter in interface Traversable<T>
        Parameters:
        predicate - the predicate to apply to the contents of this
        Returns:
        the filtered value

      • first

        default Optional<T> first​(java.util.function.Predicate<T> predicate)
        Description copied from interface: Traversable
        Find the first match in the elements using the provided Predicate. The returned Optional is null safe and will either contain the element or be an empty Optional.

        Example:

        // the result will be an Optional with the value 2
    int firstMatch = Collection(1, 2, 3, 4)
          .first(i -> i % 2 == 0);
        Specified by:
        first in interface Traversable<T>
        Parameters:
        predicate - the predicate to use
        Returns:
        the first match found

      • foldLeft

        default <U> U foldLeft​(U start,
                       java.util.function.BiFunction<? super U,​? super T,​? extends U> combiner)
        Description copied from interface: Foldable
        Folds the elements from the left, starting with the start value and combining the result by successively calling the combiner operation.

        Example: 

        // result "!test"
    List("t", "e", "s", "t").foldLeft("!",  (x, y) -> x + y)
        Specified by:
        foldLeft in interface Foldable<T>
        Type Parameters:
        U - the type of value returned
        Parameters:
        start - the start value for the fold operation
        combiner - the operation used to combine elements
        Returns:
        the folded value

      • foldRight

        default <U> U foldRight​(U start,
                        java.util.function.BiFunction<? super T,​? super U,​? extends U> combiner)
        Description copied from interface: Foldable
        Folds the elements from the right, starting with the start value and combining the result by successively calling the combiner.

        Example: 

        // result "tset!"
    List("t", "e", "s", "t").foldRight("!",  (x, y) -> x + y)
        Specified by:
        foldRight in interface Foldable<T>
        Type Parameters:
        U - the targeted type of combination method
        Parameters:
        start - the start value for the fold operation
        combiner - the operation used to combine elements
        Returns:
        the folded value

      • get

        default T get()
        This operation is a convenience method for the Iterator.next().
        Specified by:
        get in interface Value<T>
        Returns:
        the next value in the iterator
        See Also:
        Iterator.next()

      • isSingleValued

        default boolean isSingleValued()
        Description copied from interface: Value
        Is this instance single-valued or not.
        Specified by:
        isSingleValued in interface Value<T>
        Returns:
        true if single-valued, otherwise false

      • iterator

        default Iterator<T> iterator()
        Specified by:
        iterator in interface java.lang.Iterable<T>
        Specified by:
        iterator in interface Traversable<T>

      • last

        default Optional<T> last​(java.util.function.Predicate<T> predicate)
        Description copied from interface: Traversable
        Find the last match in the Iterator using the provided Predicate. The returned Optional is null safe and will either contain the element or be an empty Optional.

        Example:

        // the result will be an Optional with the value 4
    int firstMatch = Collection(1, 2, 3, 4)
          .last(i -> i % 2 == 0);
        Specified by:
        last in interface Traversable<T>
        Parameters:
        predicate - the predicate to use
        Returns:
        the last match found

      • map

        default <U> Iterator<U> map​(java.util.function.Function<T,​U> mapper)
        Description copied from interface: Streamable
        Perform a mapping operation on the elements in the stream.

        This operation will loop over all elements in the stream and apply the mapper method. The mapped values will be returned in as a new stream of elements.

        Specified by:
        map in interface Streamable<T>
        Specified by:
        map in interface Traversable<T>
        Type Parameters:
        U - the type of object expected as a result
        Parameters:
        mapper - the mapping functionality
        Returns:
        the mapped object

      • reduceLeft

        default T reduceLeft​(java.util.function.BiFunction<? super T,​? super T,​? extends T> reducer)
        Description copied from interface: Foldable

        Reduce the collection from the left, starting with the first element in the collection and successively calling the reducer until there are no more elements.

        Example: 

        // result "test"
    List("t", "e", "s", "t").reduceLeft((x, y) -> x + y)

        This operation is similar to the Foldable.foldLeft(Object, BiFunction) where the first element is the head of the elements.

        Specified by:
        reduceLeft in interface Foldable<T>
        Parameters:
        reducer - the operation to use to reduce the elements to one value
        Returns:
        the reduced value
        See Also:
        Foldable.foldLeft(Object, BiFunction)

      • reset

        void reset()
        Move the iterator back to the first element in the sequence.

      • toNativeArray

        default java.lang.Object[] toNativeArray()
        Create a primitive array of the elements contained within the iterator.
        Returns:
        the primitive array

      • concat

        @SafeVarargs
static <T> Iterator<T> concat​(Iterator<T>... iterators)
        Combine multiple iterator instances into one big iterator.
        Type Parameters:
        T - the type of the iterator
        Parameters:
        iterators - the iterators to be combined
        Returns:
        the new iterator containing all elements of all iterators