Merge branch 'develop'

* develop:
  specify next release
  add keep() method
  suppress psalm error
  add ->exclude() methods
  be more explicit with the integers
  force type declaration
  remove unnecessary annotations
  discard impure function calls
  update psalm

Author: Baptouuuu

CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 4.6.0 - 2022-10-08
+
+## Added
+
+- `Innmind\Immutable\Map::exclude()`
+- `Innmind\Immutable\Maybe::exclude()`
+- `Innmind\Immutable\Maybe::keep()`
+- `Innmind\Immutable\Sequence::exclude()`
+- `Innmind\Immutable\Sequence::keep()`
+- `Innmind\Immutable\Set::exclude()`
+- `Innmind\Immutable\Set::keep()`
+- `Innmind\Immutable\Predicate`
+- `Innmind\Immutable\Predicate\Instance`
+
 ## 4.5.0 - 2022-09-18
 
 ### Added

composer.json

@@ -31,7 +31,7 @@
     },
     "require-dev": {
         "phpunit/phpunit": "~9.0",
-        "vimeo/psalm": "~4.1 <4.16",
+        "vimeo/psalm": "~4.28",
         "innmind/black-box": "^4.4",
         "innmind/coding-standard": "~2.0"
     },

docs/MAP.md

@@ -98,6 +98,16 @@ $map = $map->filter(fn($key, $value) => ($key + $value) % 2 === 0);
 $map->equals(Map::of([1, 1]));
 ```
 
+## `->exclude()`
+
+Removes the pairs from the map that match the given predicate.
+
+```php
+$map = Map::of([1, 1], [3, 2]);
+$map = $map->exclude(fn($key, $value) => ($key + $value) % 2 === 0);
+$map->equals(Map::of([3, 2]));
+```
+
 ## `->foreach()`
 
 Use this method to call a function for each pair of the map. Since this structure is immutable it returns a `SideEffect` object, as its name suggest it is the only place acceptable to create side effects.

docs/MAYBE.md

@@ -123,6 +123,14 @@ $validDsn = $dsn->filter(fn(string $url): bool => \filter_var($url, \FILTER_VALI
 
 `$validDsn` will contain either a valid url or nothing.
 
+## `->keep()`
+
+This is similar to `->filter()` with the advantage of psalm understanding the type in the new `Maybe`.
+
+## `->exclude()`
+
+This is the inverse of the `->filter()` method.
+
 ## `->either()`
 
 This returns an [`Either`](EITHER.md) containing the value on the right side and `null` on the left side.

docs/SEQUENCE.md

@@ -158,6 +158,26 @@ $sequence = Sequence::ints(1, 2, 3, 4)->filter(fn($i) => $i % 2 === 0);
 $sequence->equals(Sequence::ints(2, 4));
 ```
 
+## `->keep()`
+
+This is similar to `->filter()` with the advantage of psalm understanding the type in the new `Sequence`.
+
+```php
+use Innmind\Immutable\Predicate\Instance;
+
+$sequence = Sequence::of(null, new \stdClass, 'foo')->keep(Instance::of('stdClass'));
+$sequence; // Sequence<stdClass>
+```
+
+## `->exclude()`
+
+Removes elements from the sequence that match the given predicate.
+
+```php
+$sequence = Sequence::ints(1, 2, 3, 4)->filter(fn($i) => $i % 2 === 0);
+$sequence->equals(Sequence::ints(1, 3));
+```
+
 ## `->foreach()`
 
 Use this method to call a function for each element of the sequence. Since this structure is immutable it returns a `SideEffect` object, as its name suggest it is the only place acceptable to create side effects.

docs/SET.md

@@ -148,6 +148,26 @@ $set = Set::ints(1, 2, 3, 4)->filter(fn($i) => $i % 2 === 0);
 $set->equals(Set::ints(2, 4));
 ```
 
+## `->keep()`
+
+This is similar to `->filter()` with the advantage of psalm understanding the type in the new `Set`.
+
+```php
+use Innmind\Immutable\Predicate\Instance;
+
+$set = Set::of(null, new \stdClass, 'foo')->keep(Instance::of('stdClass'));
+$set; // Set<stdClass>
+```
+
+## `->exclude()`
+
+Removes elements from the set that match the given predicate.
+
+```php
+$set = Set::ints(1, 2, 3, 4)->filter(fn($i) => $i % 2 === 0);
+$set->equals(Set::ints(1, 3));
+```
+
 ## `->foreach()`
 
 Use this method to call a function for each element of the set. Since this structure is immutable it returns a `SideEffect` object, as its name suggest it is the only place acceptable to create side effects.

psalm.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0"?>
 <psalm
-    totallyTyped="true"
+    errorLevel="1"
     resolveFromConfigFile="true"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xmlns="https://getpsalm.org/schema/config"
@@ -12,8 +12,4 @@
             <directory name="vendor" />
         </ignoreFiles>
     </projectFiles>
-
-    <issueHandlers>
-        <LessSpecificReturnType errorLevel="info" />
-    </issueHandlers>
 </psalm>

src/Either/Left.php

@@ -48,16 +48,19 @@ public function flatMap(callable $map): Either
 
     public function leftMap(callable $map): self
     {
+        /** @psalm-suppress ImpureFunctionCall */
         return new self($map($this->value));
     }
 
     public function match(callable $right, callable $left)
     {
+        /** @psalm-suppress ImpureFunctionCall */
         return $left($this->value);
     }
 
     public function otherwise(callable $otherwise): Either
     {
+        /** @psalm-suppress ImpureFunctionCall */
         return $otherwise($this->value);
     }
 

src/Either/Right.php

@@ -30,11 +30,13 @@ public function __construct($value)
 
     public function map(callable $map): self
     {
+        /** @psalm-suppress ImpureFunctionCall */
         return new self($map($this->value));
     }
 
     public function flatMap(callable $map): Either
     {
+        /** @psalm-suppress ImpureFunctionCall */
         return $map($this->value);
     }
 
@@ -53,6 +55,7 @@ public function leftMap(callable $map): self
 
     public function match(callable $right, callable $left)
     {
+        /** @psalm-suppress ImpureFunctionCall */
         return $right($this->value);
     }
 
@@ -63,10 +66,12 @@ public function otherwise(callable $otherwise): Either
 
     public function filter(callable $predicate, callable $otherwise): Implementation
     {
+        /** @psalm-suppress ImpureFunctionCall */
         if ($predicate($this->value) === true) {
             return $this;
         }
 
+        /** @psalm-suppress ImpureFunctionCall */
         return new Left($otherwise());
     }
 

src/Map.php

@@ -57,11 +57,17 @@ public static function of(array ...$pairs): self
         return $self;
     }
 
+    /**
+     * @return 0|positive-int
+     */
     public function size(): int
     {
         return $this->implementation->size();
     }
 
+    /**
+     * @return 0|positive-int
+     */
     public function count(): int
     {
         return $this->size();
@@ -134,6 +140,19 @@ public function filter(callable $predicate): self
         return new self($this->implementation->filter($predicate));
     }
 
+    /**
+     * Exclude elements that match the predicate
+     *
+     * @param callable(T, S): bool $predicate
+     *
+     * @return self<T, S>
+     */
+    public function exclude(callable $predicate): self
+    {
+        /** @psalm-suppress MixedArgument */
+        return $this->filter(static fn($key, $value) => !$predicate($key, $value));
+    }
+
     /**
      * Run the given function for each element of the map
      *

src/Map/DoubleIndex.php

@@ -150,6 +150,7 @@ public function filter(callable $predicate): self
     public function foreach(callable $function): SideEffect
     {
         foreach ($this->pairs->iterator() as $pair) {
+            /** @psalm-suppress ImpureFunctionCall */
             $function($pair->key(), $pair->value());
         }
 
@@ -169,6 +170,7 @@ public function groupBy(callable $discriminator): Map
         $groups = Map::of();
 
         foreach ($this->pairs->iterator() as $pair) {
+            /** @psalm-suppress ImpureFunctionCall */
             $key = $discriminator($pair->key(), $pair->value());
 
             $group = $groups->get($key)->match(
@@ -259,6 +261,7 @@ public function partition(callable $predicate): Map
             $key = $pair->key();
             $value = $pair->value();
 
+            /** @psalm-suppress ImpureFunctionCall */
             $return = $predicate($key, $value);
 
             if ($return === true) {
@@ -281,6 +284,7 @@ public function partition(callable $predicate): Map
     public function reduce($carry, callable $reducer)
     {
         foreach ($this->pairs->iterator() as $pair) {
+            /** @psalm-suppress ImpureFunctionCall */
             $carry = $reducer($carry, $pair->key(), $pair->value());
         }
 

src/Map/Implementation.php

@@ -31,6 +31,9 @@ interface Implementation extends \Countable
      */
     public function __invoke($key, $value): self;
 
+    /**
+     * @return 0|positive-int
+     */
     public function size(): int;
 
     /**

src/Map/ObjectKeys.php

@@ -73,7 +73,10 @@ public static function of($key, $value): Maybe
 
     public function size(): int
     {
-        /** @psalm-suppress ImpureMethodCall */
+        /**
+         * @psalm-suppress ImpureMethodCall
+         * @var 0|positive-int
+         */
         return $this->values->count();
     }
 
@@ -174,6 +177,7 @@ public function filter(callable $predicate): self
             /** @var S $v */
             $v = $this->values[$k];
 
+            /** @psalm-suppress ImpureFunctionCall */
             if ($predicate($key, $v) === true) {
                 $values[$k] = $v;
             }
@@ -197,6 +201,7 @@ public function foreach(callable $function): SideEffect
              */
             $v = $this->values[$k];
 
+            /** @psalm-suppress ImpureFunctionCall */
             $function($key, $v);
         }
 
@@ -225,6 +230,7 @@ public function groupBy(callable $discriminator): Map
              */
             $v = $this->values[$k];
 
+            /** @psalm-suppress ImpureFunctionCall */
             $discriminant = $discriminator($key, $v);
 
             $group = $groups->get($discriminant)->match(
@@ -282,7 +288,7 @@ public function map(callable $function): self
              */
             $v = $this->values[$k];
 
-            /** @psalm-suppress ImpureMethodCall */
+            /** @psalm-suppress ImpureFunctionCall */
             $values[$k] = $function($key, $v);
         }
 
@@ -346,6 +352,7 @@ public function partition(callable $predicate): Map
              */
             $v = $this->values[$k];
 
+            /** @psalm-suppress ImpureFunctionCall */
             $return = $predicate($key, $v);
 
             if ($return === true) {
@@ -377,6 +384,7 @@ public function reduce($carry, callable $reducer)
              */
             $v = $this->values[$k];
 
+            /** @psalm-suppress ImpureFunctionCall */
             $carry = $reducer($carry, $key, $v);
         }
 
@@ -404,6 +412,7 @@ public function find(callable $predicate): Maybe
              */
             $v = $this->values[$k];
 
+            /** @psalm-suppress ImpureFunctionCall */
             if ($predicate($key, $v)) {
                 return Maybe::just(new Pair($key, $v));
             }

src/Map/Primitive.php

@@ -160,6 +160,7 @@ public function filter(callable $predicate): self
         $values = [];
 
         foreach ($this->values as $k => $v) {
+            /** @psalm-suppress ImpureFunctionCall */
             if ($predicate($k, $v) === true) {
                 $values[$k] = $v;
             }
@@ -174,6 +175,7 @@ public function filter(callable $predicate): self
     public function foreach(callable $function): SideEffect
     {
         foreach ($this->values as $k => $v) {
+            /** @psalm-suppress ImpureFunctionCall */
             $function($k, $v);
         }
 
@@ -193,6 +195,7 @@ public function groupBy(callable $discriminator): Map
         $groups = Map::of();
 
         foreach ($this->values as $key => $value) {
+            /** @psalm-suppress ImpureFunctionCall */
             $discriminant = $discriminator($key, $value);
 
             $group = $groups->get($discriminant)->match(
@@ -241,6 +244,7 @@ public function map(callable $function): self
         $values = [];
 
         foreach ($this->values as $k => $v) {
+            /** @psalm-suppress ImpureFunctionCall */
             $values[$k] = $function($k, $v);
         }
 
@@ -289,6 +293,7 @@ public function partition(callable $predicate): Map
         $falsy = $this->clearMap();
 
         foreach ($this->values as $k => $v) {
+            /** @psalm-suppress ImpureFunctionCall */
             $return = $predicate($k, $v);
 
             if ($return === true) {
@@ -311,6 +316,7 @@ public function partition(callable $predicate): Map
     public function reduce($carry, callable $reducer)
     {
         foreach ($this->values as $k => $v) {
+            /** @psalm-suppress ImpureFunctionCall */
             $carry = $reducer($carry, $k, $v);
         }
 
@@ -329,6 +335,7 @@ public function empty(): bool
     public function find(callable $predicate): Maybe
     {
         foreach ($this->values as $k => $v) {
+            /** @psalm-suppress ImpureFunctionCall */
             if ($predicate($k, $v)) {
                 return Maybe::just(new Pair($k, $v));
             }