Clarify natatime Array helper behavior when given a code ref

[gitmo/Moose.git] / lib / Moose / Meta / Attribute / Native / Trait / Array.pm

diff --git a/lib/Moose/Meta/Attribute/Native/Trait/Array.pm b/lib/Moose/Meta/Attribute/Native/Trait/Array.pm
index 3224c04..a7046a2 100644 (file)
--- a/lib/Moose/Meta/Attribute/Native/Trait/Array.pm
+++ b/lib/Moose/Meta/Attribute/Native/Trait/Array.pm
@@ -2,35 +2,6 @@
 package Moose::Meta::Attribute::Native::Trait::Array;
 use Moose::Role;
 
-our $VERSION   = '1.16';
-$VERSION = eval $VERSION;
-our $AUTHORITY = 'cpan:STEVAN';
-
-use Moose::Meta::Method::Accessor::Native::Array::accessor;
-use Moose::Meta::Method::Accessor::Native::Array::clear;
-use Moose::Meta::Method::Accessor::Native::Array::count;
-use Moose::Meta::Method::Accessor::Native::Array::delete;
-use Moose::Meta::Method::Accessor::Native::Array::elements;
-use Moose::Meta::Method::Accessor::Native::Array::first;
-use Moose::Meta::Method::Accessor::Native::Array::get;
-use Moose::Meta::Method::Accessor::Native::Array::grep;
-use Moose::Meta::Method::Accessor::Native::Array::insert;
-use Moose::Meta::Method::Accessor::Native::Array::is_empty;
-use Moose::Meta::Method::Accessor::Native::Array::join;
-use Moose::Meta::Method::Accessor::Native::Array::map;
-use Moose::Meta::Method::Accessor::Native::Array::natatime;
-use Moose::Meta::Method::Accessor::Native::Array::pop;
-use Moose::Meta::Method::Accessor::Native::Array::push;
-use Moose::Meta::Method::Accessor::Native::Array::reduce;
-use Moose::Meta::Method::Accessor::Native::Array::set;
-use Moose::Meta::Method::Accessor::Native::Array::shift;
-use Moose::Meta::Method::Accessor::Native::Array::shuffle;
-use Moose::Meta::Method::Accessor::Native::Array::splice;
-use Moose::Meta::Method::Accessor::Native::Array::sort;
-use Moose::Meta::Method::Accessor::Native::Array::sort_in_place;
-use Moose::Meta::Method::Accessor::Native::Array::uniq;
-use Moose::Meta::Method::Accessor::Native::Array::unshift;
-
 with 'Moose::Meta::Attribute::Native::Trait';
 
 sub _helper_type { 'ArrayRef' }
@@ -39,14 +10,12 @@ no Moose::Role;
 
 1;
 
+# ABSTRACT: Helper trait for ArrayRef attributes
+
 __END__
 
 =pod
 
-=head1 NAME
-
-Moose::Meta::Attribute::Native::Trait::Array - Helper trait for array delegation
-
 =head1 SYNOPSIS
 
     package Stuff;
@@ -126,7 +95,7 @@ numbers, just as with Perl's core array handling.
 
 If the specified element does not exist, this will return C<undef>.
 
-This method does accepts just one argument.
+This method accepts just one argument.
 
 =item * B<pop>
 
@@ -164,7 +133,7 @@ This method requires at least one argument.
 
 =item * B<first( sub { ... } )>
 
-This method returns the first item matching item in the array, just like
+This method returns the first matching item in the array, just like
 L<List::Util>'s C<first> function. The matching is done with a subroutine
 reference you pass to this method. The subroutine will be called against each
 element in the array until one matches or all elements have been checked.
@@ -174,6 +143,16 @@ element in the array until one matches or all elements have been checked.
 
 This method requires a single argument.
 
+=item * B<first_index( sub { ... } )>
+
+This method returns the index of the first matching item in the array, just
+like L<List::MoreUtils>'s C<first_index> function. The matching is done with a
+subroutine reference you pass to this method. The subroutine will be called
+against each element in the array until one matches or all elements have been
+checked.
+
+This method requires a single argument.
+
 =item * B<grep( sub { ... } )>
 
 This method returns every element matching a given criteria, just like Perl's
@@ -315,29 +294,25 @@ This method accepts one or two arguments.
 =item * B<natatime($n, $code)>
 
 This method returns an iterator which, on each call, returns C<$n> more items
-from the array, in order, like C<natatime> from L<List::MoreUtils>. A coderef
-can optionally be provided; it will be called on each group of C<$n> elements
-in the array.
+from the array, in order, like C<natatime> from L<List::MoreUtils>.
+
+If you pass a coderef as the second argument, then this code ref will be
+called on each group of C<$n> elements in the array until the array is
+exhausted.
 
 This method accepts one or two arguments.
 
+=item * B<shallow_clone>
+
+This method returns a shallow clone of the array reference.  The return value
+is a reference to a new array with the same elements.  It is I<shallow>
+because any elements that were references in the original will be the I<same>
+references in the clone.
+
 =back
 
 =head1 BUGS
 
 See L<Moose/BUGS> for details on reporting bugs.
 
-=head1 AUTHOR
-
-Stevan Little E<lt>stevan@iinteractive.comE<gt>
-
-=head1 COPYRIGHT AND LICENSE
-
-Copyright 2007-2009 by Infinity Interactive, Inc.
-
-L<http://www.iinteractive.com>
-
-This library is free software; you can redistribute it and/or modify
-it under the same terms as Perl itself.
-
 =cut