--- name: "Mojo::Collection" section: "3pm" platform: "linux" package: "libmojolicious-perl" version: "9.39+dfsg-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Mojo::Collection" --- # Mojo::Collection(3pm) Collection ## 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 ($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. ``` # 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 ($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. ### 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. ``` # 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, \.