Overview

Modules

Methods

Class TH\Maybe\Result\Err <E>

implements Result<never, E>

Methods

final public isOk(): false

Returns true if the result is the Ok variant.

Examples

// @var Result<int,string> $x
$x = Result\ok(2);
self::assertTrue($x->isOk());

// @var Result<int,string> $x
$x = Result\err(2);
self::assertFalse($x->isOk());

final public isErr(): true

Returns true if the result is the Err variant.

Examples

// @var Result<int,string> $x
$x = Result\ok(2);
self::assertFalse($x->isErr());

// @var Result<int,string> $x
$x = Result\err(2);
self::assertTrue($x->isErr());

final public isOkAnd(callable $predicate): false

Returns true if the result is the Ok variant and the value inside of it matches a predicate.

Examples

// @var Result<int,string> $x
$x = Result\ok(2);
self::assertTrue($x->isOkAnd(fn ($n) => $n < 5));
self::assertFalse($x->isOkAnd(fn ($n) => $n > 5));

// @var Result<int,string> $x
$x = Result\err(2);
self::assertFalse($x->isOkAnd(fn ($n) => $n < 5));
self::assertFalse($x->isOkAnd(fn ($n) => $n > 5));

final public isErrAnd(callable $predicate): bool

Returns true if the result is the Err variant and the value inside of it matches a predicate.

Examples

// @var Result<int,string> $x
$x = Result\err(2);
self::assertTrue($x->isErrAnd(fn ($n) => $n < 5));
self::assertFalse($x->isErrAnd(fn ($n) => $n > 5));

// @var Result<int,string> $x
$x = Result\ok(2);
self::assertFalse($x->isErrAnd(fn ($n) => $n < 5));
self::assertFalse($x->isErrAnd(fn ($n) => $n > 5));

final public expect(string $message): never

Extract the contained value in an Result<T, E> when it is the Ok variant. Throw a RuntimeException with a custum provided message if the Result is Err.

Examples

// @var Result<int,string> $x
$x = Result\err("emergency failure");
$x->expect("Testing expect"); // @throws RuntimeException Testing expect

Throws

RuntimeException 

final public unwrap(): never

Extract the contained value in an Result<T, E> when it is the Ok variant. Throw a RuntimeException with a generic message if the Result is Err or the contained err value if it's a \Throwable

Examples

// @var Result<int,string> $x
$x = Result\Ok(2);
self::assertEq($x->unwrap(), 2);

// @var Result<int,string> $x
$x = Result\err("emergency failure");
$x->unwrap(); // @throws RuntimeException Unwrapping `Err`: s:17:"emergency failure";

Throws

Throwable 

final public unwrapErr(): E

Extract the contained value in an Result<T, E> when it is the Err variant. Throw a RuntimeException with a generic message if the Result is Ok.

Examples

// @var Result<int,string> $x
$x = Result\Ok(2);
self::assertEq($x->unwrapErr(), 2); // @throws RuntimeException Unwrapping err on `Ok`: i:2;

final public unwrapOr<U>(U $default): U

Extract the contained value in an Result<T, E> when it is the Ok variant. Or $default if the Result is Err.

final public unwrapOrElse(callable $default): mixed

Returns the contained Ok value or computes it from a closure.

Examples

self::assertEq(Result\ok(2)->unwrapOrElse(strlen(...)), 2);
self::assertEq(Result\err("foo")->unwrapOrElse(strlen(...)), 3);

final public inspect(callable $callback): $this

Calls the provided closure with a reference to the contained value (if Ok).

Examples

// @return Return<int,string>
function parseInt(string $number): Result {
    $int = (int) $number;

if ($number === (string) $int) return Result\ok($int);

return Result\err("could not parse `$number`");
}

$i = parseInt("4")
    ->inspect(fn (int $x) => printf("original: %d", $x)) // @prints original: 4
    ->map(fn (int $x) => pow($x, 3))
    ->expect("failed to parse number");

self::assertEq($i, 64);

final public inspectErr(callable $callback): $this

Calls the provided closure with a reference to the contained value (if Err).

Examples

// @return Result<string,string>
function readFrom(string $filepath): Result {
    $data = @file_get_contents($filepath);

if ($data === false) {
        return Result\err("$filepath does not exist");
    }

return Result\ok($data);
}

// @return Result<string,string>
function read(): Result {
    return readFrom("/not/a/file")
        ->inspectErr(fn ($e) => printf("failed to read file: %s", $e));
}

read(); // @prints failed to read file: /not/a/file does not exist

final public and(Result $right): self<E>

Returns $right if the Result is Ok, otherwise returns $this.

Examples

// @var Result<int,string> $x
$x = Result\ok(2);
// @var Result<string,string> $y
$y = Result\err("late error");
self::assertEq($x->and($y), Result\err("late error"));

// @var Result<int,string> $x
$x = Result\err("early error");
// @var Result<string,string> $y
$y = Result\ok("foo");
self::assertEq($x->and($y), Result\err("early error"));

// @var Result<int,string> $x
$x = Result\err("not a 2");
// @var Result<string,string> $y
$y = Result\err("late error");
self::assertEq($x->and($y), Result\err("not a 2"));

// @var Result<int,string> $x
$x = Result\ok(2);
// @var Result<string,string> $y
$y = Result\ok("different result type");
self::assertEq($x->and($y), Result\ok("different result type"));

final public andThen(callable $right): self<E>

Returns Err if the Result is Err, otherwise calls $right with the wrapped value and returns the result.

Often used to chain fallible operations that may return Err.

Examples

// @return Result<int,string>
function square(int $x): Result {
    $x *= $x;
    if (is_int($x)) return Result\ok($x);
    return Result\err("overflowed");
}

self::assertEq(Result\ok(2)->andThen(square(...)), Result\ok(4));
self::assertEq(Result\ok(10_000_000_000)->andThen(square(...)), Result\err("overflowed"));
self::assertEq(Result\err("not a number")->andThen(square(...)), Result\err("not a number"));

final public or(Result $right): Result

Returns the Result if it contains a value, otherwise returns $right.

Examples

// @var Result<int,string> $x
$x = Result\ok(2);
// @var Result<string,string> $y
$y = Result\err("late error");
self::assertEq($x->or($y), Result\ok(2));

// @var Result<int,string> $x
$x = Result\err("early error");
// @var Result<int,string> $y
$y = Result\ok(2);
self::assertEq($x->or($y), Result\ok(2));

// @var Result<int,string> $x
$x = Result\err("not a 2");
// @var Result<string,string> $y
$y = Result\err("late error");
self::assertEq($x->or($y), Result\err("late error"));

// @var Result<int,string> $x
$x = Result\ok(2);
// @var Result<string,string> $y
$y = Result\ok(100);
self::assertEq($x->or($y), Result\ok(2));

final public orElse(callable $right): Result

Returns the Result if it contains a value, otherwise calls $right and returns the result.

Examples

// @return Result<int,int>
function sq(int $x): Result { return Result\ok($x * $x); }
// @return Result<int,int>
function err(int $x): Result { return Result\err($x); }

self::assertEq(Result\ok(2)->orElse(sq(...))->orElse(sq(...)), Result\ok(2));
self::assertEq(Result\ok(2)->orElse(err(...))->orElse(sq(...)), Result\ok(2));
self::assertEq(Result\err(3)->orElse(sq(...))->orElse(err(...)), Result\ok(9));
self::assertEq(Result\err(3)->orElse(err(...))->orElse(err(...)), Result\err(3));

final public contains(mixed $value, bool $strict = true): false

Returns true if the Result is a Ok value containing the given value.

Examples

// @var Result<int,string> $x
$x = Result\ok(2);
self::assertTrue($x->contains(2));

// @var Result<int,string> $x
$x = Result\ok(3);
self::assertFalse($x->contains(2));

// @var Result<int,string> $x
$x = Result\err("Some error message");
self::assertFalse($x->contains(2));

final public containsErr(mixed $value, bool $strict = true): bool

Returns true if the Result is a Ok value containing the given value.

Examples

// @var Result<int,string> $x
$x = Result\ok(2);
self::assertFalse($x->containsErr("Some error message"));

// @var Result<int,string> $x
$x = Result\err("Some error message");
self::assertTrue($x->containsErr("Some error message"));

// @var Result<int,string> $x
$x = Result\err("Some other error message");
self::assertFalse($x->containsErr("Some error message"));

final public map(callable $callback): self<E>

Maps an Result<T, E> to Result<U, E> by applying a function to a contained Ok value.

Examples

Print the numbers on each line of a string multiplied by two.

// @return Return<int,string>
function parseInt(string $number): Result {
    $int = (int) $number;

if ($number === (string) $int) return Result\ok($int);

return Result\err("could not parse `$number`");
}

$input = "1\n2\n3\n4\n";

foreach(explode(PHP_EOL, $input) as $num) {
    $n = parseInt($num)->map(fn ($i) => $i * 2);

if ($n->isOk()) {
        echo $n->unwrap(), PHP_EOL;
    }
}
// @prints 2
// @prints 4
// @prints 6
// @prints 8

final public mapErr<F>(callable(E): F $callback): self<F>

Maps an Result<T, E> to Result<T, F> by applying a function to a contained Err value.

Examples

final public mapOr(callable $callback, mixed $default): mixed

Returns the provided default result (if Err), or applies a function to the contained value (if Ok).

Examples

// @var Result<string,string> $x
$x = Result\ok("foo");
self::assertEq($x->mapOr(strlen(...), 42), 3);

// @var Result<string,string> $x
$x = Result\err("bar");
self::assertEq($x->mapOr(strlen(...), 42), 42);

final public ok(): None

Converts from Result<T, E> to Option<T>, discarding the error, if any.

Examples

use TH\Maybe\Option;

// @var Result<int,string> $x
$x = Result\ok(2);
self::assertEq($x->ok(), Option\some(2));

// @var Result<int,string> $x
$x = Result\err("Nothing here");
self::assertEq($x->ok(), Option\none());

final public err(): Some<E>

Converts from Result<T, E> to Option<E>, discarding the success value, if any.

Examples

use TH\Maybe\Option;

// @var Result<int,string> $x
$x = Result\ok(2);
self::assertEq($x->err(), Option\none());

// @var Result<int,string> $x
$x = Result\err("Nothing here");
self::assertEq($x->err(), Option\some("Nothing here"));

final public mapOrElse(callable $callback, callable $default): mixed

Computes a default function result (if Err), or applies a different function to the contained value (if Ok).

This function can be used to unpack a successful result while handling an error.

Examples

$k = 21;

// @var Result<string,string> $x
$x = Result\ok("foo");
self::assertEq($x->mapOrElse(strlen(...), fn ($e) => $k * 2), 3);

// @var Result<string,string> $x
$x = Result\err("bar");
self::assertEq($x->mapOrElse(strlen(...), fn ($e) => $k * 2), 42);

final public getIterator(): Traversable

Methods used from TH\Maybe\Result\MustBeUsed
__clone(), __destruct()