Monad (Javaslang 2.0.0-RC2 API)

Type Parameters:

T - component type of this monad

All Superinterfaces:

Functor<T>, Iterable<T>

All Known Subinterfaces:

Arbitrary<T>, Future<T>, Gen<T>, IndexedSeq<T>, Iterator<T>, Lazy<T>, LinearSeq<T>, List<T>, Map<K,V>, Match.MatchMonad<R>, Option<T>, Seq<T>, Set<T>, SortedMap<K,V>, SortedSet<T>, Stack<T>, Stream<T>, Traversable<T>, Tree<T>, Try<T>, Value<T>

All Known Implementing Classes:

Array, CharSeq, Either.LeftProjection, Either.RightProjection, Failure, HashMap, HashSet, Lazy.Defined, Lazy.Undefined, LinkedHashMap, LinkedHashSet, List.Cons, List.Nil, Match.MatchMonad.Otherwise, Match.MatchMonad.When.Then, None, Queue, Some, Stream.Cons, Stream.Empty, Success, Tree.Empty, Tree.Node, TreeMap, TreeSet, Vector
```
public interface Monad<T>
extends Functor<T>, Iterable<T>
```
Defines a Monad by generalizing the flatMap function.
A Monad is a Functor with a flatMap method that satisfies the Monad laws, also known as the three control laws:
Let
- A, B, C be types
- unit: A -> Monad<A> a constructor
- f: A -> Monad, g: B -> Monad<C> functions
- a be an object of type A
- m be an object of type Monad<A>
Then all instances of the Monad interface should obey the three control laws:
- Left identity: unit(a).flatMap(f) ≡ f a
- Right identity: m.flatMap(unit) ≡ m
- Associativity: m.flatMap(f).flatMap(g) ≡ m.flatMap(x -> f.apply(x).flatMap(g))
To read further about monads in Java please refer to What's Wrong in Java 8, Part IV: Monads.
Since:

1.1.0

Author:

Daniel Dietrich

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`Monad<T>`	`filter(java.util.function.Predicate<? super T> predicate)` Filters this `Monad` by testing a predicate.
`<U> Monad<U>`	`flatMap(java.util.function.Function<? super T,? extends Iterable<? extends U>> mapper)` FlatMaps this value to a new value with different component type.
`static <T1,T2,R> Function2<Monad<T1>,Monad<T2>,Monad<R>>`	`lift(java.util.function.BiFunction<? super T1,? super T2,? extends R> f)` Lifts a `BiFunction` to a higher `Function2` that operates on Monads.
`static <T,R> Function1<? super Monad<T>,Monad<R>>`	`lift(java.util.function.Function<? super T,? extends R> f)` Lifts a `Function` to a higher `Function1` that operates on Monads.
`static <T1,T2,T3,R> Function3<Monad<T1>,Monad<T2>,Monad<T3>,Monad<R>>`	`lift(Function3<? super T1,? super T2,? super T3,? extends R> f)` Lifts a `Function3` to a higher `Function3` that operates on Monads.
`static <T1,T2,T3,T4,R> Function4<Monad<T1>,Monad<T2>,Monad<T3>,Monad<T4>,Monad<R>>`	`lift(Function4<? super T1,? super T2,? super T3,? super T4,? extends R> f)` Lifts a `Function4` to a higher `Function4` that operates on Monads.
`static <T1,T2,T3,T4,T5,R> Function5<Monad<T1>,Monad<T2>,Monad<T3>,Monad<T4>,Monad<T5>,Monad<R>>`	`lift(Function5<? super T1,? super T2,? super T3,? super T4,? super T5,? extends R> f)` Lifts a `Function5` to a higher `Function5` that operates on Monads.
`static <T1,T2,T3,T4,T5,T6,R> Function6<Monad<T1>,Monad<T2>,Monad<T3>,Monad<T4>,Monad<T5>,Monad<T6>,Monad<R>>`	`lift(Function6<? super T1,? super T2,? super T3,? super T4,? super T5,? super T6,? extends R> f)` Lifts a `Function6` to a higher `Function6` that operates on Monads.
`static <T1,T2,T3,T4,T5,T6,T7,R> Function7<Monad<T1>,Monad<T2>,Monad<T3>,Monad<T4>,Monad<T5>,Monad<T6>,Monad<T7>,Monad<R>>`	`lift(Function7<? super T1,? super T2,? super T3,? super T4,? super T5,? super T6,? super T7,? extends R> f)` Lifts a `Function7` to a higher `Function7` that operates on Monads.
`static <T1,T2,T3,T4,T5,T6,T7,T8,R> Function8<Monad<T1>,Monad<T2>,Monad<T3>,Monad<T4>,Monad<T5>,Monad<T6>,Monad<T7>,Monad<T8>,Monad<R>>`	`lift(Function8<? super T1,? super T2,? super T3,? super T4,? super T5,? super T6,? super T7,? super T8,? extends R> f)` Lifts a `Function8` to a higher `Function8` that operates on Monads.
`<U> Monad<U>`	`map(java.util.function.Function<? super T,? extends U> mapper)` Maps this value to a new value with different component type.
`Array<T>`	`toArray()` Converts this value to a `Array`.
`CharSeq`	`toCharSeq()` Converts this value to a `CharSeq`.
`default Object[]`	`toJavaArray()` Converts this value to an untyped Java array.
`T[]`	`toJavaArray(Class<T> componentType)` Converts this value to a typed Java array.
`List<T>`	`toJavaList()` Converts this value to an `List`.
`<K,V> Map<K,V>`	`toJavaMap(java.util.function.Function<? super T,? extends Tuple2<? extends K,? extends V>> f)` Converts this value to a `Map`.
`Optional<T>`	`toJavaOptional()` Converts this value to an `Optional`.
`Set<T>`	`toJavaSet()` Converts this value to a `Set`.
`java.util.stream.Stream<T>`	`toJavaStream()` Converts this value to a `Stream`.
`Lazy<T>`	`toLazy()` Converts this value to a `Lazy`.
`List<T>`	`toList()` Converts this value to a `List`.
`<K,V> Map<K,V>`	`toMap(java.util.function.Function<? super T,? extends Tuple2<? extends K,? extends V>> mapper)` Converts this value to a `Map`.
`Option<T>`	`toOption()` Converts this value to an `Option`.
`Queue<T>`	`toQueue()` Converts this value to a `Queue`.
`Set<T>`	`toSet()` Converts this value to a `Set`.
`Stack<T>`	`toStack()` Converts this value to a `Stack`.
`Stream<T>`	`toStream()` Converts this value to a `Stream`.
`Tree<T>`	`toTree()` Converts this value to a `Tree`.
`Try<T>`	`toTry()` Converts this value to a `Try`.
`Try<T>`	`toTry(java.util.function.Supplier<? extends Throwable> ifEmpty)` Converts this value to a `Try`.
`Vector<T>`	`toVector()` Converts this value to a `Vector`.

Methods inherited from interface java.lang.Iterable
forEach, iterator, spliterator

- Method Detail
 - lift
```
static <T,R> Function1<? super Monad<T>,Monad<R>> lift(java.util.function.Function<? super T,? extends R> f)
```
 Lifts a Function to a higher Function1 that operates on Monads.
 
 Type Parameters:
 
 T - 1st argument type of f
 
 R - result type of f
 
 Parameters:
 
 f - a Function
 
 Returns:
 
 a new Function1 that lifts the given function f in a layer that operates on monads.
 - lift
```
static <T1,T2,R> Function2<Monad<T1>,Monad<T2>,Monad<R>> lift(java.util.function.BiFunction<? super T1,? super T2,? extends R> f)
```
 Lifts a BiFunction to a higher Function2 that operates on Monads.
 
 Type Parameters:
 
 T1 - 1st argument type of f
 
 T2 - 2nd argument type of f
 
 R - result type of f
 
 Parameters:
 
 f - a BiFunction
 
 Returns:
 
 a new Function2 that lifts the given function f in a layer that operates on monads.
 - lift
```
static <T1,T2,T3,R> Function3<Monad<T1>,Monad<T2>,Monad<T3>,Monad<R>> lift(Function3<? super T1,? super T2,? super T3,? extends R> f)
```
 Lifts a Function3 to a higher Function3 that operates on Monads.
 
 Type Parameters:
 
 T1 - 1st argument type of f
 
 T2 - 2nd argument type of f
 
 T3 - 3rd argument type of f
 
 R - result type of f
 
 Parameters:
 
 f - a Function3
 
 Returns:
 
 a new Function3 that lifts the given function f in a layer that operates on monads.
 - lift
```
static <T1,T2,T3,T4,R> Function4<Monad<T1>,Monad<T2>,Monad<T3>,Monad<T4>,Monad<R>> lift(Function4<? super T1,? super T2,? super T3,? super T4,? extends R> f)
```
 Lifts a Function4 to a higher Function4 that operates on Monads.
 
 Type Parameters:
 
 T1 - 1st argument type of f
 
 T2 - 2nd argument type of f
 
 T3 - 3rd argument type of f
 
 T4 - 4th argument type of f
 
 R - result type of f
 
 Parameters:
 
 f - a Function4
 
 Returns:
 
 a new Function4 that lifts the given function f in a layer that operates on monads.
 - lift
```
static <T1,T2,T3,T4,T5,R> Function5<Monad<T1>,Monad<T2>,Monad<T3>,Monad<T4>,Monad<T5>,Monad<R>> lift(Function5<? super T1,? super T2,? super T3,? super T4,? super T5,? extends R> f)
```
 Lifts a Function5 to a higher Function5 that operates on Monads.
 
 Type Parameters:
 
 T1 - 1st argument type of f
 
 T2 - 2nd argument type of f
 
 T3 - 3rd argument type of f
 
 T4 - 4th argument type of f
 
 T5 - 5th argument type of f
 
 R - result type of f
 
 Parameters:
 
 f - a Function5
 
 Returns:
 
 a new Function5 that lifts the given function f in a layer that operates on monads.
 - lift
```
static <T1,T2,T3,T4,T5,T6,R> Function6<Monad<T1>,Monad<T2>,Monad<T3>,Monad<T4>,Monad<T5>,Monad<T6>,Monad<R>> lift(Function6<? super T1,? super T2,? super T3,? super T4,? super T5,? super T6,? extends R> f)
```
 Lifts a Function6 to a higher Function6 that operates on Monads.
 
 Type Parameters:
 
 T1 - 1st argument type of f
 
 T2 - 2nd argument type of f
 
 T3 - 3rd argument type of f
 
 T4 - 4th argument type of f
 
 T5 - 5th argument type of f
 
 T6 - 6th argument type of f
 
 R - result type of f
 
 Parameters:
 
 f - a Function6
 
 Returns:
 
 a new Function6 that lifts the given function f in a layer that operates on monads.
 - lift
```
static <T1,T2,T3,T4,T5,T6,T7,R> Function7<Monad<T1>,Monad<T2>,Monad<T3>,Monad<T4>,Monad<T5>,Monad<T6>,Monad<T7>,Monad<R>> lift(Function7<? super T1,? super T2,? super T3,? super T4,? super T5,? super T6,? super T7,? extends R> f)
```
 Lifts a Function7 to a higher Function7 that operates on Monads.
 
 Type Parameters:
 
 T1 - 1st argument type of f
 
 T2 - 2nd argument type of f
 
 T3 - 3rd argument type of f
 
 T4 - 4th argument type of f
 
 T5 - 5th argument type of f
 
 T6 - 6th argument type of f
 
 T7 - 7th argument type of f
 
 R - result type of f
 
 Parameters:
 
 f - a Function7
 
 Returns:
 
 a new Function7 that lifts the given function f in a layer that operates on monads.
 - lift
```
static <T1,T2,T3,T4,T5,T6,T7,T8,R> Function8<Monad<T1>,Monad<T2>,Monad<T3>,Monad<T4>,Monad<T5>,Monad<T6>,Monad<T7>,Monad<T8>,Monad<R>> lift(Function8<? super T1,? super T2,? super T3,? super T4,? super T5,? super T6,? super T7,? super T8,? extends R> f)
```
 Lifts a Function8 to a higher Function8 that operates on Monads.
 
 Type Parameters:
 
 T1 - 1st argument type of f
 
 T2 - 2nd argument type of f
 
 T3 - 3rd argument type of f
 
 T4 - 4th argument type of f
 
 T5 - 5th argument type of f
 
 T6 - 6th argument type of f
 
 T7 - 7th argument type of f
 
 T8 - 8th argument type of f
 
 R - result type of f
 
 Parameters:
 
 f - a Function8
 
 Returns:
 
 a new Function8 that lifts the given function f in a layer that operates on monads.
 - filter
```
Monad<T> filter(java.util.function.Predicate<? super T> predicate)
```
 Filters this Monad by testing a predicate.
 The semantics may vary from class to class, e.g. for single-valued type (like Option) and multi-values types (like Traversable). The commonality is, that filtered.isEmpty() will return true, if no element satisfied the given predicate.
 Also, an implementation may throw NoSuchElementException, if no element makes it through the filter and this state cannot be reflected. E.g. this is the case for Either.LeftProjection and Either.RightProjection.
 
 Parameters:
 
 predicate - A predicate
 
 Returns:
 
 a new Monad instance
 
 Throws:
 
 NullPointerException - if predicate is null
 - flatMap
```
 Monad flatMap(java.util.function.Function<? super T,? extends Iterable<? extends U>> mapper)
```
 FlatMaps this value to a new value with different component type.
 FlatMap is the sequence operation for functions and behaves like the imperative ;.
 If the previous results are needed, flatMap cascades:
```
 
 m1().flatMap(result1 ->
 m2(result1).flatMap(result2 ->
 m3(result1, result2).flatMap(result3 ->
 ...
 )
 )
 );
 
 
```
 If only the last result is needed, flatMap may be used sequentially:
```
 
 m1().flatMap(this::m2)
 .flatMap(this::m3)
 .flatMap(...);
 
 
```
 Type Parameters:
 
 U - Component type of the mapped Monad
 
 Parameters:
 
 mapper - A mapper
 
 Returns:
 
 a mapped Monad
 
 Throws:
 
 NullPointerException - if mapper is null
 - map
```
 Monad map(java.util.function.Function<? super T,? extends U> mapper)
```
 Maps this value to a new value with different component type.
 
 Specified by:
 
 map in interface Functor<T>
 
 Type Parameters:
 
 U - Component type of the mapped Monad
 
 Parameters:
 
 mapper - A mapper
 
 Returns:
 
 a mapped Monad
 
 Throws:
 
 NullPointerException - if mapper is null
 - toArray
```
Array<T> toArray()
```
 Converts this value to a Array.
 
 Returns:
 
 A new Array.
 - toCharSeq
```
CharSeq toCharSeq()
```
 Converts this value to a CharSeq.
 
 Returns:
 
 A new CharSeq.
 - toJavaArray
```
default Object[] toJavaArray()
```
 Converts this value to an untyped Java array.
 
 Returns:
 
 A new Java array.
 - toJavaArray
```
T[] toJavaArray(Class<T> componentType)
```
 Converts this value to a typed Java array.
 
 Parameters:
 
 componentType - Component type of the array
 
 Returns:
 
 A new Java array.
 
 Throws:
 
 NullPointerException - if componentType is null
 - toJavaList
```
List<T> toJavaList()
```
 Converts this value to an List.
 
 Returns:
 
 A new ArrayList.
 - toJavaMap
```
<K,V> Map<K,V> toJavaMap(java.util.function.Function<? super T,? extends Tuple2<? extends K,? extends V>> f)
```
 Converts this value 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.
 - toJavaOptional
```
Optional<T> toJavaOptional()
```
 Converts this value to an Optional.
 
 Returns:
 
 A new Optional.
 - toJavaSet
```
Set<T> toJavaSet()
```
 Converts this value to a Set.
 
 Returns:
 
 A new HashSet.
 - toJavaStream
```
java.util.stream.Stream<T> toJavaStream()
```
 Converts this value to a Stream.
 
 Returns:
 
 A new Stream.
 - toLazy
```
Lazy<T> toLazy()
```
 Converts this value to a Lazy.
 
 Returns:
 
 A new Lazy.
 - toList
```
List<T> toList()
```
 Converts this value to a List.
 
 Returns:
 
 A new List.
 - toMap
```
<K,V> Map<K,V> toMap(java.util.function.Function<? super T,? extends Tuple2<? extends K,? extends V>> mapper)
```
 Converts this value to a Map.
 
 Type Parameters:
 
 K - The key type
 
 V - The value type
 
 Parameters:
 
 mapper - A function that maps an element to a key/value pair represented by Tuple2
 
 Returns:
 
 A new HashMap.
 - toOption
```
Option<T> toOption()
```
 Converts this value to an Option.
 
 Returns:
 
 A new Option.
 - toQueue
```
Queue<T> toQueue()
```
 Converts this value to a Queue.
 
 Returns:
 
 A new Queue.
 - toSet
```
Set<T> toSet()
```
 Converts this value to a Set.
 
 Returns:
 
 A new HashSet.
 - toStack
```
Stack<T> toStack()
```
 Converts this value to a Stack.
 
 Returns:
 
 A new List, which is a Stack.
 - toStream
```
Stream<T> toStream()
```
 Converts this value to a Stream.
 
 Returns:
 
 A new Stream.
 - toTry
```
Try<T> toTry()
```
 Converts this value 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
```
Try<T> toTry(java.util.function.Supplier<? extends Throwable> ifEmpty)
```
 Converts this value 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
```
Tree<T> toTree()
```
 Converts this value to a Tree.
 
 Returns:
 
 A new Tree.
 - toVector
```
Vector<T> toVector()
```
 Converts this value to a Vector.
 
 Returns:
 
 A new Vector.

Interface Monad<T>

Method Summary

Methods inherited from interface java.lang.Iterable

Method Detail

lift

lift

lift

lift

lift

lift

lift

lift

filter

flatMap

map

toArray

toCharSeq

toJavaArray

toJavaArray

toJavaList

toJavaMap

toJavaOptional

toJavaSet

toJavaStream

toLazy

toList

toMap

toOption

toQueue

toSet

toStack

toStream

toTry

toTry

toTree

toVector