"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "public_html/lists/base/vendor/phpoption/phpoption/src/PhpOption/Option.php" between
phplist-3.4.9.tgz and phplist-3.5.0.tgz

About: phpList is a one-way email announcement delivery system for newsletters, publicity lists, notifications, and many other uses (requires PHP and MySQL).

Option.php  (phplist-3.4.9.tgz):Option.php  (phplist-3.5.0.tgz)
skipping to change at line 25 skipping to change at line 25
* See the License for the specific language governing permissions and * See the License for the specific language governing permissions and
* limitations under the License. * limitations under the License.
*/ */
namespace PhpOption; namespace PhpOption;
use ArrayAccess; use ArrayAccess;
use IteratorAggregate; use IteratorAggregate;
/** /**
* Base Option Class. * @template T
* *
* @author Johannes M. Schmitt <schmittjoh@gmail.com> * @implements IteratorAggregate<T>
*/ */
abstract class Option implements IteratorAggregate abstract class Option implements IteratorAggregate
{ {
/** /**
* Creates an option given a return value. * Creates an option given a return value.
* *
* This is intended for consuming existing APIs and allows you to easily * This is intended for consuming existing APIs and allows you to easily
* convert them to an option. By default, we treat ``null`` as the None * convert them to an option. By default, we treat ``null`` as the None
* case, and everything else as Some. * case, and everything else as Some.
* *
* @param mixed $value The actual return value. * @template S
* @param mixed $noneValue The value which should be considered "None";
* null by default.
* *
* @return Option * @param S $value The actual return value.
* @param S $noneValue The value which should be considered "None"; null by
* default.
*
* @return Option<S>
*/ */
public static function fromValue($value, $noneValue = null) public static function fromValue($value, $noneValue = null)
{ {
if ($value === $noneValue) { if ($value === $noneValue) {
return None::create(); return None::create();
} }
return new Some($value); return new Some($value);
} }
/** /**
* Creates an option from an array's value. * Creates an option from an array's value.
* *
* If the key does not exist in the array, the array is not actually an * If the key does not exist in the array, the array is not actually an
* array, or the array's value at the given key is null, None is returned. * array, or the array's value at the given key is null, None is returned.
* Otherwise, Some is returned wrapping the value at the given key. * Otherwise, Some is returned wrapping the value at the given key.
* *
* @param mixed $array A potential array or \ArrayAccess value. * @template S
* @param string $key The key to check. *
* @param array<string,S>|ArrayAccess<string,S>|null $array A potential arra
y or \ArrayAccess value.
* @param string $key The key to check
.
* *
* @return Option * @return Option<S>
*/ */
public static function fromArraysValue($array, $key) public static function fromArraysValue($array, $key)
{ {
if (!(is_array($array) || $array instanceof ArrayAccess) || !isset($arra y[$key])) { if (!(is_array($array) || $array instanceof ArrayAccess) || !isset($arra y[$key])) {
return None::create(); return None::create();
} }
return new Some($array[$key]); return new Some($array[$key]);
} }
/** /**
* Creates a lazy-option with the given callback. * Creates a lazy-option with the given callback.
* *
* This is also a helper constructor for lazy-consuming existing APIs where * This is also a helper constructor for lazy-consuming existing APIs where
* the return value is not yet an option. By default, we treat ``null`` as * the return value is not yet an option. By default, we treat ``null`` as
* None case, and everything else as Some. * None case, and everything else as Some.
* *
* @template S
*
* @param callable $callback The callback to evaluate. * @param callable $callback The callback to evaluate.
* @param array $arguments The arguments for the callback. * @param array $arguments The arguments for the callback.
* @param mixed $noneValue The value which should be considered "None"; n * @param S $noneValue The value which should be considered "None";
ull * null by default.
* by default.
* *
* @return Option * @return LazyOption<S>
*/ */
public static function fromReturn($callback, array $arguments = [], $noneVal ue = null) public static function fromReturn($callback, array $arguments = [], $noneVal ue = null)
{ {
return new LazyOption(function () use ($callback, $arguments, $noneValue ) { return new LazyOption(function () use ($callback, $arguments, $noneValue ) {
/** @var mixed */
$return = call_user_func_array($callback, $arguments); $return = call_user_func_array($callback, $arguments);
if ($return === $noneValue) { if ($return === $noneValue) {
return None::create(); return None::create();
} }
return new Some($return); return new Some($return);
}); });
} }
/** /**
* Option factory, which creates new option based on passed value. * Option factory, which creates new option based on passed value.
* *
* If value is already an option, it simply returns. If value is callable, * If value is already an option, it simply returns. If value is callable,
* LazyOption with passed callback created and returned. If Option * LazyOption with passed callback created and returned. If Option
* returned from callback, it returns directly. On other case value passed * returned from callback, it returns directly. On other case value passed
* to Option::fromValue() method. * to Option::fromValue() method.
* *
* @param Option|callable|mixed $value * @template S
* @param mixed $noneValue Used when $value is mixed or
* callable, for None-check.
* *
* @return Option * @param Option<S>|callable|S $value
* @param S $noneValue Used when $value is mixed or
* callable, for None-check.
*
* @return Option<S>|LazyOption<S>
*/ */
public static function ensure($value, $noneValue = null) public static function ensure($value, $noneValue = null)
{ {
if ($value instanceof self) { if ($value instanceof self) {
return $value; return $value;
} elseif (is_callable($value)) { } elseif (is_callable($value)) {
return new LazyOption(function () use ($value, $noneValue) { return new LazyOption(function () use ($value, $noneValue) {
/** @var mixed */
$return = $value(); $return = $value();
if ($return instanceof self) { if ($return instanceof self) {
return $return; return $return;
} else { } else {
return self::fromValue($return, $noneValue); return self::fromValue($return, $noneValue);
} }
}); });
} else { } else {
return self::fromValue($value, $noneValue); return self::fromValue($value, $noneValue);
skipping to change at line 143 skipping to change at line 153
/** /**
* Lift a function so that it accepts Option as parameters. * Lift a function so that it accepts Option as parameters.
* *
* We return a new closure that wraps the original callback. If any of the * We return a new closure that wraps the original callback. If any of the
* parameters passed to the lifted function is empty, the function will * parameters passed to the lifted function is empty, the function will
* return a value of None. Otherwise, we will pass all parameters to the * return a value of None. Otherwise, we will pass all parameters to the
* original callback and return the value inside a new Option, unless an * original callback and return the value inside a new Option, unless an
* Option is returned from the function, in which case, we use that. * Option is returned from the function, in which case, we use that.
* *
* @template S
*
* @param callable $callback * @param callable $callback
* @param mixed $noneValue * @param mixed $noneValue
* *
* @return callable * @return callable
*/ */
public static function lift($callback, $noneValue = null) public static function lift($callback, $noneValue = null)
{ {
return function () use ($callback, $noneValue) { return function () use ($callback, $noneValue) {
/** @var array<int, mixed> */
$args = func_get_args(); $args = func_get_args();
$reduced_args = array_reduce(
$args,
/** @param bool $status */
function ($status, self $o) {
return $o->isEmpty() ? true : $status;
},
false
);
// if at least one parameter is empty, return None // if at least one parameter is empty, return None
if (array_reduce($args, function ($status, self $o) { if ($reduced_args) {
return $o->isEmpty() ? true : $status;
}, false)) {
return None::create(); return None::create();
} }
$args = array_map(function (self $o) { $args = array_map(
// it is safe to do so because the fold above checked /** @return T */
// that all arguments are of type Some function (self $o) {
return $o->get(); // it is safe to do so because the fold above checked
}, $args); // that all arguments are of type Some
/** @var T */
return $o->get();
},
$args
);
return self::ensure(call_user_func_array($callback, $args), $noneVal ue); return self::ensure(call_user_func_array($callback, $args), $noneVal ue);
}; };
} }
/** /**
* Returns the value if available, or throws an exception otherwise. * Returns the value if available, or throws an exception otherwise.
* *
* @throws \RuntimeException If value is not available. * @throws \RuntimeException If value is not available.
* *
* @return mixed * @return T
*/ */
abstract public function get(); abstract public function get();
/** /**
* Returns the value if available, or the default value if not. * Returns the value if available, or the default value if not.
* *
* @param mixed $default * @template S
*
* @param S $default
* *
* @return mixed * @return T|S
*/ */
abstract public function getOrElse($default); abstract public function getOrElse($default);
/** /**
* Returns the value if available, or the results of the callable. * Returns the value if available, or the results of the callable.
* *
* This is preferable over ``getOrElse`` if the computation of the default * This is preferable over ``getOrElse`` if the computation of the default
* value is expensive. * value is expensive.
* *
* @param callable $callable * @template S
* *
* @return mixed * @param callable():S $callable
*
* @return T|S
*/ */
abstract public function getOrCall($callable); abstract public function getOrCall($callable);
/** /**
* Returns the value if available, or throws the passed exception. * Returns the value if available, or throws the passed exception.
* *
* @param \Exception $ex * @param \Exception $ex
* *
* @return mixed * @return T
*/ */
abstract public function getOrThrow(\Exception $ex); abstract public function getOrThrow(\Exception $ex);
/** /**
* Returns true if no value is available, false otherwise. * Returns true if no value is available, false otherwise.
* *
* @return bool * @return bool
*/ */
abstract public function isEmpty(); abstract public function isEmpty();
skipping to change at line 235 skipping to change at line 263
* *
* This can be used to try multiple alternatives, and is especially useful * This can be used to try multiple alternatives, and is especially useful
* with lazy evaluating options: * with lazy evaluating options:
* *
* ```php * ```php
* $repo->findSomething() * $repo->findSomething()
* ->orElse(new LazyOption(array($repo, 'findSomethingElse'))) * ->orElse(new LazyOption(array($repo, 'findSomethingElse')))
* ->orElse(new LazyOption(array($repo, 'createSomething'))); * ->orElse(new LazyOption(array($repo, 'createSomething')));
* ``` * ```
* *
* @param Option $else * @param Option<T> $else
* *
* @return Option * @return Option<T>
*/ */
abstract public function orElse(self $else); abstract public function orElse(self $else);
/** /**
* This is similar to map() below except that the return value has no meanin g; * This is similar to map() below except that the return value has no meanin g;
* the passed callable is simply executed if the option is non-empty, and * the passed callable is simply executed if the option is non-empty, and
* ignored if the option is empty. * ignored if the option is empty.
* *
* In all cases, the return value of the callable is discarded. * In all cases, the return value of the callable is discarded.
* *
skipping to change at line 259 skipping to change at line 287
* $comment->getMaybeFile()->ifDefined(function($file) { * $comment->getMaybeFile()->ifDefined(function($file) {
* // Do something with $file here. * // Do something with $file here.
* }); * });
* ``` * ```
* *
* If you're looking for something like ``ifEmpty``, you can use ``getOrCall `` * If you're looking for something like ``ifEmpty``, you can use ``getOrCall ``
* and ``getOrElse`` in these cases. * and ``getOrElse`` in these cases.
* *
* @deprecated Use forAll() instead. * @deprecated Use forAll() instead.
* *
* @param callable $callable * @param callable(T):mixed $callable
* *
* @return void * @return void
*/ */
abstract public function ifDefined($callable); abstract public function ifDefined($callable);
/** /**
* This is similar to map() except that the return value of the callable has no meaning. * This is similar to map() except that the return value of the callable has no meaning.
* *
* The passed callable is simply executed if the option is non-empty, and ig nored if the * The passed callable is simply executed if the option is non-empty, and ig nored if the
* option is empty. This method is preferred for callables with side-effects , while map() * option is empty. This method is preferred for callables with side-effects , while map()
* is intended for callables without side-effects. * is intended for callables without side-effects.
* *
* @param callable $callable * @param callable(T):mixed $callable
* *
* @return Option * @return Option<T>
*/ */
abstract public function forAll($callable); abstract public function forAll($callable);
/** /**
* Applies the callable to the value of the option if it is non-empty, * Applies the callable to the value of the option if it is non-empty,
* and returns the return value of the callable wrapped in Some(). * and returns the return value of the callable wrapped in Some().
* *
* If the option is empty, then the callable is not applied. * If the option is empty, then the callable is not applied.
* *
* ```php * ```php
* (new Some("foo"))->map('strtoupper')->get(); // "FOO" * (new Some("foo"))->map('strtoupper')->get(); // "FOO"
* ``` * ```
* *
* @param callable $callable * @template S
*
* @param callable(T):S $callable
* *
* @return Option * @return Option<S>
*/ */
abstract public function map($callable); abstract public function map($callable);
/** /**
* Applies the callable to the value of the option if it is non-empty, and * Applies the callable to the value of the option if it is non-empty, and
* returns the return value of the callable directly. * returns the return value of the callable directly.
* *
* In contrast to ``map``, the return value of the callable is expected to * In contrast to ``map``, the return value of the callable is expected to
* be an Option itself; it is not automatically wrapped in Some(). * be an Option itself; it is not automatically wrapped in Some().
* *
* @param callable $callable must return an Option * @template S
*
* @param callable(T):Option<S> $callable must return an Option
* *
* @return Option * @return Option<S>
*/ */
abstract public function flatMap($callable); abstract public function flatMap($callable);
/** /**
* If the option is empty, it is returned immediately without applying the c allable. * If the option is empty, it is returned immediately without applying the c allable.
* *
* If the option is non-empty, the callable is applied, and if it returns tr ue, * If the option is non-empty, the callable is applied, and if it returns tr ue,
* the option itself is returned; otherwise, None is returned. * the option itself is returned; otherwise, None is returned.
* *
* @param callable $callable * @param callable(T):bool $callable
* *
* @return Option * @return Option<T>
*/ */
abstract public function filter($callable); abstract public function filter($callable);
/** /**
* If the option is empty, it is returned immediately without applying the c allable. * If the option is empty, it is returned immediately without applying the c allable.
* *
* If the option is non-empty, the callable is applied, and if it returns fa lse, * If the option is non-empty, the callable is applied, and if it returns fa lse,
* the option itself is returned; otherwise, None is returned. * the option itself is returned; otherwise, None is returned.
* *
* @param callable $callable * @param callable(T):bool $callable
* *
* @return Option * @return Option<T>
*/ */
abstract public function filterNot($callable); abstract public function filterNot($callable);
/** /**
* If the option is empty, it is returned immediately. * If the option is empty, it is returned immediately.
* *
* If the option is non-empty, and its value does not equal the passed value * If the option is non-empty, and its value does not equal the passed value
* (via a shallow comparison ===), then None is returned. Otherwise, the * (via a shallow comparison ===), then None is returned. Otherwise, the
* Option is returned. * Option is returned.
* *
* In other words, this will filter all but the passed value. * In other words, this will filter all but the passed value.
* *
* @param mixed $value * @param T $value
* *
* @return Option * @return Option<T>
*/ */
abstract public function select($value); abstract public function select($value);
/** /**
* If the option is empty, it is returned immediately. * If the option is empty, it is returned immediately.
* *
* If the option is non-empty, and its value does equal the passed value (vi a * If the option is non-empty, and its value does equal the passed value (vi a
* a shallow comparison ===), then None is returned; otherwise, the Option i s * a shallow comparison ===), then None is returned; otherwise, the Option i s
* returned. * returned.
* *
* In other words, this will let all values through except the passed value. * In other words, this will let all values through except the passed value.
* *
* @param mixed $value * @param T $value
* *
* @return Option * @return Option<T>
*/ */
abstract public function reject($value); abstract public function reject($value);
/** /**
* Binary operator for the initial value and the option's value. * Binary operator for the initial value and the option's value.
* *
* If empty, the initial value is returned. If non-empty, the callable * If empty, the initial value is returned. If non-empty, the callable
* receives the initial value and the option's value as arguments. * receives the initial value and the option's value as arguments.
* *
* ```php * ```php
skipping to change at line 382 skipping to change at line 414
* $result = $none->foldLeft(1, function($a, $b) { return $a + $b; }); / / int(1) * $result = $none->foldLeft(1, function($a, $b) { return $a + $b; }); / / int(1)
* *
* // This can be used instead of something like the following: * // This can be used instead of something like the following:
* $option = Option::fromValue($integerOrNull); * $option = Option::fromValue($integerOrNull);
* $result = 1; * $result = 1;
* if ( ! $option->isEmpty()) { * if ( ! $option->isEmpty()) {
* $result += $option->get(); * $result += $option->get();
* } * }
* ``` * ```
* *
* @param mixed $initialValue * @template S
* @param callable $callable function(initialValue, callable): result
* *
* @return mixed * @param S $initialValue
* @param callable(S, T):S $callable
*
* @return S
*/ */
abstract public function foldLeft($initialValue, $callable); abstract public function foldLeft($initialValue, $callable);
/** /**
* foldLeft() but with reversed arguments for the callable. * foldLeft() but with reversed arguments for the callable.
* *
* @param mixed $initialValue * @template S
* @param callable $callable function(callable, initialValue): result *
* @param S $initialValue
* @param callable(T, S):S $callable
* *
* @return mixed * @return S
*/ */
abstract public function foldRight($initialValue, $callable); abstract public function foldRight($initialValue, $callable);
} }
 End of changes. 45 change blocks. 
54 lines changed or deleted 91 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)