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 ($word, $num) {
18           say "$num: $word";
19         });
20
21         # Use the alternative constructor
22         use Mojo::Collection qw(c);
23         c(qw(a b c))->join('/')->url_escape->say;
24

DESCRIPTION

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

FUNCTIONS

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

METHODS

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

NAME

SYNOPSIS

DESCRIPTION

FUNCTIONS

METHODS

SEE ALSO