Mojo::Collection(3)

🌸 NAME 🌸

Okay bestie, welcome to the Mojo::Collection(3) page from the User Contributed Perl Documentation. This is literally about Mojo::Collection — a Collection. No cap 💅✨

---

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

---

🦋 DESCRIPTION 🦋

Mojo::Collection is an array-based container for collections. It's giving "tiny elegant wrapper around an array," and honestly? Obsessed 🫶

# 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. That's it, that's the function ✨

---

💜 METHODS 💜

Mojo::Collection implements the following methods. Chain them, love them, live your main character life 🌈

🎀 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 ($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 });

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

🎀 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. The final girl of the array 💅

🎀 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.

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

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

🎀 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 to decide uniqueness. Note that undef and empty string are treated the same.

🫶 heads up bestie: undef and empty string are treated the same here.

# 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, <https://mojolicious.org>.

---

🫶 cute sign-off: this page is Mojo::Collection(3) from perl v5.42.0, dated 2026-07-15. Bye bestie, go chain some methods 💅✨