#!/usr/bin/perl -w
package List::Temporal;

$VERSION = "1.000";

require Exporter;
@ISA = qw(Exporter);
@EXPORT_OK = qw(tgrep);

sub version { $VERSION; }

sub new {
	my $class = shift;
	my $this = {};
	$this->{content} = [ @_ ];
	bless($this,$class);
	return $this;
}

sub grep {
	my ($this, $exp) = @_;
	my (@matches, @newcontent);
	foreach (@{$this->{content}}) {
		if ($_ =~ $exp) {
			push @matches, $_;
		} else {
			push @newcontent, $_;
		}
	}
	$this->{content} = [ @newcontent ];
	@matches;
}

sub remains {
	my ($this) = @_;
	@{$this->{content}};
}

sub tgrep {
	my ($exp, $content) = @_;
	my (@matches, @newcontent);
	foreach (@{$content}) {
		if ($_ =~ $exp) {
			push @matches, $_;
		} else {
			push @newcontent, $_;
		}
	}
	@{$content} = @newcontent;
	@matches;
}
1;

__END__

=head1 NAME

List::Temporal - Temporal list system

=head1 SYNOPSIS

  use List::Temporal;

  # Load up a list
  $templist = List::Temporal->new(qw(word1 word2 word3 word4 word5));

  # Extract first grep
  $output = $templist->grep(qr/[2-3]/); # Will contain 'word2', 'word3'
 
  # Extact second grep from whats left over from the first
  $templist->grep(qr/[2-5]/);
  # Will contain 'word4', 'word5' because 'word2' and 'word3' have
  # already been extracted.

  $templist->remains; # Will return 'word1' because its all thats left

=head2 SYNOPSIS - The Non-OO way:

  use List::Temporal qw(tgrep);
  @anarray = qw(word1 word2 word3 word4 word5);
  @matches = tgrep(qr/[2-3]/, \@anarray);
  # @anarray now has 'word1', 'word4', 'word5' in it

=head1 DESCRIPTION

Manipulates a list in that any action (such as grep) also removes the
matches putting the remaining items in the orignal list.

This differs from a normal grep which leaves the unmatched items
in the originaly given array.

=head1 AUTHOR

Matt Carter E<lt>m@ttcarter.comE<gt>

=cut