view release on metacpan or  search on metacpan

lib/Array/Each/Override.pm  view on Meta::CPAN

In list context, C<keys @array> returns a list of the indexes in the array; in
scalar context, it returns the number of elements in the array.

=item C<values>

The core C<values> function returns a list of the values in a hash, or a count
of the values in a hash when called in scalar context.  The new version of
C<values> does not change the behaviour of C<values> when called on a hash.
However, it also allows you to call C<values> on an array.

In list context, C<values @array> returns a list of the elements in the array;
in scalar context, it returns the number of elements in the array.

=back

There is a single iterator for each array, shared by all C<each>, C<keys>, and
C<values> calls in the program.  It can be reset by reading all the elements
from the iterator with C<each>, or by evaluating C<keys @array> or C<values
@array>.

=head1 ALTERNATIVE NAMES

You may prefer not to change the core C<each>, C<keys>, and C<values>
functions.  If so, you can import the new functions under alternative,
noninvasive names:

    use Array::Each::Override qw<array_each array_keys array_values>;

Or to import all of them in one go:

    use Array::Each::Override qw<:safe>;

Or mix and match:

    use Array::Each::Override qw<each array_keys array_values>;

The functions with these noninvasive names behave exactly the same as the
overridden core functions.

You might alternatively prefer to make the new functions available to all parts
of your program in one fell swoop:

    use Array::Each::Override qw<:global>;

Or make just some of the functions global:

    use Array::Each::Override qw<:global each keys>;

You can also unimport names.  For example, this removes the globally overridden
functions:

    no Array::Each::Override qw<:global>;

=head1 BUGS

=over 4

=item *

If you set C<$[> to anything other than 0, then (a) please stop doing that,
because it's been deprecated for a long time, and (b) C<each>, C<keys>, and
C<values> on arrays probably don't do what you expect.

=item *

Importing and unimporting function names has an effect on your entire package,
not just your lexical scope.

=item *

There may be some outstanding memory leaks.

=item *

Tied arrays haven't been tested at all.

=back

=head1 PERFORMANCE

There is some overhead for calling the new functions on a hash, compared to
the standard core functions.  The approximate penalties in each case are as
follows:

=over 4

=item C<each %hash>

20-25%

=item scalar-context C<keys %hash>

55-60%

=item scalar-context C<values %hash>

60-65%

=item list-context C<keys %hash>

1%

=item list-context C<values %hash>

1%

=back

If this performance penalty bothers you, use the C<:safe> function names
instead.

=head1 SEE ALSO

L<perlfunc|each>, L<perlfunc|keys>, L<perlfunc|values>.

=head1 AUTHOR

Aaron Crane E<lt>arc@cpan.orgE<gt>

Thanks to Chia-Liang Kao for his help in getting this working.