package Array::KeepGrepped;
# ABSTRACT: Like grep, only keeps the stuff it filters out

our $VERSION = 5;

require Exporter;
@ISA = qw/Exporter/;
@EXPORT_OK = qw/kgrep/;

sub kgrep (&@) {
    my $filter = shift;
    my $filtered = [];
    my @keep;
    local $_;
    for (@_) {
        if ( $filter->() ) {
            push @keep, $_;
            }
        else {
            push @$filtered, $_;
            }
        }
    return ($filtered, @keep);
    }

1;

__END__

=pod

=head1 NAME

Array::KeepGrepped - Like grep, only keeps the stuff it filters out

=head1 VERSION

version 5

=head1 SYNOPSIS

    use Array::KeepGrepped qw/kgrep/;

    my @numbers = 1..10;

    my ($even, @odd) = kgrep { $_ % 2 } @numbers;

    $, = ","; print @odd,@$even;    # prints "1,3,5,7,9,2,4,6,8,10"

=head1 DESCRIPTION

Works like the built-in Perl 'grep', but instead of just skipping over the
entries that don't match, puts them instead into a seperate array that's
returned (by reference) as the first item of the returned list.

Primary use for this is when you want to remove elements from an array
in-place, but still be able to use what you removed.

=head1 EXAMPLES

    my @good = qw/good bad good evil good wicked good/;

    my $bad;

    ($bad, @good) = kgrep { $_ =~ /good/ } @good;

    say "@$bad | @good";   # bad evil wicked | good good good good

=head1 SEE ALSO

grep

=head1 AUTHOR

Dominic Humphries <dominic@oneandoneis2.com>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Dominic Humphries.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut