Add `Equals` Operation #152

AlexandruGG · 2021-07-17T22:37:47Z

This PR:

Provides a new operation Equals which allows determining if two collections contain the same elements
Includes a small refactor for IsEmpty -> now returns a Generator so it can be piped. This is backwards-compatible at Collection level but a BC break at individual Operation level
Has unit tests (phpspec)
Has static analysis tests (psalm, phpstan)
Has documentation
Bonus: static analysis check for diff

drupol · 2021-07-18T09:54:11Z

src/Operation/Equals.php

+                );
+
+                // Point free style.
+                return $pipe;


I know this is a work in progress, but here's my thoughts just by reading it quickly:

Be careful! It's a trap !

Using Diff means that you're going to go through the whole iterator before deciding the outcome.

But yet what you're trying to do is to compare if they are equal, in other words, find if all the elements are equal, in other words: find if there is at least two elements that are different.

It means that as soon as two elements are different, there is no need to go through the whole iterator, we know that they are different.

It's then a job for the MatchOne or Every operations (My favorite operations btw!)

Example:

<?php /** * For the full copyright and license information, please view * the LICENSE file that was distributed with this source code. */ declare(strict_types=1); namespace loophp\collection\Operation; use Closure; use Generator; use Iterator; use MultipleIterator; /** * @immutable * * @template TKey * @template T */ final class Equals extends AbstractOperation { /** * @pure * * @return Closure(Iterator<TKey, T>): Closure(Iterator<TKey, T>): Generator<int, bool> */ public function __invoke(): Closure { return /** * @param Iterator<TKey, T> $other * * @return Closure(Iterator<TKey, T>): Generator<int, bool> */ static function (Iterator $left): Closure { return static function (Iterator $right) use ($left): Generator { $mit = new MultipleIterator(MultipleIterator::MIT_NEED_ANY); $mit->attachIterator($left); $mit->attachIterator($right); return yield Every::of() (static fn (): bool => true) (static fn (array $current): bool => $current[0] !== $current[1]); // Should we allow comparison customization with a callback? ($mit)->current(); }; }; } }

Or if you want to optimize things:

<?php /** * For the full copyright and license information, please view * the LICENSE file that was distributed with this source code. */ declare(strict_types=1); namespace loophp\collection\Operation; use Closure; use Generator; use Iterator; use MultipleIterator; /** * @immutable * * @template TKey * @template T */ final class Equals extends AbstractOperation { /** * @pure * * @return Closure(Iterator<TKey, T>): Closure(Iterator<TKey, T>): Generator<int, bool> */ public function __invoke(): Closure { return /** * @param Iterator<TKey, T> $other * * @return Closure(Iterator<TKey, T>): Generator<int, bool> */ static function (Iterator $left): Closure { return Pipe::of()( static function (Iterator $iterator) use ($left): Iterator { $mit = new MultipleIterator(MultipleIterator::MIT_NEED_ANY); $mit->attachIterator($left); $mit->attachIterator($iterator); return $mit; }, Every::of() (static fn (): bool => true) (static fn (array $current): bool => $current[0] !== $current[1]), Current::of()(0) ); }; } }

Hey @drupol, thanks for this; does this work if the elements are in different positions in the collections?

As in:

Collection (1, 2, 3)
Collection (2, 3, 1)

These should still be considered equal.

Or are you thinking we should consider them unequal?

I feel like there's scope to have 2 operations maybe: equals and same

Hey @drupol, thanks for this; does this work if the elements are in different positions in the collections?

As in:

Collection (1, 2, 3)
Collection (2, 3, 1)

No it doesn't do that sadly.

I feel like there's scope to have 2 operations maybe: equals and same

Exact, we should have 2 different operations for that.

Cool, in that case:

equals would need to check the entire collection, so this implementation should be fine

same should stop as soon as an element is different or the end of one collection is reached, because we want them in the same positions

Regarding allowing the user to customise the comparison behaviour:
I want at least one of the operations (I'm thinking equals) to only accept a single parameter, otherwise it won't work with PHPUnit's assertObjectEquals method: https://github.com/sebastianbergmann/phpunit/blob/master/src/Framework/Constraint/Object/ObjectEquals.php#L97-L102

Perhaps for same we can allow that with the signature:
Collection::same(Collection $other, ?callable $comparator = null): bool.

WDYT?

It seems ok to me, I guess we will refine all of these during the review.

src/Operation/Equals.php

drupol · 2021-07-18T20:47:20Z

Let's not forget to mention in the documentation that there is a "cost" with this operation.

AlexandruGG · 2021-07-18T20:52:42Z

Let's not forget to mention in the documentation that there is a "cost" with this operation.

Thanks! Didn't forget it, I was just debating whether to add it now or when we add the same operation so I can recommend using that one for better performance. I added a warning now anyway and we can modify it at that time

drupol · 2021-07-18T20:54:35Z

By the way, I'm thinking about this optimization:

diff --git a/src/Operation/Equals.php b/src/Operation/Equals.php
index d0bae356..6f091110 100644
--- a/src/Operation/Equals.php
+++ b/src/Operation/Equals.php
@@ -50,7 +50,13 @@ final class Equals extends AbstractOperation
                         return yield false;
                     }
 
-                    return yield from Pipe::of()(Diff::of()(...$other), IsEmpty::of())($iterator);
+                    foreach ($iterator as $current) {
+                        if (false === Contains::of()($current)($other)->current()) {
+                            return yield false;
+                        }
+                    }
+
+                    return yield true;
                 };
             };
     }

I think this would be better. Indeed, the Diff operation will traverse the whole collection to compute a diff. A diff can contain 1, 2, 3... n values that are different. In our case, we only need to check if there's only one which is different, then return false.

WDYT ?

drupol · 2021-07-18T20:55:11Z

docs/pages/api.rst

@@ -721,6 +721,10 @@ Elements will be compared using strict equality (``===``).
 .. tip:: This operation enables comparing ``Collection`` objects in PHPUnit tests using
    the dedicated `assertObjectEquals`_ assertion. 

+.. warning:: Because this operation *needs to traverse both collections* to determine if
+    the same elements are contained within them, a performance cost is incurred. It is not
+    recommended to use this for potentially large collections.


drupol · 2021-07-18T21:04:07Z

We can even use Every for that! Which is basically the same !

diff --git a/src/Operation/Equals.php b/src/Operation/Equals.php
index d0bae356..52304548 100644
--- a/src/Operation/Equals.php
+++ b/src/Operation/Equals.php
@@ -50,7 +50,12 @@ final class Equals extends AbstractOperation
                         return yield false;
                     }
 
-                    return yield from Pipe::of()(Diff::of()(...$other), IsEmpty::of())($iterator);
+                    return yield from Pipe::of()(
+                        Every::of()
+                            (static fn(): bool => false)
+                            (static fn($current): bool => Contains::of()($current)($other)->current()),
+                        Head::of()
+                    )($iterator);
                 };
             };
     }

AlexandruGG · 2021-07-18T21:10:15Z

By the way, I'm thinking about this optimization:

diff --git a/src/Operation/Equals.php b/src/Operation/Equals.php
index d0bae356..6f091110 100644
--- a/src/Operation/Equals.php
+++ b/src/Operation/Equals.php
@@ -50,7 +50,13 @@ final class Equals extends AbstractOperation
                         return yield false;
                     }
 
-                    return yield from Pipe::of()(Diff::of()(...$other), IsEmpty::of())($iterator);
+                    foreach ($iterator as $current) {
+                        if (false === Contains::of()($current)($other)->current()) {
+                            return yield false;
+                        }
+                    }
+
+                    return yield true;
                 };
             };
     }

I think this would be better. Indeed, the Diff operation will traverse the whole collection to compute a diff. A diff can contain 1, 2, 3... n values that are different. In our case, we only need to check if there's only one which is different, then return false.

WDYT ?

Hmm interesting one! Diff is basically doing a Filter, but we want to stop early. Could we use TakeWhile for that somehow?

drupol · 2021-07-18T21:11:26Z

Hmm interesting one! Diff is basically doing a Filter, but we want to stop early. Could we use TakeWhile for that somehow?

This is what the Match and Every operations are doing, they are not using a TakeWhile but a DropWhile instead.

AlexandruGG · 2021-07-18T21:12:28Z

Hmm interesting one! Diff is basically doing a Filter, but we want to stop early. Could we use TakeWhile for that somehow?

This is what the Match and Every operations are doing, they are not using a TakeWhile but a DropWhile instead.

I just noticed this after I wrote it 😄

drupol · 2021-07-18T21:15:36Z

This is what I would propose:

diff --git a/src/Operation/Equals.php b/src/Operation/Equals.php
index d0bae356..dcbfe2d0 100644
--- a/src/Operation/Equals.php
+++ b/src/Operation/Equals.php
@@ -50,7 +50,10 @@ final class Equals extends AbstractOperation
                         return yield false;
                     }
 
-                    return yield from Pipe::of()(Diff::of()(...$other), IsEmpty::of())($iterator);
+                    return yield from Every::of()
+                        (static fn(): bool => false)
+                        (static fn($current): bool => Contains::of()($current)($other)->current())
+                        ($iterator);
                 };
             };
     }

And like that, we gracefully get rid of the Diff::of()(...$other) !

drupol · 2021-07-18T21:24:33Z

Good for me now! Feel free to merge whenever you want!

AlexandruGG · 2021-07-18T21:24:42Z

This is what I would propose:

diff --git a/src/Operation/Equals.php b/src/Operation/Equals.php
index d0bae356..dcbfe2d0 100644
--- a/src/Operation/Equals.php
+++ b/src/Operation/Equals.php
@@ -50,7 +50,10 @@ final class Equals extends AbstractOperation
                         return yield false;
                     }
 
-                    return yield from Pipe::of()(Diff::of()(...$other), IsEmpty::of())($iterator);
+                    return yield from Every::of()
+                        (static fn(): bool => false)
+                        (static fn($current): bool => Contains::of()($current)($other)->current())
+                        ($iterator);
                 };
             };
     }

And like that, we gracefully get rid of the Diff::of()(...$other) !

This is great, I used it just had to tweak it a bit to satisfy phpcs and then psalm 😄

drupol

👍

AlexandruGG · 2021-07-18T21:25:26Z

Good for me now! Feel free to merge whenever you want!

I'll call it a day and give this a fresh final look tomorrow! But feel free to approve and I will merge it if I'm not changing anything.

AlexandruGG · 2021-07-19T07:15:09Z

@drupol thanks for all the help on this! 💯

AlexandruGG added 2 commits July 17, 2021 23:07

SA Check: Diff + More Tests

9916957

Add New Operation: Equals

dfb241b

drupol requested changes Jul 18, 2021

View reviewed changes

Add tests

755e7bb

AlexandruGG commented Jul 18, 2021

View reviewed changes

src/Operation/Equals.php Outdated Show resolved Hide resolved

Refactor to be more efficient

11611a9

AlexandruGG commented Jul 18, 2021

View reviewed changes

src/Operation/Equals.php Outdated Show resolved Hide resolved

AlexandruGG added 5 commits July 18, 2021 19:40

Uncomment tests

835baee

Refactor based on suggestion

c8bd4cd

Back to variable version

74b0e18

This one works

a4621f6

Merge master into feature branch

0e3847d

drupol added the new feature label Jul 18, 2021

Add Static Analysis & Docs

b5261da

AlexandruGG changed the title ~~Feature/equals operation~~ Add Equals Operation Jul 18, 2021

AlexandruGG added 2 commits July 18, 2021 21:38

Fix PHPStan in php 7.4

fbd0205

Remove this completely

364fe00

Mention performance cost

599807c

drupol reviewed Jul 18, 2021

View reviewed changes

Pol delivers the optimization 🎉

cb88ecc

drupol approved these changes Jul 18, 2021

View reviewed changes

AlexandruGG marked this pull request as ready for review July 18, 2021 21:25

AlexandruGG merged commit 9808b30 into master Jul 19, 2021

AlexandruGG deleted the feature/equals-operation branch July 19, 2021 07:14

AlexandruGG mentioned this pull request Jul 19, 2021

Add Operation: Same #155

Merged

5 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add `Equals` Operation #152

Add `Equals` Operation #152

AlexandruGG commented Jul 17, 2021 •

edited

Loading

drupol Jul 18, 2021 •

edited

Loading

AlexandruGG Jul 18, 2021

AlexandruGG Jul 18, 2021

drupol Jul 18, 2021

AlexandruGG Jul 18, 2021 •

edited

Loading

drupol Jul 18, 2021

drupol commented Jul 18, 2021

AlexandruGG commented Jul 18, 2021

drupol commented Jul 18, 2021 •

edited

Loading

drupol Jul 18, 2021

drupol commented Jul 18, 2021

AlexandruGG commented Jul 18, 2021

drupol commented Jul 18, 2021

AlexandruGG commented Jul 18, 2021

drupol commented Jul 18, 2021 •

edited

Loading

drupol commented Jul 18, 2021

AlexandruGG commented Jul 18, 2021

drupol left a comment

AlexandruGG commented Jul 18, 2021

AlexandruGG commented Jul 19, 2021

Add Equals Operation #152

Add Equals Operation #152

Conversation

AlexandruGG commented Jul 17, 2021 • edited Loading

drupol Jul 18, 2021 • edited Loading

Choose a reason for hiding this comment

AlexandruGG Jul 18, 2021

Choose a reason for hiding this comment

AlexandruGG Jul 18, 2021

Choose a reason for hiding this comment

drupol Jul 18, 2021

Choose a reason for hiding this comment

AlexandruGG Jul 18, 2021 • edited Loading

Choose a reason for hiding this comment

drupol Jul 18, 2021

Choose a reason for hiding this comment

drupol commented Jul 18, 2021

AlexandruGG commented Jul 18, 2021

drupol commented Jul 18, 2021 • edited Loading

drupol Jul 18, 2021

Choose a reason for hiding this comment

drupol commented Jul 18, 2021

AlexandruGG commented Jul 18, 2021

drupol commented Jul 18, 2021

AlexandruGG commented Jul 18, 2021

drupol commented Jul 18, 2021 • edited Loading

drupol commented Jul 18, 2021

AlexandruGG commented Jul 18, 2021

drupol left a comment

Choose a reason for hiding this comment

AlexandruGG commented Jul 18, 2021

AlexandruGG commented Jul 19, 2021

Add `Equals` Operation #152

Add `Equals` Operation #152

AlexandruGG commented Jul 17, 2021 •

edited

Loading

drupol Jul 18, 2021 •

edited

Loading

AlexandruGG Jul 18, 2021 •

edited

Loading

drupol commented Jul 18, 2021 •

edited

Loading

drupol commented Jul 18, 2021 •

edited

Loading