package Array::Diff;
use strict;
use warnings;
use base qw/Class::Accessor::Fast/;

use Algorithm::Diff;
eval q{ use Algorithm::Diff::XS; };

our $VERSION = '0.05002';

__PACKAGE__->mk_accessors(qw/added deleted count diff_class/);

=head1 NAME

Array::Diff - Find the differences between two arrays

=head1 SYNOPSIS

    my @old = ( 'a', 'b', 'c' );
    my @new = ( 'b', 'c', 'd' );
    
    my $diff = Array::Diff->diff( \@old, \@new );
    
    $diff->count   # 2
    $diff->added   # [ 'd' ];
    $diff->deleted # [ 'a' ];

=head1 DESCRIPTION

This module compares two arrays and returns the added or deleted elements
in two separate arrays.  It's a simple wrapper around L<Algorithm::Diff>.

And if you need more complex array tools, check L<Array::Compare>.

=head1 METHODS

=over 4

=item new ()

Create a new C<Array::Diff> object.

=cut

sub new {
    my $self = shift->SUPER::new(@_);

    $self->{diff_class} ||= $INC{'Algorithm/Diff/XS.pm'} ? 'Algorithm::Diff::XS' : 'Algorithm::Diff';

    $self;
}

=item diff ( OLD, NEW )

Compute the differences between two arrays.  The results are stored
in the C<added>, C<deleted>, and C<count> properties that may be
examined using the corresponding methods.

This method may be invoked as an object method, in which case it will
recalculate the differences and repopulate the C<count>, C<added>, and
C<removed> properties, or as a static method, in which case it will
return a newly-created C<Array::Diff> object with the properies
set appropriately.

=cut

sub diff {
    my ( $self, $old, $new ) = @_;
    $self = $self->new unless ref $self;

    $self->added(   [] );
    $self->deleted( [] );
    $self->count( 0 );

    my $diff = $self->diff_class->new( $old, $new );
    while ( $diff->Next ) {
        next if $diff->Same;

        $self->{count}++;

        push @{ $self->{deleted} }, $diff->Items(1)
            if $diff->Items(1);

        push @{ $self->{added} }, $diff->Items(2)
            if $diff->Items(2);
    }

    $self;
}

=item added ( [VALUES ] )

Get or set the elements present in the C<NEW> array and absent in
the C<OLD> one at the comparison performed by the last C<diff()>
invocation.

=item deleted ( [VALUES] )

Get or set the elements present in the C<OLD> array and absent in
the C<NEW> one at the comparison performed by the last C<diff()>
invocation.

=item count ( [VALUE] )

Get or set the total number of added or deleted elements at
the comparison performed by the last C<diff()> invocation.
This count should be equal to the sum of the number of elements in
the C<added> and C<deleted> properties.

=back

=head1 SEE ALSO

L<Algorithm::Diff>

=head1 AUTHOR

Daisuke Murase <typester@cpan.org>

=head1 COPYRIGHT AND LICENSE

Copyright (c) 2009 by Daisuke Murase.

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

The full text of the license can be found in the
LICENSE file included with this module.

=cut

1;