Package io.vavr

Interface Value<T>

Type Parameters:

T - the type of the wrapped value

All Superinterfaces:

java.lang.Iterable<T>

All Known Subinterfaces:

BitSet<T>, Either<L,R>, Future<T>, IndexedSeq<T>, Iterator<T>, LinearSeq<T>, List<T>, Map<K,V>, Multimap<K,V>, Option<T>, Seq<T>, Set<T>, SortedMap<K,V>, SortedMultimap<K,V>, SortedSet<T>, Stream<T>, Traversable<T>, Tree<T>, Try<T>, Validation<E,T>

All Known Implementing Classes:

AbstractIterator, AbstractMultimap, AbstractQueue, Array, BitSetModule.AbstractBitSet, BitSetModule.BitSet1, BitSetModule.BitSet2, BitSetModule.BitSetIterator, BitSetModule.BitSetN, CharSeq, Either.Left, Either.LeftProjection, Either.Right, Either.RightProjection, FutureImpl, HashArrayMappedTrieModule.LeafNodeIterator, HashMap, HashMultimap, HashSet, IteratorModule.CachedIterator, IteratorModule.ConcatIterator, IteratorModule.DistinctIterator, IteratorModule.EmptyIterator, IteratorModule.GroupedIterator, Lazy, LinkedHashMap, LinkedHashMultimap, LinkedHashSet, List.Cons, List.Nil, Option.None, Option.Some, PriorityQueue, Queue, Stream.Cons, Stream.Empty, StreamModule.AppendElements, StreamModule.ConsImpl, StreamModule.FlatMapIterator, StreamModule.StreamIterator, Tree.Empty, Tree.Node, TreeMap, TreeMultimap, TreeSet, Try.Failure, Try.Success, Validation.Invalid, Validation.Valid, Vector

public interface Value<T>
extends java.lang.Iterable<T>

Represents a value in a functional programming context.

A Value models the outcome of a computation that may or may not produce a result. It can be present or absent (empty), where the meaning of "empty" depends on the concrete implementation - it may represent an undefined value, a failed computation, or absence of elements.

This interface provides methods for:

• Accessing and retrieving the wrapped value safely, with defaults or exceptions.
• Transforming the value with functional operations such as map and flatMap.
• Checking equality and correspondence with other values or collections.
• Iterating over the value or performing side-effects.
• Testing characteristics like emptiness, laziness, or single-valuedness.
• Converting to other types, including Java collections, streams, Option, Try, Either, and validation types.

Note: Subclasses must define appropriate flatMap signatures.

Method Summary

Modifier and Type	Method	Description
default <R> R	collect(@NonNull java.util.function.Supplier<R> supplier, @NonNull java.util.function.BiConsumer<R,? super T> accumulator, @NonNull java.util.function.BiConsumer<R,R> combiner)	Collects the underlying value(s) (if present) using the given supplier, accumulator and combiner.
default <R,A> R	collect(@NonNull java.util.stream.Collector<? super T,A,R> collector)	Collects the underlying value(s) (if present) using the provided collector.
default boolean	contains(T element)	Shortcut for exists(e -> Objects.equals(e, element)), tests if the given element is contained.
default <U> boolean	corresponds(@NonNull java.lang.Iterable<U> that, @NonNull java.util.function.BiPredicate<? super T,? super U> predicate)	Tests whether every element of this iterable relates to the corresponding element of another iterable by satisfying a test predicate.
default boolean	eq(java.lang.Object o)	A smoothing replacement for equals.
boolean	equals(java.lang.Object o)	Clarifies that values have a proper equals() method implemented.
default boolean	exists(@NonNull java.util.function.Predicate<? super T> predicate)	Checks, if an element exists such that the predicate holds.
default boolean	forAll(@NonNull java.util.function.Predicate<? super T> predicate)	Checks, if the given predicate holds for all elements.
default void	forEach(@NonNull java.util.function.Consumer<? super T> action)	Performs an action on each element.
T	get()	Gets the underlying value or throws if no value is present.
default T	getOrElse(@NonNull java.util.function.Supplier<? extends T> supplier)	Returns the underlying value if present, otherwise other.
default T	getOrElse(T other)	Returns the underlying value if present, otherwise other.
default <X extends java.lang.Throwable> T	getOrElseThrow(@NonNull java.util.function.Supplier<X> supplier)	Returns the underlying value if present, otherwise throws supplier.get().
default T	getOrElseTry(@NonNull CheckedFunction0<? extends T> supplier)	Returns the underlying value if present, otherwise returns the result of Try.of(supplier).get().
default T	getOrNull()	Returns the underlying value if present, otherwise null.
int	hashCode()	Clarifies that values have a proper hashCode() method implemented.
boolean	isAsync()	Checks if this Value is asynchronously (short: async) computed.
boolean	isEmpty()	Checks, this Value is empty, i.e.
boolean	isLazy()	Checks if this Value is lazily evaluated.
boolean	isSingleValued()	States whether this is a single-valued type.
@NonNull Iterator<T>	iterator()	Returns a rich io.vavr.collection.Iterator.
<U> Value<U>	map(@NonNull java.util.function.Function<? super T,? extends U> mapper)	Maps the underlying value to a different component type.
default <U> Value<U>	mapTo(U value)	Maps the underlying value to another fixed value.
default Value<java.lang.Void>	mapToVoid()	Maps the underlying value to Void
static <T> Value<T>	narrow(Value<? extends T> value)	Narrows a widened Value<? extends T> to Value<T> by performing a type-safe cast.
default void	out(java.io.PrintStream out)	Sends the string representations of this to the PrintStream.
default void	out(java.io.PrintWriter writer)	Sends the string representations of this to the PrintWriter.
Value<T>	peek(@NonNull java.util.function.Consumer<? super T> action)	Performs the given action on the first element if this is an eager implementation.
default java.util.Spliterator<T>	spliterator()
default void	stderr()	Sends the string representations of this to the standard error stream System.err.
default void	stdout()	Sends the string representations of this to the standard output stream System.out.
java.lang.String	stringPrefix()	Returns the name of this Value type, which is used by toString().
default Array<T>	toArray()	Converts this to a Array.
default CharSeq	toCharSeq()	Converts this to a CharSeq.
default java.util.concurrent.CompletableFuture<T>	toCompletableFuture()	Converts this to a CompletableFuture
default <L> Either<L,T>	toEither(@NonNull java.util.function.Supplier<? extends L> leftSupplier)	Converts this to an Either.
default <L> Either<L,T>	toEither(L left)	Converts this to an Either.
default <U> Validation<T,U>	toInvalid(java.util.function.Supplier<? extends U> valueSupplier)	Deprecated. Use toValidation(Supplier) instead.
default <U> Validation<T,U>	toInvalid(U value)	Deprecated. Use toValidation(Object) instead.
default java.lang.Object[]	toJavaArray()	Converts this to a Java array with component type Object
default T[]	toJavaArray(@NonNull java.util.function.IntFunction<T[]> arrayFactory)	Converts this to a Java array having an accurate component type.
default T[]	toJavaArray(java.lang.Class<T> componentType)	Deprecated. Use toJavaArray(IntFunction) instead
default <C extends java.util.Collection<T>> C	toJavaCollection(@NonNull java.util.function.Function<java.lang.Integer,C> factory)	Converts this to a specific mutable Collection of type C.
default java.util.List<T>	toJavaList()	Converts this to a mutable List.
default <LIST extends java.util.List<T>> LIST	toJavaList(@NonNull java.util.function.Function<java.lang.Integer,LIST> factory)	Converts this to a specific mutable List.
default <K,V> java.util.Map<K,V>	toJavaMap(@NonNull java.util.function.Function<? super T,? extends Tuple2<? extends K,? extends V>> f)	Converts this to a mutable Map.
default <K,V,MAP extends java.util.Map<K,V>> MAP	toJavaMap(@NonNull java.util.function.Supplier<MAP> factory, @NonNull java.util.function.Function<? super T,? extends Tuple2<? extends K,? extends V>> f)	Converts this to a specific mutable Map.
default <K,V,MAP extends java.util.Map<K,V>> MAP	toJavaMap(@NonNull java.util.function.Supplier<MAP> factory, @NonNull java.util.function.Function<? super T,? extends K> keyMapper, @NonNull java.util.function.Function<? super T,? extends V> valueMapper)	Converts this to a specific mutable Map.
default java.util.Optional<T>	toJavaOptional()	Converts this to an Optional.
default java.util.stream.Stream<T>	toJavaParallelStream()	Converts this to a parallel Stream by calling StreamSupport.stream(this.spliterator(), true).
default java.util.Set<T>	toJavaSet()	Converts this to a mutable Set.
default <SET extends java.util.Set<T>> SET	toJavaSet(@NonNull java.util.function.Function<java.lang.Integer,SET> factory)	Converts this to a specific Set.
default java.util.stream.Stream<T>	toJavaStream()	Converts this to a sequential Stream by calling StreamSupport.stream(this.spliterator(), false).
default <R> Either<T,R>	toLeft(java.util.function.Supplier<? extends R> right)	Deprecated. Use toEither(Supplier) instead.
default <R> Either<T,R>	toLeft(R right)	Deprecated. Use toEither(Object) instead.
default <K,V> Map<K,V>	toLinkedMap(@NonNull java.util.function.Function<? super T,? extends Tuple2<? extends K,? extends V>> f)	Converts this to a Map.
default <K,V> Map<K,V>	toLinkedMap(@NonNull java.util.function.Function<? super T,? extends K> keyMapper, @NonNull java.util.function.Function<? super T,? extends V> valueMapper)	Converts this to a Map.
default Set<T>	toLinkedSet()	Converts this to a Set.
default List<T>	toList()	Converts this to a List.
default <K,V> Map<K,V>	toMap(@NonNull java.util.function.Function<? super T,? extends Tuple2<? extends K,? extends V>> f)	Converts this to a Map.
default <K,V> Map<K,V>	toMap(@NonNull java.util.function.Function<? super T,? extends K> keyMapper, @NonNull java.util.function.Function<? super T,? extends V> valueMapper)	Converts this to a Map.
default Option<T>	toOption()	Converts this to an Option.
default PriorityQueue<T>	toPriorityQueue()	Converts this to a PriorityQueue.
default PriorityQueue<T>	toPriorityQueue(@NonNull java.util.Comparator<? super T> comparator)	Converts this to a PriorityQueue.
default Queue<T>	toQueue()	Converts this to a Queue.
default <L> Either<L,T>	toRight(java.util.function.Supplier<? extends L> left)	Deprecated. Use toEither(Supplier) instead.
default <L> Either<L,T>	toRight(L left)	Deprecated. Use toEither(Object) instead.
default Set<T>	toSet()	Converts this to a Set.
default <K,V> SortedMap<K,V>	toSortedMap(@NonNull java.util.Comparator<? super K> comparator, @NonNull java.util.function.Function<? super T,? extends Tuple2<? extends K,? extends V>> f)	Converts this to a Map.
default <K,V> SortedMap<K,V>	toSortedMap(@NonNull java.util.Comparator<? super K> comparator, @NonNull java.util.function.Function<? super T,? extends K> keyMapper, @NonNull java.util.function.Function<? super T,? extends V> valueMapper)	Converts this to a Map.
default <K extends java.lang.Comparable<? super K>,V> SortedMap<K,V>	toSortedMap(@NonNull java.util.function.Function<? super T,? extends Tuple2<? extends K,? extends V>> f)	Converts this to a Map.
default <K extends java.lang.Comparable<? super K>,V> SortedMap<K,V>	toSortedMap(@NonNull java.util.function.Function<? super T,? extends K> keyMapper, @NonNull java.util.function.Function<? super T,? extends V> valueMapper)	Converts this to a Map.
default SortedSet<T>	toSortedSet()	Converts this to a SortedSet.
default SortedSet<T>	toSortedSet(@NonNull java.util.Comparator<? super T> comparator)	Converts this to a SortedSet.
default Stream<T>	toStream()	Converts this to a Stream.
java.lang.String	toString()	Clarifies that values have a proper toString() method implemented.
default Tree<T>	toTree()	Converts this to a Tree.
default <ID> List<Tree.Node<T>>	toTree(@NonNull java.util.function.Function<? super T,? extends ID> idMapper, @NonNull java.util.function.Function<? super T,? extends ID> parentMapper)	Converts this to a Tree using a idMapper and parentMapper.
default Try<T>	toTry()	Converts this to a Try.
default Try<T>	toTry(@NonNull java.util.function.Supplier<? extends java.lang.Throwable> ifEmpty)	Converts this to a Try.
default <E> Validation<E,T>	toValid(@NonNull java.util.function.Supplier<? extends E> errorSupplier)	Deprecated. Use toValidation(Supplier) instead.
default <E> Validation<E,T>	toValid(E error)	Deprecated. Use toValidation(Object) instead.
default <E> Validation<E,T>	toValidation(@NonNull java.util.function.Supplier<? extends E> invalidSupplier)	Converts this to an Validation.
default <E> Validation<E,T>	toValidation(E invalid)	Converts this to an Validation.
default Vector<T>	toVector()	Converts this to a Vector.

Method Detail

narrow

static <T> Value<T> narrow(Value<? extends T> value)

Narrows a widened Value<? extends T> to Value<T> by performing a type-safe cast. This is eligible because immutable/read-only collections are covariant.

Type Parameters:

T - Component type of the Value.

Parameters:

value - A Value.

Returns:

the given value instance as narrowed type Value<T>.

collect

default <R,A> R collect(@NonNull java.util.stream.Collector<? super T,A,R> collector)

Collects the underlying value(s) (if present) using the provided collector.

Type Parameters:

A - the mutable accumulation type of the reduction operation

R - the result type of the reduction operation

Parameters:

collector - Collector performing reduction

Returns:

R reduction result

collect

default <R> R collect(@NonNull java.util.function.Supplier<R> supplier,
                      @NonNull java.util.function.BiConsumer<R,? super T> accumulator,
                      @NonNull java.util.function.BiConsumer<R,R> combiner)

Collects the underlying value(s) (if present) using the given supplier, accumulator and combiner.

Type Parameters:

R - type of the result

Parameters:

supplier - provide unit value for reduction

accumulator - perform reduction with unit value

combiner - function for combining two values, which must be compatible with the accumulator.

Returns:

R reduction result

contains

default boolean contains(T element)

Shortcut for exists(e -> Objects.equals(e, element)), tests if the given element is contained.

Parameters:

element - An Object of type A, may be null.

Returns:

true, if element is contained, false otherwise.

corresponds

default <U> boolean corresponds(@NonNull java.lang.Iterable<U> that,
                                @NonNull java.util.function.BiPredicate<? super T,? super U> predicate)

Tests whether every element of this iterable relates to the corresponding element of another iterable by satisfying a test predicate.

Type Parameters:

U - Component type of that iterable

Parameters:

that - the other iterable

predicate - the test predicate, which relates elements from both iterables

Returns:

true if both iterables have the same length and predicate(x, y) is true for all corresponding elements x of this iterable and y of that, otherwise false.

eq

default boolean eq(java.lang.Object o)

A smoothing replacement for equals. It is similar to Scala's == but better in the way that it is not limited to collection types, e.g. Some(1) eq List(1), None eq Failure(x) etc.

In a nutshell: eq checks congruence of structures and equality of contained values.

Example:

 // ((1, 2), ((3))) => structure: (()(())) values: 1, 2, 3
 final Value<?> i1 = List.of(List.of(1, 2), Arrays.asList(List.of(3)));
 final Value<?> i2 = Queue.of(Stream.of(1, 2), List.of(Lazy.of(() -> 3)));
 assertThat(i1.eq(i2)).isTrue();
 

Semantics:

 o == this             : true
 o instanceof Value    : iterable elements are eq, non-iterable elements equals, for all (o1, o2) in (this, o)
 o instanceof Iterable : this eq Iterator.of((Iterable<?>) o);
 otherwise             : false
 

Parameters:

o - An object

Returns:

true, if this equals o according to the rules defined above, otherwise false.

exists

default boolean exists(@NonNull java.util.function.Predicate<? super T> predicate)

Checks, if an element exists such that the predicate holds.

Parameters:

predicate - A Predicate

Returns:

true, if predicate holds for one or more elements, false otherwise

Throws:

java.lang.NullPointerException - if predicate is null

forAll

default boolean forAll(@NonNull java.util.function.Predicate<? super T> predicate)

Checks, if the given predicate holds for all elements.

Parameters:

predicate - A Predicate

Returns:

true, if the predicate holds for all elements, false otherwise

Throws:

java.lang.NullPointerException - if predicate is null

forEach

default void forEach(@NonNull java.util.function.Consumer<? super T> action)

Performs an action on each element.

Specified by:

forEach in interface java.lang.Iterable<T>

Parameters:

action - A Consumer

Throws:

java.lang.NullPointerException - if action is null

get

T get()

Gets the underlying value or throws if no value is present.

IMPORTANT! This method will throw an undeclared Throwable if isEmpty() == true is true.

Because the 'empty' state indicates that there is no value present that can be returned, get() has to throw in such a case. Generally, implementing classes should throw a NoSuchElementException if isEmpty() returns true.

However, there exist use-cases, where implementations may throw other exceptions. See Try.get().

Additional note: Dynamic proxies will wrap an undeclared exception in a UndeclaredThrowableException.

Returns:

the underlying value if this is not empty, otherwise get() throws a Throwable

getOrElse

default T getOrElse(T other)

Returns the underlying value if present, otherwise other.

Parameters:

other - An alternative value.

Returns:

A value of type T

getOrElse

default T getOrElse(@NonNull java.util.function.Supplier<? extends T> supplier)

Returns the underlying value if present, otherwise other.

Parameters:

supplier - An alternative value supplier.

Returns:

A value of type T

Throws:

java.lang.NullPointerException - if supplier is null

getOrElseThrow

default <X extends java.lang.Throwable> T getOrElseThrow(@NonNull java.util.function.Supplier<X> supplier)
                                                  throws X extends java.lang.Throwable

Returns the underlying value if present, otherwise throws supplier.get().

Type Parameters:

X - a Throwable type

Parameters:

supplier - An exception supplier.

Returns:

A value of type T.

Throws:

java.lang.NullPointerException - if supplier is null

X - if no value is present

X extends java.lang.Throwable

getOrElseTry

default T getOrElseTry(@NonNull CheckedFunction0<? extends T> supplier)

Returns the underlying value if present, otherwise returns the result of Try.of(supplier).get().

Parameters:

supplier - An alternative value supplier.

Returns:

A value of type T.

Throws:

java.lang.NullPointerException - if supplier is null

getOrNull

default T getOrNull()

Returns the underlying value if present, otherwise null.

Returns:

A value of type T or null.

mapTo

default <U> Value<U> mapTo(U value)

Maps the underlying value to another fixed value.

Type Parameters:

U - The new component type

Parameters:

value - value to replace the contents with

Returns:

A new value

mapToVoid

default Value<java.lang.Void> mapToVoid()

Maps the underlying value to Void

Returns:

A new value of type Void

isAsync

boolean isAsync()

Checks if this Value is asynchronously (short: async) computed.

Methods of a Value instance that operate on the underlying value may block the current thread until the value is present and the computation can be performed.

Returns:

true if this Value is async (like Future), false otherwise.

isEmpty

boolean isEmpty()

Checks, this Value is empty, i.e. if the underlying value is absent.

Returns:

false, if no underlying value is present, true otherwise.

isLazy

boolean isLazy()

Checks if this Value is lazily evaluated.

Returns:

true if this Value is lazy (like Lazy and Stream), false otherwise.

isSingleValued

boolean isSingleValued()

States whether this is a single-valued type.

Returns:

true if this is single-valued, false otherwise.

map

<U> Value<U> map(@NonNull java.util.function.Function<? super T,? extends U> mapper)

Maps the underlying value to a different component type.

Type Parameters:

U - The new component type

Parameters:

mapper - A mapper

Returns:

A new value

peek

Value<T> peek(@NonNull java.util.function.Consumer<? super T> action)

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.

Parameters:

action - The action that will be performed on the element(s).

Returns:

this instance

stringPrefix

java.lang.String stringPrefix()

Returns the name of this Value type, which is used by toString().

Returns:

This type name.

out

@GwtIncompatible("java.io.PrintStream is not implemented")
default void out(java.io.PrintStream out)

Sends the string representations of this to the PrintStream. If this value consists of multiple elements, each element is displayed in a new line.

Parameters:

out - The PrintStream to write to

Throws:

java.lang.IllegalStateException - if PrintStream.checkError() is true after writing to stream.

out

@GwtIncompatible("java.io.PrintWriter is not implemented")
default void out(java.io.PrintWriter writer)

Sends the string representations of this to the PrintWriter. If this value consists of multiple elements, each element is displayed in a new line.

Parameters:

writer - The PrintWriter to write to

Throws:

java.lang.IllegalStateException - if PrintWriter.checkError() is true after writing to writer.

stderr

@GwtIncompatible("java.io.PrintStream is not implemented")
default void stderr()

Sends the string representations of this to the standard error stream System.err. If this value consists of multiple elements, each element is displayed in a new line.

Throws:

java.lang.IllegalStateException - if PrintStream.checkError() is true after writing to stderr.

stdout

@GwtIncompatible("java.io.PrintStream is not implemented")
default void stdout()

Sends the string representations of this to the standard output stream System.out. If this value consists of multiple elements, each element is displayed in a new line.

Throws:

java.lang.IllegalStateException - if PrintStream.checkError() is true after writing to stdout.

iterator

@NonNull Iterator<T> iterator()

Returns a rich io.vavr.collection.Iterator.

Specified by:

iterator in interface java.lang.Iterable<T>

Returns:

A new Iterator

toArray

default Array<T> toArray()

Converts this to a Array.

Returns:

A new Array.

toCharSeq

default CharSeq toCharSeq()

Converts this to a CharSeq.

Returns:

A new CharSeq.

toCompletableFuture

@GwtIncompatible
default java.util.concurrent.CompletableFuture<T> toCompletableFuture()

Converts this to a CompletableFuture

Returns:

A new CompletableFuture containing the value

toInvalid

@Deprecated
default <U> Validation<T,U> toInvalid(U value)

Deprecated.

Use toValidation(Object) instead.

Converts this to a Validation.

Type Parameters:

U - value type of a Valid

Parameters:

value - An instance of a Valid value

Returns:

A new Validation.Valid containing the given value if this is empty, otherwise a new Validation.Invalid containing this value.

toInvalid

@Deprecated
default <U> Validation<T,U> toInvalid(java.util.function.Supplier<? extends U> valueSupplier)

Deprecated.

Use toValidation(Supplier) instead.

Converts this to a Validation.

Type Parameters:

U - value type of a Valid

Parameters:

valueSupplier - A supplier of a Valid value

Returns:

A new Validation.Valid containing the result of valueSupplier if this is empty, otherwise a new Validation.Invalid containing this value.

Throws:

java.lang.NullPointerException - if valueSupplier is null

toJavaArray

default java.lang.Object[] toJavaArray()

Converts this to a Java array with component type Object

 // = [] of type Object[]
 Future.<String> of(() -> { throw new Error(); })
       .toJavaArray()

 // = [ok] of type Object[]
 Try.of(() -> "ok")
    .toJavaArray()

 // = [1, 2, 3] of type Object[]
 List.of(1, 2, 3)
     .toJavaArray()
 

Returns:

A new Java array.

toJavaArray

@Deprecated
@GwtIncompatible("reflection is not supported")
default T[] toJavaArray(java.lang.Class<T> componentType)

Deprecated.

Use toJavaArray(IntFunction) instead

Converts this to a Java array having an accurate component type.

 // = [] of type String[]
 Future.<String> of(() -> { throw new Error(); })
       .toJavaArray(String.class)

 // = [ok] of type String[]
 Try.of(() -> "ok")
    .toJavaArray(String.class)

 // = [1, 2, 3] of type Integer[]
 List.of(1, 2, 3)
     .toJavaArray(Integer.class)
 

Parameters:

componentType - Component type of the array

Returns:

A new Java array.

Throws:

java.lang.NullPointerException - if componentType is null

toJavaArray

default T[] toJavaArray(@NonNull java.util.function.IntFunction<T[]> arrayFactory)

Converts this to a Java array having an accurate component type.

 // = [] of type String[]
 Future.<String> of(() -> { throw new Error(); })
       .toJavaArray(String[]::new)

 // = [ok] of type String[]
 Try.of(() -> "ok")
    .toJavaArray(String[]::new)

 // = [1, 2, 3] of type Integer[]
 List.of(1, 2, 3)
     .toJavaArray(Integer[]::new)
 

Parameters:

arrayFactory - an int argument function that creates an array of the correct component type with the specified size

Returns:

The array provided by the factory filled with the values from this Value.

Throws:

java.lang.NullPointerException - if componentType is null

toJavaCollection

default <C extends java.util.Collection<T>> C toJavaCollection(@NonNull java.util.function.Function<java.lang.Integer,C> factory)

Converts this to a specific mutable Collection of type C. Elements are added by calling Collection.add(Object).

 // = []
 Future.<String> of(() -> { throw new Error(); })
       .toJavaCollection(java.util.HashSet::new)

 // = [ok]
 Try.of(() -> "ok")
    .toJavaCollection(java.util.HashSet::new)
 
 // = [1, 2, 3]
 List.of(1, 2, 3)
     .toJavaCollection(java.util.LinkedHashSet::new)
 

Type Parameters:

C - a sub-type of java.util.Collection

Parameters:

factory - A factory that returns an empty mutable java.util.Collection with the specified initial capacity

Returns:

a new java.util.Collection of type C

toJavaList

default java.util.List<T> toJavaList()

Converts this to a mutable List. Elements are added by calling List.add(Object).

 // = []
 Future.<String> of(() -> { throw new Error(); })
       .toJavaList()
 
 // = [ok]
 Try.of(() -> "ok")
    .toJavaList()

 // = [1, 2, 3]
 List.of(1, 2, 3)
     .toJavaList()
 

Returns:

A new ArrayList.

toJavaList

default <LIST extends java.util.List<T>> LIST toJavaList(@NonNull java.util.function.Function<java.lang.Integer,LIST> factory)

Converts this to a specific mutable List. Elements are added by calling List.add(Object).

 // = []
 Future.<String> of(() -> { throw new Error(); })
       .toJavaList(java.util.ArrayList::new)
 
 // = [ok]
 Try.of(() -> "ok")
    .toJavaList(java.util.ArrayList::new)

 // = [1, 2, 3]
 List.of(1, 2, 3)
     .toJavaList(java.util.ArrayList::new)

 // = [1, 2, 3]
 List.of(1, 2, 3)
     .toJavaList(capacity -> new java.util.LinkedList<>())
 

Type Parameters:

LIST - A sub-type of java.util.List

Parameters:

factory - A factory that returns an empty mutable java.util.List with the specified initial capacity

Returns:

a new java.util.List of type LIST

toJavaMap

default <K,V> java.util.Map<K,V> toJavaMap(@NonNull java.util.function.Function<? super T,? extends Tuple2<? extends K,? extends V>> f)

Converts this to a mutable Map. Elements are added by calling Map.put(Object, Object).

 // = {}
 Future.<String> of(() -> { throw new Error(); })
       .toJavaMap(s -> Tuple.of(s, s.length()))
 
 // = {ok=2}
 Try.of(() -> "ok")
    .toJavaMap(s -> Tuple.of(s, s.length()))

 // = {1=A, 2=B, 3=C}
 List.of(1, 2, 3)
     .toJavaMap(i -> Tuple.of(i, (char) (i + 64)))
 

Type Parameters:

K - The key type

V - The value type

Parameters:

f - A function that maps an element to a key/value pair represented by Tuple2

Returns:

A new HashMap.

toJavaMap

default <K,V,MAP extends java.util.Map<K,V>> MAP toJavaMap(@NonNull java.util.function.Supplier<MAP> factory,
                                                                             @NonNull java.util.function.Function<? super T,? extends K> keyMapper,
                                                                             @NonNull java.util.function.Function<? super T,? extends V> valueMapper)

Converts this to a specific mutable Map. Elements are added by calling Map.put(Object, Object).

 // = {}
 Future.<String> of(() -> { throw new Error(); })
       .toJavaMap(java.util.HashMap::new, s -> s, String::length)
 
 // = {ok=2}
 Try.of(() -> "ok")
    .toJavaMap(java.util.TreeMap::new, s -> s, String::length)

 // = {1=A, 2=B, 3=C}
 List.of(1, 2, 3)
     .toJavaMap(java.util.TreeMap::new, i -> i, i -> (char) (i + 64))
 

Type Parameters:

K - The key type

V - The value type

MAP - a sub-type of java.util.Map

Parameters:

factory - A factory that creates an empty mutable java.util.Map

keyMapper - A function that maps an element to a key

valueMapper - A function that maps an element to a value

Returns:

a new java.util.Map of type MAP

toJavaMap

default <K,V,MAP extends java.util.Map<K,V>> MAP toJavaMap(@NonNull java.util.function.Supplier<MAP> factory,
                                                                             @NonNull java.util.function.Function<? super T,? extends Tuple2<? extends K,? extends V>> f)

Converts this to a specific mutable Map. Elements are added by calling Map.put(Object, Object).

 // = {}
 Future.<String> of(() -> { throw new Error(); })
       .toJavaMap(java.util.HashMap::new, s -> Tuple.of(s, s.length()))
 
 // = {ok=2}
 Try.of(() -> "ok")
     .toJavaMap(java.util.TreeMap::new, s -> Tuple.of(s, s.length()))
 
 // = {1=A, 2=B, 3=C}
 List.of(1, 2, 3)
     .toJavaMap(java.util.TreeMap::new, i -> Tuple.of(i, (char) (i + 64)))
 

Type Parameters:

K - The key type

V - The value type

MAP - a sub-type of java.util.Map

Parameters:

factory - A factory that creates an empty mutable java.util.Map

f - A function that maps an element to a key/value pair represented by Tuple2

Returns:

a new java.util.Map of type MAP

toJavaOptional

default java.util.Optional<T> toJavaOptional()

Converts this to an Optional.

 // = Optional.empty
 Future.of(() -> { throw new Error(); })
       .toJavaOptional()

 // = Optional[ok]
 Try.of(() -> "ok")
     .toJavaOptional()

 // = Optional[1]
 List.of(1, 2, 3)
     .toJavaOptional()
 

Returns:

A new Optional.

toJavaSet

default java.util.Set<T> toJavaSet()

Converts this to a mutable Set. Elements are added by calling Set.add(Object).

 // = []
 Future.of(() -> { throw new Error(); })
       .toJavaSet()
 
 // = [ok]
 Try.of(() -> "ok")
     .toJavaSet()

 // = [1, 2, 3]
 List.of(1, 2, 3)
     .toJavaSet()
 

Returns:

A new HashSet.

toJavaSet

default <SET extends java.util.Set<T>> SET toJavaSet(@NonNull java.util.function.Function<java.lang.Integer,SET> factory)

Converts this to a specific Set. Elements are added by calling Set.add(Object).

 // = []
 Future.of(() -> { throw new Error(); })
       .toJavaSet(java.util.HashSet::new)
 
 // = [ok]
 Try.of(() -> "ok")
     .toJavaSet(java.util.HashSet::new)

 // = [3, 2, 1]
 List.of(1, 2, 3)
     .toJavaSet(capacity -> new java.util.TreeSet<>(Comparator.reverseOrder()))
 

Type Parameters:

SET - a sub-type of java.util.Set

Parameters:

factory - A factory that returns an empty mutable java.util.Set with the specified initial capacity

Returns:

a new java.util.Set of type SET

toJavaStream

default java.util.stream.Stream<T> toJavaStream()

Converts this to a sequential Stream by calling StreamSupport.stream(this.spliterator(), false).

 // empty Stream
 Future.of(() -> { throw new Error(); })
       .toJavaStream()

 // Stream containing "ok"
 Try.of(() -> "ok")
    .toJavaStream()

 // Stream containing 1, 2, 3
 List.of(1, 2, 3)
     .toJavaStream()
 

Returns:

A new sequential Stream.

See Also:

spliterator()

toJavaParallelStream

default java.util.stream.Stream<T> toJavaParallelStream()

Converts this to a parallel Stream by calling StreamSupport.stream(this.spliterator(), true).

 // empty Stream
 Future.of(() -> { throw new Error(); })
       .toJavaParallelStream()

 // Stream containing "ok"
 Try.of(() -> "ok")
    .toJavaParallelStream()

 // Stream containing 1, 2, 3
 List.of(1, 2, 3)
     .toJavaParallelStream()
 

Returns:

A new parallel Stream.

See Also:

spliterator()

toLeft

@Deprecated
default <R> Either<T,R> toLeft(R right)

Deprecated.

Use toEither(Object) instead.

Converts this to a Either.

Type Parameters:

R - right type

Parameters:

right - An instance of a right value

Returns:

A new Either.Right containing the value of right if this is empty, otherwise a new Either.Left containing this value.

toLeft

@Deprecated
default <R> Either<T,R> toLeft(java.util.function.Supplier<? extends R> right)

Deprecated.

Use toEither(Supplier) instead.

Converts this to a Either.

Type Parameters:

R - right type

Parameters:

right - A supplier of a right value

Returns:

A new Either.Right containing the result of right if this is empty, otherwise a new Either.Left containing this value.

Throws:

java.lang.NullPointerException - if right is null

toList

default List<T> toList()

Converts this to a List.

Returns:

A new List.

toMap

default <K,V> Map<K,V> toMap(@NonNull java.util.function.Function<? super T,? extends K> keyMapper,
                                         @NonNull java.util.function.Function<? super T,? extends V> valueMapper)

Converts this to a Map.

Type Parameters:

K - The key type

V - The value type

Parameters:

keyMapper - A function that maps an element to a key

valueMapper - A function that maps an element to a value

Returns:

A new HashMap.

toMap

default <K,V> Map<K,V> toMap(@NonNull java.util.function.Function<? super T,? extends Tuple2<? extends K,? extends V>> f)

Converts this to a Map.

Type Parameters:

K - The key type

V - The value type

Parameters:

f - A function that maps an element to a key/value pair represented by Tuple2

Returns:

A new HashMap.

toLinkedMap

default <K,V> Map<K,V> toLinkedMap(@NonNull java.util.function.Function<? super T,? extends K> keyMapper,
                                               @NonNull java.util.function.Function<? super T,? extends V> valueMapper)

Converts this to a Map.

Type Parameters:

K - The key type

V - The value type

Parameters:

keyMapper - A function that maps an element to a key

valueMapper - A function that maps an element to a value

Returns:

A new LinkedHashMap.

toLinkedMap

default <K,V> Map<K,V> toLinkedMap(@NonNull java.util.function.Function<? super T,? extends Tuple2<? extends K,? extends V>> f)

Converts this to a Map.

Type Parameters:

K - The key type

V - The value type

Parameters:

f - A function that maps an element to a key/value pair represented by Tuple2

Returns:

A new LinkedHashMap.

toSortedMap

default <K extends java.lang.Comparable<? super K>,V> SortedMap<K,V> toSortedMap(@NonNull java.util.function.Function<? super T,? extends K> keyMapper,
                                                                                             @NonNull java.util.function.Function<? super T,? extends V> valueMapper)

Converts this to a Map.

Type Parameters:

K - The key type

V - The value type

Parameters:

keyMapper - A function that maps an element to a key

valueMapper - A function that maps an element to a value

Returns:

A new TreeMap.

toSortedMap

default <K extends java.lang.Comparable<? super K>,V> SortedMap<K,V> toSortedMap(@NonNull java.util.function.Function<? super T,? extends Tuple2<? extends K,? extends V>> f)

Converts this to a Map.

Type Parameters:

K - The key type

V - The value type

Parameters:

f - A function that maps an element to a key/value pair represented by Tuple2

Returns:

A new TreeMap.

toSortedMap

default <K,V> SortedMap<K,V> toSortedMap(@NonNull java.util.Comparator<? super K> comparator,
                                                     @NonNull java.util.function.Function<? super T,? extends K> keyMapper,
                                                     @NonNull java.util.function.Function<? super T,? extends V> valueMapper)

Converts this to a Map.

Type Parameters:

K - The key type

V - The value type

Parameters:

comparator - A comparator that induces an order of the Map keys.

keyMapper - A function that maps an element to a key

valueMapper - A function that maps an element to a value

Returns:

A new TreeMap.

toSortedMap

default <K,V> SortedMap<K,V> toSortedMap(@NonNull java.util.Comparator<? super K> comparator,
                                                     @NonNull java.util.function.Function<? super T,? extends Tuple2<? extends K,? extends V>> f)

Converts this to a Map.

Type Parameters:

K - The key type

V - The value type

Parameters:

comparator - A comparator that induces an order of the Map keys.

f - A function that maps an element to a key/value pair represented by Tuple2

Returns:

A new TreeMap.

toOption

default Option<T> toOption()

Converts this to an Option.

Returns:

A new Option.

toEither

default <L> Either<L,T> toEither(L left)

Converts this to an Either.

Type Parameters:

L - Either left component type

Parameters:

left - A left value for the Either

Returns:

A new Either.

toEither

default <L> Either<L,T> toEither(@NonNull java.util.function.Supplier<? extends L> leftSupplier)

Converts this to an Either.

Type Parameters:

L - Validation error component type

Parameters:

leftSupplier - A Supplier for the left value for the Either

Returns:

A new Either.

toValidation

default <E> Validation<E,T> toValidation(E invalid)

Converts this to an Validation.

Type Parameters:

E - Validation error component type

Parameters:

invalid - An invalid value for the Validation

Returns:

A new Validation.

toValidation

default <E> Validation<E,T> toValidation(@NonNull java.util.function.Supplier<? extends E> invalidSupplier)

Converts this to an Validation.

Type Parameters:

E - Validation error component type

Parameters:

invalidSupplier - A Supplier for the invalid value for the Validation

Returns:

A new Validation.

toQueue

default Queue<T> toQueue()

Converts this to a Queue.

Returns:

A new Queue.

toPriorityQueue

default PriorityQueue<T> toPriorityQueue()

Converts this to a PriorityQueue.

Returns:

A new PriorityQueue.

toPriorityQueue

default PriorityQueue<T> toPriorityQueue(@NonNull java.util.Comparator<? super T> comparator)

Converts this to a PriorityQueue.

Parameters:

comparator - A comparator that induces an order of the PriorityQueue elements.

Returns:

A new PriorityQueue.

toRight

@Deprecated
default <L> Either<L,T> toRight(L left)

Deprecated.

Use toEither(Object) instead.

Converts this to a Either.

Type Parameters:

L - left type

Parameters:

left - An instance of a left value

Returns:

A new Either.Left containing the value of left if this is empty, otherwise a new Either.Right containing this value.

toRight

@Deprecated
default <L> Either<L,T> toRight(java.util.function.Supplier<? extends L> left)

Deprecated.

Use toEither(Supplier) instead.

Converts this to a Either.

Type Parameters:

L - left type

Parameters:

left - A supplier of a left value

Returns:

A new Either.Left containing the result of left if this is empty, otherwise a new Either.Right containing this value.

Throws:

java.lang.NullPointerException - if left is null

toSet

default Set<T> toSet()

Converts this to a Set.

Returns:

A new HashSet.

toLinkedSet

default Set<T> toLinkedSet()

Converts this to a Set.

Returns:

A new LinkedHashSet.

toSortedSet

default SortedSet<T> toSortedSet()
                          throws java.lang.ClassCastException

Converts this to a SortedSet. Current items must be comparable

Returns:

A new TreeSet.

Throws:

java.lang.ClassCastException - if items are not comparable

toSortedSet

default SortedSet<T> toSortedSet(@NonNull java.util.Comparator<? super T> comparator)

Converts this to a SortedSet.

Parameters:

comparator - A comparator that induces an order of the SortedSet elements.

Returns:

A new TreeSet.

toStream

default Stream<T> toStream()

Converts this to a Stream.

Returns:

A new Stream.

toTry

default Try<T> toTry()

Converts this to a Try.

If this value is undefined, i.e. empty, then a new Failure(NoSuchElementException) is returned, otherwise a new Success(value) is returned.

Returns:

A new Try.

toTry

default Try<T> toTry(@NonNull java.util.function.Supplier<? extends java.lang.Throwable> ifEmpty)

Converts this to a Try.

If this value is undefined, i.e. empty, then a new Failure(ifEmpty.get()) is returned, otherwise a new Success(value) is returned.

Parameters:

ifEmpty - an exception supplier

Returns:

A new Try.

toTree

default Tree<T> toTree()

Converts this to a Tree.

Returns:

A new Tree.

toTree

default <ID> List<Tree.Node<T>> toTree(@NonNull java.util.function.Function<? super T,? extends ID> idMapper,
                                       @NonNull java.util.function.Function<? super T,? extends ID> parentMapper)

Converts this to a Tree using a idMapper and parentMapper.

Type Parameters:

ID - Id type

Parameters:

idMapper - A mapper from source item to unique identifier of that item

parentMapper - A mapper from source item to unique identifier of parent item. Need return null for root items

Returns:

A new Tree.

See Also:

Tree.build(Iterable, Function, Function)

toValid

@Deprecated
default <E> Validation<E,T> toValid(E error)

Deprecated.

Use toValidation(Object) instead.

Converts this to a Validation.

Type Parameters:

E - error type of an Invalid

Parameters:

error - An error

Returns:

A new Validation.Invalid containing the given error if this is empty, otherwise a new Validation.Valid containing this value.

toValid

@Deprecated
default <E> Validation<E,T> toValid(@NonNull java.util.function.Supplier<? extends E> errorSupplier)

Deprecated.

Use toValidation(Supplier) instead.

Converts this to a Validation.

Type Parameters:

E - error type of an Invalid

Parameters:

errorSupplier - A supplier of an error

Returns:

A new Validation.Invalid containing the result of errorSupplier if this is empty, otherwise a new Validation.Valid containing this value.

Throws:

java.lang.NullPointerException - if valueSupplier is null

toVector

default Vector<T> toVector()

Converts this to a Vector.

Returns:

A new Vector.

spliterator

default java.util.Spliterator<T> spliterator()

Specified by:

spliterator in interface java.lang.Iterable<T>

equals

boolean equals(java.lang.Object o)

Clarifies that values have a proper equals() method implemented.

See Object.equals(Object).

Overrides:

equals in class java.lang.Object

Parameters:

o - An object

Returns:

true, if this equals o, false otherwise

hashCode

int hashCode()

Clarifies that values have a proper hashCode() method implemented.

See Object.hashCode().

Overrides:

hashCode in class java.lang.Object

Returns:

The hashcode of this object

toString

java.lang.String toString()

Clarifies that values have a proper toString() method implemented.

See Object.toString().

Overrides:

toString in class java.lang.Object

Returns:

A String representation of this object