Mojo::Collection(3pm)

1Mojo::Collection(3)   User Contributed Perl Documentation  Mojo::Collection(3)
2
3
4

NAME

6       Mojo::Collection - Collection
7

SYNOPSIS

9         use Mojo::Collection;
10
11         # Manipulate collection
12         my $collection = Mojo::Collection->new(qw(just works));
13         unshift @$collection, 'it';
14         say $collection->join("\n");
15
16         # Chain methods
17         $collection->map(sub { ucfirst })->shuffle->each(sub {
18           my ($word, $num) = @_;
19           say "$num: $word";
20         });
21
22         # Use the alternative constructor
23         use Mojo::Collection 'c';
24         c(qw(a b c))->join('/')->url_escape->say;
25

DESCRIPTION

27       Mojo::Collection is an array-based container for collections.
28
29         # Access array directly to manipulate collection
30         my $collection = Mojo::Collection->new(1 .. 25);
31         $collection->[23] += 100;
32         say for @$collection;
33

FUNCTIONS

35       Mojo::Collection implements the following functions, which can be
36       imported individually.
37
38   c
39         my $collection = c(1, 2, 3);
40
41       Construct a new array-based Mojo::Collection object.
42

METHODS

44       Mojo::Collection implements the following methods.
45
46   TO_JSON
47         my $array = $collection->TO_JSON;
48
49       Alias for "to_array".
50
51   compact
52         my $new = $collection->compact;
53
54       Create a new collection with all elements that are defined and not an
55       empty string.
56
57         # "0, 1, 2, 3"
58         c(0, 1, undef, 2, '', 3)->compact->join(', ');
59
60   each
61         my @elements = $collection->each;
62         $collection  = $collection->each(sub {...});
63
64       Evaluate callback for each element in collection, or return all
65       elements as a list if none has been provided. The element will be the
66       first argument passed to the callback, and is also available as $_.
67
68         # Make a numbered list
69         $collection->each(sub {
70           my ($e, $num) = @_;
71           say "$num: $e";
72         });
73
74   first
75         my $first = $collection->first;
76         my $first = $collection->first(qr/foo/);
77         my $first = $collection->first(sub {...});
78         my $first = $collection->first('some_method');
79         my $first = $collection->first('some_method', @args);
80
81       Evaluate regular expression/callback for, or call method on, each
82       element in collection and return the first one that matched the regular
83       expression, or for which the callback/method returned true. The element
84       will be the first argument passed to the callback, and is also
85       available as $_.
86
87         # Longer version
88         my $first = $collection->first(sub { $_->some_method(@args) });
89
90         # Find first value that contains the word "mojo"
91         my $interesting = $collection->first(qr/mojo/i);
92
93         # Find first value that is greater than 5
94         my $greater = $collection->first(sub { $_ > 5 });
95
96   flatten
97         my $new = $collection->flatten;
98
99       Flatten nested collections/arrays recursively and create a new
100       collection with all elements.
101
102         # "1, 2, 3, 4, 5, 6, 7"
103         c(1, [2, [3, 4], 5, [6]], 7)->flatten->join(', ');
104
105   grep
106         my $new = $collection->grep(qr/foo/);
107         my $new = $collection->grep(sub {...});
108         my $new = $collection->grep('some_method');
109         my $new = $collection->grep('some_method', @args);
110
111       Evaluate regular expression/callback for, or call method on, each
112       element in collection and create a new collection with all elements
113       that matched the regular expression, or for which the callback/method
114       returned true. The element will be the first argument passed to the
115       callback, and is also available as $_.
116
117         # Longer version
118         my $new = $collection->grep(sub { $_->some_method(@args) });
119
120         # Find all values that contain the word "mojo"
121         my $interesting = $collection->grep(qr/mojo/i);
122
123         # Find all values that are greater than 5
124         my $greater = $collection->grep(sub { $_ > 5 });
125
126   head
127         my $new = $collection->head(4);
128         my $new = $collection->head(-2);
129
130       Create a new collection with up to the specified number of elements
131       from the beginning of the collection. A negative number will count from
132       the end.
133
134         # "A B C"
135         c('A', 'B', 'C', 'D', 'E')->head(3)->join(' ');
136
137         # "A B"
138         c('A', 'B', 'C', 'D', 'E')->head(-3)->join(' ');
139
140   join
141         my $stream = $collection->join;
142         my $stream = $collection->join("\n");
143
144       Turn collection into Mojo::ByteStream.
145
146         # Join all values with commas
147         $collection->join(', ')->say;
148
149   last
150         my $last = $collection->last;
151
152       Return the last element in collection.
153
154   map
155         my $new = $collection->map(sub {...});
156         my $new = $collection->map('some_method');
157         my $new = $collection->map('some_method', @args);
158
159       Evaluate callback for, or call method on, each element in collection
160       and create a new collection from the results. The element will be the
161       first argument passed to the callback, and is also available as $_.
162
163         # Longer version
164         my $new = $collection->map(sub { $_->some_method(@args) });
165
166         # Append the word "mojo" to all values
167         my $mojoified = $collection->map(sub { $_ . 'mojo' });
168
169   new
170         my $collection = Mojo::Collection->new(1, 2, 3);
171
172       Construct a new array-based Mojo::Collection object.
173
174   reduce
175         my $result = $collection->reduce(sub {...});
176         my $result = $collection->reduce(sub {...}, $initial);
177
178       Reduce elements in collection with a callback and return its final
179       result, setting $a and $b each time the callback is executed. The first
180       time $a will be set to an optional initial value or the first element
181       in the collection.  And from then on $a will be set to the return value
182       of the callback, while $b will always be set to the next element in the
183       collection.
184
185         # Calculate the sum of all values
186         my $sum = $collection->reduce(sub { $a + $b });
187
188         # Count how often each value occurs in collection
189         my $hash = $collection->reduce(sub { $a->{$b}++; $a }, {});
190
191   reverse
192         my $new = $collection->reverse;
193
194       Create a new collection with all elements in reverse order.
195
196   shuffle
197         my $new = $collection->shuffle;
198
199       Create a new collection with all elements in random order.
200
201   size
202         my $size = $collection->size;
203
204       Number of elements in collection.
205
206   sort
207         my $new = $collection->sort;
208         my $new = $collection->sort(sub {...});
209
210       Sort elements based on return value of a callback and create a new
211       collection from the results, setting $a and $b to the elements being
212       compared, each time the callback is executed.
213
214         # Sort values case-insensitive
215         my $case_insensitive = $collection->sort(sub { uc($a) cmp uc($b) });
216
217   tail
218         my $new = $collection->tail(4);
219         my $new = $collection->tail(-2);
220
221       Create a new collection with up to the specified number of elements
222       from the end of the collection. A negative number will count from the
223       beginning.
224
225         # "C D E"
226         c('A', 'B', 'C', 'D', 'E')->tail(3)->join(' ');
227
228         # "D E"
229         c('A', 'B', 'C', 'D', 'E')->tail(-3)->join(' ');
230
231   tap
232         $collection = $collection->tap(sub {...});
233
234       Alias for "tap" in Mojo::Base.
235
236   to_array
237         my $array = $collection->to_array;
238
239       Turn collection into array reference.
240
241   uniq
242         my $new = $collection->uniq;
243         my $new = $collection->uniq(sub {...});
244         my $new = $collection->uniq('some_method');
245         my $new = $collection->uniq('some_method', @args);
246
247       Create a new collection without duplicate elements, using the string
248       representation of either the elements or the return value of the
249       callback/method to decide uniqueness. Note that "undef" and empty
250       string are treated the same.
251
252         # Longer version
253         my $new = $collection->uniq(sub { $_->some_method(@args) });
254
255         # "foo bar baz"
256         c('foo', 'bar', 'bar', 'baz')->uniq->join(' ');
257
258         # "[[1, 2], [2, 1]]"
259         c([1, 2], [2, 1], [3, 2])->uniq(sub{ $_->[1] })->to_array;
260
261   with_roles
262         my $new_class = Mojo::Collection->with_roles('Mojo::Collection::Role::One');
263         my $new_class = Mojo::Collection->with_roles('+One', '+Two');
264         $collection   = $collection->with_roles('+One', '+Two');
265
266       Alias for "with_roles" in Mojo::Base.
267

NAME

SYNOPSIS

DESCRIPTION

FUNCTIONS

METHODS

SEE ALSO