2 package Moose::Meta::Attribute::Native::Trait::Array;
5 with 'Moose::Meta::Attribute::Native::Trait';
7 sub _helper_type { 'ArrayRef' }
13 # ABSTRACT: Helper trait for array delegation
27 isa => 'ArrayRef[Str]',
28 default => sub { [] },
30 all_options => 'elements',
33 filter_options => 'grep',
34 find_option => 'first',
36 join_options => 'join',
37 count_options => 'count',
38 has_options => 'count',
39 has_no_options => 'is_empty',
40 sorted_options => 'sort',
49 This trait provides native delegation methods for array references.
53 If you don't provide an C<isa> value for your attribute, it will default to
56 =head1 PROVIDED METHODS
62 Returns the number of elements in the array.
65 $stuff->options( [ "foo", "bar", "baz", "boo" ] );
67 print $stuff->count_options; # prints 4
69 This method does not accept any arguments.
73 Returns a boolean value that is true when the array has no elements.
75 $stuff->has_no_options ? die "No options!\n" : print "Good boy.\n";
77 This method does not accept any arguments.
81 Returns all of the elements of the array as an array (not an array reference).
83 my @option = $stuff->all_options;
84 print "@options\n"; # prints "foo bar baz boo"
86 This method does not accept any arguments.
88 =item * B<get($index)>
90 Returns an element of the array by its index. You can also use negative index
91 numbers, just as with Perl's core array handling.
93 my $option = $stuff->get_option(1);
94 print "$option\n"; # prints "bar"
96 If the specified element does not exist, this will return C<undef>.
98 This method accepts just one argument.
102 Just like Perl's builtin C<pop>.
104 This method does not accept any arguments.
106 =item * B<push($value1, $value2, value3 ...)>
108 Just like Perl's builtin C<push>. Returns the number of elements in the new
111 This method accepts any number of arguments.
115 Just like Perl's builtin C<shift>.
117 This method does not accept any arguments.
119 =item * B<unshift($value1, $value2, value3 ...)>
121 Just like Perl's builtin C<unshift>. Returns the number of elements in the new
124 This method accepts any number of arguments.
126 =item * B<splice($offset, $length, @values)>
128 Just like Perl's builtin C<splice>. In scalar context, this returns the last
129 element removed, or C<undef> if no elements were removed. In list context,
130 this returns all the elements removed from the array.
132 This method requires at least one argument.
134 =item * B<first( sub { ... } )>
136 This method returns the first item matching item in the array, just like
137 L<List::Util>'s C<first> function. The matching is done with a subroutine
138 reference you pass to this method. The subroutine will be called against each
139 element in the array until one matches or all elements have been checked.
141 my $found = $stuff->find_option( sub {/^b/} );
142 print "$found\n"; # prints "bar"
144 This method requires a single argument.
146 =item * B<grep( sub { ... } )>
148 This method returns every element matching a given criteria, just like Perl's
149 core C<grep> function. This method requires a subroutine which implements the
152 my @found = $stuff->filter_options( sub {/^b/} );
153 print "@found\n"; # prints "bar baz boo"
155 This method requires a single argument.
157 =item * B<map( sub { ... } )>
159 This method transforms every element in the array and returns a new array,
160 just like Perl's core C<map> function. This method requires a subroutine which
161 implements the transformation.
163 my @mod_options = $stuff->map_options( sub { $_ . "-tag" } );
164 print "@mod_options\n"; # prints "foo-tag bar-tag baz-tag boo-tag"
166 This method requires a single argument.
168 =item * B<reduce( sub { ... } )>
170 This method turns an array into a single value, by passing a function the
171 value so far and the next value in the array, just like L<List::Util>'s
172 C<reduce> function. The reducing is done with a subroutine reference you pass
175 my $found = $stuff->reduce_options( sub { $_[0] . $_[1] } );
176 print "$found\n"; # prints "foobarbazboo"
178 This method requires a single argument.
182 =item * B<sort( sub { ... } )>
184 Returns the elements of the array in sorted order.
186 You can provide an optional subroutine reference to sort with (as you can with
187 Perl's core C<sort> function). However, instead of using C<$a> and C<$b> in
188 this subroutine, you will need to use C<$_[0]> and C<$_[1]>.
190 # ascending ASCIIbetical
191 my @sorted = $stuff->sort_options();
193 # Descending alphabetical order
194 my @sorted_options = $stuff->sort_options( sub { lc $_[1] cmp lc $_[0] } );
195 print "@sorted_options\n"; # prints "foo boo baz bar"
197 This method accepts a single argument.
199 =item * B<sort_in_place>
201 =item * B<sort_in_place( sub { ... } )>
203 Sorts the array I<in place>, modifying the value of the attribute.
205 You can provide an optional subroutine reference to sort with (as you can with
206 Perl's core C<sort> function). However, instead of using C<$a> and C<$b>, you
207 will need to use C<$_[0]> and C<$_[1]> instead.
209 This method does not define a return value.
211 This method accepts a single argument.
215 Returns the elements of the array in random order, like C<shuffle> from
218 This method does not accept any arguments.
222 Returns the array with all duplicate elements removed, like C<uniq> from
225 This method does not accept any arguments.
227 =item * B<join($str)>
229 Joins every element of the array using the separator given as argument, just
230 like Perl's core C<join> function.
232 my $joined = $stuff->join_options(':');
233 print "$joined\n"; # prints "foo:bar:baz:boo"
235 This method requires a single argument.
237 =item * B<set($index, $value)>
239 Given an index and a value, sets the specified array element's value.
241 This method returns the value at C<$index> after the set.
243 This method requires two arguments.
245 =item * B<delete($index)>
247 Removes the element at the given index from the array.
249 This method returns the deleted value. Note that if no value exists, it will
252 This method requires one argument.
254 =item * B<insert($index, $value)>
256 Inserts a new element into the array at the given index.
258 This method returns the new value at C<$index>.
260 This method requires two arguments.
264 Empties the entire array, like C<@array = ()>.
266 This method does not define a return value.
268 This method does not accept any arguments.
270 =item * B<accessor($index)>
272 =item * B<accessor($index, $value)>
274 This method provides a get/set accessor for the array, based on array indexes.
275 If passed one argument, it returns the value at the specified index. If
276 passed two arguments, it sets the value of the specified index.
278 When called as a setter, this method returns the new value at C<$index>.
280 This method accepts one or two arguments.
282 =item * B<natatime($n)>
284 =item * B<natatime($n, $code)>
286 This method returns an iterator which, on each call, returns C<$n> more items
287 from the array, in order, like C<natatime> from L<List::MoreUtils>. A coderef
288 can optionally be provided; it will be called on each group of C<$n> elements
291 This method accepts one or two arguments.
297 See L<Moose/BUGS> for details on reporting bugs.