Vavr User Guide

java// (Java, 8)
Tuple2<String, Integer> java8 = Tuple.of("Java", 8); 1

// "Java"
String s = java8._1; 2

// 8
Integer i = java8._2; 3

java// (vavr, 1)
Tuple2<String, Integer> that = java8.map(
        s -> s.substring(2) + "vr",
        i -> i / 8
);

java// (vavr, 1)
Tuple2<String, Integer> that = java8.map(
        (s, i) -> Tuple.of(s.substring(2) + "vr", i / 8)
);

java// "vavr 1"
String that = java8.apply(
        (s, i) -> s.substring(2) + "vr " + i / 8
);

javaFunction1<Integer, Integer> plusOne = a -> a + 1;
Function1<Integer, Integer> multiplyByTwo = a -> a * 2;

Function1<Integer, Integer> add1AndMultiplyBy2 = plusOne.andThen(multiplyByTwo);

then(add1AndMultiplyBy2.apply(2)).isEqualTo(6);

javaFunction1<Integer, Integer> add1AndMultiplyBy2 = multiplyByTwo.compose(plusOne);

then(add1AndMultiplyBy2.apply(2)).isEqualTo(6);

javaFunction2<Integer, Integer, Integer> divide = (a, b) -> a / b;

javaFunction2<Integer, Integer, Option<Integer>> safeDivide = Function2.lift(divide);

// = None
Option<Integer> i1 = safeDivide.apply(1, 0); 1

// = Some(2)
Option<Integer> i2 = safeDivide.apply(4, 2); 2

javaint sum(int first, int second) {
    if (first < 0 || second < 0) {
        throw new IllegalArgumentException("Only positive integers are allowed"); 1
    }
    return first + second;
}

javaFunction2<Integer, Integer, Option<Integer>> sum = Function2.lift(this::sum);

// = None
Option<Integer> optionalResult = sum.apply(-1, 2); 1

javaFunction2<Integer, Integer, Integer> sum = (a, b) -> a + b;
Function1<Integer, Integer> add2 = sum.apply(2); 1

then(add2.apply(4)).isEqualTo(6);

javaFunction5<Integer, Integer, Integer, Integer, Integer, Integer> sum = (a, b, c, d, e) -> a + b + c + d + e;
Function2<Integer, Integer, Integer> add6 = sum.apply(2, 3, 1); 1

then(add6.apply(4, 3)).isEqualTo(13);

javaFunction2<Integer, Integer, Integer> sum = (a, b) -> a + b;
Function1<Integer, Integer> add2 = sum.curried().apply(2); 1

then(add2.apply(4)).isEqualTo(6);

javaFunction3<Integer, Integer, Integer, Integer> sum = (a, b, c) -> a + b + c;
final Function1<Integer, Function1<Integer, Integer>> add2 = sum.curried().apply(2);1

then(add2.apply(4).apply(3)).isEqualTo(9); 2

javaFunction0<Double> hashCache =
        Function0.of(Math::random).memoized();

double randomValue1 = hashCache.apply();
double randomValue2 = hashCache.apply();

then(randomValue1).isEqualTo(randomValue2);

java// optional *value*, no more nulls
Option<T> option = Option.of(...);

javaOptional<String> maybeFoo = Optional.of("foo"); 1
then(maybeFoo.get()).isEqualTo("foo");
Optional<String> maybeFooBar = maybeFoo.map(s -> (String)null)  2
                                       .map(s -> s.toUpperCase() + "bar");
then(maybeFooBar.isPresent()).isFalse();

javaOption<String> maybeFoo = Option.of("foo"); 1
then(maybeFoo.get()).isEqualTo("foo");
try {
    maybeFoo.map(s -> (String)null) 2
            .map(s -> s.toUpperCase() + "bar"); 3
    Assert.fail();
} catch (NullPointerException e) {
    // this is clearly not the correct approach
}

javaOption<String> maybeFoo = Option.of("foo"); 1
then(maybeFoo.get()).isEqualTo("foo");
Option<String> maybeFooBar = maybeFoo.map(s -> (String)null) 2
                                     .flatMap(s -> Option.of(s) 3
                                                         .map(t -> t.toUpperCase() + "bar"));
then(maybeFooBar.isEmpty()).isTrue();

javaOption<String> maybeFoo = Option.of("foo"); 1
then(maybeFoo.get()).isEqualTo("foo");
Option<String> maybeFooBar = maybeFoo.flatMap(s -> Option.of((String)null)) 2
                                     .map(s -> s.toUpperCase() + "bar");
then(maybeFooBar.isEmpty()).isTrue();

java// no need to handle exceptions
Try.of(() -> bunchOfWork()).getOrElse(other);

javaimport static io.vavr.API.*;        // $, Case, Match
import static io.vavr.Predicates.*; // instanceOf

A result = Try.of(this::bunchOfWork)
    .recover(x -> Match(x).of(
        Case($(instanceOf(Exception_1.class)), t -> somethingWithException(t)),
        Case($(instanceOf(Exception_2.class)), t -> somethingWithException(t)),
        Case($(instanceOf(Exception_n.class)), t -> somethingWithException(t))
    ))
    .getOrElse(other);

javaLazy<Double> lazy = Lazy.of(Math::random);
lazy.isEvaluated(); // = false
lazy.get();         // = 0.123 (random generated)
lazy.isEvaluated(); // = true
lazy.get();         // = 0.123 (memoized)

javaCharSequence chars = Lazy.val(() -> "Yay!", CharSequence.class);

javaEither<String,Integer> value = compute().right().map(i -> i * 2).toEither();

java// future *value*, result of an async calculation
Future<T> future = Future.of(...);

javaPersonValidator personValidator = new PersonValidator();

// Valid(Person(John Doe, 30))
Validation<Seq<String>, Person> valid = personValidator.validatePerson("John Doe", 30);

// Invalid(List(Name contains invalid characters: '!4?', Age must be greater than 0))
Validation<Seq<String>, Person> invalid = personValidator.validatePerson("John? Doe!4", -1);

class PersonValidator {

    private static final String VALID_NAME_CHARS = "[a-zA-Z ]";
    private static final int MIN_AGE = 0;

    public Validation<Seq<String>, Person> validatePerson(String name, int age) {
        return Validation.combine(validateName(name), validateAge(age)).ap(Person::new);
    }

    private Validation<String, String> validateName(String name) {
        return CharSeq.of(name).replaceAll(VALID_NAME_CHARS, "").transform(seq -> seq.isEmpty()
                ? Validation.valid(name)
                : Validation.invalid("Name contains invalid characters: '"
                + seq.distinct().sorted() + "'"));
    }

    private Validation<String, Integer> validateAge(int age) {
        return age < MIN_AGE
                ? Validation.invalid("Age must be at least " + MIN_AGE)
                : Validation.valid(age);
    }

}

class Person {

    public final String name;
    public final int age;

    public Person(String name, int age) {
        this.name = name;
        this.age = age;
    }

    @Override
    public String toString() {
        return "Person(" + name + ", " + age + ")";
    }

}

java// 2, 4, 6, ...
Stream.from(1).filter(i -> i % 2 == 0);

javaimport static io.vavr.API.*;

javaString s = Match(i).of(
    Case($(1), "one"),
    Case($(2), "two"),
    Case($(), "?")
);

The last wildcard pattern $() saves us from a MatchError which is thrown if no case matches.

Because we can’t perform exhaustiveness checks like the Scala compiler, we provide the possibility to return an optional result:

As already shown, Case allows to match conditional patterns.

Vavr offers a set of default predicates.

These can be used to express the initial Scala example as follows:

Multiple Conditions

We use the isIn predicate to check multiple conditions:

Performing Side-Effects

Match acts like an expression, it results in a value. In order to perform side-effects we need to use the helper function run which returns Void:

⚡ run is used to get around ambiguities and because void isn’t a valid return value in Java.

Caution: run must not be used as direct return value, i.e. outside of a lambda body:

Otherwise the Cases will be eagerly evaluated before the patterns are matched, which breaks the whole Match expression. Instead we use it within a lambda body:

As we can see, run is error prone if not used right. Be careful. We consider deprecating it in a future release and maybe we will also provide a better API for performing side-effects.

Vavr leverages lambdas to provide named parameters for matched values.

So far we directly matched values using atomic patterns. If an atomic pattern matches, the right type of the matched object is inferred from the context of the pattern.

Next, we will take a look at recursive patterns that are able to match object graphs of (theoretically) arbitrary depth.

In Java we use constructors to instantiate classes. We understand object decomposition as destruction of objects into their parts.

While a constructor is a function which is applied to arguments and returns a new instance, a deconstructor is a function which takes an instance and returns the parts. We say an object is unapplied.

Object destruction is not necessarily a unique operation. For example, a LocalDate can be decomposed to

• the year, month and day components

• the long value representing the epoch milliseconds of the corresponding Instant

• etc.

For many Vavr types there already exist match patterns. They are imported via

For example we are now able to match the result of a Try:

⚡ A first prototype of Vavr’s Match API allowed to extract a user-defined selection of objects from a match pattern. Without proper compiler support this isn’t practicable because the number of generated methods exploded exponentially. The current API makes the compromise that all patterns are matched but only the root patterns are decomposed.

Here the root patterns are Success and Failure. They are decomposed to Tuple2 and Error, having the correct generic types.

⚡ Deeply nested types are inferred according to the Match argument and not according to the matched patterns.

It is essential to be able to unapply arbitrary objects, including instances of final classes. Vavr does this in a declarative style by providing the compile time annotations @Patterns and @Unapply.

To enable the annotation processor the artifact vavr-match needs to be added as project dependency.

⚡ Note: Of course the patterns can be implemented directly without using the code generator. For more information take a look at the generated source.

The annotation processor places a file MyPatterns in the same package (by default in target/generated-sources). Inner classes are also supported. Special case: if the class name is $, the generated class name is just Patterns, without prefix.

Now we are able to match Optionals using guards.

The predicates could be simplified by implementing isNull and isNotNull.

⚡ And yes, extracting null is weird. Instead of using Java’s Optional give Vavr’s Option a try!