Package io.vavr.collection

Interface Iterator<T>

Type Parameters:
T - the element type
All Superinterfaces:
Foldable<T>, Iterable<T>, Iterator<T>, Traversable<T>, Value<T>
All Known Implementing Classes:
AbstractIterator, BitSetModule.BitSetIterator, HashArrayMappedTrieModule.LeafNodeIterator, IteratorModule.CachedIterator, IteratorModule.ConcatIterator, IteratorModule.DistinctIterator, IteratorModule.EmptyIterator, IteratorModule.GroupedIterator, StreamModule.FlatMapIterator, StreamModule.StreamIterator
public interface Iterator<T> extends Iterator<T>, Traversable<T>
A compositional alternative to java.util.Iterator designed for single-pass traversal of a sequence.

Note: Iterators maintain an internal mutable state. They are not thread-safe and must not be reused or shared across operations (for example, after passing them to List.ofAll(Iterable)).

The abstraction defines two fundamental operations: hasNext(), which checks whether another element is available, and next(), which consumes and returns that element. If hasNext() returns false, next() will throw NoSuchElementException.

Caution: Methods other than hasNext() and next() are single-use. Once such a method has been invoked, further method calls on the same iterator are not guaranteed to succeed.

In essence, an Iterator represents a traversal cursor over a collection rather than the collection itself, and can therefore be consumed only once.

  • Method Summary

    Modifier and Type
    Method
    Description
    default <R> Iterator<R>
    collect(@NonNull PartialFunction<? super T,? extends R> partialFunction)
    Applies a PartialFunction to all elements that are defined for it and collects the results.
    static <T> Iterator<T>
    concat(Iterable<? extends Iterable<? extends T>> iterables)
    Creates an Iterator that iterates over all elements of the supplied sequence of iterables, in order.
    static <T> Iterator<T>
    concat(Iterable<? extends T>... iterables)
    Creates an Iterator that traverses the elements of the provided iterables in sequence, as if they were concatenated.
    default Iterator<T>
    concat(Iterator<? extends T> that)
    Returns a new Iterator that yields the elements of this iterator followed by all elements of the specified iterator.
    static <T> Iterator<T>
    continually(Supplier<? extends T> supplier)
    Returns an infinite Iterator that repeatedly generates values using the provided Supplier.
    static <T> Iterator<T>
    continually(T t)
    Returns an infinite Iterator that endlessly yields the given element.
    default Iterator<T>
    distinct()
    Returns a new Traversable containing the elements of this instance with all duplicates removed.
    default Iterator<T>
    distinctBy(@NonNull Comparator<? super T> comparator)
    Returns a new Traversable containing the elements of this instance without duplicates, as determined by the given comparator.
    default <U> Iterator<T>
    distinctBy(@NonNull Function<? super T,? extends U> keyExtractor)
    Returns a new Traversable containing the elements of this instance without duplicates, based on keys extracted from elements using keyExtractor.
    default Iterator<T>
    distinctByKeepLast(Comparator<? super T> comparator)
    Returns a new Iterator containing the elements of this instance without duplicates, keeping the last occurrence of each duplicate element, as determined by the given comparator.
    default <U> Iterator<T>
    distinctByKeepLast(Function<? super T,? extends U> keyExtractor)
    Returns a new Iterator containing the elements of this instance without duplicates, keeping the last occurrence of each duplicate element, based on keys extracted from elements using keyExtractor.
    default Iterator<T>
    drop(int n)
    Removes up to n elements from this iterator.
    default Iterator<T>
    dropRight(int n)
    Returns a new Traversable without the last n elements, or an empty instance if this contains fewer than n elements.
    default Iterator<T>
    dropUntil(@NonNull Predicate<? super T> predicate)
    Returns a new Traversable starting from the first element that satisfies the given predicate, dropping all preceding elements.
    default Iterator<T>
    dropWhile(@NonNull Predicate<? super T> predicate)
    Returns a new Traversable starting from the first element that does not satisfy the given predicate, dropping all preceding elements.
    static <T> Iterator<T>
    empty()
    Returns an empty Iterator.
    static <T> Iterator<T>
    fill(int n, Supplier<? extends T> s)
    Returns an Iterator over a sequence of n elements supplied by the given Supplier.
    static <T> Iterator<T>
    fill(int n, T element)
    Returns an Iterator containing the given element repeated n times.
    default Iterator<T>
    filter(@NonNull Predicate<? super T> predicate)
    Returns an Iterator that contains elements that satisfy the given predicate.
    default Option<T>
    findLast(@NonNull Predicate<? super T> predicate)
    Returns the last element that satisfies the given predicate.
    default <U> Iterator<U>
    flatMap(@NonNull Function<? super T,? extends Iterable<? extends U>> mapper)
    FlatMaps the elements of this Iterator to Iterables, which are iterated in the order of occurrence.
    default <U> U
    foldRight(U zero, @NonNull BiFunction<? super T,? super U,? extends U> f)
    Folds the elements of this structure from the right, starting with the given zero value and successively applying the combine function to each element.
    static Iterator<Integer>
    from(int value)
    Returns an infinite Iterator of int values starting from value.
    static Iterator<Integer>
    from(int value, int step)
    Returns an infinite Iterator of int values starting from value and advancing by the specified step.
    static Iterator<Long>
    from(long value)
    Returns an infinite Iterator of long values starting from value.
    static Iterator<Long>
    from(long value, long step)
    Returns an infinite Iterator of long values starting from value and advancing by the specified step.
    default T
    get()
    Returns the first element of this Traversable in iteration order.
    default <C> Map<C,Iterator<T>>
    groupBy(@NonNull Function<? super T,? extends C> classifier)
    Groups elements of this Traversable based on a classifier function.
    default Iterator<Seq<T>>
    grouped(int size)
    Splits this Traversable into consecutive blocks of the given size.
    default boolean
    hasDefiniteSize()
    Indicates whether this Traversable has a known finite size.
    default T
    head()
    Returns the first element of this non-empty Traversable.
    default Iterator<T>
    init()
    Returns all elements of this Traversable except the last one.
    default Option<Iterator<T>>
    initOption()
    Returns all elements of this Traversable except the last one, wrapped in an Option.
    default Iterator<T>
    intersperse(T element)
    Returns a new Iterator where the specified element is inserted between each element of this iterator.
    default boolean
    isAsync()
    An Iterator is computed synchronously.
    default boolean
    isEmpty()
    Checks if this Traversable contains no elements.
    default boolean
    isLazy()
    An Iterator is computed lazily.
    default boolean
    isSequential()
    Indicates whether the elements of this Traversable appear in encounter (insertion) order.
    default boolean
    isTraversableAgain()
    Checks if this Traversable can be traversed multiple times without side effects.
    static <T> Iterator<T>
    iterate(Supplier<? extends Option<? extends T>> supplier)
    Creates an Iterator that repeatedly invokes the given Supplier as long as it returns a Some value, terminating when it returns None.
    static <T> Iterator<T>
    iterate(T seed, Function<? super T,? extends T> f)
    Returns an infinite Iterator that generates values by repeatedly applying the given function to the previous value, starting with seed.
    default @NonNull Iterator<T>
    iterator()
    Returns an iterator over the elements of this Traversable, implemented via Traversable.head() and Traversable.tail().
    default T
    last()
    Returns the last element of this Traversable.
    default int
    length()
    Returns the number of elements in this Traversable.
    default <U> Iterator<U>
    map(@NonNull Function<? super T,? extends U> mapper)
    Maps the elements of this Iterator lazily using the given mapper.
    default <U> Iterator<U>
    mapTo(U value)
    Maps the underlying value to another fixed value.
    default Iterator<Void>
    mapToVoid()
    Maps the underlying value to Void
    static <T> Iterator<T>
    narrow(Iterator<? extends T> iterator)
    Narrows an Iterator<? extends T> to Iterator<T> using a type-safe cast.
    static <T> Iterator<T>
    of(T element)
    Creates an Iterator that yields exactly one element.
    static <T> Iterator<T>
    of(T... elements)
    Creates an Iterator that iterates over the provided elements.
    static Iterator<Boolean>
    ofAll(boolean... elements)
    Creates an Iterator over the given boolean values.
    static Iterator<Byte>
    ofAll(byte... elements)
    Creates an Iterator over the given byte values.
    static Iterator<Character>
    ofAll(char... elements)
    Creates an Iterator over the given char values.
    static Iterator<Double>
    ofAll(double... elements)
    Creates an Iterator over the given double values.
    static Iterator<Float>
    ofAll(float... elements)
    Creates an Iterator over the given float values.
    static Iterator<Integer>
    ofAll(int... elements)
    Creates an Iterator over the given int values.
    static Iterator<Long>
    ofAll(long... elements)
    Creates an Iterator over the given long values.
    static Iterator<Short>
    ofAll(short... elements)
    Creates an Iterator over the given short values.
    static <T> Iterator<T>
    ofAll(Iterable<? extends T> iterable)
    Creates an Iterator from the provided Iterable.
    static <T> Iterator<T>
    ofAll(Iterator<? extends T> iterator)
    Creates an Iterator that delegates hasNext() and next() to the given Iterator.
    default Iterator<T>
    orElse(Iterable<? extends T> other)
    Returns this Traversable if it is non-empty; otherwise, returns the given alternative.
    default Iterator<T>
    orElse(@NonNull Supplier<? extends Iterable<? extends T>> supplier)
    Returns this Traversable if it is non-empty; otherwise, returns the result of evaluating the given supplier.
    default Tuple2<Iterator<T>,Iterator<T>>
    partition(@NonNull Predicate<? super T> predicate)
    Splits this Traversable into two partitions according to a predicate.
    default Iterator<T>
    peek(@NonNull Consumer<? super T> action)
    Performs the given action on the first element if this is an eager implementation.
    static Iterator<Character>
    range(char from, char toExclusive)
    Creates an Iterator of characters starting from from (inclusive) up to toExclusive (exclusive).
    static Iterator<Integer>
    range(int from, int toExclusive)
    Creates an Iterator of int values starting from from (inclusive) up to toExclusive (exclusive).
    static Iterator<Long>
    range(long from, long toExclusive)
    Creates an Iterator of long values starting from from (inclusive) up to toExclusive (exclusive).
    static Iterator<Character>
    rangeBy(char from, char toExclusive, int step)
    Creates an Iterator of characters starting from from (inclusive) up to toExclusive (exclusive), advancing by the specified step.
    static Iterator<Double>
    rangeBy(double from, double toExclusive, double step)
    Creates an Iterator of double values starting from from (inclusive) up to toExclusive (exclusive), advancing by the specified step.
    static Iterator<Integer>
    rangeBy(int from, int toExclusive, int step)
    Creates an Iterator of int values starting from from (inclusive) up to toExclusive (exclusive), advancing by the specified step.
    static Iterator<Long>
    rangeBy(long from, long toExclusive, long step)
    Creates an Iterator of long values starting from from (inclusive) up to toExclusive (exclusive), advancing by the specified step.
    static Iterator<BigDecimal>
    rangeBy(BigDecimal from, BigDecimal toExclusive, BigDecimal step)
    Creates an Iterator of BigDecimal values starting from from (inclusive) up to toExclusive (exclusive), advancing by the specified step.
    static Iterator<Character>
    rangeClosed(char from, char toInclusive)
    Creates an Iterator of characters starting from from (inclusive) up to toInclusive (inclusive).
    static Iterator<Integer>
    rangeClosed(int from, int toInclusive)
    Creates an Iterator of int values starting from from (inclusive) up to toInclusive (inclusive).
    static Iterator<Long>
    rangeClosed(long from, long toInclusive)
    Creates an Iterator of long values starting from from (inclusive) up to toInclusive (inclusive).
    static Iterator<Character>
    rangeClosedBy(char from, char toInclusive, int step)
    Creates an Iterator of characters starting from from (inclusive) up to toInclusive (inclusive), advancing by the specified step.
    static Iterator<Double>
    rangeClosedBy(double from, double toInclusive, double step)
    Creates an Iterator of double values starting from from (inclusive) up to toInclusive (inclusive), advancing by the specified step.
    static Iterator<Integer>
    rangeClosedBy(int from, int toInclusive, int step)
    Creates an Iterator of int values starting from from (inclusive) up to toInclusive (inclusive), advancing by the specified step.
    static Iterator<Long>
    rangeClosedBy(long from, long toInclusive, long step)
    Creates an Iterator of long values starting from from (inclusive) up to toInclusive (inclusive), advancing by the specified step.
    default T
    reduceLeft(@NonNull BiFunction<? super T,? super T,? extends T> op)
    Reduces the elements of this Traversable from the left using the given binary operation.
    default T
    reduceRight(@NonNull BiFunction<? super T,? super T,? extends T> op)
    Reduces the elements of this Traversable from the right using the given binary operation.
    default Iterator<T>
    reject(@NonNull Predicate<? super T> predicate)
    Returns a new traversable containing only the elements that do not satisfy the given predicate.
    default Iterator<T>
    replace(T currentElement, T newElement)
    Replaces the first occurrence of currentElement with newElement, if it exists.
    default Iterator<T>
    replaceAll(T currentElement, T newElement)
    Replaces all occurrences of currentElement with newElement.
    default Iterator<T>
    retainAll(@NonNull Iterable<? extends T> elements)
    Retains only the elements from this Traversable that are contained in the given elements.
    default Traversable<T>
    scan(T zero, @NonNull BiFunction<? super T,? super T,? extends T> operation)
    Computes a prefix scan of the elements of this Traversable.
    default <U> Iterator<U>
    scanLeft(U zero, @NonNull BiFunction<? super U,? super T,? extends U> operation)
    Produces a collection containing cumulative results of applying the operator from left to right.
    default <U> Iterator<U>
    scanRight(U zero, @NonNull BiFunction<? super T,? super U,? extends U> operation)
    Produces a collection containing cumulative results of applying the operator from right to left.
    default Iterator<Seq<T>>
    slideBy(@NonNull Function<? super T,?> classifier)
    Partitions this Traversable into consecutive non-overlapping windows according to a classification function.
    default Iterator<Seq<T>>
    sliding(int size)
    Slides a window of a given size over this Traversable with a step size of 1.
    default Iterator<Seq<T>>
    sliding(int size, int step)
    Slides a window of a specific size with a given step over this Traversable.
    default Tuple2<Iterator<T>,Iterator<T>>
    span(@NonNull Predicate<? super T> predicate)
    Splits this Traversable into a prefix and remainder according to the given predicate.
    default String
    stringPrefix()
    Returns the name of this Value type, which is used by toString().
    static <T> Iterator<T>
    tabulate(int n, Function<? super Integer,? extends T> f)
    Returns an Iterator over a sequence of n elements, where each element is computed by the given function f applied to its index.
    default Iterator<T>
    tail()
    Returns a new Traversable without its first element.
    default Option<Iterator<T>>
    tailOption()
    Returns a new Traversable without its first element as an Option.
    default Iterator<T>
    take(int n)
    Take the first n elements from this iterator.
    default Iterator<T>
    takeRight(int n)
    Returns the last n elements of this Traversable, or all elements if n exceeds the length.
    default Iterator<T>
    takeUntil(@NonNull Predicate<? super T> predicate)
    Takes elements from this Traversable until the given predicate holds for an element.
    default Iterator<T>
    takeWhile(@NonNull Predicate<? super T> predicate)
    Takes elements from this Traversable while the given predicate holds.
    default <U> U
    transform(Function<? super Iterator<T>,? extends U> f)
    Applies a transformation function to this Iterator and returns the result.
    static <T> Iterator<T>
    unfold(T seed, Function<? super T,Option<Tuple2<? extends T,? extends T>>> f)
    Creates an Iterator by repeatedly applying a function to a seed value.
    static <T, U> Iterator<U>
    unfoldLeft(T seed, Function<? super T,Option<Tuple2<? extends T,? extends U>>> f)
    Creates an Iterator by repeatedly applying a function to a seed value, generating elements in a left-to-right order.
    static <T, U> Iterator<U>
    unfoldRight(T seed, Function<? super T,Option<Tuple2<? extends U,? extends T>>> f)
    Creates an Iterator by repeatedly applying a function to a seed value, generating elements in a right-to-left order.
    default <T1, T2> Tuple2<Iterator<T1>,Iterator<T2>>
    unzip(@NonNull Function<? super T,Tuple2<? extends T1,? extends T2>> unzipper)
    Unzips the elements of this Traversable by mapping each element to a pair and splitting them into two separate Traversable collections.
    default <T1, T2, T3>
    Tuple3<Iterator<T1>,Iterator<T2>,Iterator<T3>>
    unzip3(@NonNull Function<? super T,Tuple3<? extends T1,? extends T2,? extends T3>> unzipper)
    Unzips the elements of this Traversable by mapping each element to a triple and splitting them into three separate Traversable collections.
    default <U> Iterator<Tuple2<T,U>>
    zip(@NonNull Iterable<? extends U> that)
    Returns a Traversable formed by pairing elements of this Traversable with elements of another Iterable.
    default <U> Iterator<Tuple2<T,U>>
    zipAll(@NonNull Iterable<? extends U> that, T thisElem, U thatElem)
    Returns a Traversable formed by pairing elements of this Traversable with elements of another Iterable, filling in placeholder elements when one collection is shorter than the other.
    default <U, R> Iterator<R>
    zipWith(@NonNull Iterable<? extends U> that, BiFunction<? super T,? super U,? extends R> mapper)
    Returns a Traversable by combining elements of this Traversable with elements of another Iterable using a mapping function.
    default Iterator<Tuple2<T,Integer>>
    zipWithIndex()
    Zips this Traversable with its indices, starting at 0.
    default <U> Iterator<U>
    zipWithIndex(@NonNull BiFunction<? super T,? super Integer,? extends U> mapper)
    Zips this Traversable with its indices and maps the resulting pairs using the provided mapper.

    Methods inherited from interface io.vavr.collection.Foldable

    fold, reduce, reduceOption

    Methods inherited from interface java.util.Iterator

    forEachRemaining, hasNext, next, remove

    Methods inherited from interface io.vavr.collection.Traversable

    arrangeBy, average, containsAll, count, equals, existsUnique, find, foldLeft, forEachWithIndex, hashCode, headOption, isDistinct, isOrdered, isSingleValued, lastOption, max, maxBy, maxBy, min, minBy, minBy, mkCharSeq, mkCharSeq, mkCharSeq, mkString, mkString, mkString, nonEmpty, product, reduceLeftOption, reduceRightOption, single, singleOption, size, spliterator, sum

    Methods inherited from interface io.vavr.Value

    collect, collect, contains, corresponds, eq, exists, forAll, forEach, getOrElse, getOrElse, getOrElseThrow, getOrElseTry, getOrNull, out, out, stderr, stdout, toArray, toCharSeq, toCompletableFuture, toEither, toEither, toInvalid, toInvalid, toJavaArray, toJavaArray, toJavaArray, toJavaCollection, toJavaList, toJavaList, toJavaMap, toJavaMap, toJavaMap, toJavaOptional, toJavaParallelStream, toJavaSet, toJavaSet, toJavaStream, toLeft, toLeft, toLinkedMap, toLinkedMap, toLinkedSet, toList, toMap, toMap, toOption, toPriorityQueue, toPriorityQueue, toQueue, toRight, toRight, toSet, toSortedMap, toSortedMap, toSortedMap, toSortedMap, toSortedSet, toSortedSet, toStream, toString, toTree, toTree, toTry, toTry, toValid, toValid, toValidation, toValidation, toVector

  • Method Details

    • concat

      @SafeVarargs static <T> Iterator<T> concat(Iterable<? extends T>... iterables)
      Creates an Iterator that traverses the elements of the provided iterables in sequence, as if they were concatenated.
      Type Parameters:
      T - the element type
      Parameters:
      iterables - the source iterables
      Returns:
      an iterator yielding the elements of each iterable in order
      Throws:
      NullPointerException - if iterables is null

    • concat

      static <T> Iterator<T> concat(Iterable<? extends Iterable<? extends T>> iterables)
      Creates an Iterator that iterates over all elements of the supplied sequence of iterables, in order.
      Type Parameters:
      T - the element type
      Parameters:
      iterables - an iterable whose elements provide the individual iterables to traverse
      Returns:
      an iterator yielding the concatenated contents of the nested iterables
      Throws:
      NullPointerException - if iterables is null

    • empty

      static <T> Iterator<T> empty()
      Returns an empty Iterator.
      Type Parameters:
      T - the element type
      Returns:
      an iterator with no elements

    • narrow

      static <T> Iterator<T> narrow(Iterator<? extends T> iterator)
      Narrows an Iterator<? extends T> to Iterator<T> using a type-safe cast. This is valid because the iterator is read-only with respect to element types.
      Type Parameters:
      T - the element type
      Parameters:
      iterator - the iterator to narrow
      Returns:
      the same iterator, viewed as Iterator<T>
      Throws:
      NullPointerException - if iterator is null

    • of

      static <T> Iterator<T> of(T element)
      Creates an Iterator that yields exactly one element.
      Type Parameters:
      T - the element type
      Parameters:
      element - the single element
      Returns:
      an iterator containing only element

    • of

      @SafeVarargs static <T> Iterator<T> of(T... elements)
      Creates an Iterator that iterates over the provided elements.
      Type Parameters:
      T - the element type
      Parameters:
      elements - zero or more elements
      Returns:
      an iterator over the supplied elements

    • ofAll

      static <T> Iterator<T> ofAll(Iterable<? extends T> iterable)
      Creates an Iterator from the provided Iterable. This is a convenience method equivalent to calling Iterator.ofAll(iterable.iterator()).
      Type Parameters:
      T - the element type
      Parameters:
      iterable - the source iterable
      Returns:
      an iterator over the iterable's elements
      Throws:
      NullPointerException - if iterable is null

    • ofAll

      static <T> Iterator<T> ofAll(Iterator<? extends T> iterator)
      Creates an Iterator that delegates hasNext() and next() to the given Iterator.
      Type Parameters:
      T - the element type
      Parameters:
      iterator - the underlying iterator
      Returns:
      an iterator that forwards calls to iterator
      Throws:
      NullPointerException - if iterator is null

    • ofAll

      static Iterator<Boolean> ofAll(boolean... elements)
      Creates an Iterator over the given boolean values.
      Parameters:
      elements - the boolean values
      Returns:
      an iterator yielding the boxed values
      Throws:
      NullPointerException - if elements is null

    • ofAll

      static Iterator<Byte> ofAll(byte... elements)
      Creates an Iterator over the given byte values.
      Parameters:
      elements - the byte values
      Returns:
      an iterator yielding the boxed Byte values
      Throws:
      NullPointerException - if elements is null

    • ofAll

      static Iterator<Character> ofAll(char... elements)
      Creates an Iterator over the given char values.
      Parameters:
      elements - the char values
      Returns:
      an iterator yielding the boxed Character values
      Throws:
      NullPointerException - if elements is null

    • ofAll

      static Iterator<Double> ofAll(double... elements)
      Creates an Iterator over the given double values.
      Parameters:
      elements - the double values
      Returns:
      an iterator yielding the boxed Double values
      Throws:
      NullPointerException - if elements is null

    • ofAll

      static Iterator<Float> ofAll(float... elements)
      Creates an Iterator over the given float values.
      Parameters:
      elements - the float values
      Returns:
      an iterator yielding the boxed Float values
      Throws:
      NullPointerException - if elements is null

    • ofAll

      static Iterator<Integer> ofAll(int... elements)
      Creates an Iterator over the given int values.
      Parameters:
      elements - the int values
      Returns:
      an iterator yielding the boxed Integer values
      Throws:
      NullPointerException - if elements is null

    • ofAll

      static Iterator<Long> ofAll(long... elements)
      Creates an Iterator over the given long values.
      Parameters:
      elements - the long values
      Returns:
      an iterator yielding the boxed Long values
      Throws:
      NullPointerException - if elements is null

    • ofAll

      static Iterator<Short> ofAll(short... elements)
      Creates an Iterator over the given short values.
      Parameters:
      elements - the short values
      Returns:
      an iterator yielding the boxed Short values
      Throws:
      NullPointerException - if elements is null

    • tabulate

      static <T> Iterator<T> tabulate(int n, Function<? super Integer,? extends T> f)
      Returns an Iterator over a sequence of n elements, where each element is computed by the given function f applied to its index.

      The resulting sequence is f(0), f(1), ..., f(n - 1).

      Type Parameters:
      T - the element type
      Parameters:
      n - the number of elements
      f - the function computing element values
      Returns:
      an iterator over the computed elements
      Throws:
      NullPointerException - if f is null

    • fill

      static <T> Iterator<T> fill(int n, Supplier<? extends T> s)
      Returns an Iterator over a sequence of n elements supplied by the given Supplier.

      Each element is obtained by invoking s.get().

      Type Parameters:
      T - the element type
      Parameters:
      n - the number of elements
      s - the supplier providing element values
      Returns:
      an iterator over the supplied elements
      Throws:
      NullPointerException - if s is null

    • fill

      static <T> Iterator<T> fill(int n, T element)
      Returns an Iterator containing the given element repeated n times.
      Type Parameters:
      T - the element type
      Parameters:
      n - the number of repetitions
      element - the element to repeat
      Returns:
      an iterator over n occurrences of element

    • range

      static Iterator<Character> range(char from, char toExclusive)
      Creates an Iterator of characters starting from from (inclusive) up to toExclusive (exclusive).

      Examples: 

       Iterator.range('a', 'c')  // yields 'a', 'b'
 Iterator.range('c', 'a')  // yields no elements
      Parameters:
      from - the first character (inclusive)
      toExclusive - the end character (exclusive)
      Returns:
      an iterator over the specified character range, or empty if from >= toExclusive

    • rangeBy

      static Iterator<Character> rangeBy(char from, char toExclusive, int step)
      Creates an Iterator of characters starting from from (inclusive) up to toExclusive (exclusive), advancing by the specified step.

      Examples: 

       Iterator.rangeBy('a', 'c', 1)  // yields 'a', 'b'
 Iterator.rangeBy('a', 'd', 2)  // yields 'a', 'c'
 Iterator.rangeBy('d', 'a', -2) // yields 'd', 'b'
 Iterator.rangeBy('d', 'a', 2)  // yields no elements
      Parameters:
      from - the first character (inclusive)
      toExclusive - the end character (exclusive) - successor of the last character if step > 0, or predecessor if step < 0
      step - the increment between characters; must not be zero
      Returns:
      an iterator over the specified character range, or empty if the step direction does not match the direction from from to toExclusive
      Throws:
      IllegalArgumentException - if step is zero

    • rangeBy

      @GwtIncompatible("BigDecimalHelper is GwtIncompatible") static Iterator<Double> rangeBy(double from, double toExclusive, double step)
      Creates an Iterator of double values starting from from (inclusive) up to toExclusive (exclusive), advancing by the specified step.

      Examples: 

       Iterator.rangeBy(1.0, 3.0, 1.0)   // yields 1.0, 2.0
 Iterator.rangeBy(1.0, 4.0, 2.0)   // yields 1.0, 3.0
 Iterator.rangeBy(4.0, 1.0, -2.0)  // yields 4.0, 2.0
 Iterator.rangeBy(4.0, 1.0, 2.0)   // yields no elements
      Parameters:
      from - the first number (inclusive)
      toExclusive - the end number (exclusive)
      step - the increment; must not be zero
      Returns:
      an iterator over the specified range, or empty if the step direction does not match the direction from from to toExclusive, or if from == toExclusive
      Throws:
      IllegalArgumentException - if step is zero

    • rangeBy

      static Iterator<BigDecimal> rangeBy(BigDecimal from, BigDecimal toExclusive, BigDecimal step)
      Creates an Iterator of BigDecimal values starting from from (inclusive) up to toExclusive (exclusive), advancing by the specified step.

      This method provides precise decimal arithmetic suitable for financial calculations and other scenarios where exact decimal representation is required.

      Examples: 

       Iterator.rangeBy(new BigDecimal("1.0"), new BigDecimal("3.0"), new BigDecimal("1.0"))   // yields 1.0, 2.0
 Iterator.rangeBy(new BigDecimal("1.0"), new BigDecimal("4.0"), new BigDecimal("2.0"))   // yields 1.0, 3.0
 Iterator.rangeBy(new BigDecimal("4.0"), new BigDecimal("1.0"), new BigDecimal("-2.0"))  // yields 4.0, 2.0
 Iterator.rangeBy(new BigDecimal("4.0"), new BigDecimal("1.0"), new BigDecimal("2.0"))   // yields no elements
      Parameters:
      from - the first number (inclusive)
      toExclusive - the end number (exclusive)
      step - the increment; must not be zero
      Returns:
      an iterator over the specified range, or empty if the step direction does not match the direction from from to toExclusive, or if from == toExclusive
      Throws:
      IllegalArgumentException - if step is zero

    • range

      static Iterator<Integer> range(int from, int toExclusive)
      Creates an Iterator of int values starting from from (inclusive) up to toExclusive (exclusive).

      Examples: 

       Iterator.range(0, 0)   // yields no elements
 Iterator.range(2, 0)   // yields no elements
 Iterator.range(-2, 2)  // yields -2, -1, 0, 1
      Parameters:
      from - the first number (inclusive)
      toExclusive - the end number (exclusive)
      Returns:
      an iterator over the specified range, or empty if from >= toExclusive

    • rangeBy

      static Iterator<Integer> rangeBy(int from, int toExclusive, int step)
      Creates an Iterator of int values starting from from (inclusive) up to toExclusive (exclusive), advancing by the specified step.

      Examples: 

       Iterator.rangeBy(1, 3, 1)   // yields 1, 2
 Iterator.rangeBy(1, 4, 2)   // yields 1, 3
 Iterator.rangeBy(4, 1, -2)  // yields 4, 2
 Iterator.rangeBy(4, 1, 2)   // yields no elements
      Parameters:
      from - the first number (inclusive)
      toExclusive - the end number (exclusive) — last number + 1 if step > 0, or last number - 1 if step < 0
      step - the increment; must not be zero
      Returns:
      an iterator over the specified range, or empty if the step direction does not match the direction from from to toExclusive, or if from == toExclusive
      Throws:
      IllegalArgumentException - if step is zero

    • range

      static Iterator<Long> range(long from, long toExclusive)
      Creates an Iterator of long values starting from from (inclusive) up to toExclusive (exclusive).

      Examples: 

       Iterator.range(0L, 0L)   // yields no elements
 Iterator.range(2L, 0L)   // yields no elements
 Iterator.range(-2L, 2L)  // yields -2L, -1L, 0L, 1L
      Parameters:
      from - the first number (inclusive)
      toExclusive - the end number (exclusive)
      Returns:
      an iterator over the specified range, or empty if from >= toExclusive

    • rangeBy

      static Iterator<Long> rangeBy(long from, long toExclusive, long step)
      Creates an Iterator of long values starting from from (inclusive) up to toExclusive (exclusive), advancing by the specified step.

      Examples: 

       Iterator.rangeBy(1L, 3L, 1L)   // yields 1L, 2L
 Iterator.rangeBy(1L, 4L, 2L)   // yields 1L, 3L
 Iterator.rangeBy(4L, 1L, -2L)  // yields 4L, 2L
 Iterator.rangeBy(4L, 1L, 2L)   // yields no elements
      Parameters:
      from - the first number (inclusive)
      toExclusive - the end number (exclusive) — last number + 1 if step > 0, or last number - 1 if step < 0
      step - the increment; must not be zero
      Returns:
      an iterator over the specified range, or empty if the step direction does not match the direction from from to toExclusive, or if from == toExclusive
      Throws:
      IllegalArgumentException - if step is zero

    • rangeClosed

      static Iterator<Character> rangeClosed(char from, char toInclusive)
      Creates an Iterator of characters starting from from (inclusive) up to toInclusive (inclusive).

      Examples: 

       Iterator.rangeClosed('a', 'c')  // yields 'a', 'b', 'c'
 Iterator.rangeClosed('c', 'a')  // yields no elements
      Parameters:
      from - the first character (inclusive)
      toInclusive - the last character (inclusive)
      Returns:
      an iterator over the specified character range, or empty if from > toInclusive

    • rangeClosedBy

      static Iterator<Character> rangeClosedBy(char from, char toInclusive, int step)
      Creates an Iterator of characters starting from from (inclusive) up to toInclusive (inclusive), advancing by the specified step.

      Examples: 

       Iterator.rangeClosedBy('a', 'c', 1)   // yields 'a', 'b', 'c'
 Iterator.rangeClosedBy('a', 'd', 2)   // yields 'a', 'c'
 Iterator.rangeClosedBy('d', 'a', -2)  // yields 'd', 'b'
 Iterator.rangeClosedBy('d', 'a', 2)   // yields no elements
      Parameters:
      from - the first character (inclusive)
      toInclusive - the last character (inclusive)
      step - the increment; must not be zero
      Returns:
      an iterator over the specified character range, or empty if the step direction does not match the direction from from to toInclusive
      Throws:
      IllegalArgumentException - if step is zero

    • rangeClosedBy

      @GwtIncompatible static Iterator<Double> rangeClosedBy(double from, double toInclusive, double step)
      Creates an Iterator of double values starting from from (inclusive) up to toInclusive (inclusive), advancing by the specified step.

      Examples: 

       Iterator.rangeClosedBy(1.0, 3.0, 1.0)   // yields 1.0, 2.0, 3.0
 Iterator.rangeClosedBy(1.0, 4.0, 2.0)   // yields 1.0, 3.0
 Iterator.rangeClosedBy(4.0, 1.0, -2.0)  // yields 4.0, 2.0
 Iterator.rangeClosedBy(4.0, 1.0, 2.0)   // yields no elements
      Parameters:
      from - the first number (inclusive)
      toInclusive - the last number (inclusive)
      step - the increment; must not be zero
      Returns:
      an iterator over the specified range, or empty if the step direction does not match the direction from from to toInclusive, or if from == toInclusive it returns a singleton iterator
      Throws:
      IllegalArgumentException - if step is zero

    • rangeClosed

      static Iterator<Integer> rangeClosed(int from, int toInclusive)
      Creates an Iterator of int values starting from from (inclusive) up to toInclusive (inclusive).

      Examples: 

       Iterator.rangeClosed(0, 0)   // yields 0
 Iterator.rangeClosed(2, 0)   // yields no elements
 Iterator.rangeClosed(-2, 2)  // yields -2, -1, 0, 1, 2
      Parameters:
      from - the first number (inclusive)
      toInclusive - the last number (inclusive)
      Returns:
      an iterator over the specified range, or empty if from > toInclusive

    • rangeClosedBy

      static Iterator<Integer> rangeClosedBy(int from, int toInclusive, int step)
      Creates an Iterator of int values starting from from (inclusive) up to toInclusive (inclusive), advancing by the specified step.

      Examples: 

       Iterator.rangeClosedBy(1, 3, 1)   // yields 1, 2, 3
 Iterator.rangeClosedBy(1, 4, 2)   // yields 1, 3
 Iterator.rangeClosedBy(4, 1, -2)  // yields 4, 2
 Iterator.rangeClosedBy(4, 1, 2)   // yields no elements
      Parameters:
      from - the first number (inclusive)
      toInclusive - the last number (inclusive)
      step - the increment; must not be zero
      Returns:
      an iterator over the specified range, or empty if the step direction does not match the direction from from to toInclusive, or if from == toInclusive it returns a singleton iterator
      Throws:
      IllegalArgumentException - if step is zero

    • rangeClosed

      static Iterator<Long> rangeClosed(long from, long toInclusive)
      Creates an Iterator of long values starting from from (inclusive) up to toInclusive (inclusive).

      Examples: 

       Iterator.rangeClosed(0L, 0L)   // yields 0L
 Iterator.rangeClosed(2L, 0L)   // yields no elements
 Iterator.rangeClosed(-2L, 2L)  // yields -2L, -1L, 0L, 1L, 2L
      Parameters:
      from - the first number (inclusive)
      toInclusive - the last number (inclusive)
      Returns:
      an iterator over the specified range, or empty if from > toInclusive

    • rangeClosedBy

      static Iterator<Long> rangeClosedBy(long from, long toInclusive, long step)
      Creates an Iterator of long values starting from from (inclusive) up to toInclusive (inclusive), advancing by the specified step.

      Examples: 

       Iterator.rangeClosedBy(1L, 3L, 1L)   // yields 1L, 2L, 3L
 Iterator.rangeClosedBy(1L, 4L, 2L)   // yields 1L, 3L
 Iterator.rangeClosedBy(4L, 1L, -2L)  // yields 4L, 2L
 Iterator.rangeClosedBy(4L, 1L, 2L)   // yields no elements
      Parameters:
      from - the first number (inclusive)
      toInclusive - the last number (inclusive)
      step - the increment; must not be zero
      Returns:
      an iterator over the specified range, or empty if the step direction does not match the direction from from to toInclusive, or if from == toInclusive it returns a singleton iterator
      Throws:
      IllegalArgumentException - if step is zero

    • from

      static Iterator<Integer> from(int value)
      Returns an infinite Iterator of int values starting from value.

      The iterator wraps from Integer.MAX_VALUE to Integer.MIN_VALUE.

      Parameters:
      value - the starting int value
      Returns:
      an iterator that endlessly yields consecutive int values starting from value

    • from

      static Iterator<Integer> from(int value, int step)
      Returns an infinite Iterator of int values starting from value and advancing by the specified step.

      The iterator wraps from Integer.MAX_VALUE to Integer.MIN_VALUE if overflow occurs.

      Parameters:
      value - the starting int value
      step - the increment for each iteration
      Returns:
      an iterator that endlessly yields consecutive int values starting from value, spaced by step

    • from

      static Iterator<Long> from(long value)
      Returns an infinite Iterator of long values starting from value.

      The iterator wraps from Long.MAX_VALUE to Long.MIN_VALUE if overflow occurs.

      Parameters:
      value - the starting long value
      Returns:
      an iterator that endlessly yields consecutive long values starting from value

    • from

      static Iterator<Long> from(long value, long step)
      Returns an infinite Iterator of long values starting from value and advancing by the specified step.

      The iterator wraps from Long.MAX_VALUE to Long.MIN_VALUE if overflow occurs.

      Parameters:
      value - the starting long value
      step - the increment for each iteration
      Returns:
      an iterator that endlessly yields consecutive long values starting from value, spaced by step

    • continually

      static <T> Iterator<T> continually(Supplier<? extends T> supplier)
      Returns an infinite Iterator that repeatedly generates values using the provided Supplier.
      Type Parameters:
      T - the type of values produced
      Parameters:
      supplier - the supplier providing iterator values; must not be null
      Returns:
      an iterator that endlessly yields values from the supplier
      Throws:
      NullPointerException - if supplier is null

    • iterate

      static <T> Iterator<T> iterate(Supplier<? extends Option<? extends T>> supplier)
      Creates an Iterator that repeatedly invokes the given Supplier as long as it returns a Some value, terminating when it returns None.
      Type Parameters:
      T - the type of values produced
      Parameters:
      supplier - the supplier providing Option values; must not be null
      Returns:
      an iterator yielding the values wrapped in Some, stopping at the first None
      Throws:
      NullPointerException - if the supplier produces a null value

    • iterate

      static <T> Iterator<T> iterate(T seed, Function<? super T,? extends T> f)
      Returns an infinite Iterator that generates values by repeatedly applying the given function to the previous value, starting with seed.

      Each call to getNext() produces the next element by applying f to the previous element.

      Type Parameters:
      T - the type of values produced
      Parameters:
      seed - the initial value
      f - the function to compute the next value from the previous; must not be null
      Returns:
      an iterator that endlessly yields values generated from seed using f
      Throws:
      NullPointerException - if f is null

    • continually

      static <T> Iterator<T> continually(T t)
      Returns an infinite Iterator that endlessly yields the given element.
      Type Parameters:
      T - the type of the element
      Parameters:
      t - the element to repeat
      Returns:
      an iterator that repeatedly returns t

    • collect

      default <R> Iterator<R> collect(@NonNull PartialFunction<? super T,? extends R> partialFunction)
      Description copied from interface: Traversable
      Applies a PartialFunction to all elements that are defined for it and collects the results.

      For each element in iteration order, the function is first tested: 

      
 partialFunction.isDefinedAt(element)
      If true, the element is mapped to type R: 
      
 R newElement = partialFunction.apply(element)

      Note: If this Traversable is ordered (i.e., extends Ordered), the caller must ensure that the resulting elements are comparable (i.e., implement Comparable).

      Specified by:
      collect in interface Traversable<T>
      Type Parameters:
      R - the type of elements in the resulting Traversable
      Parameters:
      partialFunction - a function that may not be defined for all elements of this traversable
      Returns:
      a new Traversable containing the results of applying the partial function

    • concat

      default Iterator<T> concat(Iterator<? extends T> that)
      Returns a new Iterator that yields the elements of this iterator followed by all elements of the specified iterator.

      This method appends the elements from that to the end of this iterator, creating a concatenated sequence.

      Examples: 

       Iterator.of(1, 2).concat(Iterator.of(3, 4))  // yields 1, 2, 3, 4
 Iterator.empty().concat(Iterator.of(1, 2))   // yields 1, 2
 Iterator.of(1, 2).concat(Iterator.empty())   // yields 1, 2
      Parameters:
      that - the iterator whose elements should be appended
      Returns:
      a new iterator containing elements from both iterators
      Throws:
      NullPointerException - if that is null

    • intersperse

      default Iterator<T> intersperse(T element)
      Returns a new Iterator where the specified element is inserted between each element of this iterator.
      Parameters:
      element - the element to intersperse
      Returns:
      an iterator with element interleaved between the original elements

    • transform

      default <U> U transform(Function<? super Iterator<T>,? extends U> f)
      Applies a transformation function to this Iterator and returns the result.
      Type Parameters:
      U - the type of the result
      Parameters:
      f - the function to transform this iterator; must not be null
      Returns:
      the result of applying f to this iterator
      Throws:
      NullPointerException - if f is null

    • zip

      default <U> Iterator<Tuple2<T,U>> zip(@NonNull Iterable<? extends U> that)
      Description copied from interface: Traversable
      Returns a Traversable formed by pairing elements of this Traversable with elements of another Iterable. Pairing stops when either collection runs out of elements; any remaining elements in the longer collection are ignored.

      The length of the resulting Traversable is the minimum of the lengths of this Traversable and that.

      Specified by:
      zip in interface Traversable<T>
      Type Parameters:
      U - the type of elements in the second half of each pair
      Parameters:
      that - an Iterable providing the second element of each pair
      Returns:
      a new Traversable containing pairs of corresponding elements

    • zipWith

      default <U, R> Iterator<R> zipWith(@NonNull Iterable<? extends U> that, BiFunction<? super T,? super U,? extends R> mapper)
      Description copied from interface: Traversable
      Returns a Traversable by combining elements of this Traversable with elements of another Iterable using a mapping function. Pairing stops when either collection runs out of elements.

      The length of the resulting Traversable is the minimum of the lengths of this Traversable and that.

      Specified by:
      zipWith in interface Traversable<T>
      Type Parameters:
      U - the type of elements in the second parameter of the mapper
      R - the type of elements in the resulting Traversable
      Parameters:
      that - an Iterable providing the second parameter of the mapper
      mapper - a function that combines elements from this and that into a new element
      Returns:
      a new Traversable containing mapped elements

    • zipAll

      default <U> Iterator<Tuple2<T,U>> zipAll(@NonNull Iterable<? extends U> that, T thisElem, U thatElem)
      Description copied from interface: Traversable
      Returns a Traversable formed by pairing elements of this Traversable with elements of another Iterable, filling in placeholder elements when one collection is shorter than the other.

      The length of the resulting Traversable is the maximum of the lengths of this Traversable and that.

      If this Traversable is shorter than that, thisElem is used as a filler. Conversely, if that is shorter, thatElem is used.

      Specified by:
      zipAll in interface Traversable<T>
      Type Parameters:
      U - the type of elements in the second half of each pair
      Parameters:
      that - an Iterable providing the second element of each pair
      thisElem - the element used to fill missing values if this Traversable is shorter than that
      thatElem - the element used to fill missing values if that is shorter than this Traversable
      Returns:
      a new Traversable containing pairs of elements, including fillers as needed

    • zipWithIndex

      default Iterator<Tuple2<T,Integer>> zipWithIndex()
      Description copied from interface: Traversable
      Zips this Traversable with its indices, starting at 0.
      Specified by:
      zipWithIndex in interface Traversable<T>
      Returns:
      a new Traversable containing each element paired with its index

    • zipWithIndex

      default <U> Iterator<U> zipWithIndex(@NonNull BiFunction<? super T,? super Integer,? extends U> mapper)
      Description copied from interface: Traversable
      Zips this Traversable with its indices and maps the resulting pairs using the provided mapper.
      Specified by:
      zipWithIndex in interface Traversable<T>
      Type Parameters:
      U - the type of elements in the resulting Traversable
      Parameters:
      mapper - a function mapping an element and its index to a new element
      Returns:
      a new Traversable containing the mapped elements

    • unzip

      default <T1, T2> Tuple2<Iterator<T1>,Iterator<T2>> unzip(@NonNull Function<? super T,Tuple2<? extends T1,? extends T2>> unzipper)
      Description copied from interface: Traversable
      Unzips the elements of this Traversable by mapping each element to a pair and splitting them into two separate Traversable collections.
      Specified by:
      unzip in interface Traversable<T>
      Type Parameters:
      T1 - type of the first element in the resulting pairs
      T2 - type of the second element in the resulting pairs
      Parameters:
      unzipper - a function that maps elements of this Traversable to pairs
      Returns:
      a Tuple2 containing two Traversable collections with the split elements

    • unzip3

      default <T1, T2, T3> Tuple3<Iterator<T1>,Iterator<T2>,Iterator<T3>> unzip3(@NonNull Function<? super T,Tuple3<? extends T1,? extends T2,? extends T3>> unzipper)
      Description copied from interface: Traversable
      Unzips the elements of this Traversable by mapping each element to a triple and splitting them into three separate Traversable collections.
      Specified by:
      unzip3 in interface Traversable<T>
      Type Parameters:
      T1 - type of the first element in the resulting triples
      T2 - type of the second element in the resulting triples
      T3 - type of the third element in the resulting triples
      Parameters:
      unzipper - a function that maps elements of this Traversable to triples
      Returns:
      a Tuple3 containing three Traversable collections with the split elements

    • unfold

      static <T> Iterator<T> unfold(T seed, Function<? super T,Option<Tuple2<? extends T,? extends T>>> f)
      Creates an Iterator by repeatedly applying a function to a seed value.

      The function takes the current seed and returns None to signal the end of iteration, or Some<Tuple2> containing the next element to yield and the seed for the next step.

      Example: 

      
 Iterator.unfold(10, x -> x == 0
   ? Option.none()
   : Option.of(new Tuple2<>(x-1, x)));
 // yields 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
      Type Parameters:
      T - the type of the seed and produced elements
      Parameters:
      seed - the initial seed value
      f - the function to produce the next element and seed; must not be null
      Returns:
      an iterator producing the elements generated by repeatedly applying f
      Throws:
      NullPointerException - if f is null

    • unfoldLeft

      static <T, U> Iterator<U> unfoldLeft(T seed, Function<? super T,Option<Tuple2<? extends T,? extends U>>> f)
      Creates an Iterator by repeatedly applying a function to a seed value, generating elements in a left-to-right order.

      The function receives the current seed and returns None to signal the end of iteration, or Some<Tuple2> containing the next seed and the element to include in the iterator.

      Example: 

      
 Iterator.unfoldLeft(10, x -> x == 0
   ? Option.none()
   : Option.of(new Tuple2<>(x-1, x)));
 // yields 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
      Type Parameters:
      T - the type of the seed
      U - the type of the produced elements
      Parameters:
      seed - the initial seed value
      f - the function to produce the next element and seed; must not be null
      Returns:
      an iterator producing elements generated from the seed using f
      Throws:
      NullPointerException - if f is null

    • unfoldRight

      static <T, U> Iterator<U> unfoldRight(T seed, Function<? super T,Option<Tuple2<? extends U,? extends T>>> f)
      Creates an Iterator by repeatedly applying a function to a seed value, generating elements in a right-to-left order.

      The function receives the current seed and returns None to signal the end of iteration, or Some<Tuple2> containing the element to yield and the next seed for subsequent calls.

      Example: 

      
 Iterator.unfoldRight(10, x -> x == 0
   ? Option.none()
   : Option.of(new Tuple2<>(x, x-1)));
 // yields 10, 9, 8, 7, 6, 5, 4, 3, 2, 1
      Type Parameters:
      T - the type of the seed
      U - the type of the produced elements
      Parameters:
      seed - the initial seed value
      f - the function to produce the next element and seed; must not be null
      Returns:
      an iterator producing elements generated from the seed using f
      Throws:
      NullPointerException - if f is null

    • distinct

      default Iterator<T> distinct()
      Description copied from interface: Traversable
      Returns a new Traversable containing the elements of this instance with all duplicates removed. Element equality is determined using equals.
      Specified by:
      distinct in interface Traversable<T>
      Returns:
      a new Traversable without duplicate elements

    • distinctBy

      default Iterator<T> distinctBy(@NonNull Comparator<? super T> comparator)
      Description copied from interface: Traversable
      Returns a new Traversable containing the elements of this instance without duplicates, as determined by the given comparator.
      Specified by:
      distinctBy in interface Traversable<T>
      Parameters:
      comparator - a comparator used to determine equality of elements
      Returns:
      a new Traversable with duplicates removed

    • distinctBy

      default <U> Iterator<T> distinctBy(@NonNull Function<? super T,? extends U> keyExtractor)
      Description copied from interface: Traversable
      Returns a new Traversable containing the elements of this instance without duplicates, based on keys extracted from elements using keyExtractor.

      The first occurrence of each key is retained in the resulting sequence.

      Specified by:
      distinctBy in interface Traversable<T>
      Type Parameters:
      U - the type of key
      Parameters:
      keyExtractor - a function to extract keys for determining uniqueness
      Returns:
      a new Traversable with duplicates removed based on keys

    • distinctByKeepLast

      default Iterator<T> distinctByKeepLast(Comparator<? super T> comparator)
      Returns a new Iterator containing the elements of this instance without duplicates, keeping the last occurrence of each duplicate element, as determined by the given comparator.

      When multiple elements are considered equal according to the comparator, only the last occurrence in the sequence is retained.

      Examples: 

       Iterator.of(1, 2, 2, 3, 1).distinctByKeepLast(Comparator.naturalOrder())  // yields 2, 3, 1
      Parameters:
      comparator - the comparator used to determine equality
      Returns:
      a new iterator containing distinct elements, keeping the last occurrence of duplicates
      Throws:
      NullPointerException - if comparator is null

    • distinctByKeepLast

      default <U> Iterator<T> distinctByKeepLast(Function<? super T,? extends U> keyExtractor)
      Returns a new Iterator containing the elements of this instance without duplicates, keeping the last occurrence of each duplicate element, based on keys extracted from elements using keyExtractor.

      When multiple elements have the same extracted key, only the last occurrence in the sequence is retained.

      Examples: 

       Iterator.of("a", "ab", "abc", "b").distinctByKeepLast(String::length)  // yields "abc", "b"
      Type Parameters:
      U - the type of the extracted key
      Parameters:
      keyExtractor - function used to extract the key from elements
      Returns:
      a new iterator containing distinct elements, keeping the last occurrence of duplicates
      Throws:
      NullPointerException - if keyExtractor is null

    • drop

      default Iterator<T> drop(int n)
      Removes up to n elements from this iterator.
      Specified by:
      drop in interface Traversable<T>
      Parameters:
      n - A number
      Returns:
      The empty iterator, if n <= 0 or this is empty, otherwise a new iterator without the first n elements.

    • dropRight

      default Iterator<T> dropRight(int n)
      Description copied from interface: Traversable
      Returns a new Traversable without the last n elements, or an empty instance if this contains fewer than n elements.
      Specified by:
      dropRight in interface Traversable<T>
      Parameters:
      n - the number of elements to drop from the end
      Returns:
      a new instance excluding the last n elements

    • dropUntil

      default Iterator<T> dropUntil(@NonNull Predicate<? super T> predicate)
      Description copied from interface: Traversable
      Returns a new Traversable starting from the first element that satisfies the given predicate, dropping all preceding elements.
      Specified by:
      dropUntil in interface Traversable<T>
      Parameters:
      predicate - a condition tested on each element
      Returns:
      a new instance starting from the first element matching the predicate

    • dropWhile

      default Iterator<T> dropWhile(@NonNull Predicate<? super T> predicate)
      Description copied from interface: Traversable
      Returns a new Traversable starting from the first element that does not satisfy the given predicate, dropping all preceding elements.

      This is equivalent to dropUntil(predicate.negate()), which is useful for method references that cannot be negated directly.

      Specified by:
      dropWhile in interface Traversable<T>
      Parameters:
      predicate - a condition tested on each element
      Returns:
      a new instance starting from the first element not matching the predicate

    • filter

      default Iterator<T> filter(@NonNull Predicate<? super T> predicate)
      Returns an Iterator that contains elements that satisfy the given predicate.
      Specified by:
      filter in interface Traversable<T>
      Parameters:
      predicate - A predicate
      Returns:
      A new Iterator

    • reject

      default Iterator<T> reject(@NonNull Predicate<? super T> predicate)
      Description copied from interface: Traversable
      Returns a new traversable containing only the elements that do not satisfy the given predicate.

      This is equivalent to filter(predicate.negate()).

      Specified by:
      reject in interface Traversable<T>
      Parameters:
      predicate - the condition to test elements
      Returns:
      a traversable with elements not matching the predicate

    • findLast

      default Option<T> findLast(@NonNull Predicate<? super T> predicate)
      Description copied from interface: Traversable
      Returns the last element that satisfies the given predicate.

      Equivalent to reverse().find(predicate) but potentially more efficient.

      Specified by:
      findLast in interface Traversable<T>
      Parameters:
      predicate - the condition to test elements
      Returns:
      Some(element) if a matching element is found, otherwise None; the element may be null

    • flatMap

      default <U> Iterator<U> flatMap(@NonNull Function<? super T,? extends Iterable<? extends U>> mapper)
      FlatMaps the elements of this Iterator to Iterables, which are iterated in the order of occurrence.
      Specified by:
      flatMap in interface Traversable<T>
      Type Parameters:
      U - Component type
      Parameters:
      mapper - A mapper
      Returns:
      A new Iterable

    • foldRight

      default <U> U foldRight(U zero, @NonNull BiFunction<? super T,? super U,? extends U> f)
      Description copied from interface: Foldable
      Folds the elements of this structure from the right, starting with the given zero value and successively applying the combine function to each element.

      Folding from the right means that elements are combined starting from the last element and associating each step with the accumulated result so far.

      Example: 

      
 // Result: "!cba"
 List.of("a", "b", "c").foldRight("!", (x, acc) -> acc + x);
      Specified by:
      foldRight in interface Foldable<T>
      Specified by:
      foldRight in interface Traversable<T>
      Type Parameters:
      U - the type of the accumulated result
      Parameters:
      zero - the initial value to start folding with
      f - a function that combines the next element and the accumulated value
      Returns:
      the folded result

    • get

      default T get()
      Description copied from interface: Traversable
      Returns the first element of this Traversable in iteration order.
      Specified by:
      get in interface Traversable<T>
      Specified by:
      get in interface Value<T>
      Returns:
      the first element

    • groupBy

      default <C> Map<C,Iterator<T>> groupBy(@NonNull Function<? super T,? extends C> classifier)
      Description copied from interface: Traversable
      Groups elements of this Traversable based on a classifier function.
      Specified by:
      groupBy in interface Traversable<T>
      Type Parameters:
      C - The type of the group keys
      Parameters:
      classifier - A function that assigns each element to a group
      Returns:
      A map where each key corresponds to a group of elements
      See Also:

    • grouped

      default Iterator<Seq<T>> grouped(int size)
      Description copied from interface: Traversable
      Splits this Traversable into consecutive blocks of the given size.

      Let length be the number of elements in this Traversable:

      • If empty, the resulting Iterator is empty.
      • If size <= length, the resulting Iterator contains length / size blocks of size size and possibly a final smaller block of size length % size.
      • If size > length, the resulting Iterator contains a single block of size length.

      Examples:

       
 [].grouped(1) = []
 [].grouped(0) throws
 [].grouped(-1) throws
 [1,2,3,4].grouped(2) = [[1,2],[3,4]]
 [1,2,3,4,5].grouped(2) = [[1,2],[3,4],[5]]
 [1,2,3,4].grouped(5) = [[1,2,3,4]]

      Note: grouped(size) is equivalent to sliding(size, size).

      Specified by:
      grouped in interface Traversable<T>
      Parameters:
      size - the block size; must be positive
      Returns:
      an Iterator over blocks of elements

    • hasDefiniteSize

      default boolean hasDefiniteSize()
      Description copied from interface: Traversable
      Indicates whether this Traversable has a known finite size.

      This should typically be implemented by concrete classes, not interfaces.

      Specified by:
      hasDefiniteSize in interface Traversable<T>
      Returns:
      true if the number of elements is finite and known, false otherwise.

    • head

      default T head()
      Description copied from interface: Traversable
      Returns the first element of this non-empty Traversable.
      Specified by:
      head in interface Traversable<T>
      Returns:
      the first element

    • init

      default Iterator<T> init()
      Description copied from interface: Traversable
      Returns all elements of this Traversable except the last one.

      This is the dual of Traversable.tail().

      Specified by:
      init in interface Traversable<T>
      Returns:
      a new instance containing all elements except the last

    • initOption

      default Option<Iterator<T>> initOption()
      Description copied from interface: Traversable
      Returns all elements of this Traversable except the last one, wrapped in an Option.

      This is the dual of Traversable.tailOption().

      Specified by:
      initOption in interface Traversable<T>
      Returns:
      Some(traversable) if non-empty, or None if this Traversable is empty

    • isAsync

      default boolean isAsync()
      An Iterator is computed synchronously.
      Specified by:
      isAsync in interface Value<T>
      Returns:
      false

    • isEmpty

      default boolean isEmpty()
      Description copied from interface: Traversable
      Checks if this Traversable contains no elements.
      Specified by:
      isEmpty in interface Traversable<T>
      Specified by:
      isEmpty in interface Value<T>
      Returns:
      true if empty, false otherwise

    • isLazy

      default boolean isLazy()
      An Iterator is computed lazily.
      Specified by:
      isLazy in interface Value<T>
      Returns:
      true

    • isTraversableAgain

      default boolean isTraversableAgain()
      Description copied from interface: Traversable
      Checks if this Traversable can be traversed multiple times without side effects.

      Implementations should provide the correct behavior; this is not meant for interfaces alone.

      Specified by:
      isTraversableAgain in interface Traversable<T>
      Returns:
      true if this Traversable is guaranteed to be repeatably traversable, false otherwise

    • isSequential

      default boolean isSequential()
      Description copied from interface: Traversable
      Indicates whether the elements of this Traversable appear in encounter (insertion) order.
      Specified by:
      isSequential in interface Traversable<T>
      Returns:
      true if insertion order is preserved, false otherwise

    • iterator

      default @NonNull Iterator<T> iterator()
      Description copied from interface: Traversable
      Returns an iterator over the elements of this Traversable, implemented via Traversable.head() and Traversable.tail(). Subclasses may override for a more efficient implementation.
      Specified by:
      iterator in interface Iterable<T>
      Specified by:
      iterator in interface Traversable<T>
      Specified by:
      iterator in interface Value<T>
      Returns:
      a new Iterator over the elements of this Traversable

    • last

      default T last()
      Description copied from interface: Traversable
      Returns the last element of this Traversable.
      Specified by:
      last in interface Traversable<T>
      Returns:
      the last element

    • length

      default int length()
      Description copied from interface: Traversable
      Returns the number of elements in this Traversable.

      Equivalent to Traversable.size().

      Specified by:
      length in interface Traversable<T>
      Returns:
      the number of elements

    • map

      default <U> Iterator<U> map(@NonNull Function<? super T,? extends U> mapper)
      Maps the elements of this Iterator lazily using the given mapper.
      Specified by:
      map in interface Traversable<T>
      Specified by:
      map in interface Value<T>
      Type Parameters:
      U - Component type
      Parameters:
      mapper - A mapper.
      Returns:
      A new Iterator

    • mapTo

      default <U> Iterator<U> mapTo(U value)
      Description copied from interface: Value
      Maps the underlying value to another fixed value.
      Specified by:
      mapTo in interface Traversable<T>
      Specified by:
      mapTo in interface Value<T>
      Type Parameters:
      U - The new component type
      Parameters:
      value - value to replace the contents with
      Returns:
      A new value

    • mapToVoid

      default Iterator<Void> mapToVoid()
      Description copied from interface: Value
      Maps the underlying value to Void
      Specified by:
      mapToVoid in interface Traversable<T>
      Specified by:
      mapToVoid in interface Value<T>
      Returns:
      A new value of type Void

    • orElse

      default Iterator<T> orElse(Iterable<? extends T> other)
      Description copied from interface: Traversable
      Returns this Traversable if it is non-empty; otherwise, returns the given alternative.
      Specified by:
      orElse in interface Traversable<T>
      Parameters:
      other - an alternative Traversable to return if this is empty
      Returns:
      this Traversable if non-empty, otherwise other

    • orElse

      default Iterator<T> orElse(@NonNull Supplier<? extends Iterable<? extends T>> supplier)
      Description copied from interface: Traversable
      Returns this Traversable if it is non-empty; otherwise, returns the result of evaluating the given supplier.
      Specified by:
      orElse in interface Traversable<T>
      Parameters:
      supplier - a supplier of an alternative Traversable if this is empty
      Returns:
      this Traversable if non-empty, otherwise the result of supplier.get()

    • partition

      default Tuple2<Iterator<T>,Iterator<T>> partition(@NonNull Predicate<? super T> predicate)
      Description copied from interface: Traversable
      Splits this Traversable into two partitions according to a predicate.

      The first partition contains all elements that satisfy the predicate, and the second contains all elements that do not. The original iteration order is preserved.

      Specified by:
      partition in interface Traversable<T>
      Parameters:
      predicate - a predicate used to classify elements
      Returns:
      a Tuple2 containing the two resulting Traversable instances

    • peek

      default Iterator<T> peek(@NonNull Consumer<? super T> action)
      Description copied from interface: Value
      Performs the given action on the first element if this is an eager implementation. Performs the given action on all elements (the first immediately, successive deferred), if this is a lazy implementation.
      Specified by:
      peek in interface Traversable<T>
      Specified by:
      peek in interface Value<T>
      Parameters:
      action - The action that will be performed on the element(s).
      Returns:
      this instance

    • reduceLeft

      default T reduceLeft(@NonNull BiFunction<? super T,? super T,? extends T> op)
      Description copied from interface: Traversable
      Reduces the elements of this Traversable from the left using the given binary operation.
      Specified by:
      reduceLeft in interface Foldable<T>
      Specified by:
      reduceLeft in interface Traversable<T>
      Parameters:
      op - A binary operation combining two elements of type T
      Returns:
      the result of the reduction

    • reduceRight

      default T reduceRight(@NonNull BiFunction<? super T,? super T,? extends T> op)
      Description copied from interface: Traversable
      Reduces the elements of this Traversable from the right using the given binary operation.
      Specified by:
      reduceRight in interface Foldable<T>
      Specified by:
      reduceRight in interface Traversable<T>
      Parameters:
      op - A binary operation combining two elements of type T
      Returns:
      the result of the reduction

    • replace

      default Iterator<T> replace(T currentElement, T newElement)
      Description copied from interface: Traversable
      Replaces the first occurrence of currentElement with newElement, if it exists.
      Specified by:
      replace in interface Traversable<T>
      Parameters:
      currentElement - the element to be replaced
      newElement - the replacement element
      Returns:
      a new Traversable with the first occurrence of currentElement replaced by newElement

    • replaceAll

      default Iterator<T> replaceAll(T currentElement, T newElement)
      Description copied from interface: Traversable
      Replaces all occurrences of currentElement with newElement.
      Specified by:
      replaceAll in interface Traversable<T>
      Parameters:
      currentElement - the element to be replaced
      newElement - the replacement element
      Returns:
      a new Traversable with all occurrences of currentElement replaced by newElement

    • retainAll

      default Iterator<T> retainAll(@NonNull Iterable<? extends T> elements)
      Description copied from interface: Traversable
      Retains only the elements from this Traversable that are contained in the given elements.
      Specified by:
      retainAll in interface Traversable<T>
      Parameters:
      elements - the elements to keep
      Returns:
      a new Traversable containing only the elements present in elements, in their original order

    • scan

      default Traversable<T> scan(T zero, @NonNull BiFunction<? super T,? super T,? extends T> operation)
      Description copied from interface: Traversable
      Computes a prefix scan of the elements of this Traversable.

      The neutral element zero may be applied more than once.

      Specified by:
      scan in interface Traversable<T>
      Parameters:
      zero - the neutral element for the operator
      operation - an associative binary operator
      Returns:
      a new Traversable containing the prefix scan of the elements

    • scanLeft

      default <U> Iterator<U> scanLeft(U zero, @NonNull BiFunction<? super U,? super T,? extends U> operation)
      Description copied from interface: Traversable
      Produces a collection containing cumulative results of applying the operator from left to right.

      Will not terminate for infinite collections. The results may vary across runs unless the collection is ordered.

      Specified by:
      scanLeft in interface Traversable<T>
      Type Parameters:
      U - the type of the resulting elements
      Parameters:
      zero - the initial value
      operation - a binary operator applied to the intermediate result and each element
      Returns:
      a new Traversable containing the cumulative results

    • scanRight

      default <U> Iterator<U> scanRight(U zero, @NonNull BiFunction<? super T,? super U,? extends U> operation)
      Description copied from interface: Traversable
      Produces a collection containing cumulative results of applying the operator from right to left.

      The head of the resulting collection is the last cumulative result. Will not terminate for infinite collections. Results may vary across runs unless the collection is ordered.

      Specified by:
      scanRight in interface Traversable<T>
      Type Parameters:
      U - the type of the resulting elements
      Parameters:
      zero - the initial value
      operation - a binary operator applied to each element and the intermediate result
      Returns:
      a new Traversable containing the cumulative results

    • slideBy

      default Iterator<Seq<T>> slideBy(@NonNull Function<? super T,?> classifier)
      Description copied from interface: Traversable
      Partitions this Traversable into consecutive non-overlapping windows according to a classification function.

      Each window contains elements with the same class, as determined by classifier. Two consecutive elements belong to the same window only if classifier returns equal values for both. Otherwise, the current window ends and a new window begins with the next element.

      Examples: 

      
 [].slideBy(Function.identity()) = []
 [1,2,3,4,4,5].slideBy(Function.identity()) = [[1],[2],[3],[4,4],[5]]
 [1,2,3,10,12,5,7,20,29].slideBy(x -> x / 10) = [[1,2,3],[10,12],[5,7],[20,29]]
      Specified by:
      slideBy in interface Traversable<T>
      Parameters:
      classifier - A function classifying elements into groups
      Returns:
      An Iterator of windows (grouped elements)

    • sliding

      default Iterator<Seq<T>> sliding(int size)
      Description copied from interface: Traversable
      Slides a window of a given size over this Traversable with a step size of 1.

      This is equivalent to calling Traversable.sliding(int, int) with a step size of 1.

      Specified by:
      sliding in interface Traversable<T>
      Parameters:
      size - a positive window size
      Returns:
      An Iterator of windows, each containing up to size elements

    • sliding

      default Iterator<Seq<T>> sliding(int size, int step)
      Description copied from interface: Traversable
      Slides a window of a specific size with a given step over this Traversable.

      Examples: 

      
 [].sliding(1, 1) = []
 [1,2,3,4,5].sliding(2, 3) = [[1,2],[4,5]]
 [1,2,3,4,5].sliding(2, 4) = [[1,2],[5]]
 [1,2,3,4,5].sliding(2, 5) = [[1,2]]
 [1,2,3,4].sliding(5, 3) = [[1,2,3,4],[4]]
      Specified by:
      sliding in interface Traversable<T>
      Parameters:
      size - a positive window size
      step - a positive step size
      Returns:
      an Iterator of windows with the given size and step

    • span

      default Tuple2<Iterator<T>,Iterator<T>> span(@NonNull Predicate<? super T> predicate)
      Description copied from interface: Traversable
      Splits this Traversable into a prefix and remainder according to the given predicate.

      The first element of the returned Tuple is the longest prefix of elements satisfying predicate, and the second element is the remaining elements.

      Specified by:
      span in interface Traversable<T>
      Parameters:
      predicate - a predicate used to determine the prefix
      Returns:
      a Tuple containing the prefix and remainder

    • stringPrefix

      default String stringPrefix()
      Description copied from interface: Value
      Returns the name of this Value type, which is used by toString().
      Specified by:
      stringPrefix in interface Value<T>
      Returns:
      This type name.

    • tail

      default Iterator<T> tail()
      Description copied from interface: Traversable
      Returns a new Traversable without its first element.
      Specified by:
      tail in interface Traversable<T>
      Returns:
      a new Traversable containing all elements except the first

    • tailOption

      default Option<Iterator<T>> tailOption()
      Description copied from interface: Traversable
      Returns a new Traversable without its first element as an Option.
      Specified by:
      tailOption in interface Traversable<T>
      Returns:
      Some(traversable) if non-empty, otherwise None

    • take

      default Iterator<T> take(int n)
      Take the first n elements from this iterator.
      Specified by:
      take in interface Traversable<T>
      Parameters:
      n - A number
      Returns:
      The empty iterator, if n <= 0 or this is empty, otherwise a new iterator without the first n elements.

    • takeRight

      default Iterator<T> takeRight(int n)
      Description copied from interface: Traversable
      Returns the last n elements of this Traversable, or all elements if n exceeds the length.

      Equivalent to sublist(max(0, length() - n), length()), but safe for n < 0 or n > length().

      If n < 0, an empty instance is returned. If n > length(), the full instance is returned.

      Specified by:
      takeRight in interface Traversable<T>
      Parameters:
      n - the number of elements to take from the end
      Returns:
      a new Traversable containing the last n elements

    • takeUntil

      default Iterator<T> takeUntil(@NonNull Predicate<? super T> predicate)
      Description copied from interface: Traversable
      Takes elements from this Traversable until the given predicate holds for an element.

      Equivalent to takeWhile(predicate.negate()), but useful when using method references that cannot be negated directly.

      Specified by:
      takeUntil in interface Traversable<T>
      Parameters:
      predicate - a condition tested sequentially on the elements
      Returns:
      a new Traversable containing all elements before the first one that satisfies the predicate

    • takeWhile

      default Iterator<T> takeWhile(@NonNull Predicate<? super T> predicate)
      Description copied from interface: Traversable
      Takes elements from this Traversable while the given predicate holds.
      Specified by:
      takeWhile in interface Traversable<T>
      Parameters:
      predicate - a condition tested sequentially on the elements
      Returns:
      a new Traversable containing all elements up to (but not including) the first one that does not satisfy the predicate