NAME

    Mojo::Collection::Role::UtilsBy - List::UtilsBy methods for
    Mojo::Collection

SYNOPSIS

      use Mojo::Collection 'c';
      my $c = c(1..12)->with_roles('+UtilsBy');
      say 'Reverse lexical order: ', $c->rev_sort_by(sub { $_ })->join(',');
      
      use List::Util 'product';
      say "Product of 3 elements: $_" for $c->bundle_by(sub { product(@_) }, 3)->each;
      
      my $partitions = $c->partition_by(sub { $_ % 4 });
      # { 0 => c(4,8,12), 1 => c(1,5,9), 2 => c(2,6,10), 3 => c(3,7,11) }
      
      my $halves_and_remainders = $c->unzip_by(sub { (int($_ / 2), $_ % 2) });
      # c(c(0,1,1,2,2,3,3,4,4,5,5,6), c(1,0,1,0,1,0,1,0,1,0,1,0))
      
      my $transposed = $halves_and_remainders->zip_by(sub { c(@_) });
      # c(c(0,1), c(1,0), c(1,1), c(2,0), c(2,1), c(3,0), c(3,1), c(4,0), c(4,1), c(5,0), c(5,1), c(6,0))
      
      my $evens = $c->extract_by(sub { $_ % 2 == 0 }); # $c now contains only odd numbers

DESCRIPTION

    A role to augment Mojo::Collection with methods that call functions
    from List::UtilsBy. With the exception of "bundle_by" and "zip_by"
    which pass multiple elements in @_, all passed callbacks will be called
    with both $_ and $_[0] set to the current element in the iteration.

METHODS

    Mojo::Collection::Role::UtilsBy composes the following methods.

 all_max_by

      my $collection = $c->all_max_by(sub { $_->num });

    Return a new collection containing all of the elements that share the
    numerically largest result from the passed function, using "max_by" in
    List::UtilsBy.

 all_min_by

      my $collection = $c->all_min_by(sub { $_->num });

    Return a new collection containing all of the elements that share the
    numerically smallest result from the passed function, using "min_by" in
    List::UtilsBy.

 bundle_by

      my $collection = $c->bundle_by(sub { c(@_) }, $n);

    Return a new collection containing the results from the passed
    function, given input elements in bundles of (up to) $n at a time,
    using "bundle_by" in List::UtilsBy. The passed function will receive
    each bundle of inputs in @_, and will receive less than $n if not
    enough elements remain.

 count_by

      my $hashref = $c->count_by(sub { $_->name });

    Return a hashref where the values are the number of times each key was
    returned from the passed function, using "count_by" in List::UtilsBy.

 extract_by

      my $collection = $c->extract_by(sub { $_->num > 5 });

    Remove elements from the collection that return true from the passed
    function, and return a new collection containing the removed elements,
    using "extract_by" in List::UtilsBy.

 extract_first_by

      my $element = $c->extract_first_by(sub { $_->name eq 'Fred' });

    Remove and return the first element from the collection that returns
    true from the passed function, using "extract_first_by" in
    List::UtilsBy.

 max_by

      my $element = $c->max_by(sub { $_->num });

    Return the (first) element from the collection that returns the
    numerically largest result from the passed function, using "max_by" in
    List::UtilsBy.

 min_by

      my $element = $c->min_by(sub { $_->num });

    Return the (first) element from the collection that returns the
    numerically smallest result from the passed function, using "min_by" in
    List::UtilsBy.

 nsort_by

      my $collection = $c->nsort_by(sub { $_->num });

    Return a new collection containing the elements sorted numerically by
    the results from the passed function, using "nsort_by" in
    List::UtilsBy.

 partition_by

      my $hashref = $c->partition_by(sub { $_->name });

    Return a hashref where the values are collections of the elements that
    returned that key from the passed function, using "partition_by" in
    List::UtilsBy.

 rev_nsort_by

      my $collection = $c->rev_nsort_by(sub { $_->num });

    Return a new collection containing the elements sorted numerically in
    reverse by the results from the passed function, using "rev_nsort_by"
    in List::UtilsBy.

 rev_sort_by

      my $collection = $c->rev_sort_by(sub { $_->name });

    Return a new collection containing the elements sorted lexically in
    reverse by the results from the passed function, using "rev_sort_by" in
    List::UtilsBy.

 sort_by

      my $collection = $c->sort_by(sub { $_->name });

    Return a new collection containing the elements sorted lexically by the
    results from the passed function, using "sort_by" in List::UtilsBy.

 uniq_by

      my $collection = $c->uniq_by(sub { $_->name });

    Return a new collection containing the elements that return stringwise
    unique values from the passed function, using "uniq_by" in
    List::UtilsBy.

 unzip_by

      my $collection = $c->unzip_by(sub { ($_->name, $_->num) });
      my ($names, $nums) = @$collection_of_collections;

    Return a collection of collections where each collection contains the
    results at the corresponding position from the lists returned by the
    passed function, using "unzip_by" in List::UtilsBy. If the lists are
    uneven, the collections will contain undef in the positions without a
    corresponding value.

 weighted_shuffle_by

      my $collection = $c->weighted_shuffle_by(sub { $_->num });

    Return a new collection containing the elements shuffled with weighting
    according to the results from the passed function, using
    "weighted_shuffle_by" in List::UtilsBy.

 zip_by

      my $collection = $c->zip_by(sub { c(@_) });

    Return a new collection containing the results from the passed function
    when invoked with values from the corresponding position across all
    inner arrays, using "zip_by" in List::UtilsBy. This method must be
    called on a collection that only contains array references or
    collection objects. The passed function will receive each list of
    elements in @_. If the arrays are uneven, undef will be passed in the
    positions without a corresponding value.

BUGS

    Report any issues on the public bugtracker.

AUTHOR

    Dan Book <dbook@cpan.org>

COPYRIGHT AND LICENSE

    This software is Copyright (c) 2017 by Dan Book.

    This is free software, licensed under:

      The Artistic License 2.0 (GPL Compatible)

SEE ALSO

    Mojo::Collection, List::UtilsBy

