/ 
Mojo-Collection-Role-GroupBy-0.003
/ Mojo::Collection::Role::GroupBy

NAME

Mojo::Collection::Role::GroupBy - Group-by operations for Mojo::Collection

SYNOPSIS

use Mojo::Collection;

my $c = Mojo::Collection->new(
    [0, "a"], [1, "b"], [2, "a"]
)->with_roles('+GroupBy');

# Group by index
my $grouped = $c->group_by(1);

# Group by coderef
my $grouped = $c->group_by(sub { $_[0]->[0] % 2 });

# Group by multiple keys (composite)
my $grouped = $c->group_by([0, 1]);

# Convert to hash
my $hash = $grouped->to_hash;

# Expand to collection of key/value pairs
my $expanded = $grouped->expand;

DESCRIPTION

Mojo::Collection::Role::GroupBy is a role for Mojo::Collection that adds grouping operations. It can be applied to any Mojo::Collection instance using "with_roles" in Mojo::Base.

my $c = Mojo::Collection->new(...)->with_roles('+GroupBy');

Collection elements can be arrayrefs, hashrefs, or objects. Mixed collections will raise an error.

METHODS

Mojo::Collection::Role::GroupBy implements the following methods.

group_by

my $grouped = $c->group_by(sub { ... });
my $grouped = $c->group_by($index);
my $grouped = $c->group_by($key);
my $grouped = $c->group_by([$key1, $key2]);
my $grouped = $c->group_by($key1, $key2);

Group collection elements by the return value of a grouping function. Returns a new Mojo::Collection of [$key, $collection] pairs sorted by key.

The grouping argument can be a coderef, a scalar index or key, or an arrayref of indices or keys for composite grouping.

# Group arrayrefs by element at index 1
my $grouped = $c->group_by(1);

# Group hashrefs by key
my $grouped = $c->group_by('category');

# Group objects by method
my $grouped = $c->group_by('name');

# Group by multiple keys
my $grouped = $c->group_by([0, 1]);

# Group with a coderef
my $grouped = $c->group_by(sub { $_[0]->[0] % 2 });

to_hash

my $hash = $grouped->to_hash;
my $hash = $c->to_hash(sub { ... });
my $hash = $c->to_hash($key);

Convert a grouped collection to a hashref, or group and convert in one step by passing a grouping argument. Values are Mojo::Collection objects.

# Group first, then convert
my $hash = $c->group_by('category')->to_hash;

# Group and convert in one step
my $hash = $c->to_hash('category');

to_grouped_array

my $array = $grouped->to_grouped_array;
my $array = $c->to_grouped_array(sub { ... });

Convert a grouped collection to an arrayref of collections, sorted by key.

expand

my $expanded = $grouped->expand;

Expand a grouped collection into a new Mojo::Collection of [$key, $collection] pairs, where $key is the plain grouping key. For composite keys, $key is an arrayref of the component values.

my $expanded = $c->group_by(1)->expand;
$expanded->each(sub {
    my ($key, $values) = $_->@*;
    say "Group $key has " . $values->size . " elements";
});

# Composite keys come back as arrayrefs
my $expanded = $c->group_by([0, 1])->expand;
$expanded->each(sub {
    my ($keys, $values) = $_->@*;
    say join(", ", @$keys);
});

ERRORS

Mojo::Collection::Role::GroupBy will raise an error if the collection contains mixed element types (arrayrefs, hashrefs, and objects cannot be mixed), or if "to_hash" or "expand" are called on an ungrouped collection without a grouping argument.

SEE ALSO

Mojo::Collection, Mojo::Base, Mojo::Collection::Role::GroupBy::Util

AUTHOR

Simone Cesano <scesano@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) Simone Cesano.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.