0
# Vavr
1

2
Vavr is an object-functional language extension to Java 8+ that brings functional programming concepts to Java development. It provides persistent collections, functional abstractions for error handling, concurrent programming utilities, and pattern matching capabilities. Vavr enables developers to write more concise, safe, and functional code while maintaining full Java interoperability.
3

4
## Package Information
5

6
- **Package Name**: io.vavr:vavr
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: `implementation 'io.vavr:vavr:0.10.6'` (Gradle) or `<dependency><groupId>io.vavr</groupId><artifactId>vavr</artifactId><version>0.10.6</version></dependency>` (Maven)
10

11
## Core Imports
12

13
```java
14
import io.vavr.*;
15
import io.vavr.collection.*;
16
import io.vavr.control.*;
17
import io.vavr.concurrent.*;
18
import static io.vavr.API.*;          // Pattern matching and utilities
19
import static io.vavr.Patterns.*;    // Pattern matching patterns
20
```
21

22
Common specific imports:
23

24
```java
25
import io.vavr.collection.List;
26
import io.vavr.collection.Map;
27
import io.vavr.collection.Stream;
28
import io.vavr.control.Option;
29
import io.vavr.control.Either;
30
import io.vavr.control.Try;
31
import io.vavr.control.Validation;
32
import io.vavr.concurrent.Future;
33
import io.vavr.concurrent.Promise;
34
```
35

36
## Basic Usage
37

38
```java
39
import io.vavr.collection.List;
40
import io.vavr.control.Option;
41
import io.vavr.control.Try;
42
import static io.vavr.API.*;
43
import static io.vavr.Patterns.*;
44

45
// Immutable collections
46
List<Integer> numbers = List.of(1, 2, 3, 4, 5);
47
List<Integer> doubled = numbers.map(x -> x * 2);
48
List<Integer> evens = numbers.filter(x -> x % 2 == 0);
49

50
// Option instead of null
51
Option<String> maybeValue = Option.of("Hello");
52
String result = maybeValue.map(String::toUpperCase).getOrElse("DEFAULT");
53

54
// Exception handling with Try
55
Try<Integer> computation = Try.of(() -> Integer.parseInt("123"));
56
String outcome = computation
57
    .map(x -> "Success: " + x)
58
    .getOrElse("Failed to parse");
59

60
// Pattern matching
61
String description = Match(numbers.size()).of(
62
    Case($(0), "empty"),
63
    Case($(1), "single"),
64
    Case($(), "multiple")
65
);
66
```
67

68
## Architecture
69

70
Vavr is built around several key architectural principles:
71

72
- **Immutability**: All data structures are immutable by default with structural sharing
73
- **Functional Interfaces**: Extended function interfaces (Function0-8) with composition and memoization
74
- **Monadic Types**: Control structures (Option, Either, Try, Validation) that eliminate common error patterns
75
- **Persistent Collections**: High-performance immutable collections with logarithmic complexity
76
- **Type Safety**: Strong typing with comprehensive generic support throughout the API
77
- **Java Interoperability**: Seamless conversion between Vavr and standard Java types
78

79
## Capabilities
80

81
### Core Types and Tuples
82

83
Essential building blocks including value types, lazy evaluation, tuples, and functional interfaces.
84

85
```java { .api }
86
interface Value<T> {
87
    // Core value interface with conversion methods
88
    Option<T> toOption();
89
    Try<T> toTry();
90
    <U> List<U> toList();
91
}
92

93
class Lazy<T> implements Value<T> {
94
    static <T> Lazy<T> of(Supplier<? extends T> supplier);
95
    T get();
96
    boolean isEvaluated();
97
}
98

99
interface Tuple {
100
    static Tuple0 empty();
101
    static <T1> Tuple1<T1> of(T1 t1);
102
    static <T1, T2> Tuple2<T1, T2> of(T1 t1, T2 t2);
103
    // ... up to Tuple8
104
}
105
```
106

107
[Core Types and Tuples](./core-types.md)
108

109
### Immutable Collections
110

111
Comprehensive collection library with persistent data structures, including lists, sets, maps, and specialized collections.
112

113
```java { .api }
114
interface List<T> extends LinearSeq<T> {
115
    static <T> List<T> of(T... elements);
116
    static <T> List<T> empty();
117
    T head();
118
    List<T> tail();
119
    List<T> prepend(T element);
120
    <U> List<U> map(Function<? super T, ? extends U> mapper);
121
    List<T> filter(Predicate<? super T> predicate);
122
}
123

124
interface Map<K, V> extends Traversable<Tuple2<K, V>> {
125
    static <K, V> Map<K, V> of(K k1, V v1);
126
    static <K, V> Map<K, V> empty();
127
    Option<V> get(K key);
128
    Map<K, V> put(K key, V value);
129
    Map<K, V> remove(K key);
130
}
131
```
132

133
[Collections](./collections.md)
134

135
### Control Types
136

137
Monadic control structures for error handling, optional values, and validation with functional composition.
138

139
```java { .api }
140
interface Option<T> extends Value<T> {
141
    static <T> Option<T> of(T value);
142
    static <T> Option<T> some(T value);
143
    static <T> Option<T> none();
144
    boolean isDefined();
145
    T get();
146
    <U> Option<U> map(Function<? super T, ? extends U> mapper);
147
    <U> Option<U> flatMap(Function<? super T, ? extends Option<? extends U>> mapper);
148
}
149

150
interface Either<L, R> extends Value<R> {
151
    static <L, R> Either<L, R> left(L left);
152
    static <L, R> Either<L, R> right(R right);
153
    boolean isLeft();
154
    boolean isRight();
155
    <U> Either<L, U> map(Function<? super R, ? extends U> mapper);
156
}
157

158
interface Try<T> extends Value<T> {
159
    static <T> Try<T> of(CheckedFunction0<? extends T> supplier);
160
    boolean isSuccess();
161
    boolean isFailure();
162
    <U> Try<U> map(Function<? super T, ? extends U> mapper);
163
    Try<T> recover(Function<? super Throwable, ? extends T> recovery);
164
}
165
```
166

167
[Control Types](./control-types.md)
168

169
### Concurrent Programming
170

171
Asynchronous programming utilities with Futures, Promises, and functional composition for concurrent operations.
172

173
```java { .api }
174
interface Future<T> extends Value<T> {
175
    static <T> Future<T> of(Executor executor, CheckedFunction0<? extends T> computation);
176
    static <T> Future<T> successful(T value);
177
    boolean isCompleted();
178
    <U> Future<U> map(Function<? super T, ? extends U> mapper);
179
    <U> Future<U> flatMap(Function<? super T, ? extends Future<? extends U>> mapper);
180
    Future<T> recover(Function<? super Throwable, ? extends T> recovery);
181
}
182

183
interface Promise<T> {
184
    static <T> Promise<T> make();
185
    boolean trySuccess(T value);
186
    boolean tryFailure(Throwable exception);
187
    Future<T> future();
188
}
189
```
190

191
[Concurrent Programming](./concurrent.md)
192

193
### Functional Interfaces
194

195
Extended function interfaces with composition, memoization, and exception handling capabilities.
196

197
```java { .api }
198
@FunctionalInterface
199
interface Function1<T1, R> extends java.util.function.Function<T1, R> {
200
    static <T1, R> Function1<T1, R> of(Function1<T1, R> function);
201
    default Function1<T1, R> memoized();
202
    default <V> Function1<T1, V> andThen(Function<? super R, ? extends V> after);
203
}
204

205
@FunctionalInterface 
206
interface CheckedFunction1<T1, R> {
207
    R apply(T1 t1) throws Throwable;
208
    default Function1<T1, Try<R>> unchecked();
209
}
210
```
211

212
[Functional Interfaces](./functional-interfaces.md)
213

214
### Pattern Matching
215

216
Structural pattern matching for control flow and data destructuring with compile-time safety.
217

218
```java { .api }
219
// Core pattern matching API
220
static <T> Match.Case<T, ?> Case(Pattern<T> pattern, Object value);
221
static <T> Match.Case<T, ?> Case(Pattern<T> pattern, Supplier<Object> supplier);
222
static <T> Match.Case<T, ?> Case(Pattern<T> pattern, Function<T, Object> function);
223

224
// Pattern matching entry point
225
static <T> Match<T> Match(T value);
226

227
// Pattern creators
228
static <T> Pattern<T> $(T prototype);          // Exact match
229
static <T> Pattern<T> $();                     // Wildcard match
230
static <T> Pattern<T> $(Predicate<T> predicate); // Conditional match
231

232
// Object patterns for data types
233
static <T> Pattern<Option<T>> Some(Pattern<T> pattern);
234
static Pattern<Option<?>> None();
235
static <L, R> Pattern<Either<L, R>> Left(Pattern<L> pattern);
236
static <L, R> Pattern<Either<L, R>> Right(Pattern<R> pattern);
237
static <T> Pattern<Try<T>> Success(Pattern<T> pattern);
238
static <T> Pattern<Try<T>> Failure(Pattern<Throwable> pattern);
239
```
240

241
Pattern matching enables expressive and type-safe control flow:
242

243
```java
244
// Matching on data types
245
String result = Match(option).of(
246
    Case($Some($()), value -> "Found: " + value),
247
    Case($None(), "Not found")
248
);
249

250
// Matching with guards
251
String category = Match(number).of(
252
    Case($(n -> n < 0), "negative"),
253
    Case($(0), "zero"),
254
    Case($(n -> n > 0), "positive")
255
);
256
```
257

258
## Type Conversion
259

260
Vavr provides extensive interoperability with Java standard library types:
261

262
```java { .api }
263
// Converting from Java to Vavr
264
List<String> vavrList = List.ofAll(Arrays.asList("a", "b", "c"));
265
Option<String> vavrOption = Option.of(javaOptional.orElse(null));
266

267
// Converting from Vavr to Java  
268
java.util.List<String> javaList = vavrList.asJava();
269
java.util.Optional<String> javaOptional = vavrOption.toJavaOptional();
270
java.util.stream.Stream<String> javaStream = vavrList.toJavaStream();
271
```