Interface Traverser<T>

  • Type Parameters:
    T - traversed item type
    All Known Implementing Classes:
    AppendableTraverser, ResettableSingletonTraverser
    Functional Interface:
    This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

    @FunctionalInterface
    public interface Traverser<T>
    Traverses a potentially infinite sequence of non-null items. Each invocation of next() consumes and returns the next item in the sequence if available, or null if not. If the traverser is null-terminated, getting a null means it's exhausted and will keep returning null forever.

    All transformation methods (map(), append(), peek(), ...) are allowed to either return a new instance or to modify this instance. For correct functionality, you must always use the returned value and stop using the original instance.

    Since:
    Jet 3.0
    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      default Traverser<T> append​(T item)
      Returns a traverser that will return all the items of this traverser, plus an additional item once this one returns null.
      default Traverser<T> dropWhile​(java.util.function.Predicate<? super T> predicate)
      Returns a traverser that will emit a suffix of the original traverser, starting from the item for which the predicate fails (inclusive).
      default Traverser<T> filter​(java.util.function.Predicate<? super T> filterFn)
      Returns a traverser that will emit the same items as this traverser, but only those that pass the given predicate.
      default <R> Traverser<R> flatMap​(java.util.function.Function<? super T,​? extends Traverser<R>> flatMapFn)
      Returns a traverser that will apply the given mapping function to each item retrieved from this traverser and emit all the items from the resulting traversers, which must be null-terminated.
      default <R> Traverser<R> map​(java.util.function.Function<? super T,​? extends R> mapFn)
      Returns a traverser that will emit the results of applying mapFn to this traverser's items.
      T next()
      Returns the next item, removing it from this traverser.
      default Traverser<T> onFirstNull​(java.lang.Runnable action)
      Returns a traverser that will emit the same items as this traverser and additionally run the supplied action the first time this traverser returns null.
      default Traverser<T> peek​(java.util.function.Consumer<? super T> action)
      Returns a traverser that will emit the same items as this traverser, additionally passing each (non-null) item to the supplied consumer.
      default Traverser<T> prepend​(T item)
      Returns a traverser which prepends an additional item in front of all the items of this traverser.
      default Traverser<T> takeWhile​(java.util.function.Predicate<? super T> predicate)
      Returns a traverser that will emit a prefix of the original traverser, up to the item for which the predicate fails (exclusive).
    • Method Detail

      • next

        T next()
        Returns the next item, removing it from this traverser. If no item is available, returns null. If this traverser is null-terminated, getting a null means it's exhausted and will keep returning null forever. Otherwise, trying again later may produce one.
      • map

        @Nonnull
        @CheckReturnValue
        default <R> Traverser<R> map​(@Nonnull
                                     java.util.function.Function<? super T,​? extends R> mapFn)
        Returns a traverser that will emit the results of applying mapFn to this traverser's items. If mapFn returns null for an item, the returned traverser drops it and immediately moves on to the next item from this traverser. This way mapFn can perform filtering in addition to transformation.
      • filter

        @Nonnull
        @CheckReturnValue
        default Traverser<T> filter​(@Nonnull
                                    java.util.function.Predicate<? super T> filterFn)
        Returns a traverser that will emit the same items as this traverser, but only those that pass the given predicate.
      • flatMap

        @Nonnull
        @CheckReturnValue
        default <R> Traverser<R> flatMap​(@Nonnull
                                         java.util.function.Function<? super T,​? extends Traverser<R>> flatMapFn)
        Returns a traverser that will apply the given mapping function to each item retrieved from this traverser and emit all the items from the resulting traversers, which must be null-terminated.

        The function must not return null traverser, but can return an empty traverser.

      • takeWhile

        @Nonnull
        @CheckReturnValue
        default Traverser<T> takeWhile​(@Nonnull
                                       java.util.function.Predicate<? super T> predicate)
        Returns a traverser that will emit a prefix of the original traverser, up to the item for which the predicate fails (exclusive).
      • dropWhile

        @Nonnull
        @CheckReturnValue
        default Traverser<T> dropWhile​(@Nonnull
                                       java.util.function.Predicate<? super T> predicate)
        Returns a traverser that will emit a suffix of the original traverser, starting from the item for which the predicate fails (inclusive).
      • append

        @Nonnull
        @CheckReturnValue
        default Traverser<T> append​(@Nonnull
                                    T item)
        Returns a traverser that will return all the items of this traverser, plus an additional item once this one returns null. After that it continues forwarding the return values of this traverser. It is meant to be used on finite traversers.

        Default implementations always returns a new traverser instance. If you need to append multiple objects or use this method frequently, AppendableTraverser might be a better choice.

      • prepend

        @Nonnull
        @CheckReturnValue
        default Traverser<T> prepend​(@Nonnull
                                     T item)
        Returns a traverser which prepends an additional item in front of all the items of this traverser.
      • peek

        @Nonnull
        @CheckReturnValue
        default Traverser<T> peek​(@Nonnull
                                  java.util.function.Consumer<? super T> action)
        Returns a traverser that will emit the same items as this traverser, additionally passing each (non-null) item to the supplied consumer.
      • onFirstNull

        @Nonnull
        @CheckReturnValue
        default Traverser<T> onFirstNull​(@Nonnull
                                         java.lang.Runnable action)
        Returns a traverser that will emit the same items as this traverser and additionally run the supplied action the first time this traverser returns null.