File Coverage

blib/lib/Mojo/Collection.pm

Criterion	Covered	Total	%
statement	96	96	100.0
branch	26	26	100.0
condition	13	15	86.6
subroutine	34	34	100.0
pod	22	22	100.0
total	191	193	98.9

package Mojo::Collection;
use Mojo::Base -strict;

use re       qw(is_regexp);
use Carp     qw(croak);
use Exporter qw(import);
use List::Util;
use Mojo::ByteStream;
use Scalar::Util qw(blessed);

our @EXPORT_OK = ('c');

sub TO_JSON { [@{shift()}] }

sub c { __PACKAGE__->new(@_) }

sub compact {
  my $self = shift;
  return $self->new(grep { defined && (ref || length) } @$self);
}

sub each {
  my ($self, $cb) = @_;
  return @$self unless $cb;
  my $i = 1;
  $_->$cb($i++) for @$self;
  return $self;
}

sub first {
  my ($self, $cb) = (shift, shift);
  return $self->[0] unless $cb;
  return List::Util::first { $_ =~ $cb } @$self if is_regexp $cb;
  return List::Util::first { $_->$cb(@_) } @$self;
}

sub flatten { $_[0]->new(_flatten(@{$_[0]})) }

sub grep {
  my ($self, $cb) = (shift, shift);
  return $self->new(grep { $_ =~ $cb } @$self) if is_regexp $cb;
  return $self->new(grep { $_->$cb(@_) } @$self);
}

sub head {
  my ($self, $size) = @_;
  return $self->new(@$self)                   if $size > @$self;
  return $self->new(@$self[0 .. ($size - 1)]) if $size >= 0;
  return $self->new(@$self[0 .. ($#$self + $size)]);
}

sub join {
  Mojo::ByteStream->new(join $_[1] // '', map {"$_"} @{$_[0]});
}

sub last { shift->[-1] }

sub map {
  my ($self, $cb) = (shift, shift);
  return $self->new(map { $_->$cb(@_) } @$self);
}

sub new {
  my $class = shift;
  return bless [@_], ref $class || $class;
}

sub reduce {
  my $self = shift;
  @_ = (@_, @$self);
  goto &List::Util::reduce;
}

sub reverse { $_[0]->new(reverse @{$_[0]}) }

sub shuffle { $_[0]->new(List::Util::shuffle @{$_[0]}) }

sub size { scalar @{$_[0]} }

sub sort {
  my ($self, $cb) = @_;

  return $self->new(sort @$self) unless $cb;

  my $caller = caller;
  no strict 'refs';
  my @sorted = sort {
    local (*{"${caller}::a"}, *{"${caller}::b"}) = (\$a, \$b);
    $a->$cb($b);
  } @$self;
  return $self->new(@sorted);
}

sub tail {
  my ($self, $size) = @_;
  return $self->new(@$self)                                     if $size > @$self;
  return $self->new(@$self[($#$self - ($size - 1)) .. $#$self]) if $size >= 0;
  return $self->new(@$self[(0 - $size) .. $#$self]);
}

sub tap { shift->Mojo::Base::tap(@_) }

sub to_array { [@{shift()}] }

sub uniq {
  my ($self, $cb) = (shift, shift);
  my %seen;
  return $self->new(grep { !$seen{$_->$cb(@_) // ''}++ } @$self) if $cb;
  return $self->new(grep { !$seen{$_ // ''}++ } @$self);
}

sub with_roles { shift->Mojo::Base::with_roles(@_) }

sub _flatten {
  map { _ref($_) ? _flatten(@$_) : $_ } @_;
}

sub _ref { ref $_[0] eq 'ARRAY' || blessed $_[0] && $_[0]->isa(__PACKAGE__) }

1;

=encoding utf8

=head1 NAME

Mojo::Collection - Collection

=head1 SYNOPSIS

  use Mojo::Collection;

  # Manipulate collection
  my $collection = Mojo::Collection->new(qw(just works));
  unshift @$collection, 'it';
  say $collection->join("\n");

  # Chain methods
  $collection->map(sub { ucfirst })->shuffle->each(sub ($word, $num) {
    say "$num: $word";
  });

  # Use the alternative constructor
  use Mojo::Collection qw(c);
  c(qw(a b c))->join('/')->url_escape->say;

=head1 DESCRIPTION

L is an array-based container for collections.

  # Access array directly to manipulate collection
  my $collection = Mojo::Collection->new(1 .. 25);
  $collection->[23] += 100;
  say for @$collection;

=head1 FUNCTIONS

L implements the following functions, which can be imported individually.

=head2 c

  my $collection = c(1, 2, 3);

Construct a new array-based L object.

=head1 METHODS

L implements the following methods.

=head2 TO_JSON

  my $array = $collection->TO_JSON;

Alias for L.

=head2 compact

  my $new = $collection->compact;

Create a new collection with all elements that are defined and not an empty string.

  # "0, 1, 2, 3"
  c(0, 1, undef, 2, '', 3)->compact->join(', ');

=head2 each

  my @elements = $collection->each;
  $collection  = $collection->each(sub {...});

Evaluate callback for each element in collection, or return all elements as a list if none has been provided. The
element will be the first argument passed to the callback, and is also available as C<$_>.

  # Make a numbered list
  $collection->each(sub ($e, $num) {
    say "$num: $e";
  });

=head2 first

  my $first = $collection->first;
  my $first = $collection->first(qr/foo/);
  my $first = $collection->first(sub {...});
  my $first = $collection->first('some_method');
  my $first = $collection->first('some_method', @args);

Evaluate regular expression/callback for, or call method on, each element in collection and return the first one that
matched the regular expression, or for which the callback/method returned true. The element will be the first argument
passed to the callback, and is also available as C<$_>.

  # Longer version
  my $first = $collection->first(sub { $_->some_method(@args) });

  # Find first value that contains the word "mojo"
  my $interesting = $collection->first(qr/mojo/i);

  # Find first value that is greater than 5
  my $greater = $collection->first(sub { $_ > 5 });

=head2 flatten

  my $new = $collection->flatten;

Flatten nested collections/arrays recursively and create a new collection with all elements.

  # "1, 2, 3, 4, 5, 6, 7"
  c(1, [2, [3, 4], 5, [6]], 7)->flatten->join(', ');

=head2 grep

  my $new = $collection->grep(qr/foo/);
  my $new = $collection->grep(sub {...});
  my $new = $collection->grep('some_method');
  my $new = $collection->grep('some_method', @args);

Evaluate regular expression/callback for, or call method on, each element in collection and create a new collection
with all elements that matched the regular expression, or for which the callback/method returned true. The element will
be the first argument passed to the callback, and is also available as C<$_>.

  # Longer version
  my $new = $collection->grep(sub { $_->some_method(@args) });

  # Find all values that contain the word "mojo"
  my $interesting = $collection->grep(qr/mojo/i);

  # Find all values that are greater than 5
  my $greater = $collection->grep(sub { $_ > 5 });

=head2 head

  my $new = $collection->head(4);
  my $new = $collection->head(-2);

Create a new collection with up to the specified number of elements from the beginning of the collection. A negative
number will count from the end.

  # "A B C"
  c('A', 'B', 'C', 'D', 'E')->head(3)->join(' ');

  # "A B"
  c('A', 'B', 'C', 'D', 'E')->head(-3)->join(' ');

=head2 join

  my $stream = $collection->join;
  my $stream = $collection->join("\n");

Turn collection into L.

  # Join all values with commas
  $collection->join(', ')->say;

=head2 last

  my $last = $collection->last;

Return the last element in collection.

=head2 map

  my $new = $collection->map(sub {...});
  my $new = $collection->map('some_method');
  my $new = $collection->map('some_method', @args);

Evaluate callback for, or call method on, each element in collection and create a new collection from the results. The
element will be the first argument passed to the callback, and is also available as C<$_>.

  # Longer version
  my $new = $collection->map(sub { $_->some_method(@args) });

  # Append the word "mojo" to all values
  my $mojoified = $collection->map(sub { $_ . 'mojo' });

=head2 new

  my $collection = Mojo::Collection->new(1, 2, 3);

Construct a new array-based L object.

=head2 reduce

  my $result = $collection->reduce(sub {...});
  my $result = $collection->reduce(sub {...}, $initial);

Reduce elements in collection with a callback and return its final result, setting C<$a> and C<$b> each time the
callback is executed. The first time C<$a> will be set to an optional initial value or the first element in the
collection. And from then on C<$a> will be set to the return value of the callback, while C<$b> will always be set to
the next element in the collection.

  # Calculate the sum of all values
  my $sum = $collection->reduce(sub { $a + $b });

  # Count how often each value occurs in collection
  my $hash = $collection->reduce(sub { $a->{$b}++; $a }, {});

=head2 reverse

  my $new = $collection->reverse;

Create a new collection with all elements in reverse order.

=head2 shuffle

  my $new = $collection->shuffle;

Create a new collection with all elements in random order.

=head2 size

  my $size = $collection->size;

Number of elements in collection.

=head2 sort

  my $new = $collection->sort;
  my $new = $collection->sort(sub {...});

Sort elements based on return value of a callback and create a new collection from the results, setting C<$a> and C<$b>
to the elements being compared, each time the callback is executed.

  # Sort values case-insensitive
  my $case_insensitive = $collection->sort(sub { uc($a) cmp uc($b) });

=head2 tail

  my $new = $collection->tail(4);
  my $new = $collection->tail(-2);

Create a new collection with up to the specified number of elements from the end of the collection. A negative number
will count from the beginning.

  # "C D E"
  c('A', 'B', 'C', 'D', 'E')->tail(3)->join(' ');

  # "D E"
  c('A', 'B', 'C', 'D', 'E')->tail(-3)->join(' ');

=head2 tap

  $collection = $collection->tap(sub {...});

Alias for L.

=head2 to_array

  my $array = $collection->to_array;

Turn collection into array reference.

=head2 uniq

  my $new = $collection->uniq;
  my $new = $collection->uniq(sub {...});
  my $new = $collection->uniq('some_method');
  my $new = $collection->uniq('some_method', @args);

Create a new collection without duplicate elements, using the string representation of either the elements or the
return value of the callback/method to decide uniqueness. Note that C and empty string are treated the same.

  # Longer version
  my $new = $collection->uniq(sub { $_->some_method(@args) });

  # "foo bar baz"
  c('foo', 'bar', 'bar', 'baz')->uniq->join(' ');

  # "[[1, 2], [2, 1]]"
  c([1, 2], [2, 1], [3, 2])->uniq(sub{ $_->[1] })->to_array;

=head2 with_roles

  my $new_class = Mojo::Collection->with_roles('Mojo::Collection::Role::One');
  my $new_class = Mojo::Collection->with_roles('+One', '+Two');
  $collection   = $collection->with_roles('+One', '+Two');

Alias for L.

=head1 SEE ALSO

L, L, L.

=cut