Data::Perl::Role::Collection::Array(3pm)

1Data::Perl::Role::ColleUcsteironC:o:nAtrrriabyu(t3e)d PeDraltaD:o:cPuemreln:t:aRtoiloen::Collection::Array(3)
2
3
4

NAME

6       Data::Perl::Role::Collection::Array - Wrapping class for Perl's built
7       in array structure.
8

VERSION

10       version 0.002011
11

SYNOPSIS

13         use Data::Perl qw/array/;
14
15         my $array = array(1, 2, 3);
16
17         $array->push(5);
18
19         $array->grep(sub { $_ > 2 })->map(sub { $_ ** 2 })->elements; # (3, 5);
20

DESCRIPTION

22       This class provides a wrapper and methods for interacting with an
23       array.  All methods that return a list do so via a
24       Data::Perl::Collection::Array object.
25

PROVIDED METHODS

27       new($value, $value, ....)
28           Constructs a new Data::Perl::Collection::Array object initialized
29           with passed in values, and returns it.
30
31       count
32           Returns the number of elements in the array.
33
34             $stuff = Data::Perl::Collection::Array->new(qw/foo bar baz boo/);
35
36             print $stuff->count; # prints 4
37
38           This method does not accept any arguments.
39
40       is_empty
41           Returns a boolean value that is true when the array has no
42           elements.
43
44             $stuff->is_empty ? die "No options!\n" : print "Good boy.\n";
45
46           This method does not accept any arguments.
47
48       elements/all
49           Returns all of the elements of the array as an array (not an array
50           reference).
51
52             my @options = $stuff->elements;
53             print "@options\n";    # prints "foo bar baz boo"
54
55           This method does not accept any arguments.
56
57       get($index)
58           Returns an element of the array by its index. You can also use
59           negative index numbers, just as with Perl's core array handling.
60
61             my $option = $stuff->get(1);
62             print "$option\n";    # prints "bar"
63
64           If the specified element does not exist, this will return "undef".
65
66           This method accepts just one argument.
67
68       pop Just like Perl's builtin "pop".
69
70           This method does not accept any arguments.
71
72       push($value1, $value2, value3 ...)
73           Just like Perl's builtin "push". Returns the number of elements in
74           the new array.
75
76           This method accepts any number of arguments.
77
78       shift
79           Just like Perl's builtin "shift".
80
81           This method does not accept any arguments.
82
83       unshift($value1, $value2, value3 ...)
84           Just like Perl's builtin "unshift". Returns the number of elements
85           in the new array.
86
87           This method accepts any number of arguments.
88
89       splice($offset, $length, @values)
90           Just like Perl's builtin "splice". In scalar context, this returns
91           the last element removed, or "undef" if no elements were removed.
92           In list context, this returns all the elements removed from the
93           array, wrapped in a Collection::Array object.
94
95           This method requires at least one argument.
96
97       first( sub { ... } )
98           This method returns the first matching item in the array, just like
99           List::Util's "first" function. The matching is done with a
100           subroutine reference you pass to this method. The subroutine will
101           be called against each element in the array until one matches or
102           all elements have been checked.
103
104             my $found = $stuff->find_option( sub {/^b/} );
105             print "$found\n";    # prints "bar"
106
107           This method requires a single argument.
108
109       first_index( sub { ... } )
110           This method returns the index of the first matching item in the
111           array, just like List::MoreUtils's "first_index" function. The
112           matching is done with a subroutine reference you pass to this
113           method. The subroutine will be called against each element in the
114           array until one matches or all elements have been checked.
115
116           This method requires a single argument.
117
118       grep( sub { ... } )
119           This method returns every element matching a given criteria, just
120           like Perl's core "grep" function. This method requires a subroutine
121           which implements the matching logic. The returned list is provided
122           as a Collection::Array object.
123
124             my @found = $stuff->grep( sub {/^b/} );
125             print "@found\n";    # prints "bar baz boo"
126
127           This method requires a single argument.
128
129       map( sub { ... } )
130           This method transforms every element in the array and returns a new
131           array, just like Perl's core "map" function. This method requires a
132           subroutine which implements the transformation. The returned list
133           is provided as a Collection::Array object.
134
135             my @mod_options = $stuff->map( sub { $_ . "-tag" } );
136             print "@mod_options\n";    # prints "foo-tag bar-tag baz-tag boo-tag"
137
138           This method requires a single argument.
139
140       reduce( sub { ... } )
141           This method turns an array into a single value, by passing a
142           function the value so far and the next value in the array, just
143           like List::Util's "reduce" function. The reducing is done with a
144           subroutine reference you pass to this method.
145
146             my $found = $stuff->reduce( sub { $_[0] . $_[1] } );
147             print "$found\n";    # prints "foobarbazboo"
148
149           This method requires a single argument.
150
151       sort
152       sort( sub { ... } )
153           Returns the elements of the array in sorted order.
154
155           You can provide an optional subroutine reference to sort with (as
156           you can with Perl's core "sort" function). However, instead of
157           using $a and $b in this subroutine, you will need to use $_[0] and
158           $_[1]. The returned list is provided as a Collection::Array object.
159
160             # ascending ASCIIbetical
161             my @sorted = $stuff->sort();
162
163             # Descending alphabetical order
164             my @sorted_options = $stuff->sort( sub { lc $_[1] cmp lc $_[0] } );
165             print "@sorted_options\n";    # prints "foo boo baz bar"
166
167           This method accepts a single argument.
168
169       sort_in_place
170       sort_in_place( sub { ... } )
171           Sorts the array in place, modifying the value of the attribute.
172
173           You can provide an optional subroutine reference to sort with (as
174           you can with Perl's core "sort" function). However, instead of
175           using $a and $b, you will need to use $_[0] and $_[1] instead. The
176           returned list is provided as a Collection::Array object.
177
178           This method accepts a single argument.
179
180       reverse
181           Returns the elements of the array in reversed order. The returned
182           list is provided as a Collection::Array object.
183
184           This method does not accept any arguments.
185
186       shuffle
187           Returns the elements of the array in random order, like "shuffle"
188           from List::Util. The returned list is provided as a
189           Collection::Array object.
190
191           This method does not accept any arguments.
192
193       uniq
194           Returns the array with all duplicate elements removed, like "uniq"
195           from List::MoreUtils. The returned list is provided as a
196           Collection::Array object.
197
198           This method does not accept any arguments.
199
200       head($count)
201           Returns the first $count elements of the array. If $count is
202           greater than the number of elements in the array, the array
203           (without spurious "undef"s) is returned. Negative $count means "all
204           but the last $count elements". The returned list is provided as a
205           Collection::Array object.
206
207       tail($count)
208           Returns the last $count elements of the array. If $count is greater
209           than the number of elements in the array, the array (without
210           spurious "undef"s) is returned. Negative $count means "all but the
211           first $count elements". The returned list is provided as a
212           Collection::Array object.
213
214       join($str)
215           Joins every element of the array using the separator given as
216           argument, just like Perl's core "join" function.
217
218             my $joined = $stuff->join(':');
219             print "$joined\n";    # prints "foo:bar:baz:boo"
220
221           This method requires a single argument.
222
223       print($handle, $str)
224           Prints the output of join($str) to $handle. $handle defaults to
225           STDOUT, and join $str defaults to join()'s default of ','.
226
227             $joined = $stuff->print(*STDERR, ';'); # prints foo;bar;baz to STDERR
228
229       set($index, $value)
230           Given an index and a value, sets the specified array element's
231           value.
232
233           This method returns the value at $index after the set.
234
235           This method requires two arguments.
236
237       delete($index)
238           Removes the element at the given index from the array.
239
240           This method returns the deleted value, either as an array or scalar
241           as dependent on splice context semantics. Note that if no value
242           exists, it will
243
244           return "undef".
245
246           This method requires one argument.
247
248       insert($index, $value)
249           Inserts a new element into the array at the given index.
250
251           This method returns the new value at $index, either as an array or
252           scalar as dependent on splice context semantics.
253
254           This method requires two arguments.
255
256       clear
257           Empties the entire array, like "@array = ()".
258
259           This method does not define a return value.
260
261           This method does not accept any arguments.
262
263       accessor($index)
264       accessor($index, $value)
265           This method provides a get/set accessor for the array, based on
266           array indexes.  If passed one argument, it returns the value at the
267           specified index.  If passed two arguments, it sets the value of the
268           specified index.
269
270           When called as a setter, this method returns the new value at
271           $index.
272
273           This method accepts one or two arguments.
274
275       natatime($n)
276       natatime($n, $code)
277           This method returns an iterator which, on each call, returns $n
278           more items from the array, in order, like "natatime" from
279           List::MoreUtils. A coderef can optionally be provided; it will be
280           called on each group of $n elements in the array.
281
282           This method accepts one or two arguments.
283
284       shallow_clone
285           This method returns a shallow clone of the array reference.  The
286           return value is a reference to a new array with the same elements.
287           It is shallow because any elements that were references in the
288           original will be the same references in the clone.
289
290       flatten
291           This method returns a list of elements in the array.  This method
292           is an alias to the elements method.
293
294       flatten_deep($level)
295           This method returns a flattened list of elements in the array. Will
296           flatten arrays contained within the root array recursively - depth
297           is controlled by the optional $level parameter.
298

AUTHOR

305       Matthew Phillips <mattp@cpan.org>
306

COPYRIGHT AND LICENSE

308       This software is copyright (c) 2020 by Matthew Phillips
309       <mattp@cpan.org>.
310
311       This is free software; you can redistribute it and/or modify it under
312       the same terms as the Perl 5 programming language system itself.
313
314
315
316perl v5.36.0                      2023-01D-a2t0a::Perl::Role::Collection::Array(3)