NAME

       Mojo::Collection - Collection

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 {
           my ($word, $num) = @_;
           say "$num: $word";
         });

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

DESCRIPTION

       Mojo::Collection 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;

FUNCTIONS

       Mojo::Collection implements the following functions, which can be imported individually.

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

       Construct a new array-based Mojo::Collection object.

METHODS

       Mojo::Collection implements the following methods.

   TO_JSON
         my $array = $collection->TO_JSON;

       Alias for "to_array".

   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(', ');

   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 $_.

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

   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 $_.

         # 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 });

   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(', ');

   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 $_.

         # 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 });

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

       Turn collection into Mojo::ByteStream.

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

   last
         my $last = $collection->last;

       Return the last element in collection.

   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 $_.

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

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

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

       Construct a new array-based Mojo::Collection object.

   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 $a and
       $b each time the callback is executed. The first time $a will be set to an optional
       initial value or the first element in the collection.  And from then on $a will be set to
       the return value of the callback, while $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 }, {});

   reverse
         my $new = $collection->reverse;

       Create a new collection with all elements in reverse order.

   slice
         my $new = $collection->slice(4 .. 7);

       Create a new collection with all selected elements.

         # "B C E"
         c('A', 'B', 'C', 'D', 'E')->slice(1, 2, 4)->join(' ');

   shuffle
         my $new = $collection->shuffle;

       Create a new collection with all elements in random order.

   size
         my $size = $collection->size;

       Number of elements in collection.

   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 $a and $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) });

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

       Alias for "tap" in Mojo::Base.

   to_array
         my $array = $collection->to_array;

       Turn collection into array reference.

   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.

         # 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;

   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 "with_roles" in Mojo::Base.

SEE ALSO

       Mojolicious, Mojolicious::Guides, <http://mojolicious.org>.