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:

AbstractIterator, AbstractMultimap, AbstractQueue, Array, BitSetModule.AbstractBitSet, BitSetModule.BitSet1, BitSetModule.BitSet2, BitSetModule.BitSetIterator, BitSetModule.BitSetN, CharSeq, HashArrayMappedTrieModule.LeafNodeIterator, HashMap, HashMultimap, HashSet, IteratorModule.CachedIterator, IteratorModule.ConcatIterator, IteratorModule.DistinctIterator, IteratorModule.EmptyIterator, IteratorModule.GroupedIterator, LinkedHashMap, LinkedHashMultimap, LinkedHashSet, List.Cons, List.Nil, PriorityQueue, Queue, Stream.Cons, Stream.Empty, StreamModule.AppendElements, StreamModule.ConsImpl, StreamModule.FlatMapIterator, StreamModule.StreamIterator, 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);
 

Method Summary

Modifier and Type	Method	Description
default T	fold(T zero, @NonNull java.util.function.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 java.util.function.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 java.util.function.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 java.util.function.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 java.util.function.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 java.util.function.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 java.util.function.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 java.util.function.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 java.util.function.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 Detail

fold

default T fold(T zero,
               @NonNull java.util.function.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:

java.lang.NullPointerException - if combine is null

foldLeft

<U> U foldLeft(U zero,
               @NonNull java.util.function.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:

java.lang.NullPointerException - if combine is null

foldRight

<U> U foldRight(U zero,
                @NonNull java.util.function.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:

java.lang.NullPointerException - if combine is null

reduce

default T reduce(@NonNull java.util.function.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:

java.util.NoSuchElementException - if this Foldable is empty

java.lang.NullPointerException - if op is null

reduceOption

default Option<T> reduceOption(@NonNull java.util.function.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:

java.lang.NullPointerException - if op is null

reduceLeft

T reduceLeft(@NonNull java.util.function.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:

java.util.NoSuchElementException - if this Foldable is empty

java.lang.NullPointerException - if op is null

reduceLeftOption

Option<T> reduceLeftOption(@NonNull java.util.function.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:

java.lang.NullPointerException - if op is null

reduceRight

T reduceRight(@NonNull java.util.function.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:

java.util.NoSuchElementException - if this Foldable is empty

java.lang.NullPointerException - if op is null

reduceRightOption

Option<T> reduceRightOption(@NonNull java.util.function.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:

java.lang.NullPointerException - if op is null