Try<V>

// Wrap any throwing computation — catches Throwable, not just Exception
Try<Integer> parsed   = Try.of(() -> Integer.parseInt(input));
Try<String>  content  = Try.of(() -> Files.readString(path));

// Wrap a void side-effect (result value is null on success)
Try<Void> written = Try.run(() -> Files.writeString(path, data));

// Construct directly when you already know the outcome
Try<Integer> ok  = Try.success(42);
Try<Integer> err = Try.failure(new RuntimeException("oops"));

Try<Integer> t = Try.of(() -> Integer.parseInt(input));

t.isSuccess(); // true if Success
t.isFailure(); // true if Failure

// Exhaustive pattern matching — preferred
String msg = switch (t) {
    case Try.Success<Integer> s -> "Parsed: " + s.value();
    case Try.Failure<Integer> f -> "Failed: " + f.cause().getMessage();
};

Try<Integer> t = Try.of(() -> Integer.parseInt(input));

// Safe: always returns a value
int n = t.getOrElse(0);
int m = t.getOrElseGet(() -> computeDefault());

// Expressive: handles both tracks
String result = t.fold(
    value -> "Parsed: " + value,
    ex    -> "Error: "  + ex.getMessage()
);

// Unsafe: throws if Failure
int raw  = t.get();      // throws NoSuchElementException
Throwable e = t.getCause(); // throws NoSuchElementException if Success

// Rethrow the original exception (or wrap it)
int val = t.getOrThrow();                        // rethrows as-is
int v2  = t.getOrThrow(ex -> new AppException(ex)); // maps to RuntimeException

Try<String> binary = Try.of(() -> Integer.parseInt(input))
    .map(Integer::toBinaryString); // Try<Integer> → Try<String>

// If the mapper throws, the exception is captured as a Failure
Try<JsonNode> json = Try.of(() -> Files.readString(path))
    .map(Json::parse); // IOException or JsonException → Failure

// flatMap chains fallible operations without nesting
Try<Config> config = Try.of(() -> Files.readString(configPath))
    .flatMap(text -> Try.of(() -> Json.parse(text)))
    .flatMap(json -> Try.of(() -> Config.from(json)));

// Equivalent flatMapError: recover on failure with another Try
Try<String> result = Try.of(() -> fetchRemote(url))
    .flatMapError(ex -> Try.of(() -> fetchFallback(url)));

// Default: converts to Failure(IllegalArgumentException) when predicate fails
Try<Integer> positive = Try.of(() -> Integer.parseInt(input))
    .filter(n -> n > 0);

// Custom exception supplier
Try<Integer> valid = Try.of(() -> Integer.parseInt(input))
    .filter(n -> n > 0, () -> new IllegalArgumentException("Must be positive"));

// Value-aware error (receives the failing value)
Try<Integer> age = Try.of(() -> Integer.parseInt(input))
    .filter(n -> n >= 0, n -> new IllegalArgumentException("Negative age: " + n));

Try<Integer> t = Try.of(() -> Integer.parseInt(input));

// onSuccess / onFailure — chainable, return this
t.onSuccess(n  -> log.info("Parsed: {}", n))
 .onFailure(ex -> log.warn("Parse failed: {}", ex.getMessage()));

// match — terminal, void; both branches must be handled
t.match(
    value -> metrics.increment("parse.ok"),
    ex    -> metrics.increment("parse.error")
);

// recover — map the exception to a fallback value
Try<String> result = Try.of(() -> fetchRemote(url))
    .recover(ex -> "default-value");

// recover by exception type — only handles the matched subtype
Try<String> typed = Try.of(() -> fetchRemote(url))
    .recover(IOException.class, ex -> "offline-fallback");

// recoverWith — map to a new Try (for chaining another fallible operation)
Try<String> chain = Try.of(() -> fetchPrimary(url))
    .recoverWith(ex -> Try.of(() -> fetchSecondary(url)));

// recoverWith by exception type
Try<String> typed2 = Try.of(() -> fetchPrimary(url))
    .recoverWith(TimeoutException.class, ex -> Try.of(() -> fetchSecondary(url)));

List<String> inputs = List.of("1", "2", "abc", "4");

// sequence: Stream<Try<V>> → Try<List<V>> — fails fast on first Failure
Try<List<Integer>> allOrNone = Try.sequence(
    inputs.stream().map(s -> Try.of(() -> Integer.parseInt(s)))
);
// → Failure(NumberFormatException) — stops at "abc"

// traverse: applies the mapper and collects — same fail-fast behaviour
Try<List<Integer>> result = Try.traverse(inputs, s -> Try.of(() -> Integer.parseInt(s)));

// sequence also accepts an Iterable
List<Try<Integer>> tries = List.of(Try.success(1), Try.success(2));
Try<List<Integer>> list  = Try.sequence(tries); // → Success([1, 2])

// ── Try.toList() — returns first Failure (stream still fully traversed) ──────
Try<List<Integer>> parsed =
    Stream.of("1", "2", "3")
          .map(s -> Try.of(() -> Integer.parseInt(s)))
          .collect(Try.toList());
// → Success([1, 2, 3])

Try<List<Integer>> broken =
    Stream.of("1", "bad", "3")
          .map(s -> Try.of(() -> Integer.parseInt(s)))
          .collect(Try.toList());
// → Failure(NumberFormatException) — "3" is still parsed; collector returns first Failure

// Real-world: parse all config values — returns first parse error encountered
// Note: all keys are parsed regardless; do not rely on early termination for
// expensive or side-effecting upstream work.
Try<List<Duration>> timeouts = configKeys.stream()
    .map(key -> Try.of(() -> Duration.parse(config.get(key))))
    .collect(Try.toList());

// ── Try.partitioningBy() — process all, split successes from failures ─────────
Try.Partition<Path> result = filePaths.stream()
    .map(path -> Try.of(() -> validateFile(path)))
    .collect(Try.partitioningBy());

List<Path>       valid   = result.successes(); // files that passed validation
List<Throwable>  errors  = result.failures();  // exceptions from invalid files

// Real-world: import as many files as possible; log failures without aborting
importService.bulkProcess(result.successes());
result.failures().forEach(ex -> log.error("Skipping file: {}", ex.getMessage()));

// ── Tries.toList() — same as Try.toList(), single import entry point ─────────
Try<List<Integer>> all = Stream.of("10", "20", "30")
    .map(s -> Try.of(() -> Integer.parseInt(s)))
    .collect(Tries.toList());
// → Success([10, 20, 30])

// ── Tries.partitioning() — collect all results, split by outcome ─────────────
Tries.Partition<byte[]> partition = urls.stream()
    .map(url -> Try.of(() -> httpClient.fetch(url)))
    .collect(Tries.partitioning());

partition.successes().forEach(body -> indexer.ingest(body));
partition.failures().forEach(ex  -> metrics.recordError(ex));

// Bridge to Try.Partition when needed
Try.Partition<byte[]> tp = partition.toTryPartition();

// Try.run() wraps a void computation — the success value is null
Try<Void> written = Try.run(() -> Files.writeString(path, content));
written.isSuccess(); // true
written.getOrNull(); // null — do NOT use toOption() here; it always returns None

// Use isSuccess() or fold() to observe a run() outcome
boolean ok = written.isSuccess();
String msg = written.fold(_ -> "written", ex -> "failed: " + ex.getMessage());

// sequence preserves null values (uses Collections.unmodifiableList, not List.copyOf)
Try<List<String>> result = Try.sequence(
    Stream.of(Try.success("a"), Try.success(null), Try.success("c"))
);
// → Success(["a", null, "c"])

Try<String> t = Try.of(() -> Files.readString(path));

// Try → Option (discards the exception; Success(null) also maps to None)
Option<String> opt = t.toOption();

// Try → Result<V, Throwable> (keeps the exception as a typed error)
Result<String, Throwable> raw = t.toResult();

// Try → Result<V, E> with error mapping
Result<String, AppError> typed = t.toResult(ex -> new AppError(ex.getMessage()));

// Try → Either<Throwable, V>  (throws NPE on Success(null))
Either<Throwable, String> either = t.toEither();

// Try → Optional<V> (Failure and Success(null) → Optional.empty())
Optional<String> javaOpt = t.toOptional();

// Try → Stream<V> (empty on Failure, single element on Success)
t.stream().forEach(System.out::println);

// Try → CompletableFuture<V> (already-completed future)
CompletableFuture<String> future = t.toFuture();

// ── From other types ──────────────────────────────────────────────────────────

// Option → Try
Option<String> option = Option.some("hello");
Try<String> fromOpt = Try.fromOption(option, () -> new NoSuchElementException("missing"));

// Optional → Try
Optional<String> optional = Optional.of("hello");
Try<String> fromOptional = Try.fromOptional(optional, () -> new NoSuchElementException("missing"));

// Either<L, R> → Try  (left value mapped to a Throwable)
Either<String, Integer> left  = Either.left("not found");
Either<String, Integer> right = Either.right(42);
Try<Integer> fromLeft  = Try.fromEither(left,  IllegalArgumentException::new);
// Try.failure(new IllegalArgumentException("not found"))
Try<Integer> fromRight = Try.fromEither(right, IllegalArgumentException::new);
// Try.success(42)

// Result<V, Throwable> → Try
Result<String, IOException> result = Result.err(new IOException("oops"));
Try<String> fromResult = Try.fromResult(result);

// CompletableFuture → Try (blocks until complete; unwraps CompletionException)
Try<String> fromFuture = Try.fromFuture(CompletableFuture.completedFuture("done"));

// Static factory — enforce a time limit from the start
Try<Response> result = Try.withTimeout(
    Duration.ofSeconds(5),
    () -> httpClient.get(url)
);

// Exceeded deadline → Failure(TimeoutException("Operation timed out after 100000000ns"))
Try<String> timedOut = Try.withTimeout(
    Duration.ofMillis(100),
    () -> { Thread.sleep(10_000); return "never"; }
);
timedOut.isFailure();  // true
timedOut.getCause();   // TimeoutException: "Operation timed out after 100000000ns"

// Composes naturally with the rest of the API
Try.withTimeout(Duration.ofSeconds(3), () -> fetchUser(id))
   .recover(TimeoutException.class, ex -> User.anonymous())
   .flatMap(user -> validateActive(user))
   .onSuccess(user -> cache.put(id, user));

// Bad: throws NoSuchElementException if Failure
int n = Try.of(() -> Integer.parseInt(input)).get();

// Good: safe extraction
int n = Try.of(() -> Integer.parseInt(input)).getOrElse(0);

// Good: handle both tracks explicitly
int n = Try.of(() -> Integer.parseInt(input))
    .fold(value -> value, ex -> { log.warn("bad input", ex); return 0; });

// Bad: Try buries the error domain — callers can't branch on error type
Try<User> findUser(long id) {
    return Try.of(() -> userRepo.find(id));
}

// Good: when you own the error type, use Result
Result<User, UserError> findUser(long id) {
    return userRepo.find(id)
        .map(Result::<User, UserError>ok)
        .orElse(Result.err(UserError.NOT_FOUND));
}

// Good: use Try only at the boundary where legacy code throws
Result<User, UserError> findUser(long id) {
    return Try.of(() -> legacyRepo.find(id))
        .toResult(ex -> new UserError(ex.getMessage()));
}

// File → parse → validate → save pipeline
// Each step may throw; Try captures the exception at every boundary.

Try<ReportId> saveReport(Path path) {
    return Try.of(() -> Files.readString(path))           // IOException
        .map(text  -> Json.parse(text))                   // JsonException
        .flatMap(json  -> Try.of(() -> validate(json)))   // ValidationException
        .flatMap(valid -> Try.of(() -> reportRepo.save(valid))) // SQLException
        .map(Report::id);
}

// At the call site, fold handles both outcomes
saveReport(uploadedPath).fold(
    id -> Response.ok("Saved report " + id),
    ex -> switch (ex) {
        case IOException      e -> Response.error(503, "Storage unavailable");
        case JsonException    e -> Response.error(400, "Invalid JSON");
        case ValidationException e -> Response.error(422, e.getMessage());
        default                  -> Response.error(500, "Unexpected error");
    }
);