Package io.vavr.collection

Interface Foldable<T>

Type Parameters:
T - the type of elements contained in this foldable structure
All Known Subinterfaces:
BitSet<T>, IndexedSeq<T>, Iterator<T>, LinearSeq<T>, List<T>, Map<K,V>, Multimap<K,V>, Seq<T>, Set<T>, SortedMap<K,V>, SortedMultimap<K,V>, SortedSet<T>, Stream<T>, Traversable<T>, Tree<T>
All Known Implementing Classes:
Array, CharSeq, HashMap, HashMultimap, HashSet, LinkedHashMap, LinkedHashMultimap, LinkedHashSet, List.Cons, List.Nil, PriorityQueue, Queue, Stream.Cons, Stream.Empty, Tree.Empty, Tree.Node, TreeMap, TreeMultimap, TreeSet, Vector
public interface Foldable<T>
Represents a data structure that can be folded (reduced) into a single value.

Folding is the process of combining the elements of a structure using a provided function, typically accumulating a result.

Example: 


 // Concatenates all elements into a single String: "123"
 Stream.of("1", "2", "3")
       .fold("", (acc, element) -> acc + element);
Author:
Daniel Dietrich

  • Method Summary

    Modifier and Type
    Method
    Description
    default T
    fold(T zero, @NonNull BiFunction<? super T,? super T,? extends T> combine)
    Folds the elements of this structure using the given associative binary operator, starting with the provided zero element and successively applying combine.
    <U> U
    foldLeft(U zero, @NonNull BiFunction<? super U,? super T,? extends U> combine)
    Folds the elements of this structure from the left, starting with the given zero value and successively applying the combine function to each element.
    <U> U
    foldRight(U zero, @NonNull BiFunction<? super T,? super U,? extends U> combine)
    Folds the elements of this structure from the right, starting with the given zero value and successively applying the combine function to each element.
    default T
    reduce(@NonNull BiFunction<? super T,? super T,? extends T> op)
    Reduces the elements of this Foldable by repeatedly applying the given binary operation op.
    T
    reduceLeft(@NonNull BiFunction<? super T,? super T,? extends T> op)
    Reduces the elements of this Foldable from the left by successively applying the given operation op.
    Option<T>
    reduceLeftOption(@NonNull BiFunction<? super T,? super T,? extends T> op)
    Reduces the elements of this Foldable from the left by successively applying the given operation op.
    default Option<T>
    reduceOption(@NonNull BiFunction<? super T,? super T,? extends T> op)
    Reduces the elements of this Foldable by repeatedly applying the given binary operation op.
    T
    reduceRight(@NonNull BiFunction<? super T,? super T,? extends T> op)
    Reduces the elements of this Foldable from the right by successively applying the given operation op.
    Option<T>
    reduceRightOption(@NonNull BiFunction<? super T,? super T,? extends T> op)
    Reduces the elements of this Foldable from the right by successively applying the given operation op.

  • Method Details

    • fold

      default T fold(T zero, @NonNull BiFunction<? super T,? super T,? extends T> combine)
      Folds the elements of this structure using the given associative binary operator, starting with the provided zero element and successively applying combine.

      The order in which elements are combined is non-deterministic. Therefore, combine must be associative to guarantee a consistent result regardless of traversal order.

      The fold operations differ in how elements are combined:

      • foldLeft(Object, BiFunction): combines elements from left to right.
      • foldRight(Object, BiFunction): combines elements from right to left.
      • fold: requires an associative combine operation, as the element traversal is unordered. Associativity ensures the result is the same regardless of combination order. Note that most binary operators are not associative, so the result may vary if elements are combined in a different order.

        Together, this Foldable and the associative combine operation form a Monoid.

      Example: 
      
 // Result: 6
 Set.of(1, 2, 3).fold(0, (a, b) -> a + b);
      Parameters:
      zero - the initial value to start folding with
      combine - the function to combine two elements
      Returns:
      the folded result
      Throws:
      NullPointerException - if combine is null

    • foldLeft

      <U> U foldLeft(U zero, @NonNull BiFunction<? super U,? super T,? extends U> combine)
      Folds the elements of this structure from the left, starting with the given zero value and successively applying the combine function to each element.

      Folding from the left means that elements are combined in the order they are encountered, associating each step with the accumulated result so far.

      Example: 

      
 // Result: "cba!"
 List.of("a", "b", "c").foldLeft("!", (acc, x) -> x + acc);
      Type Parameters:
      U - the type of the accumulated result
      Parameters:
      zero - the initial value to start folding with
      combine - a function that combines the accumulated value and the next element
      Returns:
      the folded result
      Throws:
      NullPointerException - if combine is null

    • foldRight

      <U> U foldRight(U zero, @NonNull BiFunction<? super T,? super U,? extends U> combine)
      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);
      Type Parameters:
      U - the type of the accumulated result
      Parameters:
      zero - the initial value to start folding with
      combine - a function that combines the next element and the accumulated value
      Returns:
      the folded result
      Throws:
      NullPointerException - if combine is null

    • reduce

      default T reduce(@NonNull BiFunction<? super T,? super T,? extends T> op)
      Reduces the elements of this Foldable by repeatedly applying the given binary operation op.

      The order in which elements are combined is non-deterministic, so op should be associative to guarantee a consistent result.

      This method throws NoSuchElementException if the Foldable is empty.

      Parameters:
      op - a binary function to combine two elements
      Returns:
      the reduced result
      Throws:
      NoSuchElementException - if this Foldable is empty
      NullPointerException - if op is null

    • reduceOption

      default Option<T> reduceOption(@NonNull BiFunction<? super T,? super T,? extends T> op)
      Reduces the elements of this Foldable by repeatedly applying the given binary operation op.

      The order of element combination is non-deterministic, so op should be associative to guarantee a consistent result.

      Parameters:
      op - a binary function to combine two elements
      Returns:
      an Option containing the reduced result, or Option.none() if this Foldable is empty
      Throws:
      NullPointerException - if op is null

    • reduceLeft

      T reduceLeft(@NonNull BiFunction<? super T,? super T,? extends T> op)
      Reduces the elements of this Foldable from the left by successively applying the given operation op.

      Elements are combined in encounter order, starting from the left.

      Parameters:
      op - a binary function to combine two elements
      Returns:
      the reduced result
      Throws:
      NoSuchElementException - if this Foldable is empty
      NullPointerException - if op is null

    • reduceLeftOption

      Option<T> reduceLeftOption(@NonNull BiFunction<? super T,? super T,? extends T> op)
      Reduces the elements of this Foldable from the left by successively applying the given operation op.

      Returns an Option instead of throwing an exception if the Foldable is empty.

      Parameters:
      op - a binary function to combine two elements
      Returns:
      an Option containing the reduced result, or Option.none() if empty
      Throws:
      NullPointerException - if op is null

    • reduceRight

      T reduceRight(@NonNull BiFunction<? super T,? super T,? extends T> op)
      Reduces the elements of this Foldable from the right by successively applying the given operation op.

      Elements are combined starting from the rightmost element.

      Parameters:
      op - a binary function to combine two elements
      Returns:
      the reduced result
      Throws:
      NoSuchElementException - if this Foldable is empty
      NullPointerException - if op is null

    • reduceRightOption

      Option<T> reduceRightOption(@NonNull BiFunction<? super T,? super T,? extends T> op)
      Reduces the elements of this Foldable from the right by successively applying the given operation op.

      Returns an Option instead of throwing an exception if the Foldable is empty.

      Parameters:
      op - a binary function to combine two elements
      Returns:
      an Option containing the reduced result, or Option.none() if empty
      Throws:
      NullPointerException - if op is null