zicht / itertools

use Zicht\Itertools\conversions;

use Zicht\Itertools\lib\GroupbyIterator;

trait GroupByTrait

{

    /**

     * Make an iterator that returns consecutive groups from this

     * iterable.  Generally, this iterable needs to already be sorted on

     * the same key function.

     *

     * When $strategy is a string, the key is obtained through one of

     * the following:

     * 1. $value->{$strategy}, when $value is an object and

     *    $strategy is an existing property,

     * 2. call $value->{$strategy}(), when $value is an object and

     *    $strategy is an existing method,

     * 3. $value[$strategy], when $value is an array and $strategy

     *    is an existing key,

     * 4. otherwise the key will default to null.

     *

     * Alternatively $strategy can be a closure.  In this case the

     * $strategy closure is called with each value in this iterable and the

     * key will be its return value.  $strategy is called with two

     * parameters: the value and the key of the iterable as the first and

     * second parameter, respectively.

     *

     * The operation of groupBy() is similar to the uniq filter in Unix.

     * It generates a break or new group every time the value of the key

     * function changes (which is why it is usually necessary to have

     * sorted the data using the same key function).  That behavior

     * differs from SQL's GROUP BY which aggregates common elements

     * regardless of their input order.

     *

     * > $list = [['type'=>'A', 'title'=>'one'], ['type'=>'A', 'title'=>'two'], ['type'=>'B', 'title'=>'three']]

     * > iter\iterable($list)->groupBy('type')

     * 'A'=>[['type'=>'A', 'title'=>'one'], ['type'=>'A', 'title'=>'two']] 'B'=>[['type'=>'B', 'title'=>'three']]

     *

     * @param null|string|\Closure $strategy

     * @param bool $sort

     * @return GroupbyIterator

     */

    public function groupBy($strategy, $sort = true)

    {

        if (!is_bool($sort)) {

            throw new \InvalidArgumentException('Argument $sort must be a boolean');

        }

        if ($this instanceof \Iterator) {

            return new GroupbyIterator(

                conversions\mixed_to_value_getter($strategy),

                $sort ? $this->sorted($strategy) : $this

            );

        }

        return null;

    }

}

use Zicht\Itertools\conversions;

use Zicht\Itertools\lib\SortedIterator;

trait SortedTrait

{

    /**

     * Make an iterator that returns the values from this iterable

     * sorted by $strategy

     *

     * When determining the order of two entries the $strategy is called

     * twice, once for each value, and the results are used to determine

     * the order.  $strategy is called with two parameters: the value and

     * the key of the iterable as the first and second parameter, respectively.

     *

     * When $reverse is true the order of the results are reversed.

     *

     * The sorted() function is guaranteed to be stable.  A sort is stable

     * if it guarantees not to change the relative order of elements that

     * compare equal.  this is helpful for sorting in multiple passes (for

     * example, sort by department, then by salary grade).  This also

     * holds up when $reverse is true.

     *

     * > $list = [['type'=>'B', 'title'=>'second'], ['type'=>'C', 'title'=>'third'], ['type'=>'A', 'title'=>'first']]

     * > iter\iterable($list)->sorted('type')

     * ['type'=>'A', 'title'=>'first'] ['type'=>'B', 'title'=>'second']] ['type'=>'C', 'title'=>'third']

     *

     * @param null|string|\Closure $strategy

     * @param bool $reverse

     * @return SortedIterator

     */

    public function sorted($strategy = null, $reverse = false)

    {

        if (!is_bool($reverse)) {

            throw new \InvalidArgumentException('Argument $reverse must be boolean');

        }

        if ($this instanceof \Iterator) {

            return new SortedIterator(

                conversions\mixed_to_value_getter($strategy),

                $this,

                $reverse

            );

        }

        return null;

    }

}