Feat: null filter

[bpolaszek]

Since we can omit the 2nd argument of the native array_filter function, resulting in an output array is filtered on truthy values, we should be able to invoke IterableObject::filter() similarly.

This PR allows IterableObject::filter() to accept a null callback (or no args at all) to enable this behavior.

To prevent this default filter from being applied when IterableObject::$filter is null (with the "no filter" intention), IterableObject's constructor is now private, and the IterableObject::filter() method MUST be used to ensure user's intention. Hence $filter and $map arguments from the iterable() function have been removed to enforce using the fluent interface.

@simPod would you mind reviewing this?

[codecov]

Codecov Report

Merging #25 (fd05360) into 2.0.x-dev (7da8363) will not change coverage.
The diff coverage is 100.00%.

@@             Coverage Diff             @@
##           2.0.x-dev       #25   +/-   ##
===========================================
  Coverage     100.00%   100.00%           
===========================================
  Files              2         2           
  Lines             43        48    +5     
===========================================
+ Hits              43        48    +5     

Impacted Files	Coverage Δ
src/IterableObject.php	100.00% <100.00%> (ø)
src/iterable-functions.php	100.00% <100.00%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 7da8363...fd05360. Read the comment docs.

[simPod]

Today I stumbled upon this iterable() fn wondering what it does, had no time to check the docs so I guess the time is now 😄

But first, I don't get the readme

When you have an iterable type-hint somewhere, and don't know in advance wether you'll pass an array or a Traversable, just call the magic iterable() factory:

Why should it matter whether I pass an array or Traversable into iterable?

[bpolaszek]

Why should it matter whether I pass an array or Traversable into iterable?

I think there's a mistake in the doc indeed ^^ I thought about iterable output, array|Traversable input. Example:

interface StuffProviderInterface
{
    public function getStuff(): iterable;
}

function ingestStuff(Traversable $stuff): void
{
    // do something
}

// ...

ingestStuff(iterable($stuffProvider->getStuff())); // bec. we're not supposed to know if the implementation returns an array or a Traversable

Similarly:

interface StuffProviderInterface
{
    public function getStuff(): iterable;
}

function ingestStuff(array $stuff): void
{
    // do something
}

// ...

ingestStuff(iterable($stuffProvider->getStuff())->asArray());

But that's not really relevant since we provide functions for that.

[bpolaszek]

But basically we should think about iterable as a convenient, fluent factory for IterableObject (which is @internal and is not supposed to be instanciated outside of the library) to write code like iterable($stuff)->filter($filterFn)->map($mapFn). I will rewrite that section of the doc.

[simPod]

When I did the benchmarking last time on 7.4, using intval or boolval in this case was faster than anon. fcn.

[bpolaszek]

Good idea 🙂 but I just tested it, and it throws warnings when used within CallbackFilterIterator because it expects 1 parameter, and the CallbackFilterIterator injects 3.

[bpolaszek]

That reminds me that we currently don't support the $mode argument of the array_filter() function, I'll try to address that in a separate PR.

[bpolaszek]

@simPod I'd like to merge this one, along with #26. Any objection?

[simPod]

@bpolaszek no, let's 🚢