Package io.vavr

Interface Value<T>

Type Parameters:
T - the type of the wrapped value
All Superinterfaces:
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 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 Details

    • 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 Collector<? super T,A,R> collector)
      Collects the underlying value(s) (if present) using the provided collector.
      Type Parameters:
      R - the result type of the reduction operation
      A - the mutable accumulation type of the reduction operation
      Parameters:
      collector - Collector performing reduction
      Returns:
      R reduction result

    • collect

      default <R> R collect(@NonNull Supplier<R> supplier, @NonNull BiConsumer<R,? super T> accumulator, @NonNull 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 Iterable<U> that, @NonNull 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(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 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:
      NullPointerException - if predicate is null

    • forAll

      default boolean forAll(@NonNull 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:
      NullPointerException - if predicate is null

    • forEach

      default void forEach(@NonNull Consumer<? super T> action)
      Performs an action on each element.
      Specified by:
      forEach in interface Iterable<T>
      Parameters:
      action - A Consumer
      Throws:
      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 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:
      NullPointerException - if supplier is null

    • getOrElseThrow

      default <X extends Throwable> T getOrElseThrow(@NonNull Supplier<X> supplier) throws X
      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:
      NullPointerException - if supplier is null
      X - if no value is present

    • 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:
      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<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 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 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

      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(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:
      IllegalStateException - if PrintStream.checkError() is true after writing to stream.

    • out

      @GwtIncompatible("java.io.PrintWriter is not implemented") default void out(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:
      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:
      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:
      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 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 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(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:
      NullPointerException - if valueSupplier is null

    • toJavaArray

      default 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(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:
      NullPointerException - if componentType is null

    • toJavaArray

      default T[] toJavaArray(@NonNull 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:
      NullPointerException - if componentType is null

    • toJavaCollection

      default <C extends Collection<T>> C toJavaCollection(@NonNull Function<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 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 List<T>> LIST toJavaList(@NonNull Function<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> Map<K,V> toJavaMap(@NonNull 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 Map<K, V>> MAP toJavaMap(@NonNull Supplier<MAP> factory, @NonNull Function<? super T,? extends K> keyMapper, @NonNull 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 Map<K, V>> MAP toJavaMap(@NonNull Supplier<MAP> factory, @NonNull 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 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 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 Set<T>> SET toJavaSet(@NonNull Function<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 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:

    • toJavaParallelStream

      default 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:

    • 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(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:
      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 Function<? super T,? extends K> keyMapper, @NonNull 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 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 Function<? super T,? extends K> keyMapper, @NonNull 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 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 Comparable<? super K>, V> SortedMap<K,V> toSortedMap(@NonNull Function<? super T,? extends K> keyMapper, @NonNull 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 Comparable<? super K>, V> SortedMap<K,V> toSortedMap(@NonNull 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 Comparator<? super K> comparator, @NonNull Function<? super T,? extends K> keyMapper, @NonNull 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 Comparator<? super K> comparator, @NonNull 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 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 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 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(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:
      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 ClassCastException
      Converts this to a SortedSet. Current items must be comparable
      Returns:
      A new TreeSet.
      Throws:
      ClassCastException - if items are not comparable

    • toSortedSet

      default SortedSet<T> toSortedSet(@NonNull 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 Supplier<? extends 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 Function<? super T,? extends ID> idMapper, @NonNull 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:

    • 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 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:
      NullPointerException - if valueSupplier is null

    • toVector

      default Vector<T> toVector()
      Converts this to a Vector.
      Returns:
      A new Vector.

    • spliterator

      default Spliterator<T> spliterator()
      Specified by:
      spliterator in interface Iterable<T>

    • equals

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

      See Object.equals(Object).

      Overrides:
      equals in class 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 Object
      Returns:
      The hashcode of this object

    • toString

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

      See Object.toString().

      Overrides:
      toString in class Object
      Returns:
      A String representation of this object