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.002009
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       join($str)
201           Joins every element of the array using the separator given as
202           argument, just like Perl's core "join" function.
203
204             my $joined = $stuff->join(':');
205             print "$joined\n";    # prints "foo:bar:baz:boo"
206
207           This method requires a single argument.
208
209       print($handle, $str)
210           Prints the output of join($str) to $handle. $handle defaults to
211           STDOUT, and join $str defaults to join()'s default of ','.
212
213             $joined = $stuff->print(*STDERR, ';'); # prints foo;bar;baz to STDERR
214
215       set($index, $value)
216           Given an index and a value, sets the specified array element's
217           value.
218
219           This method returns the value at $index after the set.
220
221           This method requires two arguments.
222
223       delete($index)
224           Removes the element at the given index from the array.
225
226           This method returns the deleted value, either as an array or scalar
227           as dependent on splice context semantics. Note that if no value
228           exists, it will
229
230           return "undef".
231
232           This method requires one argument.
233
234       insert($index, $value)
235           Inserts a new element into the array at the given index.
236
237           This method returns the new value at $index, either as an array or
238           scalar as dependent on splice context semantics.
239
240           This method requires two arguments.
241
242       clear
243           Empties the entire array, like "@array = ()".
244
245           This method does not define a return value.
246
247           This method does not accept any arguments.
248
249       accessor($index)
250       accessor($index, $value)
251           This method provides a get/set accessor for the array, based on
252           array indexes.  If passed one argument, it returns the value at the
253           specified index.  If passed two arguments, it sets the value of the
254           specified index.
255
256           When called as a setter, this method returns the new value at
257           $index.
258
259           This method accepts one or two arguments.
260
261       natatime($n)
262       natatime($n, $code)
263           This method returns an iterator which, on each call, returns $n
264           more items from the array, in order, like "natatime" from
265           List::MoreUtils. A coderef can optionally be provided; it will be
266           called on each group of $n elements in the array.
267
268           This method accepts one or two arguments.
269
270       shallow_clone
271           This method returns a shallow clone of the array reference.  The
272           return value is a reference to a new array with the same elements.
273           It is shallow because any elements that were references in the
274           original will be the same references in the clone.
275
276       flatten
277           This method returns a list of elements in the array.  This method
278           is an alias to the elements method.
279
280       flatten_deep($level)
281           This method returns a flattened list of elements in the array. Will
282           flatten arrays contained within the root array recursively - depth
283           is controlled by the optional $level parameter.
284

AUTHOR

291       Matthew Phillips <mattp@cpan.org>
292

COPYRIGHT AND LICENSE

294       This software is copyright (c) 2014 by Matthew Phillips
295       <mattp@cpan.org>.
296
297       This is free software; you can redistribute it and/or modify it under
298       the same terms as the Perl 5 programming language system itself.
299
300
301
302perl v5.28.1                      2014-06D-a2t7a::Perl::Role::Collection::Array(3)