Make the CollectionHumanizer::oxford to accept an \Iterator interface

[gabrielanhaia]

What is the Idea?

The idea is to improve the make Coduo\PHPHumanizer\CollectionHumanizer::oxford() accept an \Iterator interface instead of an array always. With this, We could send real collections, arrays, etc. To make it work, all We will need is to iterate it (call the array_map as it's being done) and rely on a possible toString implementation, in case it doesn't have OR the result of each iteration is not a string eligible/parseable, so, We just throw an exception.

I can submit a PR with the idea if you guys agree with the improvement.

[norberttech]

Hey, I'm honestly not sure if I fully understand the problem that \Iterator would solve here. Could you maybe come up with some pseudo code example to help me visualize it?

[cyrillkalita]

@norberttech i think i know what @gabrielanhaia means:

Right now if I want to oxford something, i must do:

$collection = collect(['Eneh', 'Beneh', 'Rabba', 'Clatu',' Verata', 'Nictu']);

Coduo\PHPHumanizer\CollectionHumanizer::oxford($collection->toArray(), 3)

and it would be swell if we can just pass a collection

[gabrielanhaia]

@cyrillkalita is correct.

I would say that \Traversable interface would be an even better option. We could even do things like:

class CustomCollection implements \Traversable
{...}

...
function listWithGenerator(array $array): \Generator
{
    foreach ($array as $x) {
           //... Do something here
           //... 
           yield $x;
    }
}

all of the above options would work:

$collection = new CustomCollection(['Eneh', 'Beneh', 'Rabba', 'Clatu',' Verata', 'Nictu']);
$collection2 = collect(['Eneh', 'Beneh', 'Rabba', 'Clatu',' Verata', 'Nictu']);
$array = ['Eneh', 'Beneh', 'Rabba', 'Clatu',' Verata', 'Nictu'];
$generators = $this->listWithGenerator(['Eneh', 'Beneh', 'Rabba', 'Clatu',' Verata', 'Nictu']);


Coduo\PHPHumanizer\CollectionHumanizer::oxford($collection, 3);
Coduo\PHPHumanizer\CollectionHumanizer::oxford($collection2, 3);
Coduo\PHPHumanizer\CollectionHumanizer::oxford($array, 3);
Coduo\PHPHumanizer\CollectionHumanizer::oxford($generators, 3);

[norberttech]

The prosed change is too big BC break compared to the benefits in my opinion.

- public static function oxford(array $collection, int $limit = null, string $locale = 'en') : string
+ public static function oxford(\Traversable $collection, int $limit = null, string $locale = 'en') : string

However:

-   public static function oxford(array $collection, int $limit = null, string $locale = 'en') : string
+   public static function oxford(iterable $collection, int $limit = null, string $locale = 'en') : string
    {
        $oxford = new Oxford(
            new Formatter(Builder::build($locale))
        );

-       return $oxford->format($collection, $limit);
+       return $oxford->format((array) $collection, $limit);
    }

Should be fine, iterable pseud type will support both, array and \Traversable so it does not seem to be a BC break.