Merge branch 'develop'

* develop:
  specify next release
  add Sequence::takeWhile()
  add Sequence::dropWhile()
  make monads templates covariant
  add Sequence::toSet()
  add Set::memoize()
  add Sequence::memoize()
  add Either::memoize()
  add Maybe::memoize()

CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 4.13.0 - 2023-04-10
+
+### Added
+
+- `Innmind\Immutable\Maybe::memoize()`
+- `Innmind\Immutable\Either::memoize()`
+- `Innmind\Immutable\Sequence::memoize()`
+- `Innmind\Immutable\Set::memoize()`
+- `Innmind\Immutable\Sequence::toSet()`
+- `Innmind\Immutable\Sequence::dropWhile()`
+- `Innmind\Immutable\Sequence::takeWhile()`
+
+### Changed
+
+- Monads templates are now covariant
+
 ## 4.12.0 - 2023-03-30
 
 ### Added

docs/EITHER.md

@@ -173,3 +173,19 @@ Either::left('something')->maybe()->match(
     static fn() => null,
 ); // returns null
 ```
+
+## `->memoize()`
+
+This method force to load the contained value into memory. This is only useful for a deferred `Either`, this will do nothing for other either as the value is already known.
+
+```php
+Either::defer(function() {
+    return Either::right(\rand());
+})
+    ->map(static fn($i) => $i * 2) // value still not loaded here
+    ->memoize() // call the rand function and then apply the map and store it in memory
+    ->match(
+        static fn($i) => doStuff($i),
+        static fn() => null,
+    );
+```

docs/MAYBE.md

@@ -164,3 +164,19 @@ Maybe::nothing()
         static fn($left) => $left,
     ); // return 'something'
 ```
+
+## `->memoize()`
+
+This method force to load the contained value into memory. This is only useful for a deferred `Maybe`, this will do nothing for other maybe as the value is already known.
+
+```php
+Maybe::defer(function() {
+    return Maybe::just(\rand());
+})
+    ->map(static fn($i) => $i * 2) // value still not loaded here
+    ->memoize() // call the rand function and then apply the map and store it in memory
+    ->match(
+        static fn($i) => doStuff($i),
+        static fn() => null,
+    );
+```

docs/SEQUENCE.md

@@ -552,3 +552,40 @@ $lines; // ['foo', 'bar', 'baz', '']
 ```
 
 > **Note** The `flatMap` is here in case there is only one chunk in the sequence, in which case the `aggregate` is not called
+
+## `->memoize()`
+
+This method will load all the values in memory. This is useful only for a deferred or lazy `Sequence`, the other sequence will be unaffected.
+
+```php
+$sequence = Sequence::lazy(function() {
+    $stream = \fopen('some-file', 'r');
+    while (!\feof($stream)) {
+        yield \fgets($stream);
+    }
+})
+    ->map(static fn($line) => \strtoupper($line)) // still no line loaded here
+    ->memoize(); // load all lines and apply strtoupper on each
+```
+
+## `->dropWhile()`
+
+This removes all the elements from the start of the sequence while the condition returns `true`.
+
+```php
+$values = Sequence::of(0, 0, 0, 1, 2, 3, 0)
+    ->dropWhile(static fn($i) => $i === 0)
+    ->toList();
+$values === [1, 2, 3, 0];
+```
+
+## `->takeWhile()`
+
+This keeps all the elements from the start of the sequence while the condition returns `true`.
+
+```php
+$values = Sequence::of(1, 2, 3, 0, 4, 5, 6, 0)
+    ->takeWhile(static fn($i) => $i === 0)
+    ->toList();
+$values === [1, 2, 3];
+```

docs/SET.md

@@ -382,3 +382,18 @@ Set::lazy(function() {
 ```
 
 This example will print `a`, `b` and `c` before throwing an exception because of the second `a`. Use this method carefully.
+
+## `->memoize()`
+
+This method will load all the values in memory. This is useful only for a deferred or lazy `Set`, the other set will be unaffected.
+
+```php
+$set = Set::lazy(function() {
+    $stream = \fopen('some-file', 'r');
+    while (!\feof($stream)) {
+        yield \fgets($stream);
+    }
+})
+    ->map(static fn($line) => \strtoupper($line)) // still no line loaded here
+    ->memoize(); // load all lines and apply strtoupper on each
+```

src/Either.php

@@ -11,8 +11,8 @@
 };
 
 /**
- * @template L
- * @template R
+ * @template-covariant L
+ * @template-covariant R
  * @psalm-immutable
  */
 final class Either
@@ -155,4 +155,14 @@ public function maybe(): Maybe
     {
         return $this->either->maybe();
     }
+
+    /**
+     * Force loading the value in memory (only useful for a deferred Either)
+     *
+     * @return self<L, R>
+     */
+    public function memoize(): self
+    {
+        return $this->either->memoize();
+    }
 }

src/Either/Defer.php

@@ -65,6 +65,14 @@ public function maybe(): Maybe
         return Maybe::defer(fn() => $this->unwrap()->maybe());
     }
 
+    /**
+     * @return Either<L1, R1>
+     */
+    public function memoize(): Either
+    {
+        return $this->unwrap();
+    }
+
     /**
      * @return Either<L1, R1>
      */

src/Either/Implementation.php

@@ -78,4 +78,9 @@ public function filter(callable $predicate, callable $otherwise): self;
      * @return Maybe<R>
      */
     public function maybe(): Maybe;
+
+    /**
+     * @return Either<L, R>
+     */
+    public function memoize(): Either;
 }

src/Either/Left.php

@@ -73,4 +73,12 @@ public function maybe(): Maybe
     {
         return Maybe::nothing();
     }
+
+    /**
+     * @return Either<L1, R1>
+     */
+    public function memoize(): Either
+    {
+        return Either::left($this->value);
+    }
 }

src/Either/Right.php

@@ -79,4 +79,12 @@ public function maybe(): Maybe
     {
         return Maybe::just($this->value);
     }
+
+    /**
+     * @return Either<L1, R1>
+     */
+    public function memoize(): Either
+    {
+        return Either::right($this->value);
+    }
 }

src/Map.php

@@ -4,8 +4,8 @@
 namespace Innmind\Immutable;
 
 /**
- * @template T
- * @template S
+ * @template-covariant T
+ * @template-covariant S
  * @psalm-immutable
  */
 final class Map implements \Countable

src/Maybe.php

@@ -11,7 +11,7 @@
 };
 
 /**
- * @template T
+ * @template-covariant T
  * @psalm-immutable
  */
 final class Maybe
@@ -184,4 +184,14 @@ public function either(): Either
     {
         return $this->maybe->either();
     }
+
+    /**
+     * Force loading the value in memory (only useful for a deferred Maybe)
+     *
+     * @return self<T>
+     */
+    public function memoize(): self
+    {
+        return $this->maybe->memoize();
+    }
 }

src/Maybe/Defer.php

@@ -59,6 +59,14 @@ public function either(): Either
         return Either::defer(fn() => $this->unwrap()->either());
     }
 
+    /**
+     * @return Maybe<V>
+     */
+    public function memoize(): Maybe
+    {
+        return $this->unwrap();
+    }
+
     /**
      * @return Maybe<V>
      */

src/Maybe/Implementation.php

@@ -63,4 +63,9 @@ public function filter(callable $predicate): self;
      * @return Either<null, T>
      */
     public function either(): Either;
+
+    /**
+     * @return Maybe<T>
+     */
+    public function memoize(): Maybe;
 }

src/Maybe/Just.php

@@ -64,4 +64,12 @@ public function either(): Either
     {
         return Either::right($this->value);
     }
+
+    /**
+     * @return Maybe<V>
+     */
+    public function memoize(): Maybe
+    {
+        return Maybe::just($this->value);
+    }
 }

src/Maybe/Nothing.php

@@ -46,4 +46,13 @@ public function either(): Either
     {
         return Either::left(null);
     }
+
+    /**
+     * @return Maybe<empty>
+     */
+    public function memoize(): Maybe
+    {
+        /** @var Maybe<empty> */
+        return Maybe::nothing();
+    }
 }

src/Sequence.php

@@ -4,7 +4,7 @@
 namespace Innmind\Immutable;
 
 /**
- * @template T
+ * @template-covariant T
  * @psalm-immutable
  */
 final class Sequence implements \Countable
@@ -586,6 +586,14 @@ public function empty(): bool
         return $this->implementation->empty();
     }
 
+    /**
+     * @return Set<T>
+     */
+    public function toSet(): Set
+    {
+        return $this->implementation->toSet();
+    }
+
     /**
      * @return list<T>
      */
@@ -709,4 +717,34 @@ public function aggregate(callable $map): self
 
         return new self($this->implementation->aggregate($map, $exfiltrate));
     }
+
+    /**
+     * Force to load all values into memory (only useful for deferred and lazy Sequence)
+     *
+     * @return self<T>
+     */
+    public function memoize(): self
+    {
+        return new self($this->implementation->memoize());
+    }
+
+    /**
+     * @param callable(T): bool $condition
+     *
+     * @return self<T>
+     */
+    public function dropWhile(callable $condition): self
+    {
+        return new self($this->implementation->dropWhile($condition));
+    }
+
+    /**
+     * @param callable(T): bool $condition
+     *
+     * @return self<T>
+     */
+    public function takeWhile(callable $condition): self
+    {
+        return new self($this->implementation->takeWhile($condition));
+    }
 }