File Coverage

blib/lib/Array/Each/Override.pm

Criterion	Covered	Total	%
statement	51	51	100.0
branch	11	12	91.6
condition	8	9	88.8
subroutine	11	11	100.0
pod			n/a
total	81	83	97.5

package Array::Each::Override;

use strict;
use warnings;

our $VERSION = '0.05';

use XSLoader;
XSLoader::load(__PACKAGE__, $VERSION);

use Scalar::Util qw;
use Carp qw;

my @FUNCTIONS = qw;
my %KNOWN_FUNCTION = map { ($_ => 1, "array_$_" => 1) } @FUNCTIONS;

sub import {
    my ($class, @imports) = @_;
    my $caller = caller;
    for my $export (_parse_import_list($caller, @imports)) {
        my ($dest, $name, $func) = @$export{qw};
        no strict qw;
        *{"$dest\::$name"} = $func;
    }
}

sub unimport {
    my ($package, @imports) = @_;
    my $caller = caller;
    for my $export (_parse_import_list($caller, @imports)) {
        my ($dest, $name, $func) = @$export{qw};
        no strict qw;
        delete ${"$dest\::"}{$name}
    }
}

sub _parse_import_list {
    my ($importer, @imports) = @_;

    for my $name (@imports) {
        croak "Unknown function '$name'"
            if !$KNOWN_FUNCTION{$name}
            && $name ne ':global'
            && $name ne ':safe';
    }

    my $mode = '';
    $mode = shift @imports
        if @imports && $imports[0] =~ /\A :/xms;

    croak ":global or :safe must be the first item in the import list"
        if grep { /^:/ } @imports;

    @imports = @FUNCTIONS if !@imports;

    $importer = 'CORE::GLOBAL'
        if $mode eq ':global';

    return map {
        (my $func_name = $_) =~ s/\A (?!array_)/array_/xms;
        $_ = $func_name if $mode eq ':safe';
        my $func = do { no strict 'refs'; \&$func_name };
        +{
            dest => $importer,
            func => $func,
            name => $_,
        };
    } @imports;
}

1;

=head1 NAME

Array::Each::Override - C for iterating over an array's keys and values

=head1 SYNOPSIS

    use Array::Each::Override;

    my @array = get_data();
    while (my ($i, $val) = each @array) {
        print "Position $i contains: $val\n";
    }

=head1 DESCRIPTION

This module provides new implementations of three core functions: C,
C, and C.

=over 4

=item C

The core C function iterates over a hash; each time it's called, it
returns a 2-element list of a key and value in the hash.  The new version of
C does not change the behaviour of C when called on a hash.
However, it also allows you to call C on array.  Each time it's called,
it returns a 2-element list of the next uniterated index in the the array, and
the value at that index.

When the array is entirely iterated, an empty list is returned in list context.
The next call to array C after that will start iterating again.

=item C

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

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

=item C

The core C 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 does not change the behaviour of C when called on a hash.
However, it also allows you to call C on an array.

In list context, C 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, C, and
C calls in the program.  It can be reset by reading all the elements
from the iterator with C, or by evaluating C or C
@array>.

=head1 ALTERNATIVE NAMES

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

    use Array::Each::Override qw;

Or to import all of them in one go:

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

Or mix and match:

    use Array::Each::Override qw;

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, C, and
C 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

20-25%

=item scalar-context C

55-60%

=item scalar-context C

60-65%

=item list-context C

1%

=item list-context C

1%

=back

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

=head1 SEE ALSO

L, L, L.

=head1 AUTHOR

Aaron Crane [e-mail]

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

=head1 COPYRIGHT

Copyright 2007 Aaron Crane.

This library is free software; you can redistribute it and/or modify it under
the terms of the Artistic License, or (at your option) under the terms of the
GNU General Public License version 2.

=cut