Namespace TH\Maybe\Option

some

Return a Option\Some option containing $value.

none

Return a Option\None option containing no values.

fromValue

Transform a value into an Option. It will be a Some option containing $value if $value is different from $noneValue (default null), or, when $isSome is given, if $isSome($value) returns true ($strict is then ignored). $noneValue and $isSome cannot be used together: an \InvalidArgumentException is thrown if both are given.

Examples

self::assertEq(Option\fromValue("fruits"), Option\some("fruits"));
self::assertEq(Option\fromValue(null), Option\none());

Using a predicate:

self::assertEq(Option\fromValue(3, isSome: is_int(...)), Option\some(3));
self::assertEq(Option\fromValue(false, isSome: is_int(...)), Option\none());

$noneValue and $isSome are mutually exclusive:

Option\fromValue(3, noneValue: 0, isSome: is_int(...));
// @throws InvalidArgumentException $noneValue and $isSome cannot be used together

of

Execute a callable and transform the result into an Option. It will be a Some option containing the result if it is different from $noneValue (default null), or, when $isSome is given, if $isSome($result) returns true ($noneValue and $isSome cannot be used together).

Examples

Successful execution:

self::assertEq(Option\of(fn() => "fruits"), Option\some("fruits"));

Conversion of null to Option\None:

self::assertEq(Option\of(fn() => null), Option\none());

Using a predicate:

self::assertEq(Option\of(fn() => strpos("fruits", "z"), isSome: is_int(...)), Option\none());

tryOf

Execute a callable and transform the result into an Option as Option\of() does but also return Option\None if an exception matching $exceptionClass was thrown.

Examples

Successful execution:

self::assertEq(Option\tryOf(fn () => strtolower("FRUITS")), Option\some("fruits"));

Conversion of null to Option\None:

self::assertEq(Option\tryOf(fn() => null), Option\none());

Checked Exception:

self::assertEq(Option\tryOf(fn () => new \DateTimeImmutable("nope")), Option\none());

Unchecked Exception:

self::assertEq(Option\tryOf(fn () => 1 / 0), Option\none());
// @throws DivisionByZeroError Division by zero

ify

Wrap a callable into one that transforms its result into an Option. It will be a Some option containing the result if it is different from $noneValue (default null), or, when $isSome is given, if $isSome($result) returns true ($noneValue and $isSome cannot be used together).

Examples

Successful execution:

self::assertEq(Option\ify(strtolower(...))("FRUITS"), Option\some("fruits"));

Conversion of null to Option\None:

self::assertEq(Option\ify(fn() => null)(), Option\none());

Option-ify strpos():

$strpos = Option\ify(strpos(...), isSome: is_int(...));

self::assertEq($strpos("fruits", "u"), Option\some(2));
self::assertEq($strpos("fruits", "z"), Option\none());

tryIfy

Wrap a callable into one that transforms its result into an Option like Option\ify() does but also return Option\None if an exception matching $exceptionClass was thrown.

Examples

Successful execution:

self::assertEq(Option\tryIfy(strtolower(...))("FRUITS"), Option\some("fruits"));

Conversion of null to Option\None:

self::assertEq(Option\tryIfy(fn() => null)(), Option\none());

Checked Exception:

self::assertEq(Option\tryIfy(fn () => new \DateTimeImmutable("nope"))(), Option\none());

Unchecked Exception:

self::assertEq(Option\tryIfy(fn () => 1 / 0)(), Option\none());
// @throws DivisionByZeroError Division by zero

flatten

Converts from Option<Option<T>> to Option<T>.

Examples

$x = Option\Some("vegetables");
self::assertSame(Option\flatten(Option\some($x)), $x);
self::assertSame(Option\flatten(Option\some(Option\none())), Option\none());
self::assertSame(Option\flatten(Option\none()), Option\none());

unzip

Unzips an option containing a tuple of two options.

If self is Some([a, b]) this method returns [Some(a), Some(b)]. Otherwise, [None, None] is returned.

$x = Option\Some("vegetables");
self::assertEq(Option\unzip(Option\some(["a", 2])), [Option\some("a"), Option\some(2)]);
self::assertSame(Option\unzip(Option\none()), [Option\none(), Option\none()]);

transpose

Transposes an Option of a Result into a Result of an Option.

None will be mapped to Ok(None). Some(Ok(_)) and Some(Err(_)) will be mapped to Ok(Some(_)) and Err(_).

use TH\Maybe\Result;

self::assertEq(Result\ok(Option\some(4)), Option\transpose(Option\some(Result\ok(4))));
self::assertEq(Result\err("meat"), Option\transpose(Option\some(Result\err("meat"))));
self::assertEq(Option\transpose(Option\none()), Result\ok(Option\none()));

collect

Takes each element in the iterable: if it is a None, no further elements are taken and None is returned. Should no None occur, a Some containing the list of all the values is returned.

Examples

self::assertEq(Option\collect([Option\some(1), Option\some(2)]), Option\some([1, 2]));
self::assertEq(Option\collect([Option\some(1), Option\none()]), Option\none());
self::assertEq(Option\collect([Option\none(), Option\some(2)]), Option\none());
self::assertEq(Option\collect([]), Option\some([]));