Permalink
Browse files

Clean up the docs to follow the doc standards (such as they are)

* Illustrative usage first with all variables
* Example after description
* Refer to those variables in the docs rather than "the argument"

Link to the pop/shift documentation.

I also didn't think it's necessary to explain that pop changes the
@array.  Maybe that's a bad assumption?

For #149
  • Loading branch information...
1 parent f035722 commit 68b9d5c9adc723a413bb5404d2cf3830ff56bf17 @schwern schwern committed Nov 25, 2011
Showing with 15 additions and 11 deletions.
  1. +15 −11 lib/perl5i.pm
View
@@ -676,24 +676,28 @@ L<Path::Class>, etc.), it tries its best to treat them as strings or numbers.
=head3 popn
+ my @newarray = @array->popn($n);
+
+L<Pops|perlfunc/pop> C<$n> values from the C<@array>.
+
+If C<$n> is greater than the length of C<@array>, it will return the
+whole C<@array>. If C<$n> is 0, it will return an empty array.
+
+A negative C<$n> or non-integer is an error.
+
my @array = (1, 2, 3, 4, 5);
my @newarray = @array->popn(3); # (3, 4, 5)
-Pops off n values from the C<@array>, changes the original array. If the
-argument is less than 0, it will error. If the argument is greater than
-the length of the array, just return the whole array. If the argument is
-non-integer, it will error out.
-
=head3 shiftn
- my @array = (1, 2, 3, 4, 5);
- my @newarray = @array->shiftn(3); # (1, 2, 3)
+ my @newarray = @array->shiftn($n);
+
+Works like L<popn>, but it L<shifts|perlfunc/shift> off the front of
+the array instead of popping off the end.
-Shifts n values from C<@array>, changes the original array. It will error
-if the argument is less than 0. If the argument is greater than the length,
-just returns the whole array. If the argument is non-integer, it will error
-out.
+ my @array = (1, 2, 3, 4, 5);
+ my @newarray = @array->shiftn(3); # (1, 2, 3)
=head3 intersect

0 comments on commit 68b9d5c

Please sign in to comment.