io.vavr.collection

Interface Foldable<T>

Type Parameters:

T - Component type of this foldable

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>

Interface of foldable data structures.

Example:

 // = "123"
 Stream.of("1", "2", "3").fold("", (a1, a2) -> a1 + a2);
 

Author:

Daniel Dietrich

Method Summary

Modifier and Type	Method and Description
default T	fold(T zero, BiFunction<? super T,? super T,? extends T> combine) Folds this elements using the given associative binary operator, starting with zero and successively calling combine.
<U> U	foldLeft(U zero, BiFunction<? super U,? super T,? extends U> combine) Folds this elements from the left, starting with zero and successively calling combine.
<U> U	foldRight(U zero, BiFunction<? super T,? super U,? extends U> combine) Folds this elements from the right, starting with zero and successively calling combine.
default T	reduce(BiFunction<? super T,? super T,? extends T> op) Accumulates the elements of this Foldable by successively calling the given operation op.
T	reduceLeft(BiFunction<? super T,? super T,? extends T> op) Accumulates the elements of this Foldable by successively calling the given operation op from the left.
Option<T>	reduceLeftOption(BiFunction<? super T,? super T,? extends T> op) Accumulates the elements of this Foldable by successively calling the given operation op from the left.
default Option<T>	reduceOption(BiFunction<? super T,? super T,? extends T> op) Accumulates the elements of this Foldable by successively calling the given operation op.
T	reduceRight(BiFunction<? super T,? super T,? extends T> op) Accumulates the elements of this Foldable by successively calling the given operation op from the right.
Option<T>	reduceRightOption(BiFunction<? super T,? super T,? extends T> op) Accumulates the elements of this Foldable by successively calling the given operation op from the right.

Method Detail

fold

default T fold(T zero,
               BiFunction<? super T,? super T,? extends T> combine)

Folds this elements using the given associative binary operator, starting with zero and successively calling combine. The order in which the elements are combined is non-deterministic.

The methods fold, foldLeft and foldRight differ in how the elements are combined:

• foldLeft(Object, BiFunction) associates to the left
• foldRight(Object, BiFunction) associates to the right
• fold takes an associative combine operation because the traversal of elements is unordered/non-deterministic. The associativity guarantees that in each case the result will be the same, it does not matter in which order the elements are combined. Generally binary operators aren't associative, i.e. the result may differ if elements are combined in a different order.

  We say that this Foldable and the associative combine operation form a Monoid.

Example:

 
 // = 6
 Set(1, 2, 3).fold(0, (a, b) -> a + b);
  

Parameters:

zero - A zero element to start with.

combine - A function which combines elements.

Returns:

a folded value

Throws:

NullPointerException - if combine is null

foldLeft

<U> U foldLeft(U zero,
               BiFunction<? super U,? super T,? extends U> combine)

Folds this elements from the left, starting with zero and successively calling combine.

Example:

 
 // = "cba!"
 List("a", "b", "c").foldLeft("!", (xs, x) -> x + xs)
  

Type Parameters:

U - the type to fold over

Parameters:

zero - A zero element to start with.

combine - A function which combines elements.

Returns:

a folded value

Throws:

NullPointerException - if combine is null

foldRight

<U> U foldRight(U zero,
                BiFunction<? super T,? super U,? extends U> combine)

Folds this elements from the right, starting with zero and successively calling combine.

Example:

 
 // = "!cba"
 List("a", "b", "c").foldRight("!", (x, xs) -> xs + x)
  

Type Parameters:

U - the type of the folded value

Parameters:

zero - A zero element to start with.

combine - A function which combines elements.

Returns:

a folded value

Throws:

NullPointerException - if combine is null

reduce

default T reduce(BiFunction<? super T,? super T,? extends T> op)

Accumulates the elements of this Foldable by successively calling the given operation op. The order of element iteration is undetermined.

Parameters:

op - A BiFunction of type T

Returns:

the reduced value.

Throws:

NoSuchElementException - if this is empty

NullPointerException - if op is null

reduceOption

default Option<T> reduceOption(BiFunction<? super T,? super T,? extends T> op)

Accumulates the elements of this Foldable by successively calling the given operation op. The order of element iteration is undetermined.

Parameters:

op - A BiFunction of type T

Returns:

Some of reduced value or None if the Foldable is empty.

Throws:

NullPointerException - if op is null

reduceLeft

T reduceLeft(BiFunction<? super T,? super T,? extends T> op)

Accumulates the elements of this Foldable by successively calling the given operation op from the left.

Parameters:

op - A BiFunction of type T

Returns:

the reduced value.

Throws:

NoSuchElementException - if this is empty

NullPointerException - if op is null

reduceLeftOption

Option<T> reduceLeftOption(BiFunction<? super T,? super T,? extends T> op)

Accumulates the elements of this Foldable by successively calling the given operation op from the left.

Parameters:

op - A BiFunction of type T

Returns:

Some of reduced value or None if the Foldable is empty.

Throws:

NullPointerException - if op is null

reduceRight

T reduceRight(BiFunction<? super T,? super T,? extends T> op)

Accumulates the elements of this Foldable by successively calling the given operation op from the right.

Parameters:

op - An operation of type T

Returns:

the reduced value.

Throws:

NoSuchElementException - if this is empty

NullPointerException - if op is null

reduceRightOption

Option<T> reduceRightOption(BiFunction<? super T,? super T,? extends T> op)

Accumulates the elements of this Foldable by successively calling the given operation op from the right.

Parameters:

op - An operation of type T

Returns:

Some of reduced value or None.

Throws:

NullPointerException - if op is null