.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Mojo::Collection 3pm"
.TH Mojo::Collection 3pm 2024-05-15 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Mojo::Collection \- Collection
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  use Mojo::Collection;
\&
\&  # Manipulate collection
\&  my $collection = Mojo::Collection\->new(qw(just works));
\&  unshift @$collection, \*(Aqit\*(Aq;
\&  say $collection\->join("\en");
\&
\&  # 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(\*(Aq/\*(Aq)\->url_escape\->say;
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Mojo::Collection is an array-based container for collections.
.PP
.Vb 4
\&  # Access array directly to manipulate collection
\&  my $collection = Mojo::Collection\->new(1 .. 25);
\&  $collection\->[23] += 100;
\&  say for @$collection;
.Ve
.SH FUNCTIONS
.IX Header "FUNCTIONS"
Mojo::Collection implements the following functions, which can be imported individually.
.SS c
.IX Subsection "c"
.Vb 1
\&  my $collection = c(1, 2, 3);
.Ve
.PP
Construct a new array-based Mojo::Collection object.
.SH METHODS
.IX Header "METHODS"
Mojo::Collection implements the following methods.
.SS TO_JSON
.IX Subsection "TO_JSON"
.Vb 1
\&  my $array = $collection\->TO_JSON;
.Ve
.PP
Alias for "to_array".
.SS compact
.IX Subsection "compact"
.Vb 1
\&  my $new = $collection\->compact;
.Ve
.PP
Create a new collection with all elements that are defined and not an empty string.
.PP
.Vb 2
\&  # "0, 1, 2, 3"
\&  c(0, 1, undef, 2, \*(Aq\*(Aq, 3)\->compact\->join(\*(Aq, \*(Aq);
.Ve
.SS each
.IX Subsection "each"
.Vb 2
\&  my @elements = $collection\->each;
\&  $collection  = $collection\->each(sub {...});
.Ve
.PP
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 \f(CW$_\fR.
.PP
.Vb 4
\&  # Make a numbered list
\&  $collection\->each(sub ($e, $num) {
\&    say "$num: $e";
\&  });
.Ve
.SS first
.IX Subsection "first"
.Vb 5
\&  my $first = $collection\->first;
\&  my $first = $collection\->first(qr/foo/);
\&  my $first = $collection\->first(sub {...});
\&  my $first = $collection\->first(\*(Aqsome_method\*(Aq);
\&  my $first = $collection\->first(\*(Aqsome_method\*(Aq, @args);
.Ve
.PP
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 \f(CW$_\fR.
.PP
.Vb 2
\&  # 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 });
.Ve
.SS flatten
.IX Subsection "flatten"
.Vb 1
\&  my $new = $collection\->flatten;
.Ve
.PP
Flatten nested collections/arrays recursively and create a new collection with all elements.
.PP
.Vb 2
\&  # "1, 2, 3, 4, 5, 6, 7"
\&  c(1, [2, [3, 4], 5, [6]], 7)\->flatten\->join(\*(Aq, \*(Aq);
.Ve
.SS grep
.IX Subsection "grep"
.Vb 4
\&  my $new = $collection\->grep(qr/foo/);
\&  my $new = $collection\->grep(sub {...});
\&  my $new = $collection\->grep(\*(Aqsome_method\*(Aq);
\&  my $new = $collection\->grep(\*(Aqsome_method\*(Aq, @args);
.Ve
.PP
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 \f(CW$_\fR.
.PP
.Vb 2
\&  # 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 });
.Ve
.SS head
.IX Subsection "head"
.Vb 2
\&  my $new = $collection\->head(4);
\&  my $new = $collection\->head(\-2);
.Ve
.PP
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.
.PP
.Vb 2
\&  # "A B C"
\&  c(\*(AqA\*(Aq, \*(AqB\*(Aq, \*(AqC\*(Aq, \*(AqD\*(Aq, \*(AqE\*(Aq)\->head(3)\->join(\*(Aq \*(Aq);
\&
\&  # "A B"
\&  c(\*(AqA\*(Aq, \*(AqB\*(Aq, \*(AqC\*(Aq, \*(AqD\*(Aq, \*(AqE\*(Aq)\->head(\-3)\->join(\*(Aq \*(Aq);
.Ve
.SS join
.IX Subsection "join"
.Vb 2
\&  my $stream = $collection\->join;
\&  my $stream = $collection\->join("\en");
.Ve
.PP
Turn collection into Mojo::ByteStream.
.PP
.Vb 2
\&  # Join all values with commas
\&  $collection\->join(\*(Aq, \*(Aq)\->say;
.Ve
.SS last
.IX Subsection "last"
.Vb 1
\&  my $last = $collection\->last;
.Ve
.PP
Return the last element in collection.
.SS map
.IX Subsection "map"
.Vb 3
\&  my $new = $collection\->map(sub {...});
\&  my $new = $collection\->map(\*(Aqsome_method\*(Aq);
\&  my $new = $collection\->map(\*(Aqsome_method\*(Aq, @args);
.Ve
.PP
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 \f(CW$_\fR.
.PP
.Vb 2
\&  # Longer version
\&  my $new = $collection\->map(sub { $_\->some_method(@args) });
\&
\&  # Append the word "mojo" to all values
\&  my $mojoified = $collection\->map(sub { $_ . \*(Aqmojo\*(Aq });
.Ve
.SS new
.IX Subsection "new"
.Vb 1
\&  my $collection = Mojo::Collection\->new(1, 2, 3);
.Ve
.PP
Construct a new array-based Mojo::Collection object.
.SS reduce
.IX Subsection "reduce"
.Vb 2
\&  my $result = $collection\->reduce(sub {...});
\&  my $result = $collection\->reduce(sub {...}, $initial);
.Ve
.PP
Reduce elements in collection with a callback and return its final result, setting \f(CW$a\fR and \f(CW$b\fR each time the
callback is executed. The first time \f(CW$a\fR will be set to an optional initial value or the first element in the
collection. And from then on \f(CW$a\fR will be set to the return value of the callback, while \f(CW$b\fR will always be set to
the next element in the collection.
.PP
.Vb 2
\&  # 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 }, {});
.Ve
.SS reverse
.IX Subsection "reverse"
.Vb 1
\&  my $new = $collection\->reverse;
.Ve
.PP
Create a new collection with all elements in reverse order.
.SS shuffle
.IX Subsection "shuffle"
.Vb 1
\&  my $new = $collection\->shuffle;
.Ve
.PP
Create a new collection with all elements in random order.
.SS size
.IX Subsection "size"
.Vb 1
\&  my $size = $collection\->size;
.Ve
.PP
Number of elements in collection.
.SS sort
.IX Subsection "sort"
.Vb 2
\&  my $new = $collection\->sort;
\&  my $new = $collection\->sort(sub {...});
.Ve
.PP
Sort elements based on return value of a callback and create a new collection from the results, setting \f(CW$a\fR and \f(CW$b\fR
to the elements being compared, each time the callback is executed.
.PP
.Vb 2
\&  # Sort values case\-insensitive
\&  my $case_insensitive = $collection\->sort(sub { uc($a) cmp uc($b) });
.Ve
.SS tail
.IX Subsection "tail"
.Vb 2
\&  my $new = $collection\->tail(4);
\&  my $new = $collection\->tail(\-2);
.Ve
.PP
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.
.PP
.Vb 2
\&  # "C D E"
\&  c(\*(AqA\*(Aq, \*(AqB\*(Aq, \*(AqC\*(Aq, \*(AqD\*(Aq, \*(AqE\*(Aq)\->tail(3)\->join(\*(Aq \*(Aq);
\&
\&  # "D E"
\&  c(\*(AqA\*(Aq, \*(AqB\*(Aq, \*(AqC\*(Aq, \*(AqD\*(Aq, \*(AqE\*(Aq)\->tail(\-3)\->join(\*(Aq \*(Aq);
.Ve
.SS tap
.IX Subsection "tap"
.Vb 1
\&  $collection = $collection\->tap(sub {...});
.Ve
.PP
Alias for "tap" in Mojo::Base.
.SS to_array
.IX Subsection "to_array"
.Vb 1
\&  my $array = $collection\->to_array;
.Ve
.PP
Turn collection into array reference.
.SS uniq
.IX Subsection "uniq"
.Vb 4
\&  my $new = $collection\->uniq;
\&  my $new = $collection\->uniq(sub {...});
\&  my $new = $collection\->uniq(\*(Aqsome_method\*(Aq);
\&  my $new = $collection\->uniq(\*(Aqsome_method\*(Aq, @args);
.Ve
.PP
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 \f(CW\*(C`undef\*(C'\fR and empty string are treated the same.
.PP
.Vb 2
\&  # Longer version
\&  my $new = $collection\->uniq(sub { $_\->some_method(@args) });
\&
\&  # "foo bar baz"
\&  c(\*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq)\->uniq\->join(\*(Aq \*(Aq);
\&
\&  # "[[1, 2], [2, 1]]"
\&  c([1, 2], [2, 1], [3, 2])\->uniq(sub{ $_\->[1] })\->to_array;
.Ve
.SS with_roles
.IX Subsection "with_roles"
.Vb 3
\&  my $new_class = Mojo::Collection\->with_roles(\*(AqMojo::Collection::Role::One\*(Aq);
\&  my $new_class = Mojo::Collection\->with_roles(\*(Aq+One\*(Aq, \*(Aq+Two\*(Aq);
\&  $collection   = $collection\->with_roles(\*(Aq+One\*(Aq, \*(Aq+Two\*(Aq);
.Ve
.PP
Alias for "with_roles" in Mojo::Base.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Mojolicious, Mojolicious::Guides, <https://mojolicious.org>.